From 285b36c63c1dc52c02562624bc8964db3ff15a69 Mon Sep 17 00:00:00 2001
From: Kostya Farber <kostya.farber@gmail.com>
Date: Wed, 6 May 2026 11:08:05 +0100
Subject: [PATCH 01/11] examples: add dimensions hud overlay example (#8767)

having fun with the new overlay utils, this adds a design tool like
overlay that tells you the dimensions of your shapes


https://github.com/user-attachments/assets/932bd100-8229-4e2b-9695-8a261b8a162d

### Change type

- [ ] `bugfix`
- [ ] `improvement`
- [ ] `feature`
- [ ] `api`
- [x] `other`
---
 .../dimensions-hud/DimensionsHudExample.tsx   |  39 ++++
 .../DimensionsHudOverlayUtil.ts               | 190 ++++++++++++++++++
 .../editor-api/dimensions-hud/README.md       |  12 ++
 3 files changed, 241 insertions(+)
 create mode 100644 apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudExample.tsx
 create mode 100644 apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/editor-api/dimensions-hud/README.md

diff --git a/apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudExample.tsx b/apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudExample.tsx
new file mode 100644
index 000000000000..6e789b9aad84
--- /dev/null
+++ b/apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudExample.tsx
@@ -0,0 +1,39 @@
+import { Tldraw, defaultOverlayUtils } from 'tldraw'
+import 'tldraw/tldraw.css'
+import { DimensionsHudOverlayUtil } from './DimensionsHudOverlayUtil'
+
+// There's a guide at the bottom of this file!
+
+// [1]
+const overlayUtils = [...defaultOverlayUtils, DimensionsHudOverlayUtil]
+
+export default function DimensionsHudExample() {
+	return (
+		<div className="tldraw__editor">
+			{/* [2] */}
+			<Tldraw overlayUtils={overlayUtils} />
+		</div>
+	)
+}
+
+/*
+This example adds a non-interactive dimensions label that follows the current
+selection. The label is implemented as a custom `OverlayUtil`, so it renders in
+the editor's canvas overlay layer rather than in the React tree.
+
+`DimensionsHudOverlayUtil.ts` does three things:
+
+- `isActive()` subscribes to the current selection and skips work when nothing
+  is selected.
+- `getOverlays()` derives the label's page-space position, dimensions, and
+  rotation from the selected shape or selection bounds.
+- `render()` draws the pill with Canvas 2D APIs.
+
+[1]
+Register the custom overlay util after `defaultOverlayUtils` so the built-in
+overlays remain enabled. The util's `options.zIndex` controls where it appears
+relative to the selection handles and other canvas overlays.
+
+[2]
+Pass the overlay util array to the `overlayUtils` prop on `<Tldraw>`.
+*/
diff --git a/apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudOverlayUtil.ts b/apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudOverlayUtil.ts
new file mode 100644
index 000000000000..1506a8130f93
--- /dev/null
+++ b/apps/examples/src/examples/editor-api/dimensions-hud/DimensionsHudOverlayUtil.ts
@@ -0,0 +1,190 @@
+import { Box, OverlayUtil, type TLOverlay, Vec } from 'tldraw'
+
+interface TLDimensionsHudOverlay extends TLOverlay {
+	props: {
+		x: number
+		y: number
+		w: number
+		h: number
+		rotation: number
+	}
+}
+
+const LABEL_PADDING = 20
+const PI2 = Math.PI * 2
+
+type LabelEdge = 'top' | 'right' | 'bottom' | 'left'
+
+// [1]
+function getLabelEdge(rotation: number): LabelEdge {
+	const quarterTurn = Math.round(rotation / (Math.PI / 2))
+	const normalizedQuarterTurn = ((quarterTurn % 4) + 4) % 4
+
+	switch (normalizedQuarterTurn) {
+		case 0:
+			return 'bottom'
+		case 1:
+			return 'right'
+		case 2:
+			return 'top'
+		default:
+			return 'left'
+	}
+}
+
+// [2]
+function getReadableRotation(rotation: number): number {
+	const normalizedRotation = ((rotation + Math.PI) % PI2) - Math.PI
+	return Math.abs(normalizedRotation) > Math.PI / 2 ? rotation + Math.PI : rotation
+}
+
+// [3]
+function getLabelPointForEdge(edge: LabelEdge, bounds: Box, padding: number): Vec {
+	switch (edge) {
+		case 'bottom':
+			return new Vec(bounds.midX, bounds.maxY + padding)
+		case 'right':
+			return new Vec(bounds.maxX + padding, bounds.midY)
+		case 'top':
+			return new Vec(bounds.midX, bounds.minY - padding)
+		case 'left':
+			return new Vec(bounds.minX - padding, bounds.midY)
+	}
+}
+
+export class DimensionsHudOverlayUtil extends OverlayUtil<TLDimensionsHudOverlay> {
+	static override type = 'dimensions-hud'
+	override options = { zIndex: 950 }
+
+	override isActive(): boolean {
+		return this.editor.getSelectedShapeIds().length > 0
+	}
+
+	override getOverlays(): TLDimensionsHudOverlay[] {
+		const selectedShapeIds = this.editor.getSelectedShapeIds()
+
+		if (selectedShapeIds.length === 0) return []
+
+		// [4]
+		if (selectedShapeIds.length > 1) {
+			const bounds = this.editor.getSelectionPageBounds()
+			if (!bounds) return []
+			const zoom = this.editor.getZoomLevel()
+
+			return [
+				{
+					id: 'dimensions-hud',
+					type: 'dimensions-hud',
+					props: {
+						x: bounds.midX,
+						y: bounds.maxY + LABEL_PADDING / zoom,
+						w: Math.round(bounds.width),
+						h: Math.round(bounds.height),
+						rotation: 0,
+					},
+				},
+			]
+		}
+
+		const shape = this.editor.getShape(selectedShapeIds[0])
+		if (!shape) return []
+
+		// [5]
+		const bounds = this.editor.getShapeGeometry(shape).bounds
+		const transform = this.editor.getShapePageTransform(shape)
+		const zoom = this.editor.getZoomLevel()
+		const rotation = transform.rotation()
+
+		// [6]
+		const padding = LABEL_PADDING / zoom
+
+		const labelEdge = getLabelEdge(rotation)
+		const localLabelPoint = getLabelPointForEdge(labelEdge, bounds, padding)
+
+		const labelPoint = transform.applyToPoint(localLabelPoint)
+		const labelRotation =
+			labelEdge === 'left' || labelEdge === 'right' ? rotation + Math.PI / 2 : rotation
+		const readableLabelRotation = getReadableRotation(labelRotation)
+
+		return [
+			{
+				id: 'dimensions-hud',
+				type: 'dimensions-hud',
+				props: {
+					x: labelPoint.x,
+					y: labelPoint.y,
+					w: Math.round(bounds.width),
+					h: Math.round(bounds.height),
+					rotation: readableLabelRotation,
+				},
+			},
+		]
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLDimensionsHudOverlay[]): void {
+		const overlay = overlays[0]
+		if (!overlay) return
+
+		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]
+
+		const { x, y, w, h, rotation } = overlay.props
+		const zoom = this.editor.getZoomLevel()
+
+		ctx.save()
+
+		// [7]
+		ctx.textAlign = 'center'
+		ctx.textBaseline = 'middle'
+		ctx.font = `${10 / zoom}px sans-serif`
+
+		const dimensionsLabel = `${w} × ${h}`
+		const metrics = ctx.measureText(dimensionsLabel)
+		const textHeight = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent
+		const textWidth = metrics.width
+		const pillPaddingX = 5 / zoom
+		const pillWidth = textWidth + pillPaddingX * 2
+		const pillHeight = textHeight * 2
+
+		ctx.translate(x, y)
+		ctx.rotate(rotation)
+
+		ctx.fillStyle = colors.selectionStroke
+		ctx.beginPath()
+		ctx.roundRect(-pillWidth / 2, -pillHeight / 2, pillWidth, pillHeight, pillHeight / 3.5)
+		ctx.fill()
+
+		ctx.fillStyle = colors.selectedContrast
+		ctx.fillText(dimensionsLabel, 0, 0)
+		ctx.restore()
+	}
+}
+
+/*
+[1]
+Pick the side of the selected shape that is closest to the bottom of the page.
+This keeps the label near the user's expected resize readout position even when
+the shape is rotated.
+
+[2]
+Flip the label by half a turn when it would otherwise be upside down.
+
+[3]
+Calculate the label point in the shape's local coordinate space. The shape's
+page transform converts it to page space later.
+
+[4]
+Multiple selections do not have a single rotation, so the label uses the
+selection's page bounds and stays horizontal.
+
+[5]
+Use shape geometry bounds for the width and height. These are local bounds, so
+they represent the unrotated dimensions the user is editing.
+
+[6]
+Overlay drawing happens in page space. Divide fixed screen-space values by the
+zoom level so padding, text, and the pill size look consistent while zooming.
+
+[7]
+Save and restore the canvas context around all drawing state because overlay
+utils share the same Canvas 2D context.
+*/
diff --git a/apps/examples/src/examples/editor-api/dimensions-hud/README.md b/apps/examples/src/examples/editor-api/dimensions-hud/README.md
new file mode 100644
index 000000000000..21579baa0904
--- /dev/null
+++ b/apps/examples/src/examples/editor-api/dimensions-hud/README.md
@@ -0,0 +1,12 @@
+---
+title: Dimensions HUD
+component: ./DimensionsHudExample.tsx
+priority: 3
+keywords: [overlay, overlayutil, hud, dimensions, resize, bounds, gesture]
+---
+
+Show a live width × height pill for the current selection.
+
+---
+
+A non-interactive HUD that piggybacks on the editor's existing selection and resize state. The overlay renders into the canvas in page space, so it follows pan and zoom for free without any `pageToScreen` plumbing.

From b01f99f12d7e51550cb6853a9178c8a201ff717d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mime=20=C4=8Cuvalo?= <mimecuvalo@gmail.com>
Date: Wed, 6 May 2026 11:08:49 +0100
Subject: [PATCH 02/11] fix(editor): restore ctrl+click and Android long-press
 context menu (#8772)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to fix two regressions introduced by #8501 (right-click and
drag to pan the camera), this PR makes the canvas's `onContextMenu`
handler more selective. The new handler was unconditionally calling
`preventDefault` on every trusted `contextmenu` event, and Radix's
`composeEventHandlers` skips its own handler when
`event.defaultPrevented` is true. That broke the two context menu
sources where the SDK relies on the browser-native `contextmenu` rather
than synthesising one itself:

- ctrl+click on macOS — the OS-translated `contextmenu` after a
`pointerdown` with `button=0` (closes #8771)
- long-press on Android (and other touch devices) — the `contextmenu`
Android Chrome dispatches after the OS long-press timeout (closes #8770)

Now we only suppress the native `contextmenu` when it follows a real
right-click (`button === 2` with no ctrl modifier). That's the only case
where our pointer handling has already decided what to do — either we'll
dispatch a synthetic `contextmenu` from `onPointerUp` to open the menu
at the release position, or we'll have panned and don't want a menu at
all. Every other source (ctrl+click, two-finger trackpad tap on macOS
reported as `button=2 + ctrlKey=true` by some Chromium builds,
long-press on touch) flows through to Radix as before.

### Change type

- [x] `bugfix`

### Test plan

1. On macOS, hold ctrl and click the canvas — the context menu opens at
the click position.
2. On Android (or any touch device), long-press the canvas — the context
menu opens after the long-press.
3. Right-click on empty canvas — the context menu still opens at the
release position (existing behaviour).
4. Right-click + drag — the camera still pans without opening a menu
(existing behaviour).
5. Two-finger trackpad tap on macOS — the context menu still opens
(existing behaviour).

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

### Release notes

- Fix the context menu not opening on ctrl+click on macOS and long-press
on Android.

### Code changes

| Section   | LOC change |
| --------- | ---------- |
| Core code | +13 / -8   |

Made with [Cursor](https://cursor.com)

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../editor/src/lib/hooks/useCanvasEvents.ts   | 21 ++++++++++++-------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/packages/editor/src/lib/hooks/useCanvasEvents.ts b/packages/editor/src/lib/hooks/useCanvasEvents.ts
index 136237b81e25..24fb42650b54 100644
--- a/packages/editor/src/lib/hooks/useCanvasEvents.ts
+++ b/packages/editor/src/lib/hooks/useCanvasEvents.ts
@@ -169,14 +169,19 @@ export function useCanvasEvents() {
 				// menu opens on press.
 				if (!editor.options.rightClickPanning) return
 				// Synthetic events — our own dispatch from onPointerUp, or tests using
-				// fireEvent.contextMenu — pass through so Radix can open the menu. The real
-				// browser contextmenu is always suppressed: right-click behavior has
-				// already been decided by our pointer handling (either we dispatched a
-				// synthetic to open the menu at the release position, or we panned and
-				// don't want a menu at all).
-				if (e.nativeEvent.isTrusted) {
-					preventDefault(e)
-				}
+				// fireEvent.contextMenu — pass through so Radix can open the menu.
+				if (!e.nativeEvent.isTrusted) return
+				// Only suppress the native browser contextmenu when it follows a real
+				// right-click (button=2 with no ctrl modifier). For those, our pointer
+				// handling has already decided what to do (either we'll dispatch a
+				// synthetic contextmenu on pointerup to open the menu at the release
+				// position, or we panned and don't want a menu at all).
+				//
+				// Other contextmenu sources must reach Radix so the menu opens:
+				// - ctrl+click on macOS (button=0, or button=2 with ctrlKey=true)
+				// - long-press on touch devices (button=0, pointerType=touch)
+				if (e.button !== 2 || e.ctrlKey) return
+				preventDefault(e)
 			}
 
 			return {

From cf26b495516ce24ad8a932be4fbd5f6b5e2c6d8e Mon Sep 17 00:00:00 2001
From: Steve Ruiz <steveruizok@gmail.com>
Date: Wed, 6 May 2026 11:38:31 +0100
Subject: [PATCH 03/11] refactor(editor): drop redundant tl-overlays wrapper
 (#8773)

In order to clean up the canvas DOM after the OverlayUtil refactor
(#8633), this PR drops the now-redundant `tl-overlays` wrapper around
the canvas overlay element and folds the `tl-canvas__in-front` wrapper
(with its event handlers) into `InFrontOfTheCanvasWrapper` so it isn't
rendered when no `InFrontOfTheCanvas` component is registered.

Since the OverlayUtil rewrite, `CanvasOverlays` only renders a single
`<canvas class=\"tl-canvas-overlays\">`, and the wrapper's only
meaningful contribution was the `--tl-layer-canvas-overlays` z-index.
That now lives directly on `.tl-canvas-overlays`. The matching
`.tl-overlays` and `.tl-overlays__item` rules are removed, along with
`DefaultCursor.tsx`, which was the last consumer of `.tl-overlays__item`
and has been orphaned (not exported, not rendered) since the
EditorComponents `Cursor` slot was removed in #8633.

### Change type

- [x] `other`

### Test plan

1. Run \`yarn dev\` and confirm canvas overlays still render and
interact normally (selection, brush, snap lines, scribble, collaborator
cursors).
2. Confirm an example that registers an \`InFrontOfTheCanvas\` component
still renders inside the \`tl-canvas__in-front\` wrapper and receives
pointer/touch events.
3. Confirm overlay stacking order is unchanged (overlays sit above
shapes and HTML layers).

### Release notes

- None.

### Code changes

| Section   | LOC change |
| --------- | ---------- |
| Core code | +21 / -98  |
---
 .../TlaEditor/TlaEditorTopLeftPanel.tsx       |  4 +-
 packages/editor/editor.css                    | 21 +------
 .../default-components/DefaultCanvas.tsx      | 27 +++++----
 .../default-components/DefaultCursor.tsx      | 59 -------------------
 .../MainMenu/DefaultMainMenuContent.tsx       |  6 +-
 5 files changed, 18 insertions(+), 99 deletions(-)
 delete mode 100644 packages/editor/src/lib/components/default-components/DefaultCursor.tsx

diff --git a/apps/dotcom/client/src/tla/components/TlaEditor/TlaEditorTopLeftPanel.tsx b/apps/dotcom/client/src/tla/components/TlaEditor/TlaEditorTopLeftPanel.tsx
index 2ab7ce7470d2..6879461f4ee5 100644
--- a/apps/dotcom/client/src/tla/components/TlaEditor/TlaEditorTopLeftPanel.tsx
+++ b/apps/dotcom/client/src/tla/components/TlaEditor/TlaEditorTopLeftPanel.tsx
@@ -444,6 +444,7 @@ function TlaPreferencesGroup() {
 					<ToggleEdgeScrollingItem />
 					<ToggleDynamicSizeModeItem />
 					<TogglePasteAtCursorItem />
+					<ToggleDebugModeItem />
 				</TldrawUiMenuGroup>
 				<TldrawUiMenuGroup id="user-interface-submenus">
 					<ColorSchemeMenu />
@@ -451,9 +452,6 @@ function TlaPreferencesGroup() {
 					<AccessibilityMenu />
 					<InputModeMenu />
 				</TldrawUiMenuGroup>
-				<TldrawUiMenuGroup id="debug">
-					<ToggleDebugModeItem />
-				</TldrawUiMenuGroup>
 			</TldrawUiMenuSubmenu>
 			<LanguageMenu />
 			<KeyboardShortcutsMenuItem />
diff --git a/packages/editor/editor.css b/packages/editor/editor.css
index 98ad66801134..18eef884516e 100644
--- a/packages/editor/editor.css
+++ b/packages/editor/editor.css
@@ -317,26 +317,6 @@ input,
 	z-index: var(--tl-layer-canvas-shapes);
 }
 
-.tl-overlays {
-	position: absolute;
-	top: 0px;
-	left: 0px;
-	height: 100%;
-	width: 100%;
-	contain: strict;
-	pointer-events: none;
-	z-index: var(--tl-layer-canvas-overlays);
-}
-
-.tl-overlays__item {
-	position: absolute;
-	top: 0px;
-	left: 0px;
-	overflow: visible;
-	pointer-events: none;
-	transform-origin: top left;
-}
-
 .tl-svg-context {
 	position: absolute;
 	top: 0px;
@@ -963,6 +943,7 @@ input,
 	position: absolute;
 	inset: 0;
 	pointer-events: none;
+	z-index: var(--tl-layer-canvas-overlays);
 }
 
 /* ---------------------- Shape --------------------- */
diff --git a/packages/editor/src/lib/components/default-components/DefaultCanvas.tsx b/packages/editor/src/lib/components/default-components/DefaultCanvas.tsx
index 01098d842fbc..415c827e7131 100644
--- a/packages/editor/src/lib/components/default-components/DefaultCanvas.tsx
+++ b/packages/editor/src/lib/components/default-components/DefaultCanvas.tsx
@@ -155,29 +155,30 @@ export function DefaultCanvas({ className }: TLCanvasComponentProps) {
 					{SelectionBackground && <SelectionBackgroundWrapper />}
 					{hideShapes ? null : <ShapesLayer canvasRef={rCanvas} />}
 				</div>
-				<div className="tl-overlays">
-					<CanvasOverlays />
-				</div>
+				<CanvasOverlays />
 				<MovingCameraHitTestBlocker />
 			</div>
-			<div
-				className="tl-canvas__in-front"
-				onPointerDown={editor.markEventAsHandled}
-				onPointerUp={editor.markEventAsHandled}
-				onTouchStart={editor.markEventAsHandled}
-				onTouchEnd={editor.markEventAsHandled}
-			>
-				<InFrontOfTheCanvasWrapper />
-			</div>
+			<InFrontOfTheCanvasWrapper />
 			<MenuClickCapture />
 		</>
 	)
 }
 
 function InFrontOfTheCanvasWrapper() {
+	const editor = useEditor()
 	const { InFrontOfTheCanvas } = useEditorComponents()
 	if (!InFrontOfTheCanvas) return null
-	return <InFrontOfTheCanvas />
+	return (
+		<div
+			className="tl-canvas__in-front"
+			onPointerDown={editor.markEventAsHandled}
+			onPointerUp={editor.markEventAsHandled}
+			onTouchStart={editor.markEventAsHandled}
+			onTouchEnd={editor.markEventAsHandled}
+		>
+			<InFrontOfTheCanvas />
+		</div>
+	)
 }
 
 function GridWrapper() {
diff --git a/packages/editor/src/lib/components/default-components/DefaultCursor.tsx b/packages/editor/src/lib/components/default-components/DefaultCursor.tsx
deleted file mode 100644
index d1c68d55f38b..000000000000
--- a/packages/editor/src/lib/components/default-components/DefaultCursor.tsx
+++ /dev/null
@@ -1,59 +0,0 @@
-import { VecModel } from '@tldraw/tlschema'
-import classNames from 'classnames'
-import { memo, useRef } from 'react'
-import { useSharedSafeId } from '../../hooks/useSafeId'
-import { useTransform } from '../../hooks/useTransform'
-
-/** @public */
-export interface TLCursorProps {
-	userId: string
-	className?: string
-	point: VecModel | null
-	zoom: number
-	color?: string
-	name: string | null
-	chatMessage: string
-}
-
-/** @public @react */
-export const DefaultCursor = memo(function DefaultCursor({
-	className,
-	zoom,
-	point,
-	color,
-	name,
-	chatMessage,
-}: TLCursorProps) {
-	const rCursor = useRef<HTMLDivElement>(null)
-	useTransform(rCursor, point?.x, point?.y, 1 / zoom)
-
-	const cursorId = useSharedSafeId('cursor')
-
-	if (!point) return null
-
-	return (
-		<div ref={rCursor} className={classNames('tl-overlays__item', className)}>
-			<svg className="tl-cursor" aria-hidden="true">
-				<use href={`#${cursorId}`} color={color} />
-			</svg>
-			{chatMessage ? (
-				<>
-					{name && (
-						<div className="tl-nametag-title" style={{ color }}>
-							{name}
-						</div>
-					)}
-					<div className="tl-nametag-chat" style={{ backgroundColor: color }}>
-						{chatMessage}
-					</div>
-				</>
-			) : (
-				name && (
-					<div className="tl-nametag" style={{ backgroundColor: color }}>
-						{name}
-					</div>
-				)
-			)}
-		</div>
-	)
-})
diff --git a/packages/tldraw/src/lib/ui/components/MainMenu/DefaultMainMenuContent.tsx b/packages/tldraw/src/lib/ui/components/MainMenu/DefaultMainMenuContent.tsx
index b931a114e8c8..b199317c284f 100644
--- a/packages/tldraw/src/lib/ui/components/MainMenu/DefaultMainMenuContent.tsx
+++ b/packages/tldraw/src/lib/ui/components/MainMenu/DefaultMainMenuContent.tsx
@@ -163,14 +163,12 @@ export function PreferencesGroup() {
 					<ToggleEdgeScrollingItem />
 					<ToggleDynamicSizeModeItem />
 					<TogglePasteAtCursorItem />
+					<ToggleDebugModeItem />
 				</TldrawUiMenuGroup>
 				<TldrawUiMenuGroup id="user-interface-submenus">
-					<ColorSchemeMenu />
 					<AccessibilityMenu />
 					<InputModeMenu />
-				</TldrawUiMenuGroup>
-				<TldrawUiMenuGroup id="debug">
-					<ToggleDebugModeItem />
+					<ColorSchemeMenu />
 				</TldrawUiMenuGroup>
 			</TldrawUiMenuSubmenu>
 			<LanguageMenu />

From 2d31e495fdfcfeb1ef4cb42a4ffac871b523164f Mon Sep 17 00:00:00 2001
From: Steve Ruiz <steveruizok@gmail.com>
Date: Wed, 6 May 2026 11:39:14 +0100
Subject: [PATCH 04/11] docs: update README with missing starter kit and
 Node.js version (#8526)

In order to keep the top-level README accurate against the current repo
state, this PR adds the `Image pipeline` starter kit (which is already
shipped via `npm create tldraw` in
`packages/create-tldraw/src/templates.ts`) to the starter kits list, and
notes the required Node.js version (`^20.0.0`, per the `engines` field
in `package.json`) in the Local development section.

### Change type

- [x] `other`

### Test plan

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

### Code changes

| Section       | LOC change |
| ------------- | ---------- |
| Documentation | +2 / -1    |

Co-authored-by: Claude <noreply@anthropic.com>
---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c821c8b594df..3a71ee96a2ab 100644
--- a/README.md
+++ b/README.md
@@ -69,12 +69,13 @@ npx create-tldraw@latest
 - **Agent** — AI agents that read, interpret, and modify canvas content
 - **Workflow** — drag-and-drop node builder for automation pipelines, visual programming, and no-code platforms
 - **Chat** — canvas-powered AI chat where users sketch, annotate, and mark up images alongside conversations
+- **Image pipeline** — node-based builder for image generation pipelines
 - **Branching chat** — AI chat with visual branching, letting users explore and compare different conversation paths
 - **Shader** — WebGL shaders that respond to canvas interactions
 
 ## Local development
 
-The development server runs the examples app at `localhost:5420`. Clone the repo, then enable [corepack](https://nodejs.org/api/corepack.html) for the correct yarn version:
+The development server runs the examples app at `localhost:5420`. You'll need [Node.js](https://nodejs.org) `^20.0.0`. Clone the repo, then enable [corepack](https://nodejs.org/api/corepack.html) for the correct yarn version:
 
 ```bash
 npm i -g corepack

From f9947dae5989ff5158892c2d24e179df7ec9ad24 Mon Sep 17 00:00:00 2001
From: Steve Ruiz <steveruizok@gmail.com>
Date: Wed, 6 May 2026 11:39:50 +0100
Subject: [PATCH 05/11] feat(tldraw): add locale prop for setting UI language
 (#8462)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to let developers set the editor's UI language without
workarounds, this PR adds a `locale` prop to the `<Tldraw>` component.
Closes #6321.

Previously, setting the locale required configuring user preferences in
`onMount` (via `useTldrawUser` or `editor.user.updateUserPreferences`),
which caused a flash of the wrong language on first render. Now
developers can pass it declaratively:

```tsx
<Tldraw locale="fr" />
```

The locale is a top-level prop rather than an option in `TldrawOptions`,
keeping options focused on editor behavior configuration.

The priority chain for locale resolution is:
1. User's explicit locale preference (set via
`editor.user.updateUserPreferences`) — highest
2. `locale` prop on `<Tldraw>` — new
3. `navigator.languages` default — existing behavior

### Change type

- [x] `feature`

### Test plan

1. Render `<Tldraw locale="fr" />` — UI should appear in French
immediately with no flash of English
2. Render `<Tldraw />` without locale — behavior unchanged, uses
`navigator.languages`
3. Set `locale="fr"` then call `editor.user.updateUserPreferences({
locale: 'ja' })` — Japanese should take priority

- [x] Unit tests (existing UserPreferencesManager tests pass)

### Release notes

- Add `locale` prop to `<Tldraw>` for setting the UI language
declaratively via `<Tldraw locale="fr" />`, eliminating the flash of
wrong language on mount.

### API changes

- Added `TldrawBaseProps.locale: string | undefined` for declarative
locale configuration

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Core code       | +15 / -1   |
| Automated files | +1 / -0    |

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../sdk-features/internationalization.mdx     | 19 +++++++++++++++++++
 packages/tldraw/api-report.api.md             |  1 +
 packages/tldraw/src/lib/Tldraw.tsx            | 17 ++++++++++++++++-
 3 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/apps/docs/content/sdk-features/internationalization.mdx b/apps/docs/content/sdk-features/internationalization.mdx
index b641f2e5d8f7..c18e4bcaafa6 100644
--- a/apps/docs/content/sdk-features/internationalization.mdx
+++ b/apps/docs/content/sdk-features/internationalization.mdx
@@ -25,6 +25,25 @@ Tldraw's UI supports 50 languages out of the box, including right-to-left langua
 
 The user's locale is stored in [user preferences](/sdk-features/user-preferences). By default, tldraw detects the browser's language and selects the closest match from supported languages.
 
+The simplest way to set the locale is with the `locale` prop on the `Tldraw` component:
+
+```tsx
+import { Tldraw } from 'tldraw'
+import 'tldraw/tldraw.css'
+
+export default function App() {
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw locale="fr" />
+		</div>
+	)
+}
+```
+
+The `locale` prop takes priority over the browser's language preferences but can still be overridden by the user's explicit locale preference (e.g. via `editor.user.updateUserPreferences`).
+
+You can also set the locale imperatively after the editor mounts:
+
 ```tsx
 import { Tldraw } from 'tldraw'
 import 'tldraw/tldraw.css'
diff --git a/packages/tldraw/api-report.api.md b/packages/tldraw/api-report.api.md
index 9fa3e43aedfd..2f28c71aa7f1 100644
--- a/packages/tldraw/api-report.api.md
+++ b/packages/tldraw/api-report.api.md
@@ -4085,6 +4085,7 @@ export interface TldrawBaseProps extends TldrawUiProps, TldrawEditorBaseProps, T
     components?: TLComponents;
     // @deprecated
     embeds?: TLEmbedDefinition[];
+    locale?: string;
     // @deprecated
     textOptions?: TLTextOptions;
 }
diff --git a/packages/tldraw/src/lib/Tldraw.tsx b/packages/tldraw/src/lib/Tldraw.tsx
index c3e6834ef1c0..ba70db3a7934 100644
--- a/packages/tldraw/src/lib/Tldraw.tsx
+++ b/packages/tldraw/src/lib/Tldraw.tsx
@@ -97,6 +97,19 @@ export interface TldrawBaseProps
 	 * @deprecated Use `options.text` instead. This prop will be removed in a future release.
 	 */
 	textOptions?: TLTextOptions
+	/**
+	 * The locale to use for the editor's UI. When set, this takes priority over
+	 * both the browser's language preferences (`navigator.languages`) and the
+	 * user's locale preference (e.g. via
+	 * `editor.user.updateUserPreferences({ locale: '...' })`), giving the
+	 * application explicit control over the displayed language.
+	 *
+	 * @example
+	 * ```tsx
+	 * <Tldraw locale="fr" />
+	 * ```
+	 */
+	locale?: string
 }
 
 /** @public */
@@ -151,6 +164,7 @@ export function Tldraw(props: TldrawProps) {
 		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		embeds,
 		options,
+		locale,
 		// needs to be here for backwards compatibility with TldrawEditor
 		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		textOptions: _textOptions,
@@ -264,7 +278,8 @@ export function Tldraw(props: TldrawProps) {
 		<AssetUrlsProvider assetUrls={useDefaultUiAssetUrlsWithOverrides(rest.assetUrls)}>
 			<TldrawUiTranslationProvider
 				overrides={useMergedTranslationOverrides(rest.overrides)}
-				locale={rest.user?.userPreferences.get().locale ?? defaultUserPreferences.locale}
+				// If the locale prop is provided, then use that and assume it to be controlled
+				locale={locale ?? rest.user?.userPreferences.get().locale ?? defaultUserPreferences.locale}
 			>
 				<TldrawEditor
 					initialState="select"

From 149adb3a441172e97940c7593ec1a531f5f9e98d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mitja=20Bezen=C5=A1ek?= <mitja.bezensek@gmail.com>
Date: Wed, 6 May 2026 12:40:02 +0200
Subject: [PATCH 06/11] docs(sync): describe SQLite as primary persistence in
 template docs (#8751)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to reflect the current `sync-cloudflare` template
implementation, this PR updates the template README and the sync docs to
describe SQLite (via `DurableObjectSqliteSyncWrapper`) as the room-state
persistence mechanism. R2 in the template is only used for uploaded
assets (images, videos), not for room snapshots. Closes #8560.

Note: this is about the self-hosted template —
`apps/dotcom/sync-worker/` still writes R2 snapshots as a backup layer,
but that's not what these docs describe.

### Change type

- [x] `docs`

### Test plan

1. Read `templates/sync-cloudflare/README.md` and confirm the
persistence and deployment sections match the template's actual behavior
(SQLite for room state, R2 only for assets).
2. Read `apps/docs/content/docs/sync.mdx` Cloudflare-template section
and confirm SQLite is described as the room-state storage.

### Release notes

- Sync docs: clarify that the Cloudflare template persists room state to
durable object SQLite storage; R2 is only used for assets.
---
 apps/docs/content/docs/sync.mdx     |  4 ++--
 templates/sync-cloudflare/README.md | 22 +++++++++++-----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/apps/docs/content/docs/sync.mdx b/apps/docs/content/docs/sync.mdx
index 2857f54a1cda..05d279e6a4da 100644
--- a/apps/docs/content/docs/sync.mdx
+++ b/apps/docs/content/docs/sync.mdx
@@ -37,8 +37,8 @@ The best way to get started hosting your own backend is to clone and deploy [our
 
 It uses:
 
-- [Durable Objects](https://developers.cloudflare.com/durable-objects/) to provide a unique WebSocket server per room.
-- [R2](https://developers.cloudflare.com/r2/) to persist document snapshots and store large binary assets like images and videos.
+- [Durable Objects](https://developers.cloudflare.com/durable-objects/) to provide a unique WebSocket server per room. Room state is persisted automatically to the durable object's built-in SQLite storage.
+- [R2](https://developers.cloudflare.com/r2/) to store large binary assets like images and videos.
 
 There are some features that we have not provided and you might want to add yourself, such as authentication and authorization, rate limiting and size limiting for asset uploads, storing snapshots of documents over time for long-term history, and listing and searching for rooms.
 
diff --git a/templates/sync-cloudflare/README.md b/templates/sync-cloudflare/README.md
index 83b253ab53bc..c2fca79ed02b 100644
--- a/templates/sync-cloudflare/README.md
+++ b/templates/sync-cloudflare/README.md
@@ -7,8 +7,9 @@ This is a production-ready backend for [tldraw sync](https://tldraw.dev/docs/syn
   to be deployed to your own Cloudflare account.
 - Each whiteboard is synced via
   [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) to a [Cloudflare
-  Durable Object](https://developers.cloudflare.com/durable-objects/).
-- Whiteboards and any uploaded images/videos are stored in a [Cloudflare
+  Durable Object](https://developers.cloudflare.com/durable-objects/), which persists room state in
+  its built-in SQLite storage.
+- Uploaded images and videos are stored in a [Cloudflare
   R2](https://developers.cloudflare.com/r2/) bucket.
 - Although unrelated to tldraw sync, this server also includes a component to fetch link previews
   for URLs added to the canvas.
@@ -25,14 +26,13 @@ When a user opens a room, they connect via Workers to a durable object. Each dur
 its own miniature server. There's only ever one for each room, and all the users of that room
 connect to it. When a user makes a change to the drawing, it's sent via a websocket connection to
 the durable object for that room. The durable object applies the change to its in-memory copy of the
-document, and broadcasts the change via websockets to all other connected clients. On a regular
-schedule, the durable object persists its contents to an R2 bucket. When the last client leaves the
-room, the durable object will shut down.
+document, and broadcasts the change via websockets to all other connected clients. Room state is
+persisted automatically to the durable object's built-in SQLite storage, so it survives restarts
+and hibernation. When the last client leaves the room, the durable object will shut down.
 
 Static assets like images and videos are too big to be synced via websockets and a durable object.
-Instead, they're uploaded to workers which store them in the same R2 bucket as the rooms. When
-they're downloaded, they're cached on cloudflare's edge network to reduce costs and make serving
-them faster.
+Instead, they're uploaded to workers which store them in an R2 bucket. When they're downloaded,
+they're cached on cloudflare's edge network to reduce costs and make serving them faster.
 
 ## Development
 
@@ -49,7 +49,7 @@ The backend worker is under [`worker`](./worker/), and is split across several f
 - **[`worker/TldrawDurableObject.ts`](./worker/TldrawDurableObject.ts):** the sync durable object.
   An instance of this is created for every active room. This exposes a
   [`TLSocketRoom`](https://tldraw.dev/reference/sync-core/TLSocketRoom) over websockets, and
-  periodically saves room data to R2.
+  persists room state to the durable object's built-in SQLite storage.
 - **[`worker/assetUploads.ts`](./worker/assetUploads.ts):** uploads, downloads, and caching for
   static assets like images and videos.
 - **[`worker/bookmarkUnfurling.ts`](./worker/bookmarkUnfurling.ts):** extract URL metadata for bookmark shapes.
@@ -86,8 +86,8 @@ of these files to point at your new `wrangler dev` server.
 ## Deployment
 
 To deploy this example, you'll need to create a cloudflare account and create an R2 bucket to store
-your data. Update `bucket_name = 'tldraw-content'` in [`wrangler.toml`](./wrangler.toml) with the
-name of your new bucket.
+uploaded images and videos. Update `bucket_name = 'tldraw-content'` in
+[`wrangler.toml`](./wrangler.toml) with the name of your new bucket.
 
 To actually deploy the app, first create a production build using `yarn build`. Then, run `yarn
 wrangler deploy`. This will deploy the backend worker along with the frontend app to cloudflare.

From 4eede505b0c944b288b8a0fd6598c0f89f76a56a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mitja=20Bezen=C5=A1ek?= <mitja.bezensek@gmail.com>
Date: Wed, 6 May 2026 12:50:47 +0200
Subject: [PATCH 07/11] example: tower defense game showcasing OverlayUtil
 (#8762)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to exercise the new `OverlayUtil` system end-to-end under
animation load, this PR adds a tower-defense mini-game example that uses
overlays for everything except the towers themselves. Towers are real
geo shapes; the path, enemies, projectiles, range indicators, placement
preview, hit explosions, and per-tower upgrade button are all
`OverlayUtil` subclasses. Builds on #8633.

The example covers most of the OverlayUtil surface: `isActive`
reactivity, `getOverlays` driven by `@tldraw/state` atoms ticked from
`editor.on('tick')`, `getGeometry` / `getOverlayAtPoint` hit testing,
`getCursor` swaps, `onPointerDown` for placement and upgrades, custom
zIndex layering, and shape↔overlay reactivity (towers as locked geo
shapes feed projectile spawns and upgrade levels via `shape.meta`).

### How to play

- Pick a tower from the toolbar (or press `1` / `2` / `3`), then click
the canvas to place it.
  - Triangle = Archer (50g, fast, low damage)
  - Rectangle = Cannon (120g, slow, high damage)
  - Ellipse = Magic (80g, medium, AOE)
- Hover a placed tower to see its range; click the `+` in its center to
upgrade (cost scales 60% per level, max 4 levels). Upgrades change the
shape's `fill` / `color` so the level is readable at a glance.
- Click an enemy to chip-damage it for free. Enemies that reach the end
cost a life.
- `Esc` cancels placement, `Space` restarts.

### Overlays added by the example

| Util | zIndex | Role |
| --- | --- | --- |
| `PathOverlayUtil` | 50 | Decorative enemy path |
| `TowerRangeOverlayUtil` | 100 | Hover-driven range ring on placed
towers |
| `PlacementPreviewOverlayUtil` | 150 | Ghost shape + range circle at
the cursor while a tower is armed; click-to-place via `onPointerDown` |
| `EnemyOverlayUtil` | 200 | Animated enemies with HP bar; hit-test +
click-to-damage |
| `ExplosionOverlayUtil` | 230 | Fading ring on Magic AOE impact |
| `ProjectileOverlayUtil` | 250 | Arrows / rocks / orbs in flight |
| `UpgradeButtonOverlayUtil` | 260 | Per-tower upgrade `+` button; click
via `onPointerDown` |

### Notes for reviewers

- Placement clicks and upgrade clicks route through
`OverlayUtil.onPointerDown` — no DOM intercept. Locked-shape clicks
correctly fall through to overlays because `select.idle.onPointerDown`
checks `getOverlayAtPoint` before the locked-shape skip.
- Upgrade and restart paths wrap `editor.updateShape` /
`editor.deleteShapes` in `editor.run(..., { ignoreShapeLock: true })`
because the runtime silently skips locked shapes otherwise.
- Per-tick shape walks (`UpgradeButtonOverlayUtil._candidates`,
`TowerRangeOverlayUtil._hoveredTowers`) are memoised with `computed()`
so a mousemove storm only re-runs the cheap pointer filter, not the
bounds resolution pass.
- Sounds are synthesized with the Web Audio API (no asset loading) —
fire tones per projectile kind and a small upgrade chime.

### Change type

- [x] `feature`

### Test plan

1. `yarn dev` and open `localhost:5420/use-cases/tower-defense`.
2. Place each tower type via the toolbar buttons and via `1` / `2` / `3`
shortcuts.
3. Confirm the placement preview shows ghost shape + range while a tower
is armed and disappears when you can't afford it.
4. Hover a placed tower → range ring; click the central `+` → tower's
color/fill changes per level and the chime plays.
5. Magic projectile impact → fading explosion ring + AOE damage to
nearby enemies.
6. Click an enemy → chip damage; hover an enemy → HP readout above its
HP bar.
7. Let enemies through → lives drop, game-over state appears, restart
via button or `Space` clears all shapes and resets gold/lives/score/wave
timer.
8. Toggle dark/light mode → overlay strokes and fills update.

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

### Release notes

- Add a tower-defense example under `examples/use-cases/tower-defense`
showcasing the new `OverlayUtil` system.
---
 .../use-cases/tower-defense/README.md         |  16 +
 .../tower-defense/TowerDefenseExample.tsx     | 291 ++++++++++++++++++
 .../use-cases/tower-defense/enemy-config.ts   |  59 ++++
 .../use-cases/tower-defense/game-loop.ts      | 278 +++++++++++++++++
 .../use-cases/tower-defense/game-state.ts     | 107 +++++++
 .../overlays/EnemyOverlayUtil.ts              | 143 +++++++++
 .../overlays/ExplosionOverlayUtil.ts          |  62 ++++
 .../tower-defense/overlays/PathOverlayUtil.ts |  47 +++
 .../overlays/PlacementPreviewOverlayUtil.ts   | 116 +++++++
 .../overlays/ProjectileOverlayUtil.ts         |  82 +++++
 .../overlays/TowerRangeOverlayUtil.ts         |  79 +++++
 .../overlays/UpgradeButtonOverlayUtil.ts      | 192 ++++++++++++
 .../examples/use-cases/tower-defense/path.ts  |  63 ++++
 .../use-cases/tower-defense/sounds.ts         |  92 ++++++
 .../use-cases/tower-defense/tower-config.ts   |  92 ++++++
 .../use-cases/tower-defense/tower-defense.css | 131 ++++++++
 16 files changed, 1850 insertions(+)
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/README.md
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/TowerDefenseExample.tsx
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/enemy-config.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/game-loop.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/game-state.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/EnemyOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/ExplosionOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/PathOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/PlacementPreviewOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/ProjectileOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/TowerRangeOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/overlays/UpgradeButtonOverlayUtil.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/path.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/sounds.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/tower-config.ts
 create mode 100644 apps/examples/src/examples/use-cases/tower-defense/tower-defense.css

diff --git a/apps/examples/src/examples/use-cases/tower-defense/README.md b/apps/examples/src/examples/use-cases/tower-defense/README.md
new file mode 100644
index 000000000000..4d6cefa06d95
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/README.md
@@ -0,0 +1,16 @@
+---
+title: Tower defense
+component: ./TowerDefenseExample.tsx
+priority: 5
+keywords: [overlay, overlayutil, canvas, animation, game, hit testing, raf, tick]
+---
+
+A tiny tower defense game built on the OverlayUtil system.
+
+---
+
+Draw triangle, rectangle, or ellipse geo shapes onto the canvas to place towers — each geo type maps to a different tower with its own range, fire rate, damage, and projectile. Enemies follow a fixed path; click an enemy to deal damage manually.
+
+The game's path, enemies, projectiles, and tower range indicator all render through `OverlayUtil` subclasses. The game state lives in `@tldraw/state` atoms read inside `getOverlays()`, so when the game loop ticks the atoms, every overlay redraws reactively. Hit-testing for clicks on enemies uses `getGeometry()` and the built-in `editor.overlays.getOverlayAtPoint` path; `getCursor()` swaps to a crosshair on hover and `onPointerDown()` applies damage.
+
+The game loop is driven by the editor's `tick` event, which fires once per frame with the elapsed delta in milliseconds. Towers are real geo shapes that the side-effects layer locks on creation so they can't be moved during play.
diff --git a/apps/examples/src/examples/use-cases/tower-defense/TowerDefenseExample.tsx b/apps/examples/src/examples/use-cases/tower-defense/TowerDefenseExample.tsx
new file mode 100644
index 000000000000..c069dcc67ee3
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/TowerDefenseExample.tsx
@@ -0,0 +1,291 @@
+import { useCallback, useEffect } from 'react'
+import {
+	Box,
+	Editor,
+	TLAnyOverlayUtilConstructor,
+	TLUiComponents,
+	Tldraw,
+	defaultOverlayUtils,
+	useEditor,
+	useValue,
+} from 'tldraw'
+import 'tldraw/tldraw.css'
+import { resetSpawnTimer, runGameTick } from './game-loop'
+import {
+	enemies$,
+	gameOver$,
+	gold$,
+	lives$,
+	placingTower$,
+	projectiles$,
+	resetGameState,
+	score$,
+} from './game-state'
+import { EnemyOverlayUtil } from './overlays/EnemyOverlayUtil'
+import { ExplosionOverlayUtil } from './overlays/ExplosionOverlayUtil'
+import { PathOverlayUtil } from './overlays/PathOverlayUtil'
+import { PlacementPreviewOverlayUtil } from './overlays/PlacementPreviewOverlayUtil'
+import { ProjectileOverlayUtil } from './overlays/ProjectileOverlayUtil'
+import { TowerRangeOverlayUtil } from './overlays/TowerRangeOverlayUtil'
+import { UpgradeButtonOverlayUtil } from './overlays/UpgradeButtonOverlayUtil'
+import { TOWER_GEOS, TOWER_STATS_BY_GEO, TowerGeo } from './tower-config'
+import './tower-defense.css'
+
+const overlayUtils: TLAnyOverlayUtilConstructor[] = [
+	...defaultOverlayUtils,
+	PathOverlayUtil,
+	TowerRangeOverlayUtil,
+	PlacementPreviewOverlayUtil,
+	EnemyOverlayUtil,
+	ProjectileOverlayUtil,
+	ExplosionOverlayUtil,
+	UpgradeButtonOverlayUtil,
+]
+
+function pickTower(geo: TowerGeo) {
+	const cost = TOWER_STATS_BY_GEO[geo].cost
+	// Refuse to arm a tower the player can't afford so the preview / placement
+	// flow only kicks in when a click would actually result in a tower.
+	if (gold$.get() < cost) return
+	placingTower$.set(geo)
+}
+
+function pickSelect(editor: Editor) {
+	placingTower$.set(null)
+	editor.setCurrentTool('select')
+}
+
+function restartGame(editor: Editor) {
+	resetGameState()
+	resetSpawnTimer()
+	placingTower$.set(null)
+	// Just nuke everything on the page — towers are the only thing the user
+	// can produce here, and starting fresh shouldn't leave any stragglers.
+	const allShapeIds = editor.getCurrentPageShapes().map((s) => s.id)
+	if (allShapeIds.length === 0) return
+	editor.run(() => editor.deleteShapes(allShapeIds), { ignoreShapeLock: true })
+}
+
+function GameRunner() {
+	const editor = useEditor()
+
+	useEffect(() => {
+		const onTick = (elapsedMs: number) => {
+			// Clamp on tab-resume; tldraw emits a single big elapsed when the tab
+			// has been idle, which would otherwise teleport enemies.
+			const dt = Math.min(60, elapsedMs)
+			runGameTick(editor, dt)
+		}
+		editor.on('tick', onTick)
+
+		// Keyboard: 1/2/3 arm a tower, Esc selects, Space restarts.
+		const onKeyDown = (e: KeyboardEvent) => {
+			if (e.metaKey || e.ctrlKey || e.altKey) return
+			const target = e.target as HTMLElement | null
+			if (target?.matches('input, textarea, [contenteditable="true"]')) return
+			if (e.key === '1') pickTower('triangle')
+			else if (e.key === '2') pickTower('rectangle')
+			else if (e.key === '3') pickTower('ellipse')
+			else if (e.key === 'Escape') pickSelect(editor)
+			else if (e.key === ' ') {
+				e.preventDefault()
+				restartGame(editor)
+			}
+		}
+		window.addEventListener('keydown', onKeyDown)
+
+		return () => {
+			editor.off('tick', onTick)
+			window.removeEventListener('keydown', onKeyDown)
+			placingTower$.set(null)
+		}
+	}, [editor])
+
+	return null
+}
+
+function GameToolbar() {
+	const editor = useEditor()
+	const placingGeo = useValue('placingGeo', () => placingTower$.get(), [])
+	const gold = useValue('gold', () => gold$.get(), [])
+
+	const onPickSelect = useCallback(() => pickSelect(editor), [editor])
+
+	return (
+		<div className="td-toolbar">
+			<button
+				className={'td-toolbar__btn' + (placingGeo === null ? ' is-active' : '')}
+				onClick={onPickSelect}
+				title="Select (Esc)"
+			>
+				<SelectGlyph />
+				<span className="td-toolbar__label">Select</span>
+				<span className="td-toolbar__cost">
+					<kbd>esc</kbd>
+				</span>
+			</button>
+			{TOWER_GEOS.map((geo, i) => {
+				const stats = TOWER_STATS_BY_GEO[geo]
+				const isActive = placingGeo === geo
+				const canAfford = gold >= stats.cost
+				const cls =
+					'td-toolbar__btn' + (isActive ? ' is-active' : '') + (canAfford ? '' : ' is-disabled')
+				return (
+					<button
+						key={geo}
+						className={cls}
+						onClick={() => canAfford && pickTower(geo)}
+						disabled={!canAfford}
+						title={`${stats.label} (${geo}) — ${stats.cost} gold — press ${i + 1}`}
+					>
+						<TowerGlyph geo={geo} />
+						<span className="td-toolbar__label">{stats.label}</span>
+						<span className="td-toolbar__cost">
+							{stats.cost}g · <kbd>{i + 1}</kbd>
+						</span>
+					</button>
+				)
+			})}
+		</div>
+	)
+}
+
+function SelectGlyph() {
+	return (
+		<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
+			<path
+				d="M4 3 L4 15 L7.5 12 L9.7 17 L11.5 16.2 L9.3 11.2 L14 11 Z"
+				fill="currentColor"
+				stroke="currentColor"
+				strokeWidth="1"
+				strokeLinejoin="round"
+			/>
+		</svg>
+	)
+}
+
+function TowerGlyph({ geo }: { geo: TowerGeo }) {
+	const stroke = 'currentColor'
+	if (geo === 'triangle') {
+		return (
+			<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
+				<polygon points="10,2 18,18 2,18" fill="none" stroke={stroke} strokeWidth="2" />
+			</svg>
+		)
+	}
+	if (geo === 'rectangle') {
+		return (
+			<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
+				<rect x="2" y="4" width="16" height="12" fill="none" stroke={stroke} strokeWidth="2" />
+			</svg>
+		)
+	}
+	return (
+		<svg width="20" height="20" viewBox="0 0 20 20" aria-hidden>
+			<ellipse cx="10" cy="10" rx="8" ry="6" fill="none" stroke={stroke} strokeWidth="2" />
+		</svg>
+	)
+}
+
+function HUD() {
+	const editor = useEditor()
+	const score = useValue('score', () => score$.get(), [])
+	const gold = useValue('gold', () => gold$.get(), [])
+	const lives = useValue('lives', () => lives$.get(), [])
+	const enemyCount = useValue('enemies', () => enemies$.get().length, [])
+	const projectileCount = useValue('projectiles', () => projectiles$.get().length, [])
+	const gameOver = useValue('gameOver', () => gameOver$.get(), [])
+
+	const onRestart = useCallback(() => restartGame(editor), [editor])
+
+	return (
+		<div className="td-hud">
+			<div className="td-hud__row">
+				<span>
+					Gold <strong>{gold}</strong>
+				</span>
+				<span>
+					Score <strong>{score}</strong>
+				</span>
+				<span>
+					Lives <strong>{lives}</strong>
+				</span>
+				<span>
+					Enemies <strong>{enemyCount}</strong>
+				</span>
+				<span>
+					Shots <strong>{projectileCount}</strong>
+				</span>
+				<button className="td-hud__btn" onClick={onRestart}>
+					Restart
+				</button>
+			</div>
+			<div className="td-hud__hint">
+				Pick a tower from the toolbar (or press <kbd>1</kbd>/<kbd>2</kbd>/<kbd>3</kbd>), then click
+				the canvas to place it. Each tower costs gold; kill enemies to earn more. Magic blasts deal
+				area damage. Click an enemy to chip damage for free. Press <kbd>space</kbd> to restart.
+			</div>
+			{gameOver && <div className="td-hud__gameover">Game over — press Restart</div>}
+		</div>
+	)
+}
+
+const components: Required<TLUiComponents> = {
+	TopPanel: HUD,
+	Toolbar: GameToolbar,
+	ContextMenu: null,
+	ActionsMenu: null,
+	HelpMenu: null,
+	ZoomMenu: null,
+	MainMenu: null,
+	Minimap: null,
+	StylePanel: null,
+	PageMenu: null,
+	NavigationPanel: null,
+	KeyboardShortcutsDialog: null,
+	QuickActions: null,
+	HelperButtons: null,
+	DebugPanel: null,
+	DebugMenu: null,
+	SharePanel: null,
+	MenuPanel: null,
+	CursorChatBubble: null,
+	RichTextToolbar: null,
+	ImageToolbar: null,
+	VideoToolbar: null,
+	Dialogs: null,
+	Toasts: null,
+	A11y: null,
+	FollowingIndicator: null,
+	PeopleMenu: null,
+	PeopleMenuAvatar: null,
+	PeopleMenuItem: null,
+	PeopleMenuFacePile: null,
+	UserPresenceEditor: null,
+}
+
+function onEditorMount(editor: Editor) {
+	resetGameState()
+	resetSpawnTimer()
+	editor.zoomToBounds(new Box(-300, 0, 1700, 700), { immediate: true })
+}
+
+// Disable the built-in double-click-to-create-text behavior — there's no text
+// shape in this example and a stray double-click while clearing enemies would
+// otherwise drop a text shape on the canvas.
+const tldrawOptions = { createTextOnCanvasDoubleClick: false }
+
+export default function TowerDefenseExample() {
+	return (
+		<div className="tldraw__editor">
+			<Tldraw
+				overlayUtils={overlayUtils}
+				components={components}
+				options={tldrawOptions}
+				onMount={onEditorMount}
+			>
+				<GameRunner />
+			</Tldraw>
+		</div>
+	)
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/enemy-config.ts b/apps/examples/src/examples/use-cases/tower-defense/enemy-config.ts
new file mode 100644
index 000000000000..e0c84824dbb4
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/enemy-config.ts
@@ -0,0 +1,59 @@
+// Enemy archetypes. Each carries its own multipliers and visual identity so
+// later waves can mix tougher/faster targets and the overlay layer has more
+// to render than uniform circles.
+
+export type EnemyType = 'grunt' | 'runner' | 'brute'
+
+export interface EnemyConfig {
+	label: string
+	hpMultiplier: number
+	speedMultiplier: number
+	radius: number
+	bountyMultiplier: number
+	bodyColor: string
+	ringColor: string
+}
+
+export const ENEMY_CONFIG: Record<EnemyType, EnemyConfig> = {
+	grunt: {
+		label: 'Grunt',
+		hpMultiplier: 1,
+		speedMultiplier: 1,
+		radius: 18,
+		bountyMultiplier: 1,
+		bodyColor: '#c84',
+		ringColor: '#000',
+	},
+	runner: {
+		label: 'Runner',
+		hpMultiplier: 0.55,
+		speedMultiplier: 1.9,
+		radius: 13,
+		bountyMultiplier: 1.4,
+		bodyColor: '#3aa',
+		ringColor: '#055',
+	},
+	brute: {
+		label: 'Brute',
+		hpMultiplier: 3.2,
+		speedMultiplier: 0.62,
+		radius: 26,
+		bountyMultiplier: 2.6,
+		bodyColor: '#735',
+		ringColor: '#220',
+	},
+}
+
+// Weighted spawn picker: the longer the game runs, the more often runners and
+// brutes appear. Returns an enemy type.
+export function pickEnemyType(elapsedMs: number): EnemyType {
+	const t = Math.min(1, elapsedMs / 60_000)
+	const wGrunt = Math.max(0.2, 1 - t)
+	const wRunner = 0.3 + 0.4 * t
+	const wBrute = 0.05 + 0.5 * t
+	const total = wGrunt + wRunner + wBrute
+	const r = Math.random() * total
+	if (r < wGrunt) return 'grunt'
+	if (r < wGrunt + wRunner) return 'runner'
+	return 'brute'
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/game-loop.ts b/apps/examples/src/examples/use-cases/tower-defense/game-loop.ts
new file mode 100644
index 000000000000..fe78c6de7082
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/game-loop.ts
@@ -0,0 +1,278 @@
+import { Editor, TLGeoShape } from 'tldraw'
+import { ENEMY_CONFIG, pickEnemyType } from './enemy-config'
+import {
+	Enemy,
+	Explosion,
+	Projectile,
+	elapsedMs$,
+	enemies$,
+	explosions$,
+	gainBounty,
+	gameOver$,
+	lives$,
+	nextEnemyId,
+	nextExplosionId,
+	nextProjectileId,
+	projectiles$,
+	towerCooldowns,
+} from './game-state'
+import { PATH_LENGTH, getPositionAtDistance } from './path'
+import { playFireSound } from './sounds'
+import { getScaledStats, getTowerLevel, getTowerStats } from './tower-config'
+
+const SPAWN_BASE_INTERVAL_MS = 1400
+const SPAWN_RAMP_RATE = 0.00004 // shaves spawn interval over time
+const SPAWN_INTERVAL_FLOOR_MS = 350
+const ENEMY_BASE_HP = 50
+const ENEMY_HP_RAMP = 0.025 // per second of game time
+const ENEMY_BASE_SPEED = 65 // page units / sec
+const ENEMY_BASE_BOUNTY = 5
+const PROJECTILE_MAX_AGE_MS = 4000
+const MAGIC_AOE_RADIUS = 60
+// Magic projectiles slow enemies they hit for this long, scaling speed by
+// MAGIC_SLOW_FACTOR until the timer expires.
+const MAGIC_SLOW_DURATION_MS = 1500
+const MAGIC_SLOW_FACTOR = 0.4
+
+let lastSpawnAt = 0
+
+export function resetSpawnTimer() {
+	lastSpawnAt = 0
+}
+
+export function runGameTick(editor: Editor, dtMs: number) {
+	if (gameOver$.get()) return
+	const now = elapsedMs$.get() + dtMs
+	elapsedMs$.set(now)
+	const dt = dtMs / 1000
+
+	maybeSpawn(now)
+	moveEnemies(dt, now)
+	fireTowers(editor, now)
+	moveProjectiles(dt, dtMs)
+	resolveHits()
+	tickExplosions(dtMs)
+	checkGameOver()
+}
+
+const EXPLOSION_DURATION_MS = 320
+
+function spawnExplosion(x: number, y: number, radius: number) {
+	const exp: Explosion = {
+		id: nextExplosionId(),
+		x,
+		y,
+		radius,
+		ageMs: 0,
+		maxAgeMs: EXPLOSION_DURATION_MS,
+	}
+	explosions$.update((list) => [...list, exp])
+}
+
+function tickExplosions(dtMs: number) {
+	const list = explosions$.get()
+	if (list.length === 0) return
+	const next: Explosion[] = []
+	for (const e of list) {
+		const ageMs = e.ageMs + dtMs
+		if (ageMs >= e.maxAgeMs) continue
+		next.push({ ...e, ageMs })
+	}
+	explosions$.set(next)
+}
+
+function maybeSpawn(now: number) {
+	const interval = Math.max(
+		SPAWN_INTERVAL_FLOOR_MS,
+		SPAWN_BASE_INTERVAL_MS - now * SPAWN_RAMP_RATE * SPAWN_BASE_INTERVAL_MS
+	)
+	if (now - lastSpawnAt < interval) return
+	lastSpawnAt = now
+	const type = pickEnemyType(now)
+	const cfg = ENEMY_CONFIG[type]
+	const hpScale = 1 + (now / 1000) * ENEMY_HP_RAMP
+	const maxHp = Math.round(ENEMY_BASE_HP * hpScale * cfg.hpMultiplier)
+	const bounty = Math.round((ENEMY_BASE_BOUNTY + maxHp / 10) * cfg.bountyMultiplier)
+	const enemy: Enemy = {
+		id: nextEnemyId(),
+		type,
+		distance: 0,
+		hp: maxHp,
+		maxHp,
+		speed: (ENEMY_BASE_SPEED + Math.random() * 25) * cfg.speedMultiplier,
+		radius: cfg.radius,
+		bounty,
+		slowedUntilMs: 0,
+	}
+	enemies$.update((list) => [...list, enemy])
+}
+
+function moveEnemies(dt: number, now: number) {
+	const enemies = enemies$.get()
+	if (enemies.length === 0) return
+	const next: Enemy[] = []
+	let leaks = 0
+	for (const e of enemies) {
+		const isSlowed = e.slowedUntilMs > now
+		const speed = isSlowed ? e.speed * MAGIC_SLOW_FACTOR : e.speed
+		const distance = e.distance + speed * dt
+		if (distance >= PATH_LENGTH) {
+			leaks++
+			continue
+		}
+		next.push({ ...e, distance })
+	}
+	if (leaks > 0) lives$.update((l) => Math.max(0, l - leaks))
+	enemies$.set(next)
+}
+
+function fireTowers(editor: Editor, now: number) {
+	const enemies = enemies$.get()
+	if (enemies.length === 0) return
+	const shapes = editor.getCurrentPageShapes()
+	for (const shape of shapes) {
+		if (shape.type !== 'geo') continue
+		const baseStats = getTowerStats((shape as TLGeoShape).props.geo)
+		if (!baseStats) continue
+		const stats = getScaledStats(baseStats, getTowerLevel(shape))
+		const cooldown = towerCooldowns.get(shape.id)
+		if (cooldown && now - cooldown.lastFiredAt < stats.fireRateMs) continue
+		const bounds = editor.getShapePageBounds(shape.id)
+		if (!bounds) continue
+		const cx = bounds.center.x
+		const cy = bounds.center.y
+		// Pick the enemy closest to the end of the path within range.
+		let target: Enemy | null = null
+		let targetPos = { x: 0, y: 0 }
+		let bestProgress = -1
+		for (const enemy of enemies) {
+			const pos = getPositionAtDistance(enemy.distance)
+			const dx = pos.x - cx
+			const dy = pos.y - cy
+			if (dx * dx + dy * dy > stats.range * stats.range) continue
+			if (enemy.distance > bestProgress) {
+				bestProgress = enemy.distance
+				target = enemy
+				targetPos = pos
+			}
+		}
+		if (!target) continue
+		const dx = targetPos.x - cx
+		const dy = targetPos.y - cy
+		const dist = Math.hypot(dx, dy) || 1
+		const projectile: Projectile = {
+			id: nextProjectileId(),
+			x: cx,
+			y: cy,
+			vx: (dx / dist) * stats.projectileSpeed,
+			vy: (dy / dist) * stats.projectileSpeed,
+			damage: stats.damage,
+			kind: stats.projectileKind,
+			targetEnemyId: target.id,
+			ageMs: 0,
+		}
+		projectiles$.update((list) => [...list, projectile])
+		towerCooldowns.set(shape.id, { lastFiredAt: now })
+		playFireSound(stats.projectileKind)
+	}
+}
+
+function moveProjectiles(dt: number, dtMs: number) {
+	const list = projectiles$.get()
+	if (list.length === 0) return
+	const next: Projectile[] = []
+	for (const p of list) {
+		const ageMs = p.ageMs + dtMs
+		if (ageMs > PROJECTILE_MAX_AGE_MS) continue
+		next.push({ ...p, x: p.x + p.vx * dt, y: p.y + p.vy * dt, ageMs })
+	}
+	projectiles$.set(next)
+}
+
+function resolveHits() {
+	const projectiles = projectiles$.get()
+	if (projectiles.length === 0) return
+	const enemies = enemies$.get()
+	if (enemies.length === 0) {
+		// Projectiles whose targets vanished can keep flying until expiry.
+		return
+	}
+	const now = elapsedMs$.get()
+	const enemyById = new Map<number, Enemy>()
+	for (const e of enemies) enemyById.set(e.id, e)
+
+	const survivingProjectiles: Projectile[] = []
+	const damageByEnemyId = new Map<number, number>()
+	const slowedEnemyIds = new Set<number>()
+	for (const p of projectiles) {
+		// Use current position of the original target if still alive; otherwise
+		// look for any nearby enemy to make impacts feel responsive.
+		const target = enemyById.get(p.targetEnemyId)
+		let hit: Enemy | null = null
+		if (target) {
+			const pos = getPositionAtDistance(target.distance)
+			if (Math.hypot(p.x - pos.x, p.y - pos.y) <= target.radius) hit = target
+		}
+		if (!hit) {
+			for (const e of enemies) {
+				const pos = getPositionAtDistance(e.distance)
+				if (Math.hypot(p.x - pos.x, p.y - pos.y) <= e.radius) {
+					hit = e
+					break
+				}
+			}
+		}
+		if (hit) {
+			if (p.kind === 'orb') {
+				// Magic projectiles explode on impact: damage and slow every
+				// enemy in the AOE, plus a transient ring overlay.
+				spawnExplosion(p.x, p.y, MAGIC_AOE_RADIUS)
+				for (const e of enemies) {
+					const pos = getPositionAtDistance(e.distance)
+					if (Math.hypot(p.x - pos.x, p.y - pos.y) <= MAGIC_AOE_RADIUS + e.radius) {
+						damageByEnemyId.set(e.id, (damageByEnemyId.get(e.id) ?? 0) + p.damage)
+						slowedEnemyIds.add(e.id)
+					}
+				}
+			} else {
+				damageByEnemyId.set(hit.id, (damageByEnemyId.get(hit.id) ?? 0) + p.damage)
+			}
+		} else {
+			survivingProjectiles.push(p)
+		}
+	}
+	if (survivingProjectiles.length !== projectiles.length) {
+		projectiles$.set(survivingProjectiles)
+	}
+	if (damageByEnemyId.size === 0 && slowedEnemyIds.size === 0) return
+
+	let bountyGained = 0
+	const slowExpiry = now + MAGIC_SLOW_DURATION_MS
+	const nextEnemies: Enemy[] = []
+	for (const e of enemies) {
+		const dmg = damageByEnemyId.get(e.id) ?? 0
+		const slowed = slowedEnemyIds.has(e.id)
+		if (dmg === 0 && !slowed) {
+			nextEnemies.push(e)
+			continue
+		}
+		const hp = e.hp - dmg
+		if (hp <= 0) {
+			bountyGained += e.bounty
+			continue
+		}
+		nextEnemies.push({
+			...e,
+			hp,
+			// Slows refresh — multiple magic hits keep the effect alive rather
+			// than stacking duration.
+			slowedUntilMs: slowed ? Math.max(e.slowedUntilMs, slowExpiry) : e.slowedUntilMs,
+		})
+	}
+	enemies$.set(nextEnemies)
+	if (bountyGained > 0) gainBounty(bountyGained)
+}
+
+function checkGameOver() {
+	if (lives$.get() <= 0) gameOver$.set(true)
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/game-state.ts b/apps/examples/src/examples/use-cases/tower-defense/game-state.ts
new file mode 100644
index 000000000000..a9b97e97b49f
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/game-state.ts
@@ -0,0 +1,107 @@
+import { atom } from 'tldraw'
+import { EnemyType } from './enemy-config'
+import { ProjectileKind, TowerGeo } from './tower-config'
+
+export interface Enemy {
+	id: number
+	type: EnemyType
+	distance: number
+	hp: number
+	maxHp: number
+	speed: number
+	radius: number
+	bounty: number
+	// Absolute elapsedMs at which any active slow ends. 0 = not slowed.
+	slowedUntilMs: number
+}
+
+export interface Projectile {
+	id: number
+	x: number
+	y: number
+	vx: number
+	vy: number
+	damage: number
+	kind: ProjectileKind
+	targetEnemyId: number
+	ageMs: number
+}
+
+export interface TowerCooldown {
+	lastFiredAt: number
+}
+
+export interface Explosion {
+	id: number
+	x: number
+	y: number
+	radius: number
+	ageMs: number
+	maxAgeMs: number
+}
+
+export const STARTING_GOLD = 100
+export const STARTING_LIVES = 20
+
+export const enemies$ = atom<Enemy[]>('enemies', [])
+export const projectiles$ = atom<Projectile[]>('projectiles', [])
+export const explosions$ = atom<Explosion[]>('explosions', [])
+// Currently armed tower placement; non-null while the player has a tower
+// "in hand" from the toolbar / keyboard.
+export const placingTower$ = atom<TowerGeo | null>('placingTower', null)
+export const score$ = atom('score', 0)
+export const gold$ = atom('gold', STARTING_GOLD)
+export const lives$ = atom('lives', STARTING_LIVES)
+export const gameOver$ = atom('gameOver', false)
+export const elapsedMs$ = atom('elapsedMs', 0)
+
+// Tower cooldowns are keyed by shape id. Not an atom — only the game loop reads
+// and writes them, and they don't need to drive overlay reactivity.
+export const towerCooldowns = new Map<string, TowerCooldown>()
+
+let _nextEnemyId = 1
+export const nextEnemyId = () => _nextEnemyId++
+let _nextProjId = 1
+export const nextProjectileId = () => _nextProjId++
+let _nextExplosionId = 1
+export const nextExplosionId = () => _nextExplosionId++
+
+export function resetGameState() {
+	enemies$.set([])
+	projectiles$.set([])
+	explosions$.set([])
+	score$.set(0)
+	gold$.set(STARTING_GOLD)
+	lives$.set(STARTING_LIVES)
+	gameOver$.set(false)
+	elapsedMs$.set(0)
+	towerCooldowns.clear()
+	_nextEnemyId = 1
+	_nextProjId = 1
+	_nextExplosionId = 1
+}
+
+export function gainBounty(amount: number) {
+	score$.update((s) => s + amount)
+	gold$.update((g) => g + amount)
+}
+
+export function applyDamage(enemyId: number, amount: number) {
+	const enemies = enemies$.get()
+	const next: Enemy[] = []
+	let killed: Enemy | null = null
+	for (const e of enemies) {
+		if (e.id !== enemyId) {
+			next.push(e)
+			continue
+		}
+		const hp = e.hp - amount
+		if (hp <= 0) {
+			killed = e
+		} else {
+			next.push({ ...e, hp })
+		}
+	}
+	if (killed) gainBounty(killed.bounty)
+	enemies$.set(next)
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/EnemyOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/EnemyOverlayUtil.ts
new file mode 100644
index 000000000000..1a9dec2f6444
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/EnemyOverlayUtil.ts
@@ -0,0 +1,143 @@
+import { Circle2d, Geometry2d, OverlayUtil, TLCursorType, TLOverlay } from 'tldraw'
+import { ENEMY_CONFIG, EnemyType } from '../enemy-config'
+import { applyDamage, elapsedMs$, enemies$ } from '../game-state'
+import { getPositionAtDistance } from '../path'
+
+interface TLEnemyOverlay extends TLOverlay {
+	props: {
+		enemyId: number
+		type: EnemyType
+		x: number
+		y: number
+		hp: number
+		maxHp: number
+		radius: number
+		slowed: boolean
+	}
+}
+
+const CLICK_DAMAGE = 5
+
+export class EnemyOverlayUtil extends OverlayUtil<TLEnemyOverlay> {
+	static override type = 'td-enemy'
+	override options = { zIndex: 200 }
+
+	override isActive(): boolean {
+		return enemies$.get().length > 0
+	}
+
+	override getOverlays(): TLEnemyOverlay[] {
+		const now = elapsedMs$.get()
+		return enemies$.get().map((e) => {
+			const pos = getPositionAtDistance(e.distance)
+			return {
+				id: `td-enemy:${e.id}`,
+				type: 'td-enemy',
+				props: {
+					enemyId: e.id,
+					type: e.type,
+					x: pos.x,
+					y: pos.y,
+					hp: e.hp,
+					maxHp: e.maxHp,
+					radius: e.radius,
+					slowed: e.slowedUntilMs > now,
+				},
+			}
+		})
+	}
+
+	override getGeometry(overlay: TLEnemyOverlay): Geometry2d {
+		const { x, y, radius } = overlay.props
+		// Circle2d's x/y is the bounding-box top-left, so center = (x+radius, y+radius).
+		return new Circle2d({ x: x - radius, y: y - radius, radius, isFilled: true })
+	}
+
+	override getCursor(): TLCursorType {
+		return 'cross'
+	}
+
+	override onPointerDown(overlay: TLEnemyOverlay): boolean {
+		applyDamage(overlay.props.enemyId, CLICK_DAMAGE)
+		// Returning truthy keeps the editor from starting a brush/select drag on
+		// what is effectively a game click.
+		return true
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLEnemyOverlay[]): void {
+		const zoom = this.editor.getZoomLevel()
+		const isDark = this.editor.getColorMode() === 'dark'
+		const hoveredId = this.editor.overlays.getHoveredOverlayId()
+		for (const overlay of overlays) {
+			const { x, y, hp, maxHp, radius, type, slowed } = overlay.props
+			const cfg = ENEMY_CONFIG[type]
+			const t = Math.max(0, Math.min(1, hp / maxHp))
+
+			ctx.save()
+			ctx.beginPath()
+			ctx.arc(x, y, radius, 0, Math.PI * 2)
+			ctx.fillStyle = cfg.bodyColor
+			ctx.fill()
+			ctx.lineWidth = 2 / zoom
+			ctx.strokeStyle = cfg.ringColor
+			ctx.stroke()
+			// Inner ring shrinks/dims with HP so wounded enemies read at a glance.
+			ctx.beginPath()
+			ctx.arc(x, y, radius * 0.55, 0, Math.PI * 2)
+			ctx.fillStyle = `rgba(0, 0, 0, ${0.15 + 0.45 * (1 - t)})`
+			ctx.fill()
+
+			// Frosty halo when slowed by Magic.
+			if (slowed) {
+				ctx.beginPath()
+				ctx.arc(x, y, radius + 4 / zoom, 0, Math.PI * 2)
+				ctx.fillStyle = 'rgba(140, 200, 255, 0.35)'
+				ctx.fill()
+				ctx.lineWidth = 1.5 / zoom
+				ctx.strokeStyle = 'rgba(180, 220, 255, 0.9)'
+				ctx.setLineDash([4 / zoom, 3 / zoom])
+				ctx.stroke()
+				ctx.setLineDash([])
+			}
+
+			// HP bar above the enemy.
+			const barW = radius * 2
+			const barH = 5 / zoom
+			const barX = x - radius
+			const barY = y - radius - barH - 4 / zoom
+			ctx.fillStyle = isDark ? 'rgba(60,60,80,0.85)' : 'rgba(220,220,230,0.9)'
+			ctx.fillRect(barX, barY, barW, barH)
+			ctx.fillStyle = '#3bce5a'
+			ctx.fillRect(barX, barY, barW * t, barH)
+			ctx.lineWidth = 1 / zoom
+			ctx.strokeStyle = isDark ? '#000' : '#444'
+			ctx.strokeRect(barX, barY, barW, barH)
+
+			// HP readout above the bar when this enemy is hovered.
+			if (overlay.id === hoveredId) {
+				const text = `${cfg.label} · ${Math.max(0, Math.ceil(hp))} / ${maxHp}`
+				const fontPx = 12 / zoom
+				ctx.font = `600 ${fontPx}px sans-serif`
+				ctx.textAlign = 'center'
+				ctx.textBaseline = 'bottom'
+				const textY = barY - 4 / zoom
+				const metrics = ctx.measureText(text)
+				const padX = 6 / zoom
+				const padY = 3 / zoom
+				const boxW = metrics.width + padX * 2
+				const boxH = fontPx + padY * 2
+				const boxX = x - boxW / 2
+				const boxY = textY - boxH + padY
+				ctx.fillStyle = isDark ? 'rgba(20,20,28,0.92)' : 'rgba(255,255,255,0.95)'
+				ctx.fillRect(boxX, boxY, boxW, boxH)
+				ctx.lineWidth = 1 / zoom
+				ctx.strokeStyle = isDark ? '#fff' : '#000'
+				ctx.strokeRect(boxX, boxY, boxW, boxH)
+				ctx.fillStyle = isDark ? '#fff' : '#000'
+				ctx.fillText(text, x, textY)
+			}
+
+			ctx.restore()
+		}
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/ExplosionOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/ExplosionOverlayUtil.ts
new file mode 100644
index 000000000000..28625f868d57
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/ExplosionOverlayUtil.ts
@@ -0,0 +1,62 @@
+import { OverlayUtil, TLOverlay } from 'tldraw'
+import { explosions$ } from '../game-state'
+
+interface TLExplosionOverlay extends TLOverlay {
+	props: {
+		x: number
+		y: number
+		radius: number
+		t: number // 0 = just spawned, 1 = about to expire
+	}
+}
+
+export class ExplosionOverlayUtil extends OverlayUtil<TLExplosionOverlay> {
+	static override type = 'td-explosion'
+	override options = { zIndex: 230 }
+
+	override isActive(): boolean {
+		return explosions$.get().length > 0
+	}
+
+	override getOverlays(): TLExplosionOverlay[] {
+		return explosions$.get().map((e) => ({
+			id: `td-explosion:${e.id}`,
+			type: 'td-explosion',
+			props: {
+				x: e.x,
+				y: e.y,
+				radius: e.radius,
+				t: Math.min(1, e.ageMs / e.maxAgeMs),
+			},
+		}))
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLExplosionOverlay[]): void {
+		const zoom = this.editor.getZoomLevel()
+		ctx.save()
+		for (const overlay of overlays) {
+			const { x, y, radius, t } = overlay.props
+			// Expanding ring + fading filled core.
+			const ringR = radius * (0.4 + 0.6 * t)
+			const alpha = 1 - t
+
+			ctx.globalAlpha = alpha * 0.45
+			const grd = ctx.createRadialGradient(x, y, 1, x, y, radius)
+			grd.addColorStop(0, 'rgba(180, 220, 255, 1)')
+			grd.addColorStop(0.6, 'rgba(120, 160, 240, 0.5)')
+			grd.addColorStop(1, 'rgba(80, 120, 220, 0)')
+			ctx.fillStyle = grd
+			ctx.beginPath()
+			ctx.arc(x, y, radius, 0, Math.PI * 2)
+			ctx.fill()
+
+			ctx.globalAlpha = alpha
+			ctx.lineWidth = 3 / zoom
+			ctx.strokeStyle = 'rgba(180, 220, 255, 1)'
+			ctx.beginPath()
+			ctx.arc(x, y, ringR, 0, Math.PI * 2)
+			ctx.stroke()
+		}
+		ctx.restore()
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/PathOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/PathOverlayUtil.ts
new file mode 100644
index 000000000000..0e5c401195c9
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/PathOverlayUtil.ts
@@ -0,0 +1,47 @@
+import { OverlayUtil, TLOverlay } from 'tldraw'
+import { PATH } from '../path'
+
+interface TLPathOverlay extends TLOverlay {
+	props: Record<string, never>
+}
+
+export class PathOverlayUtil extends OverlayUtil<TLPathOverlay> {
+	static override type = 'td-path'
+	override options = { zIndex: 50 }
+
+	override isActive(): boolean {
+		return true
+	}
+
+	override getOverlays(): TLPathOverlay[] {
+		return [{ id: 'td-path:main', type: 'td-path', props: {} }]
+	}
+
+	override render(ctx: CanvasRenderingContext2D): void {
+		const zoom = this.editor.getZoomLevel()
+		const isDark = this.editor.getColorMode() === 'dark'
+
+		ctx.save()
+		ctx.lineCap = 'round'
+		ctx.lineJoin = 'round'
+
+		// Wide soft track
+		ctx.lineWidth = 38
+		ctx.strokeStyle = isDark ? 'rgba(80, 80, 110, 0.45)' : 'rgba(160, 170, 200, 0.45)'
+		ctx.beginPath()
+		ctx.moveTo(PATH[0].x, PATH[0].y)
+		for (let i = 1; i < PATH.length; i++) ctx.lineTo(PATH[i].x, PATH[i].y)
+		ctx.stroke()
+
+		// Center dashed line
+		ctx.lineWidth = 2 / zoom
+		ctx.setLineDash([10 / zoom, 10 / zoom])
+		ctx.strokeStyle = isDark ? 'rgba(220, 220, 240, 0.7)' : 'rgba(60, 60, 80, 0.7)'
+		ctx.beginPath()
+		ctx.moveTo(PATH[0].x, PATH[0].y)
+		for (let i = 1; i < PATH.length; i++) ctx.lineTo(PATH[i].x, PATH[i].y)
+		ctx.stroke()
+
+		ctx.restore()
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/PlacementPreviewOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/PlacementPreviewOverlayUtil.ts
new file mode 100644
index 000000000000..fabdf9c6496f
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/PlacementPreviewOverlayUtil.ts
@@ -0,0 +1,116 @@
+import { Circle2d, Geometry2d, OverlayUtil, TLCursorType, TLOverlay, createShapeId } from 'tldraw'
+import { gold$, placingTower$ } from '../game-state'
+import { TOWER_PLACEMENT_SIZE, TOWER_STATS_BY_GEO, TowerGeo, getTowerStats } from '../tower-config'
+
+interface TLPlacementPreviewOverlay extends TLOverlay {
+	props: {
+		geo: TowerGeo
+		x: number
+		y: number
+		range: number
+	}
+}
+
+export class PlacementPreviewOverlayUtil extends OverlayUtil<TLPlacementPreviewOverlay> {
+	static override type = 'td-placement-preview'
+	override options = { zIndex: 150 }
+
+	override isActive(): boolean {
+		const placing = placingTower$.get()
+		if (!placing) return false
+		const stats = TOWER_STATS_BY_GEO[placing]
+		return gold$.get() >= stats.cost
+	}
+
+	override getOverlays(): TLPlacementPreviewOverlay[] {
+		const geo = placingTower$.get()
+		if (!geo) return []
+		const stats = getTowerStats(geo)
+		if (!stats) return []
+		const { x, y } = this.editor.inputs.getCurrentPagePoint()
+		return [
+			{
+				id: 'td-placement-preview:main',
+				type: 'td-placement-preview',
+				props: { geo, x, y, range: stats.range },
+			},
+		]
+	}
+
+	// The preview tracks the cursor, so a click at the cursor always lands inside
+	// this circle — that's how we route placement through the overlay system
+	// instead of bolting on a capture-phase canvas listener.
+	override getGeometry(overlay: TLPlacementPreviewOverlay): Geometry2d {
+		const { x, y } = overlay.props
+		const r = TOWER_PLACEMENT_SIZE / 2
+		return new Circle2d({ x: x - r, y: y - r, radius: r, isFilled: true })
+	}
+
+	override getCursor(): TLCursorType {
+		return 'cross'
+	}
+
+	override onPointerDown(overlay: TLPlacementPreviewOverlay): boolean {
+		const { geo, x, y } = overlay.props
+		const stats = TOWER_STATS_BY_GEO[geo]
+		if (gold$.get() < stats.cost) return true
+		this.editor.createShape({
+			id: createShapeId(),
+			type: 'geo',
+			x: x - TOWER_PLACEMENT_SIZE / 2,
+			y: y - TOWER_PLACEMENT_SIZE / 2,
+			isLocked: true,
+			props: { geo, w: TOWER_PLACEMENT_SIZE, h: TOWER_PLACEMENT_SIZE },
+		})
+		gold$.update((g) => g - stats.cost)
+		placingTower$.set(null)
+		return true
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLPlacementPreviewOverlay[]): void {
+		const overlay = overlays[0]
+		if (!overlay) return
+		const { geo, x, y, range } = overlay.props
+		const zoom = this.editor.getZoomLevel()
+		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]
+
+		ctx.save()
+
+		// Range ring + soft fill.
+		ctx.lineWidth = 2 / zoom
+		ctx.setLineDash([8 / zoom, 6 / zoom])
+		ctx.strokeStyle = colors.selectionStroke
+		ctx.fillStyle = colors.selectionFill
+		ctx.globalAlpha = 0.35
+		ctx.beginPath()
+		ctx.arc(x, y, range, 0, Math.PI * 2)
+		ctx.fill()
+		ctx.globalAlpha = 1
+		ctx.stroke()
+		ctx.setLineDash([])
+
+		// Ghost shape silhouette at the would-be placement.
+		const half = TOWER_PLACEMENT_SIZE / 2
+		ctx.globalAlpha = 0.55
+		ctx.lineWidth = 2 / zoom
+		ctx.strokeStyle = colors.selectionStroke
+		ctx.fillStyle = colors.selectionFill
+
+		ctx.beginPath()
+		if (geo === 'rectangle') {
+			ctx.rect(x - half, y - half, TOWER_PLACEMENT_SIZE, TOWER_PLACEMENT_SIZE)
+		} else if (geo === 'ellipse') {
+			ctx.ellipse(x, y, half, half, 0, 0, Math.PI * 2)
+		} else {
+			// Triangle — match how the geo shape renders: top-center, bottom-left, bottom-right.
+			ctx.moveTo(x, y - half)
+			ctx.lineTo(x + half, y + half)
+			ctx.lineTo(x - half, y + half)
+			ctx.closePath()
+		}
+		ctx.fill()
+		ctx.stroke()
+
+		ctx.restore()
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/ProjectileOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/ProjectileOverlayUtil.ts
new file mode 100644
index 000000000000..5d83e407d9c2
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/ProjectileOverlayUtil.ts
@@ -0,0 +1,82 @@
+import { OverlayUtil, TLOverlay } from 'tldraw'
+import { projectiles$ } from '../game-state'
+import { ProjectileKind } from '../tower-config'
+
+interface TLProjectileOverlay extends TLOverlay {
+	props: {
+		x: number
+		y: number
+		angle: number
+		kind: ProjectileKind
+	}
+}
+
+export class ProjectileOverlayUtil extends OverlayUtil<TLProjectileOverlay> {
+	static override type = 'td-projectile'
+	override options = { zIndex: 250 }
+
+	override isActive(): boolean {
+		return projectiles$.get().length > 0
+	}
+
+	override getOverlays(): TLProjectileOverlay[] {
+		return projectiles$.get().map((p) => ({
+			id: `td-projectile:${p.id}`,
+			type: 'td-projectile',
+			props: {
+				x: p.x,
+				y: p.y,
+				angle: Math.atan2(p.vy, p.vx),
+				kind: p.kind,
+			},
+		}))
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLProjectileOverlay[]): void {
+		const zoom = this.editor.getZoomLevel()
+		const isDark = this.editor.getColorMode() === 'dark'
+		for (const overlay of overlays) {
+			const { x, y, angle, kind } = overlay.props
+			ctx.save()
+			ctx.translate(x, y)
+			ctx.rotate(angle)
+			switch (kind) {
+				case 'arrow':
+					ctx.lineWidth = 2 / zoom
+					ctx.strokeStyle = isDark ? '#ddd' : '#222'
+					ctx.beginPath()
+					ctx.moveTo(-10, 0)
+					ctx.lineTo(8, 0)
+					ctx.stroke()
+					ctx.beginPath()
+					ctx.moveTo(8, 0)
+					ctx.lineTo(2, -3)
+					ctx.lineTo(2, 3)
+					ctx.closePath()
+					ctx.fillStyle = isDark ? '#ddd' : '#222'
+					ctx.fill()
+					break
+				case 'rock':
+					ctx.beginPath()
+					ctx.arc(0, 0, 6, 0, Math.PI * 2)
+					ctx.fillStyle = '#806040'
+					ctx.fill()
+					ctx.lineWidth = 1.5 / zoom
+					ctx.strokeStyle = '#3a2a1a'
+					ctx.stroke()
+					break
+				case 'orb': {
+					const grd = ctx.createRadialGradient(0, 0, 1, 0, 0, 8)
+					grd.addColorStop(0, 'rgba(180, 220, 255, 1)')
+					grd.addColorStop(1, 'rgba(80, 120, 220, 0.1)')
+					ctx.fillStyle = grd
+					ctx.beginPath()
+					ctx.arc(0, 0, 8, 0, Math.PI * 2)
+					ctx.fill()
+					break
+				}
+			}
+			ctx.restore()
+		}
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/TowerRangeOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/TowerRangeOverlayUtil.ts
new file mode 100644
index 000000000000..980f60d7ebcc
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/TowerRangeOverlayUtil.ts
@@ -0,0 +1,79 @@
+import { computed, OverlayUtil, TLGeoShape, TLOverlay } from 'tldraw'
+import { getScaledStats, getTowerLevel, getTowerStats } from '../tower-config'
+
+interface TLTowerRangeOverlay extends TLOverlay {
+	props: {
+		shapeId: string
+		cx: number
+		cy: number
+		range: number
+	}
+}
+
+export class TowerRangeOverlayUtil extends OverlayUtil<TLTowerRangeOverlay> {
+	static override type = 'td-tower-range'
+	override options = { zIndex: 100 }
+
+	// We deliberately don't rely on `editor.getHoveredShape()` here: default geo
+	// shapes have `fill: 'none'`, which makes their interiors transparent to
+	// hover hit-testing. Walking tower bounds directly means hovering anywhere
+	// inside a tower's bounding box highlights its range, regardless of fill.
+	// Memoised via computed so isActive() + getOverlays() share one walk per tick.
+	private _hoveredTowers = computed('td-tower-range:hovered', (): TLTowerRangeOverlay[] => {
+		const point = this.editor.inputs.getCurrentPagePoint()
+		const result: TLTowerRangeOverlay[] = []
+		for (const shape of this.editor.getCurrentPageShapes()) {
+			if (shape.type !== 'geo') continue
+			const baseStats = getTowerStats((shape as TLGeoShape).props.geo)
+			if (!baseStats) continue
+			const stats = getScaledStats(baseStats, getTowerLevel(shape))
+			const bounds = this.editor.getShapePageBounds(shape.id)
+			if (!bounds) continue
+			// Always preview the range while a tower is being placed (unlocked);
+			// once placed (locked), only show on hover. Filtering on isLocked
+			// avoids flicker as the in-progress shape's bounds chase the pointer.
+			const isPlacing = !shape.isLocked
+			if (!isPlacing && !bounds.containsPoint(point)) continue
+			result.push({
+				id: `td-tower-range:${shape.id}`,
+				type: 'td-tower-range',
+				props: {
+					shapeId: shape.id,
+					cx: bounds.center.x,
+					cy: bounds.center.y,
+					range: stats.range,
+				},
+			})
+		}
+		return result
+	})
+
+	override isActive(): boolean {
+		return this._hoveredTowers.get().length > 0
+	}
+
+	override getOverlays(): TLTowerRangeOverlay[] {
+		return this._hoveredTowers.get()
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLTowerRangeOverlay[]): void {
+		const zoom = this.editor.getZoomLevel()
+		const colors = this.editor.getCurrentTheme().colors[this.editor.getColorMode()]
+
+		ctx.save()
+		ctx.lineWidth = 2 / zoom
+		ctx.setLineDash([8 / zoom, 6 / zoom])
+		ctx.strokeStyle = colors.selectionStroke
+		ctx.fillStyle = colors.selectionFill
+		for (const overlay of overlays) {
+			const { cx, cy, range } = overlay.props
+			ctx.globalAlpha = 0.4
+			ctx.beginPath()
+			ctx.arc(cx, cy, range, 0, Math.PI * 2)
+			ctx.fill()
+			ctx.globalAlpha = 1
+			ctx.stroke()
+		}
+		ctx.restore()
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/overlays/UpgradeButtonOverlayUtil.ts b/apps/examples/src/examples/use-cases/tower-defense/overlays/UpgradeButtonOverlayUtil.ts
new file mode 100644
index 000000000000..0546d7808d1e
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/overlays/UpgradeButtonOverlayUtil.ts
@@ -0,0 +1,192 @@
+import {
+	Box,
+	Circle2d,
+	Geometry2d,
+	OverlayUtil,
+	TLCursorType,
+	TLGeoShape,
+	TLOverlay,
+	TLShapeId,
+	computed,
+} from 'tldraw'
+import { gold$ } from '../game-state'
+import { playUpgradeSound } from '../sounds'
+import {
+	MAX_TOWER_LEVEL,
+	getTowerLevel,
+	getTowerStats,
+	getUpgradeCost,
+	levelColor,
+} from '../tower-config'
+
+interface TLUpgradeBtnOverlay extends TLOverlay {
+	props: {
+		shapeId: TLShapeId
+		x: number
+		y: number
+		radius: number
+		level: number
+		upgradeCost: number
+		canAfford: boolean
+	}
+}
+
+const BTN_RADIUS = 14
+
+interface UpgradeCandidate {
+	shapeId: TLShapeId
+	cx: number
+	cy: number
+	bounds: Box
+	level: number
+	upgradeCost: number
+}
+
+export class UpgradeButtonOverlayUtil extends OverlayUtil<TLUpgradeBtnOverlay> {
+	static override type = 'td-upgrade-btn'
+	override options = { zIndex: 260 }
+
+	// Walk the page shapes once per shape/bounds change. Filtering by pointer
+	// happens in getOverlays(), so a mousemove storm only re-runs the cheap
+	// pointer filter — not the full shape scan and bounds resolution.
+	private _candidates = computed('td-upgrade-btn:candidates', (): UpgradeCandidate[] => {
+		const result: UpgradeCandidate[] = []
+		for (const shape of this.editor.getCurrentPageShapes()) {
+			if (shape.type !== 'geo' || !shape.isLocked) continue
+			const stats = getTowerStats((shape as TLGeoShape).props.geo)
+			if (!stats) continue
+			const level = getTowerLevel(shape)
+			if (level >= MAX_TOWER_LEVEL) continue
+			const bounds = this.editor.getShapePageBounds(shape.id)
+			if (!bounds) continue
+			result.push({
+				shapeId: shape.id,
+				cx: bounds.center.x,
+				cy: bounds.center.y,
+				bounds,
+				level,
+				upgradeCost: getUpgradeCost(stats.cost, level),
+			})
+		}
+		return result
+	})
+
+	override isActive(): boolean {
+		return this._candidates.get().length > 0
+	}
+
+	override getOverlays(): TLUpgradeBtnOverlay[] {
+		const candidates = this._candidates.get()
+		if (candidates.length === 0) return []
+		const gold = gold$.get()
+		const point = this.editor.inputs.getCurrentPagePoint()
+		const result: TLUpgradeBtnOverlay[] = []
+		for (const c of candidates) {
+			// Show only while the pointer is over the tower or the button itself —
+			// the button stays accessible after the cursor moves up onto it.
+			const overShape = c.bounds.containsPoint(point)
+			const dx = point.x - c.cx
+			const dy = point.y - c.cy
+			const overButton = dx * dx + dy * dy <= BTN_RADIUS * BTN_RADIUS
+			if (!overShape && !overButton) continue
+			result.push({
+				id: `td-upgrade-btn:${c.shapeId}`,
+				type: 'td-upgrade-btn',
+				props: {
+					shapeId: c.shapeId,
+					x: c.cx,
+					y: c.cy,
+					radius: BTN_RADIUS,
+					level: c.level,
+					upgradeCost: c.upgradeCost,
+					canAfford: gold >= c.upgradeCost,
+				},
+			})
+		}
+		return result
+	}
+
+	override getGeometry(overlay: TLUpgradeBtnOverlay): Geometry2d {
+		const { x, y, radius } = overlay.props
+		return new Circle2d({ x: x - radius, y: y - radius, radius, isFilled: true })
+	}
+
+	override getCursor(): TLCursorType {
+		return 'pointer'
+	}
+
+	override onPointerDown(overlay: TLUpgradeBtnOverlay): boolean {
+		const { shapeId, upgradeCost, level, canAfford } = overlay.props
+		if (!canAfford) return true
+		const shape = this.editor.getShape(shapeId)
+		if (!shape) return true
+		const nextLevel = level + 1
+		gold$.update((g) => g - upgradeCost)
+		// updateShape silently skips locked shapes unless run with ignoreShapeLock;
+		// without this the meta + props don't persist on placed (locked) towers.
+		this.editor.run(
+			() => {
+				this.editor.updateShape({
+					id: shapeId,
+					type: 'geo',
+					meta: { ...shape.meta, towerLevel: nextLevel },
+					props: { fill: 'solid', color: levelColor(nextLevel) },
+				})
+			},
+			{ ignoreShapeLock: true }
+		)
+		playUpgradeSound()
+		return true
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLUpgradeBtnOverlay[]): void {
+		const zoom = this.editor.getZoomLevel()
+		const isDark = this.editor.getColorMode() === 'dark'
+		for (const overlay of overlays) {
+			const { x, y, radius, level, upgradeCost, canAfford } = overlay.props
+			ctx.save()
+			ctx.beginPath()
+			ctx.arc(x, y, radius, 0, Math.PI * 2)
+			ctx.fillStyle = canAfford ? '#3aa56a' : isDark ? '#444' : '#aaa'
+			ctx.fill()
+			ctx.lineWidth = 2 / zoom
+			ctx.strokeStyle = isDark ? '#000' : '#222'
+			ctx.stroke()
+
+			// Plus sign.
+			ctx.lineWidth = 3 / zoom
+			ctx.lineCap = 'round'
+			ctx.strokeStyle = '#fff'
+			const arm = radius * 0.5
+			ctx.beginPath()
+			ctx.moveTo(x - arm, y)
+			ctx.lineTo(x + arm, y)
+			ctx.moveTo(x, y - arm)
+			ctx.lineTo(x, y + arm)
+			ctx.stroke()
+
+			// Cost + level chip below the button.
+			const fontPx = 11 / zoom
+			ctx.font = `600 ${fontPx}px sans-serif`
+			ctx.textAlign = 'center'
+			ctx.textBaseline = 'top'
+			const text = `L${level}→${level + 1} · ${upgradeCost}g`
+			const metrics = ctx.measureText(text)
+			const padX = 5 / zoom
+			const padY = 2 / zoom
+			const boxW = metrics.width + padX * 2
+			const boxH = fontPx + padY * 2
+			const boxX = x - boxW / 2
+			const boxY = y + radius + 3 / zoom
+			ctx.fillStyle = isDark ? 'rgba(20,20,28,0.92)' : 'rgba(255,255,255,0.95)'
+			ctx.fillRect(boxX, boxY, boxW, boxH)
+			ctx.lineWidth = 1 / zoom
+			ctx.strokeStyle = isDark ? '#fff' : '#000'
+			ctx.strokeRect(boxX, boxY, boxW, boxH)
+			ctx.fillStyle = canAfford ? (isDark ? '#fff' : '#000') : isDark ? '#888' : '#888'
+			ctx.fillText(text, x, boxY + padY)
+
+			ctx.restore()
+		}
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/path.ts b/apps/examples/src/examples/use-cases/tower-defense/path.ts
new file mode 100644
index 000000000000..9d1c335dffa7
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/path.ts
@@ -0,0 +1,63 @@
+// Hardcoded enemy path. Page-space waypoints; enemies move along it from start
+// to end. Kept simple so the OverlayUtil mechanics, not the routing, are the
+// point of the example.
+
+export interface Waypoint {
+	x: number
+	y: number
+}
+
+export const PATH: Waypoint[] = [
+	{ x: -200, y: 200 },
+	{ x: 200, y: 200 },
+	{ x: 200, y: 500 },
+	{ x: 600, y: 500 },
+	{ x: 600, y: 100 },
+	{ x: 1000, y: 100 },
+	{ x: 1000, y: 600 },
+	{ x: 1400, y: 600 },
+]
+
+const SEGMENT_LENGTHS: number[] = []
+let TOTAL_LENGTH = 0
+for (let i = 1; i < PATH.length; i++) {
+	const dx = PATH[i].x - PATH[i - 1].x
+	const dy = PATH[i].y - PATH[i - 1].y
+	const len = Math.hypot(dx, dy)
+	SEGMENT_LENGTHS.push(len)
+	TOTAL_LENGTH += len
+}
+
+export const PATH_LENGTH = TOTAL_LENGTH
+
+export interface PointOnPath {
+	x: number
+	y: number
+	angle: number
+}
+
+export function getPositionAtDistance(distance: number): PointOnPath {
+	if (distance <= 0) {
+		const a = PATH[0]
+		const b = PATH[1]
+		return { x: a.x, y: a.y, angle: Math.atan2(b.y - a.y, b.x - a.x) }
+	}
+	let remaining = distance
+	for (let i = 0; i < SEGMENT_LENGTHS.length; i++) {
+		const segLen = SEGMENT_LENGTHS[i]
+		if (remaining <= segLen) {
+			const a = PATH[i]
+			const b = PATH[i + 1]
+			const t = remaining / segLen
+			return {
+				x: a.x + (b.x - a.x) * t,
+				y: a.y + (b.y - a.y) * t,
+				angle: Math.atan2(b.y - a.y, b.x - a.x),
+			}
+		}
+		remaining -= segLen
+	}
+	const last = PATH[PATH.length - 1]
+	const prev = PATH[PATH.length - 2]
+	return { x: last.x, y: last.y, angle: Math.atan2(last.y - prev.y, last.x - prev.x) }
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/sounds.ts b/apps/examples/src/examples/use-cases/tower-defense/sounds.ts
new file mode 100644
index 000000000000..21ce52fc7d97
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/sounds.ts
@@ -0,0 +1,92 @@
+import { ProjectileKind } from './tower-config'
+
+// We synthesize fire sounds with Web Audio API rather than loading assets so
+// the example stays self-contained. The AudioContext is created lazily on the
+// first call to side-step browser autoplay restrictions — by then the user has
+// already clicked something to place a tower.
+
+let ctx: AudioContext | null = null
+let lastPlayedAt = 0
+const MIN_INTERVAL_MS = 25 // hard cap to stop a wall of overlapping shots
+
+function getCtx(): AudioContext | null {
+	if (ctx) return ctx
+	try {
+		const Ctor =
+			window.AudioContext ??
+			(window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext
+		if (!Ctor) return null
+		ctx = new Ctor()
+		return ctx
+	} catch {
+		return null
+	}
+}
+
+interface ToneSpec {
+	type: OscillatorType
+	startFreq: number
+	endFreq: number
+	durationMs: number
+	gain: number
+}
+
+const TONES: Record<ProjectileKind, ToneSpec> = {
+	arrow: { type: 'sawtooth', startFreq: 760, endFreq: 480, durationMs: 90, gain: 0.07 },
+	rock: { type: 'square', startFreq: 160, endFreq: 70, durationMs: 180, gain: 0.1 },
+	orb: { type: 'sine', startFreq: 880, endFreq: 320, durationMs: 220, gain: 0.09 },
+}
+
+export function playUpgradeSound() {
+	const c = getCtx()
+	if (!c) return
+	if (c.state === 'suspended') c.resume().catch(() => {})
+
+	// Two quick ascending sine notes — a small "level up" chime.
+	const t0 = c.currentTime
+	const notes = [
+		{ freq: 660, start: 0, durMs: 120 },
+		{ freq: 990, start: 90, durMs: 180 },
+	]
+	for (const n of notes) {
+		const osc = c.createOscillator()
+		osc.type = 'sine'
+		const gain = c.createGain()
+		const startAt = t0 + n.start / 1000
+		const stopAt = startAt + n.durMs / 1000
+		osc.frequency.setValueAtTime(n.freq, startAt)
+		gain.gain.setValueAtTime(0.001, startAt)
+		gain.gain.exponentialRampToValueAtTime(0.12, startAt + 0.01)
+		gain.gain.exponentialRampToValueAtTime(0.0001, stopAt)
+		osc.connect(gain).connect(c.destination)
+		osc.start(startAt)
+		osc.stop(stopAt + 0.02)
+	}
+}
+
+export function playFireSound(kind: ProjectileKind) {
+	const c = getCtx()
+	if (!c) return
+	if (c.state === 'suspended') c.resume().catch(() => {})
+
+	const now = performance.now()
+	if (now - lastPlayedAt < MIN_INTERVAL_MS) return
+	lastPlayedAt = now
+
+	const spec = TONES[kind]
+	const t0 = c.currentTime
+	const t1 = t0 + spec.durationMs / 1000
+
+	const osc = c.createOscillator()
+	osc.type = spec.type
+	osc.frequency.setValueAtTime(spec.startFreq, t0)
+	osc.frequency.exponentialRampToValueAtTime(Math.max(20, spec.endFreq), t1)
+
+	const gain = c.createGain()
+	gain.gain.setValueAtTime(spec.gain, t0)
+	gain.gain.exponentialRampToValueAtTime(0.0001, t1)
+
+	osc.connect(gain).connect(c.destination)
+	osc.start(t0)
+	osc.stop(t1 + 0.02)
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/tower-config.ts b/apps/examples/src/examples/use-cases/tower-defense/tower-config.ts
new file mode 100644
index 000000000000..7750856de71e
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/tower-config.ts
@@ -0,0 +1,92 @@
+// Maps geo shape variants to tower stats. Only these three geo types act as
+// towers; other geo shapes the user draws are ignored by the game loop so the
+// editor stays usable.
+
+import { TLShape } from 'tldraw'
+
+export type ProjectileKind = 'arrow' | 'rock' | 'orb'
+
+export const MAX_TOWER_LEVEL = 4
+
+export type TowerGeo = 'triangle' | 'rectangle' | 'ellipse'
+export const TOWER_GEOS: TowerGeo[] = ['triangle', 'rectangle', 'ellipse']
+export const TOWER_PLACEMENT_SIZE = 60
+
+export interface TowerStats {
+	label: string
+	range: number
+	fireRateMs: number
+	damage: number
+	projectileSpeed: number
+	projectileKind: ProjectileKind
+	cost: number
+}
+
+// Cost is roughly proportional to overall strength (range × damage / fireRate).
+// Starting gold (see game-state) is calibrated to afford one Archer immediately
+// and earn the others through kills.
+export const TOWER_STATS_BY_GEO: Record<string, TowerStats> = {
+	triangle: {
+		label: 'Archer',
+		range: 220,
+		fireRateMs: 350,
+		damage: 8,
+		projectileSpeed: 700,
+		projectileKind: 'arrow',
+		cost: 50,
+	},
+	rectangle: {
+		label: 'Cannon',
+		range: 160,
+		fireRateMs: 1100,
+		damage: 30,
+		projectileSpeed: 380,
+		projectileKind: 'rock',
+		cost: 120,
+	},
+	ellipse: {
+		label: 'Magic',
+		range: 190,
+		fireRateMs: 600,
+		damage: 14,
+		projectileSpeed: 520,
+		projectileKind: 'orb',
+		cost: 80,
+	},
+}
+
+export function getTowerStats(geo: string | undefined): TowerStats | null {
+	if (!geo) return null
+	return TOWER_STATS_BY_GEO[geo] ?? null
+}
+
+export function getTowerLevel(shape: TLShape): number {
+	const lvl = shape.meta?.towerLevel
+	return typeof lvl === 'number' && lvl >= 1 ? Math.min(MAX_TOWER_LEVEL, lvl) : 1
+}
+
+// Each upgrade adds 60% of base cost per level: L1→2 = 60%, L2→3 = 120%, L3→4 = 180%.
+export function getUpgradeCost(baseCost: number, currentLevel: number): number {
+	if (currentLevel >= MAX_TOWER_LEVEL) return 0
+	return Math.ceil(baseCost * 0.6 * currentLevel)
+}
+
+// Visual cue for tower level — also makes the level readable at a glance.
+export function levelColor(level: number): 'blue' | 'violet' | 'red' | 'orange' {
+	if (level >= 4) return 'red'
+	if (level === 3) return 'violet'
+	if (level === 2) return 'blue'
+	return 'orange'
+}
+
+// Damage and range grow with level; fire rate shortens. Level 1 returns base.
+export function getScaledStats(stats: TowerStats, level: number): TowerStats {
+	const k = Math.max(0, level - 1)
+	if (k === 0) return stats
+	return {
+		...stats,
+		damage: Math.round(stats.damage * Math.pow(1.4, k)),
+		range: Math.round(stats.range * Math.pow(1.06, k)),
+		fireRateMs: Math.round(stats.fireRateMs * Math.pow(0.9, k)),
+	}
+}
diff --git a/apps/examples/src/examples/use-cases/tower-defense/tower-defense.css b/apps/examples/src/examples/use-cases/tower-defense/tower-defense.css
new file mode 100644
index 000000000000..eed699fd153c
--- /dev/null
+++ b/apps/examples/src/examples/use-cases/tower-defense/tower-defense.css
@@ -0,0 +1,131 @@
+.td-hud {
+	display: flex;
+	flex-direction: column;
+	gap: 4px;
+	padding: 8px 12px;
+	background: var(--color-panel);
+	border-radius: 8px;
+	box-shadow: var(--shadow-2);
+	font-size: 12px;
+	color: var(--color-text);
+	max-width: 720px;
+	pointer-events: auto;
+}
+
+.td-hud__row {
+	display: flex;
+	gap: 16px;
+	align-items: center;
+	flex-wrap: wrap;
+}
+
+.td-hud__row strong {
+	font-variant-numeric: tabular-nums;
+	font-weight: 600;
+}
+
+.td-hud__btn {
+	margin-left: auto;
+	padding: 4px 10px;
+	border: 1px solid var(--color-divider);
+	border-radius: 6px;
+	background: var(--color-low);
+	color: var(--color-text);
+	cursor: pointer;
+	font: inherit;
+}
+
+.td-hud__btn:hover {
+	background: var(--color-hint);
+}
+
+.td-hud__hint {
+	color: var(--color-text-1);
+	font-size: 11px;
+	opacity: 0.85;
+}
+
+.td-hud__hint code,
+.td-hud__hint kbd {
+	display: inline-block;
+	padding: 0 4px;
+	border-radius: 3px;
+	background: var(--color-low);
+	font: inherit;
+	font-size: 10px;
+}
+
+.td-hud__gameover {
+	color: #d33;
+	font-weight: 600;
+}
+
+.td-toolbar {
+	display: flex;
+	gap: 6px;
+	padding: 6px;
+	background: var(--color-panel);
+	border-radius: 10px;
+	box-shadow: var(--shadow-2);
+	pointer-events: auto;
+}
+
+.td-toolbar__btn {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 2px;
+	min-width: 56px;
+	padding: 6px 8px;
+	border: 1px solid transparent;
+	border-radius: 8px;
+	background: transparent;
+	color: var(--color-text);
+	cursor: pointer;
+	font-size: 11px;
+	font: inherit;
+}
+
+.td-toolbar__btn:hover {
+	background: var(--color-hint);
+}
+
+.td-toolbar__btn.is-active {
+	border-color: var(--color-selected);
+	background: var(--color-selected-contrast);
+	color: var(--color-selected);
+}
+
+.td-toolbar__btn.is-disabled,
+.td-toolbar__btn:disabled {
+	opacity: 0.4;
+	cursor: not-allowed;
+}
+
+.td-toolbar__btn.is-disabled:hover,
+.td-toolbar__btn:disabled:hover {
+	background: transparent;
+}
+
+.td-toolbar__label {
+	font-size: 10px;
+	letter-spacing: 0.02em;
+}
+
+.td-toolbar__cost {
+	font-size: 10px;
+	color: var(--color-text-1);
+	font-variant-numeric: tabular-nums;
+}
+
+.td-toolbar__cost kbd {
+	display: inline-block;
+	padding: 0 4px;
+	min-width: 14px;
+	text-align: center;
+	border: 1px solid var(--color-divider);
+	border-radius: 3px;
+	background: var(--color-low);
+	font: inherit;
+	font-size: 9px;
+}

From 012f1734850540a2667579ffd8133c1c229565ba Mon Sep 17 00:00:00 2001
From: Steve Ruiz <steveruizok@gmail.com>
Date: Wed, 6 May 2026 12:01:51 +0100
Subject: [PATCH 08/11] docs(releases): add migration guides for breaking
 changes (#8776)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to make the `tldraw-migrate` skill version-agnostic and stop
duplicating migration recipes between the skill and the release notes,
this PR adds explicit migration guide blocks for every breaking change
in the v4.2, v4.3, and `next.mdx` release notes — and refactors the
skill to drive off those blocks instead of carrying its own copies.

Version-specific knowledge belongs next to the breaking change that
introduced it. The skill stays small and stable; the release notes own
the recipes.

### Release notes content

- `apps/docs/content/releases/v4.2.0.mdx` — TipTap v3 section gets a
migration block covering the dual-install diagnostic, default→named
export changes, `TextStyleKit`/`FontFamily` reorganization, and
transaction handler types.
- `apps/docs/content/releases/v4.3.0.mdx` — Custom shape/binding pattern
section gets a migration block covering
`TLGlobalShapePropsMap`/`TLGlobalBindingPropsMap` augmentation, the
rename ripple when shape names collide, `as const` on `static override
type` / `static override shapeType`, and the heterogeneous
`createShapes`/`updateShapes` cast.
- `apps/docs/content/releases/next.mdx` — adds migration blocks for
`ShapeUtil.indicator()` → `getIndicatorPath()`, `<Tldraw>` options
consolidation (`cameraOptions`/`textOptions`/`deepLinks` → `options`
prop, `embeds` → `EmbedShapeUtil.configure`,
`setDefaultEditorAssetUrls`/`setDefaultUiAssetUrls` demoted to
`@internal`), and `useTldrawUser` removal. Several previously-unmarked
breaking changes in the API list are now marked with `💥` and given
inline replacement guidance.

### Skill changes

- `skills/write-release-notes/SKILL.md` — new step requiring a migration
recipe for every `💥` (block for featured sections; inline replacement
for one-line API entries). Verify step now grep-checks that every `💥`
has a recipe.
- `skills/tldraw-migrate/SKILL.md` — major refactor:
- Renames `${CLAUDE_SKILL_DIR}` → `${SKILL_DIR}` and probes common skill
locations so the skill works under non-Claude agent setups.
- Adds support for migrating to a target version other than `latest`.
Pass a dist-tag (`canary`, `next`, `beta`) or a pre-release semver as
the second argument.
- When the target is a pre-release, auto-fetches
`apps/docs/content/releases/next.mdx` from `main` so canary/next deltas
are searchable alongside the stable changelog.
- Step 4 fix patterns are now version-agnostic — they categorize errors
by TS code and route to the correct migration block in the changelog.
Each sub-step ends with a verify step that re-runs typecheck.
- Quality audit now distinguishes typed `as` casts from `as const` and
import-path `as`, and adds a module-augmentation audit (catches the
anti-pattern of re-exposing `@internal` symbols).
- `skills/tldraw-migrate/detect-target.mjs` (new) — resolves the
migration target from the skill arguments. `latest` by default; supports
dist-tags and pre-release semvers.

### Change type

- [x] `other` (skill + docs)

### Test plan

1. Skim each `<details><summary>Migration guide</summary>` block in
`next.mdx`, `v4.2.0.mdx`, and `v4.3.0.mdx` for accuracy.
2. Verify every `💥` has a recipe: `grep -nE '💥'
apps/docs/content/releases/{next,v4.2.0,v4.3.0}.mdx` and confirm each
line has either a nearby migration block or an inline replacement.
3. Run the migrate skill on a v4.1 → 4.6.0-canary project: confirm the
auto-fetch blocks resolve `${SKILL_DIR}` and that
`references/tldraw-next.mdx` is pulled when the target is a pre-release.
4. Run with no second argument and confirm the target resolves to
`latest` and `tldraw-next.mdx` is skipped.

### Release notes

- Add migration guides for every breaking change in the v4.2 and v4.3
release notes.

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Documentation   | +184 / -4  |
| Config/tooling  | +195 / -60 |
---
 apps/docs/content/releases/next.mdx     | 106 +++++++++++++-
 apps/docs/content/releases/v4.2.0.mdx   |  35 ++++-
 apps/docs/content/releases/v4.3.0.mdx   |  47 ++++++-
 skills/tldraw-migrate/SKILL.md          | 179 ++++++++++++++++--------
 skills/tldraw-migrate/detect-target.mjs |  34 +++++
 skills/write-release-notes/SKILL.md     |  42 +++++-
 6 files changed, 379 insertions(+), 64 deletions(-)
 create mode 100644 skills/tldraw-migrate/detect-target.mjs

diff --git a/apps/docs/content/releases/next.mdx b/apps/docs/content/releases/next.mdx
index 0fb44195faf2..dd198da81364 100644
--- a/apps/docs/content/releases/next.mdx
+++ b/apps/docs/content/releases/next.mdx
@@ -122,7 +122,25 @@ The following slots have been removed from `TLEditorComponents`. Subclass the ma
 
 The corresponding `Default*` exports and `LiveCollaborators` have also been removed.
 
-Customizing shape indicators — `ShapeIndicator`, `ShapeIndicators`, and `ShapeIndicatorErrorFallback` are gone. Indicators now render through each shape util's `getIndicatorPath()`. Override it to change how a shape's indicator is drawn.
+**`ShapeUtil.indicator()` → `ShapeUtil.getIndicatorPath()`.** The shape util method that draws a shape's selection indicator no longer returns JSX. It now returns a `Path2D` (or a `TLIndicatorPath`) and is composited onto the canvas overlay layer. Every custom `ShapeUtil` that overrides `indicator` needs to migrate:
+
+```tsx
+// Before
+override indicator(shape: MyShape) {
+	return <rect width={shape.props.w} height={shape.props.h} />
+}
+
+// After
+override getIndicatorPath(shape: MyShape): Path2D {
+	const path = new Path2D()
+	path.rect(0, 0, shape.props.w, shape.props.h)
+	return path
+}
+```
+
+For shapes whose indicator should match the shape's geometry, return `path` built from the same primitives. For placeholder shapes (e.g. an `ErrorShape`), return an empty `new Path2D()` and declare the return type explicitly so TypeScript doesn't infer `never`.
+
+The React component slots `ShapeIndicator`, `ShapeIndicators`, and `ShapeIndicatorErrorFallback` are also removed from `TLEditorComponents` — there is no replacement React slot, since indicators now render through `getIndicatorPath()`.
 
 Overlays cannot render React; they draw into a 2D canvas context. For React-based overlays, render an HTML layer above the canvas via a regular `TLEditorComponents` slot like `InFrontOfTheCanvas`.
 
@@ -134,6 +152,57 @@ Overriding them (or the removed selectors `.tl-brush`, `.tl-scribble`, `.tl-snap
 
 </details>
 
+### 💥 Tldraw component options
+
+Several `<Tldraw>` props that previously lived at the top level have been consolidated under the `options` prop, and a few extension points moved off the component entirely.
+
+<details>
+<summary>Migration guide</summary>
+
+**`cameraOptions`, `textOptions`, and `deepLinks` props moved into `options`:**
+
+```tsx
+// Before
+<Tldraw cameraOptions={camOpts} textOptions={txtOpts} deepLinks />
+
+// After
+<Tldraw options={{ camera: camOpts, text: txtOpts, deepLinks: true }} />
+```
+
+**`embeds` prop removed; configure embed definitions on `EmbedShapeUtil`:**
+
+```tsx
+// Before
+<Tldraw embeds={[...DEFAULT_EMBED_DEFINITIONS, customEmbed]} />
+
+// After
+import { EmbedShapeUtil } from 'tldraw'
+const ConfiguredEmbedShapeUtil = EmbedShapeUtil.configure({
+	embedDefinitions: [...DEFAULT_EMBED_DEFINITIONS, customEmbed],
+})
+<Tldraw shapeUtils={[ConfiguredEmbedShapeUtil]} />
+```
+
+This silently compiles in some setups (the prop is unknown but JSX won't always reject it), so this is the kind of change that the typecheck won't always catch — search the source for `embeds=` and migrate any matches.
+
+**`setDefaultEditorAssetUrls()` and `setDefaultUiAssetUrls()` are no longer part of the public API.** They still exist at runtime for now, but they're marked `@internal` and should not be relied on. Pass `assetUrls` to each `<Tldraw>` instead:
+
+```tsx
+// Before
+import { setDefaultEditorAssetUrls, setDefaultUiAssetUrls } from 'tldraw'
+setDefaultEditorAssetUrls(assetUrls)
+setDefaultUiAssetUrls(assetUrls)
+
+<Tldraw />
+
+// After
+<Tldraw assetUrls={assetUrls} />
+```
+
+Do not reach for module augmentation to re-expose the old globals — find each `<Tldraw>` mount point and pass `assetUrls` directly.
+
+</details>
+
 ### Custom record types ([#8213](https://github.com/tldraw/tldraw/pull/8213))
 
 You can now register custom record types in the tldraw store for persisting and synchronizing domain-specific data that doesn't fit into shapes, bindings, or assets. Custom records support scoping (document/session/presence), validation, migrations, and default properties.
@@ -282,6 +351,33 @@ const schema = createTLSchema({
 
 Note shapes now track and display a "first edited by" attribution label in the bottom-right corner, showing who first added text to the note.
 
+<details>
+<summary>Migration guide</summary>
+
+**`useTldrawUser` has been removed.** Previously it bundled user *preferences* (color, color scheme) and user *identity* (id, name) into a single object. These are now separate concerns:
+
+- **Preferences** (color, color scheme, snap mode, etc.) are managed via `TLUserPreferences`. Set them with the editor's user-preferences API directly.
+- **Identity** for attribution comes from a `TLUserStore` provider passed to the new `users` prop on `<Tldraw>`.
+
+```tsx
+// Before
+const user = useTldrawUser({ userPreferences, setUserPreferences })
+<Tldraw user={user} />
+
+// After
+<Tldraw
+	users={{
+		getCurrentUser: () => currentUserSignal,
+		resolve: (userId) => resolvedUserSignal(userId),
+	}}
+	colorScheme={userPreferences.colorScheme}
+/>
+```
+
+If you only need preferences (no custom identity), pass `colorScheme` directly and seed preferences imperatively after mount; if you only need identity, pass `users`. Most apps want both.
+
+</details>
+
 ### @tldraw/driver ([#7952](https://github.com/tldraw/tldraw/pull/7952))
 
 A new `@tldraw/driver` package provides an imperative API for driving the tldraw editor programmatically. `Driver` wraps an `Editor` instance and exposes event dispatch, selection transforms, clipboard operations, and shape queries with fluent chaining.
@@ -387,6 +483,14 @@ New APIs include `handleSocketResume()` for restoring sessions from snapshots, `
 - 💥 Change `notifyIfFileNotAllowed` signature from `(file, options)` to `(editor, file, options)`. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
 - 💥 Change `getAssetInfo` signature from `(file, options, assetId?)` to `(editor, file, assetId?)` and return `TLAsset | null` instead of throwing. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
 - 💥 Move the `Cmd+Shift+C` / `Ctrl+Shift+C` shortcut from "Copy as SVG" to "Copy as PNG". ([#8532](https://github.com/tldraw/tldraw/pull/8532))
+- 💥 Replace `ShapeUtil.indicator()` (returned JSX) with `ShapeUtil.getIndicatorPath()` (returns `Path2D | TLIndicatorPath | undefined`). Indicators now render to the canvas overlay layer instead of as React elements. ([#8469](https://github.com/tldraw/tldraw/pull/8469))
+- 💥 Move `cameraOptions`, `textOptions`, and `deepLinks` from top-level `<Tldraw>` props into the `options` prop (e.g. `options={{ camera, text, deepLinks }}`).
+- 💥 Remove the `embeds` prop from `<Tldraw>`. Configure embed definitions via `EmbedShapeUtil.configure({ embedDefinitions })` and pass the configured util through `shapeUtils`.
+- 💥 Demote `setDefaultEditorAssetUrls()` and `setDefaultUiAssetUrls()` to `@internal`. Pass `assetUrls` to each `<Tldraw>` instead.
+- 💥 Remove `useTldrawUser`. Use the new `users` prop (`TLUserStore`) for identity and `TLUserPreferences` for preferences.
+- 💥 Replace `TLDrawShapeSegment.points` with the helper `getPointsFromDrawSegment(segment, scaleX, scaleY)` so segment points respect the shape's current scale.
+- 💥 Change `BindingUtil` hook params: `fromShapeType`/`toShapeType` are removed in favor of full `fromShape`/`toShape` records (read `fromShape.type` / `toShape.type` directly).
+- 💥 Add `'middle-legacy'` (and other legacy values) to the `align` union resolved by `PlainTextLabel`/`RichTextLabel`. If your code maps `align` into `PlainTextLabel.textAlign`, narrow legacy values to one of `'start' | 'center' | 'end'` before passing them through.
 - Add `TLTheme`, `TLThemeId`, `TLThemes`, `TLThemeDefaultColors`, `TLThemeColors`, `TLRemovedDefaultThemeColors`, `ThemeManager`, `getDisplayValues()`, `getColorValue()`, and `DEFAULT_THEME` for the new theme system. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
 - Add `themes` and `initialTheme` props to `<Tldraw>` and `<TldrawEditor>`. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
 - Add `getCurrentTheme()`, `setCurrentTheme()`, `getThemes()`, `getTheme()`, `updateTheme()`, `updateThemes()`, and `getColorMode()` to the editor. ([#8410](https://github.com/tldraw/tldraw/pull/8410))
diff --git a/apps/docs/content/releases/v4.2.0.mdx b/apps/docs/content/releases/v4.2.0.mdx
index 3ed6708c7585..283084b6f53c 100644
--- a/apps/docs/content/releases/v4.2.0.mdx
+++ b/apps/docs/content/releases/v4.2.0.mdx
@@ -19,10 +19,43 @@ This month's release includes many bug fixes and small API additions, along with
 
 ## What's new
 
-### TipTap v3 ([#5717](https://github.com/tldraw/tldraw/pull/5717))
+### 💥 TipTap v3 ([#5717](https://github.com/tldraw/tldraw/pull/5717))
 
 We've upgraded TipTap from v2 to v3. If you've done any customization to our standard TipTap kit, please refer to TipTap's guide [How to upgrade Tiptap v2 to v3](https://tiptap.dev/docs/guides/upgrade-tiptap-v2) for breaking changes you might experience.
 
+<details>
+<summary>Migration guide</summary>
+
+Starting in v4.2, tldraw bundles TipTap v3 as a transitive dependency. If your project pins `@tiptap/*` v2 packages directly, upgrade them to v3 *before* trying to fix any code-level errors — leaving v2 in place produces a dual install that surfaces as confusing type errors.
+
+**Dual-install symptom.** Deeply-nested errors like *"Property 'getCharacterCount' is missing in type 'Editor' but required in type 'Editor'"*, with the two `Editor` types resolving to different paths (one under `node_modules/@tiptap/core`, the other under `node_modules/@tldraw/editor/node_modules/@tiptap/core`), are not API changes — they are the v2/v3 dual install. The `Editor` classes are structurally similar but nominally different. Finishing the v3 upgrade collapses the duplicate and these errors disappear without code changes.
+
+**Code-level changes that affect tldraw users:**
+
+- **Default → named exports.** Several extensions changed from default to named exports:
+
+  ```ts
+  // Before
+  import StarterKit from '@tiptap/starter-kit'
+
+  // After
+  import { StarterKit } from '@tiptap/starter-kit'
+  ```
+
+- **`TextStyle` → `TextStyleKit`, and `FontFamily` moved.** The `FontFamily` extension is no longer in `@tiptap/extension-font-family`; it's part of `TextStyleKit` in `@tiptap/extension-text-style`. The `setFontFamily` and `setFontSize` chain commands only exist on `TextStyleKit`, not on bare `TextStyle`.
+
+- **Transaction handler types.** Inline parameter type annotations on TipTap event handlers no longer work. Import the proper event-map type:
+
+  ```ts
+  import { EditorEvents } from '@tiptap/core'
+  // ...
+  onTransaction: (props: EditorEvents['transaction']) => { /* ... */ }
+  ```
+
+- **Custom chained commands** still register via `declare module '@tiptap/core'` augmentation in v3 — the augmentation target is the same.
+
+</details>
+
 ## API changes
 
 - Add `Editor.setTool`/`Editor.removeTool` for dynamically altering the editor's tool state chart. ([#6909](https://github.com/tldraw/tldraw/pull/6909)) ([#7134](https://github.com/tldraw/tldraw/pull/7134))
diff --git a/apps/docs/content/releases/v4.3.0.mdx b/apps/docs/content/releases/v4.3.0.mdx
index d21c6e72266e..346c4fdb2c9d 100644
--- a/apps/docs/content/releases/v4.3.0.mdx
+++ b/apps/docs/content/releases/v4.3.0.mdx
@@ -13,7 +13,7 @@ This release introduces several significant changes: a new pattern for defining
 
 ---
 
-### New pattern for defining custom shape/binding types (breaking change) ([#7091](https://github.com/tldraw/tldraw/pull/7091))
+### 💥 New pattern for defining custom shape/binding types ([#7091](https://github.com/tldraw/tldraw/pull/7091))
 
 We've improved the developer experience of working with custom shape and binding types. There's now less boilerplate and fewer gotchas when using tldraw APIs in a type-safe manner.
 
@@ -61,7 +61,50 @@ editor.createShape({ type: 'my-shape', props: { w: 100, h: 100, text: 'Hello' }
 editor.createShape({ type: 'my-shape', props: { w: 100, h: 100, text: 123 } })
 ```
 
-The same pattern applies to custom bindings. See the [Custom Shapes Guide](https://tldraw.dev/docs/shapes#custom-shapes) and the [Pin Bindings example](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/shapes/tools/pin-bindings) for details.
+The same pattern applies to custom bindings — augment `TLGlobalBindingPropsMap` and use `TLBinding<'binding-name'>`:
+
+```ts
+declare module 'tldraw' {
+	export interface TLGlobalBindingPropsMap {
+		'my-binding': { offset: number }
+	}
+}
+
+type MyBinding = TLBinding`<'my-binding'>`
+```
+
+See the [Custom Shapes Guide](https://tldraw.dev/docs/shapes#custom-shapes) and the [Pin Bindings example](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/shapes/tools/pin-bindings) for details.
+
+**After registering, remove the `TLBaseShape` import** — it's no longer used and will trip lint rules that flag unused imports.
+
+**Shape type names are global.** `TLGlobalShapePropsMap` is a single shared registry, so two custom shapes that previously used the same type name in different files now collide. Pick a unique name for each, and remember the rename ripples beyond the type alias:
+
+- `static override type = '...'` on the `ShapeUtil` subclass
+- Every `editor.createShape({ type: '...' })` and `editor.updateShape({ type: '...' })` call site
+- The `TLGlobalShapePropsMap` entry itself
+- Any persisted snapshot or migration JSON that references the old name
+
+**Use `as const` on the static `type` field.** TypeScript may widen `static override type = 'my-shape'` to `string`, which fails the new constraint. Add `as const` to keep it a string literal:
+
+```ts
+class MyShapeUtil extends ShapeUtil`<MyShape>` {
+	static override type = 'my-shape' as const
+	// ...
+}
+```
+
+The same fix applies to `BaseBoxShapeTool` (and other tool) subclasses, which expose `static override shapeType = '...'`. If you see TS2416 on a tool's `shapeType`, add `as const` there too. The two fields are easy to confuse — check both.
+
+**Heterogeneous `createShapes`/`updateShapes` arrays may need a cast.** Because `TLShape` is now a discriminated union over the global props map, a mapped array of mixed shape types no longer narrows automatically. For homogeneous arrays where every item shares one shape type, `as const` on the `type` field in the mapped object literal is enough. For genuinely heterogeneous arrays, go straight to `as TLShapePartial[]` (or `as TLCreateShapePartial[]` for `createShapes`):
+
+```ts
+// Heterogeneous update — the union doesn't narrow
+editor.updateShapes(
+	shapes.map((s) => ({ id: s.id, type: s.type, x: s.x + 10 })) as TLShapePartial[]
+)
+```
+
+Don't reach for `satisfies TLShapePartial` here — `TLShapePartial` is distributive over the `TLShape` union, so `satisfies` enforces a literal-per-variant constraint that mapped-over heterogeneous shapes can't meet. The cast is the right tool for this specific shape of code.
 
 </details>
 
diff --git a/skills/tldraw-migrate/SKILL.md b/skills/tldraw-migrate/SKILL.md
index 307fd4562682..b1c7bbf580de 100644
--- a/skills/tldraw-migrate/SKILL.md
+++ b/skills/tldraw-migrate/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: tldraw-migrate
 description: Migrate a project to a newer version of the tldraw SDK. Use when upgrading tldraw packages, fixing TypeScript errors after a tldraw upgrade, or when the user mentions tldraw migration.
-argument-hint: '[previous-version]'
+argument-hint: '[from-version] [target]'
 disable-model-invocation: true
 user-invocable: true
 ---
@@ -10,16 +10,33 @@ user-invocable: true
 
 You are helping migrate a project to a newer version of the tldraw SDK. Follow this process carefully.
 
-Previous version (auto-detected from git history; pass an explicit version as `/tldraw-migrate <version>` to override): !`node ${CLAUDE_SKILL_DIR}/detect-versions.mjs $ARGUMENTS`
+Throughout this skill, `${SKILL_DIR}` refers to this skill's own directory (where `SKILL.md`, the helper `.mjs` scripts, and the cached `references/` folder live). The auto-fetch blocks below resolve it from the `SKILL_DIR` env var if set, otherwise probe the common skill locations (`.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `skills/`). When you run shell commands later in the workflow that reference `${SKILL_DIR}`, substitute the same absolute path.
+
+**Arguments**: `/tldraw-migrate [from-version] [target]`. Both optional. `from-version` defaults to the previous tldraw version detected from git history. `target` defaults to `latest` (the latest stable release on npm); pass a dist-tag (`canary`, `next`, `beta`) or a pre-release semver (e.g. `4.6.0-canary.abc123`) to migrate to a pre-release.
+
+Resolved migration: !`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && FROM=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS) && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && echo "from $FROM → target $TARGET"`
 
 ## Resources (auto-fetched on invocation)
 
-!`mkdir -p ${CLAUDE_SKILL_DIR}/references && CHANGELOG=${CLAUDE_SKILL_DIR}/references/tldraw-releases.txt && PREV=$(node ${CLAUDE_SKILL_DIR}/detect-versions.mjs $ARGUMENTS) && curl --fail -sS https://tldraw.dev/llms-releases.txt | node ${CLAUDE_SKILL_DIR}/filter-changelog.mjs "$PREV" > "$CHANGELOG" && echo "Saved changelog (from $PREV) to $CHANGELOG ($(wc -l < "$CHANGELOG") lines)"`
+!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && CHANGELOG="$SKILL_DIR/references/tldraw-releases.txt" && PREV=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS) && [ -n "$PREV" ] && curl --fail -sS https://tldraw.dev/llms-releases.txt | node "$SKILL_DIR/filter-changelog.mjs" "$PREV" > "$CHANGELOG" && echo "Saved changelog (from $PREV) to $CHANGELOG ($(wc -l < "$CHANGELOG") lines)"`
 
-!`DOCS=${CLAUDE_SKILL_DIR}/references/tldraw-full-docs.txt && if [ -s "$DOCS" ]; then echo "Using cached full docs at $DOCS ($(wc -l < "$DOCS") lines) — delete the file to refresh"; else curl --fail -sS https://tldraw.dev/llms-full.txt -o "$DOCS" && echo "Saved full docs to $DOCS ($(wc -l < "$DOCS") lines)"; fi`
+!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && DOCS="$SKILL_DIR/references/tldraw-full-docs.txt" && if [ -s "$DOCS" ]; then echo "Using cached full docs at $DOCS ($(wc -l < "$DOCS") lines) — delete the file to refresh"; else curl --fail -sS https://tldraw.dev/llms-full.txt -o "$DOCS" && echo "Saved full docs to $DOCS ($(wc -l < "$DOCS") lines)"; fi`
 
-- **[Filtered changelog](references/tldraw-releases.txt)** — release notes for versions between the previous version and now. Read this first to understand what changed.
+!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && case "$TARGET" in canary|next|beta|alpha|rc|*-canary*|*-next*|*-beta*|*-alpha*|*-rc*) NEXT="$SKILL_DIR/references/tldraw-next.mdx" && curl --fail -sS https://raw.githubusercontent.com/tldraw/tldraw/main/apps/docs/content/releases/next.mdx -o "$NEXT" && echo "Pre-release target ($TARGET) — saved next-release notes to $NEXT ($(wc -l < "$NEXT") lines)" ;; *) echo "Stable target ($TARGET) — skipping next-release notes" ;; esac`
+
+- **[Filtered changelog](references/tldraw-releases.txt)** — release notes for stable versions between the previous version and now. Each breaking change (marked `💥`) carries a `<details><summary>Migration guide</summary>` block with a before/after recipe. **These migration blocks are the primary source for version-specific fixes** — this skill intentionally does not duplicate them. When you hit a TS error, grep for the relevant API name in this file and read its migration block.
 - **[Full docs](references/tldraw-full-docs.txt)** — complete tldraw SDK docs (~1.5MB). Do NOT read this upfront. Use Grep or Read with line ranges to search for specific topics as needed (e.g., custom shapes, TLTextOptions).
+- **[Next-release notes](references/tldraw-next.mdx)** — *only present when the target is a pre-release.* The in-progress release notes (raw MDX from `main`) for the upcoming version. Same `<details><summary>Migration guide</summary>` structure. The stable changelog won't cover canary/next deltas; this file is where you'll find them.
+
+**Searching for migration recipes:**
+
+```sh
+# List every breaking change with a migration block
+grep -nE '💥|<summary>Migration guide' ${SKILL_DIR}/references/tldraw-next.mdx
+
+# Find the migration recipe for a specific symbol
+grep -n -B2 -A20 'getIndicatorPath\|TLUserStore\|EmbedShapeUtil' ${SKILL_DIR}/references/tldraw-next.mdx
+```
 
 ## Step 1: Understand the environment
 
@@ -27,87 +44,100 @@ Before making any changes, scan the project to understand what you're working wi
 
 - **Package manager**: Check for lock files (`yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`, `package-lock.json`). Use the corresponding tool throughout.
 - **tldraw packages**: `grep -E "tldraw|@tldraw" package.json` — which packages are installed, and at what versions? Note: not every project uses all tldraw packages.
-- **Import style**: `grep -r "from '@tldraw/" src/ --include="*.ts" --include="*.tsx" -l | head -5` — does the project import from `'tldraw'`, `'@tldraw/editor'`, or both? This affects module augmentation targets.
-- **TypeScript**: Check `package.json` for a `typecheck` or `tsc` script. Also check the TypeScript version — is it a direct dependency or does the project rely on a global install?
+- **Source directory**: figure out where the project's TypeScript sources live (commonly `src/`, `app/`, or `lib/`; Next.js App Router projects don't have `src/`). Use this directory for every grep below — don't assume `src/`.
+- **Import style**: `grep -r "from '@tldraw" <source-dir> --include="*.ts" --include="*.tsx" -l | head -5` — does the project import from `'tldraw'`, `'@tldraw/editor'`, or both? This affects module augmentation targets.
+- **TypeScript**: Check `package.json` for a `typecheck` or `tsc` script. If neither exists, fall back to `npx tsc --noEmit` (TypeScript is usually a devDependency). Also check the TypeScript version.
 - **Build tool**: Check `package.json` scripts for the build command (vite, next, webpack, esbuild, etc.)
 - **Linter**: Check for eslint/biome config files (`.eslintrc*`, `eslint.config.*`, `biome.json`). A linter may help catch deprecations later.
 - **Monorepo**: Is `package.json` at the working directory root, or is this a nested package? Check for workspaces config.
 
 ## Step 2: Upgrade packages
 
-Using the detected package manager, upgrade all tldraw packages that are already in the project's dependencies to the latest version. Don't add new packages the project doesn't already use.
+Using the detected package manager, upgrade all tldraw packages that are already in the project's dependencies to the resolved target (printed in the "Resolved migration" line above). Don't add new packages the project doesn't already use.
+
+- For a stable target (`latest` or a stable semver): install at that tag/version, e.g. `yarn add tldraw@latest` or `npm install tldraw@4.5.10`.
+- For a pre-release target (`canary`, `next`, `beta`, or a pre-release semver): install at that tag/version, e.g. `yarn add tldraw@canary`. If multiple `@tldraw/*` packages are listed, pin them all to the same target to avoid version skew.
 
 ## Step 3: Identify all TypeScript errors
 
 Run the project's typecheck command (from Step 1) and categorize the errors:
 
-1. **Count errors by TS code** (e.g., TS2344, TS2786) to understand the distribution
-2. **List unique files with errors** to understand the scope
-3. **Identify error patterns** — common categories in tldraw upgrades:
-   - React types mismatch (TS2786 "cannot be used as JSX component") — usually means `@types/react` version doesn't match what tldraw bundles. To find the bundled version: with npm or yarn classic, check `node_modules/@tldraw/editor/node_modules/@types/react/package.json`; with pnpm or yarn berry, run the package manager's "why" command (e.g. `pnpm why @types/react`, `yarn why @types/react`) to see the resolved range.
-   - Custom shape type registration (TS2344 "does not satisfy constraint TLShape/TLBaseBoxShape") — tldraw v4.3+ requires module augmentation of `TLGlobalShapePropsMap`
-   - Custom binding type registration — same pattern with `TLGlobalBindingPropsMap`
-   - `BaseBoxShapeTool.shapeType` type mismatch (TS2416) — needs `as const`
-   - API renames/removals (TS2305, TS2724) — check changelog for specific migrations
-   - `createShapes`/`updateShapes` type widening (TS2345) — mapped arrays need `TLShapePartial` or `TLCreateShapePartial` casts
+1. **Count errors by TS code** (e.g., TS2344, TS2786) to understand the distribution.
+2. **List unique files with errors** to understand the scope.
+3. **Identify error patterns.** The categories below are version-agnostic — they describe the *shape* of common errors. The *specific* fix for each rename, removal, or signature change lives in the release-notes migration blocks (see "Searching for migration recipes" above), not in this skill.
+
+   - **TS2786** "cannot be used as JSX component" / "bigint not assignable to ReactNode": React types skew. `@types/react` (and usually `@types/react-dom`) don't match the version tldraw bundles. To find the bundled version: with npm or yarn classic, check `node_modules/@tldraw/editor/node_modules/@types/react/package.json`; with pnpm or yarn berry, run the package manager's "why" command (e.g. `pnpm why @types/react`).
+   - **TS2344** "does not satisfy constraint TLShape/TLBaseBoxShape" / **TS2416** `shapeType` mismatch: custom shape or binding type isn't registered for the new global props maps. Fix pattern in 4b.
+   - **TS2305** / **TS2724** "has no exported member" / "is not exported": API removed or renamed. Find the replacement in the matching `Migration guide` block in `tldraw-releases.txt` / `tldraw-next.mdx`.
+   - **TS2339** "property does not exist": API renamed or method signature changed. Same lookup.
+   - **TS2515** "non-abstract class does not implement inherited abstract member": a base class gained a required method. The error names the method — search the migration blocks for that method name. (Note: if your implementation only throws, TypeScript may infer `never`; add an explicit return type to satisfy the base class signature.)
+   - **TS2345** on `createShapes`/`updateShapes`: heterogeneous mapped arrays need `as TLShapePartial[]` / `as TLCreateShapePartial[]` casts. See 4e.
+   - **TS2345** with two structurally-similar `Editor` classes resolving to different paths under `node_modules/@tiptap/core` and `node_modules/@tldraw/editor/node_modules/@tiptap/core`: TipTap v2/v3 dual install. See 4d.
 
 ## Step 4: Fix errors in order of impact
 
-Fix in this order (each fix eliminates many downstream errors):
+Fix in this order (each fix eliminates many downstream errors). After each sub-step, re-run the project's typecheck and confirm that the error codes targeted by *that* sub-step are resolved (or at least decreasing). Ignore unrelated error codes — they belong to later sub-steps. This catches regressions early without blocking on errors you haven't gotten to yet.
 
 ### 4a. Fix React types
 
-If you see TS2786 "bigint not assignable to ReactNode" errors, upgrade `@types/react` and `@types/react-dom` to match tldraw's bundled version.
+If you see TS2786 "bigint not assignable to ReactNode" errors, upgrade `@types/react` AND `@types/react-dom` together to match tldraw's bundled version. Bumping only `@types/react` will leave a transitive dependency on the old `@types/react-dom` and the same errors will reappear from a different path (e.g. inside `TldrawUiToolbarButton`).
+
+**Verify**: re-run typecheck — TS2786 errors should be gone.
 
 ### 4b. Register custom shapes and bindings
 
-For every `TLBaseShape<'name', Props>` in the codebase, add module augmentation. Use the import style detected in Step 1 as the module target:
-
-```ts
-declare module 'tldraw' {
-	interface TLGlobalShapePropsMap {
-		'shape-name': {
-			/* props */
-		}
-	}
-}
-type MyShape = TLShape<'shape-name'>
+If you see TS2344 ("does not satisfy constraint `TLShape`/`TLBaseBoxShape`") or TS2416 (`shapeType` mismatch) errors, the project is using the pre-v4.3 `TLBaseShape<'name', Props>` pattern and needs to migrate to `TLGlobalShapePropsMap` module augmentation.
+
+The full recipe — module augmentation for shapes and bindings, the rename ripple when shape names collide, `as const` on `static override type` / `static override shapeType`, and the heterogeneous `createShapes`/`updateShapes` cast guidance — lives in the v4.3 release notes migration block. Find it with:
+
+```sh
+grep -n -B2 -A80 'TLGlobalShapePropsMap' ${SKILL_DIR}/references/tldraw-releases.txt
 ```
 
-Same pattern for bindings with `TLGlobalBindingPropsMap` and `TLBinding<'name'>`.
+Apply that recipe across the project. Use the import style detected in Step 1 as the module-augmentation target (`declare module 'tldraw'` vs. `declare module '@tldraw/editor'`).
 
-**IMPORTANT**: If multiple files use the same shape type name with different props, rename them to be unique — they all share the global type registry.
+**Verify**: re-run typecheck — TS2344 and TS2416 errors should be gone.
 
-Add `as const` to all `static override shapeType = '...'` properties.
+### 4c. Fix API renames, removals, and abstract-method additions
 
-### 4c. Fix API renames and removals
+This is where the version-specific work happens, and it's driven entirely by the release-notes migration blocks. The skill does *not* enumerate which APIs changed — that's the changelog's job, and it would go stale on every release.
 
-Cross-reference each TS2305/TS2724/TS2339 error with the changelog. Common patterns:
+For each TS2305 / TS2724 / TS2339 / TS2515 error:
 
-- Removed exports: find replacement by grepping the tldraw type definitions
-- Renamed properties: check changelog for the new name
-- Changed method signatures: check the current type definitions
+1. Pull the symbol name out of the error.
+2. Grep the migration blocks for it: `grep -n -B2 -A20 'SymbolName' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx`.
+3. Apply the recipe shown in the matching `Migration guide` block. Migration blocks contain before/after code snippets; copy the structure.
 
-To find tldraw type definitions, check which paths exist — the location varies by version:
+If the symbol isn't in any migration block:
 
-- `node_modules/tldraw/dist-cjs/index.d.ts`
-- `node_modules/tldraw/dist/index.d.ts`
-- `node_modules/@tldraw/editor/dist-cjs/index.d.ts`
-- `node_modules/@tldraw/tlschema/dist-cjs/index.d.ts`
+- **Demoted to `@internal`** (still exported at runtime, but missing from `.d.ts`): check whether a `<details><summary>Migration guide</summary>` mentions it as part of a larger API. The right fix is almost always to switch to the public replacement, *not* to use module augmentation to re-expose the symbol. If you reach for `declare module 'tldraw' { export function X(): ... }`, stop — find the public replacement instead.
+- **Truly unmentioned**: check the type defs in `node_modules/tldraw/dist-cjs/index.d.ts`, `node_modules/@tldraw/editor/dist-cjs/index.d.ts`, or `node_modules/@tldraw/tlschema/dist-cjs/index.d.ts` (the layout varies by version and package manager). If the symbol is genuinely gone with no listed replacement, treat the gap as a documentation bug worth flagging in your final report.
+
+For TS2515 (newly-required abstract method): if your implementation only throws, declare the return type explicitly so TypeScript doesn't infer `never` and the abstract-mismatch error doesn't linger.
+
+**Verify**: re-run typecheck — count TS2305, TS2724, TS2339, and TS2515 errors before and after. Each fix should knock out one error. If counts haven't dropped, you missed a migration block — re-grep before continuing.
 
 ### 4d. Fix TipTap imports if needed
 
-If the project uses TipTap (`@tiptap/*` in dependencies or imports), the tldraw upgrade may require upgrading TipTap as well. Starting with tldraw v4.2, tldraw bundles TipTap v3 as a transitive dependency. If the project pins TipTap v2 packages directly, this will cause version conflicts and broken imports. **Upgrade the project's direct `@tiptap/*` dependencies to v3** to match what tldraw expects — leaving them on v2 will not work.
+**Skip this entire sub-step if the project has no `@tiptap/*` dependencies or imports.** Confirm with `grep -E '@tiptap/' package.json` and a recursive grep for `from '@tiptap` in the source directory. If both come back empty, jump to 4e.
 
-After upgrading, fix any breaking TipTap v2 → v3 changes:
+If the project uses TipTap, your migration may need to cross the v2 → v3 cutover (introduced in tldraw v4.2). The full v2 → v3 recipe — dual-install diagnostic, default-to-named export changes, `TextStyle`/`TextStyleKit`/`FontFamily` reorganization, transaction-handler types — lives in the v4.2 release notes migration block. Find it with:
 
-- **Default → named exports**: If a default import fails, switch to a named import: `import StarterKit from '@tiptap/starter-kit'` → `import { StarterKit } from '@tiptap/starter-kit'`
-- **Renames**: If a named import fails, check the package's actual exports: `grep 'export' node_modules/@tiptap/<package>/dist/index.js | head` — some extensions were renamed in TipTap v3 (e.g., `TextStyle` → `TextStyleKit`).
-- **Transaction handler types**: If TipTap event handler types break, import the proper types: `import { EditorEvents } from '@tiptap/core'` and type handlers as `(props: EditorEvents['transaction']) => void` rather than inline type annotations.
+```sh
+grep -n -B2 -A60 'TipTap v3' ${SKILL_DIR}/references/tldraw-releases.txt
+```
+
+Apply that recipe. The tldraw skill only adds two version-agnostic notes on top:
+
+> **Install ordering trap (any TipTap upgrade).** Running `npm install @tiptap/core@3 @tiptap/starter-kit@3 ...` against a project that already has v2 in `node_modules` will fail with `ERESOLVE`, because the v2 `starter-kit` declares `peer @tiptap/core@^2.7`. Either uninstall the v2 packages first (`npm uninstall @tiptap/core @tiptap/starter-kit ...`) or pass `--legacy-peer-deps`.
+
+> **Custom chained commands.** Whatever TipTap version, custom chain commands register via `declare module '@tiptap/core'` augmentation. This is a TipTap idiom, not a tldraw one — see TipTap's docs.
+
+**Verify**: re-run typecheck — TipTap import and type errors should be gone.
 
 ### 4e. Fix remaining type errors
 
-- `createShapes`/`updateShapes` with `.map()`: The proper fix is to add `as const` to the `type` field in the mapped object literal so TypeScript narrows it to the string literal type. If that's not sufficient, use a `satisfies` annotation on the return value. Only as a last resort, cast the result to `TLCreateShapePartial` or `TLShapePartial`.
+- `createShapes`/`updateShapes` with `.map()`: see the v4.3 migration block for the full recipe (`as const` on the `type` field for homogeneous arrays; `as TLShapePartial[]` / `as TLCreateShapePartial[]` for heterogeneous ones; *not* `satisfies TLShapePartial`).
 - TipTap extension commands not on `ChainedCommands`: use `declare module '@tiptap/core'` augmentation to register custom commands.
 - **General rule**: every `as` cast you add is tech debt. Before adding one, exhaust these alternatives in order:
   1. `as const` on object literals to narrow string literal types
@@ -116,15 +146,37 @@ After upgrading, fix any breaking TipTap v2 → v3 changes:
   4. Module augmentation to teach TypeScript about your types
   5. Only then, a targeted `as` cast with a comment explaining why it's needed
 
+**Verify**: re-run typecheck — remaining errors should all be resolved. If any remain, re-categorize and route them back to 4a–4d as appropriate.
+
 ## Step 5: Fix deprecations
 
-After all type errors are resolved, find and fix deprecated API usage. These still compile but should be migrated.
+After all type errors are resolved, find and fix `@deprecated` API usage. These still compile but should be migrated.
+
+1. **Find deprecated symbols.** The changelog is the most reliable starting point — tldraw's `.d.ts` files use multi-line JSDoc, so grepping the type defs is fragile (the declaration line is typically 2–5 lines after the `@deprecated` tag, not adjacent to it).
+
+   Start here:
 
-1. **Find deprecated symbols** — grep the tldraw type definitions for `@deprecated` annotations. Also search the changelog for "deprecated" in `${CLAUDE_SKILL_DIR}/references/tldraw-releases.txt`.
+   ```sh
+   grep -i 'deprecated' ${SKILL_DIR}/references/tldraw-releases.txt
+   ```
 
-2. **Check if a linter is configured** — look for eslint, biome, or other linting config in the project. If available, run the linter — it may flag deprecated usage automatically (e.g., eslint's `deprecation/deprecation` rule). If no linter is configured, skip to step 3.
+   When the target is a pre-release, also: `grep -i 'deprecated' ${SKILL_DIR}/references/tldraw-next.mdx`.
 
-3. **Search the project source** for each deprecated symbol found in step 1. Replace with the recommended alternative from the `@deprecated` JSDoc comment or changelog.
+   To cross-check against the type defs (one package at a time — repeat for each `@tldraw/*` package the project imports from, and `tldraw` itself), use `-A` not `-B`:
+
+   ```sh
+   grep -A5 '@deprecated' node_modules/@tldraw/editor/dist-cjs/index.d.ts \
+     | grep -oE '\b(class|function|interface|const|type|let|var)\s+\w+' \
+     | awk '{print $NF}' | sort -u
+   ```
+
+   This catches multi-line JSDoc but produces some false positives — treat the output as a candidate list, not an authoritative one. The changelog grep is what you should drive from.
+
+2. **Run the linter if configured** — eslint's `deprecation/deprecation` rule will flag deprecated imports automatically. If no linter is configured, skip this step.
+
+3. **Search the project source** for each deprecated symbol. Replace with the recommended alternative from the `@deprecated` JSDoc comment, the changelog entry, or the docs.
+
+4. **Sanity-check renames the typecheck didn't catch.** If the changelog or `tldraw-next.mdx` describes a rename and the project still imports the old name, TypeScript may resolve it through a wildcard re-export and miss it. Skim the changelog/next.mdx for "renamed" / "moved to" entries and grep the source for any old names you find.
 
 ## Step 6: Verify
 
@@ -136,9 +188,18 @@ If errors remain, repeat the categorize-and-fix cycle.
 
 After all errors are resolved, do a quick audit:
 
-1. **Count `as` casts before vs after**: Run `grep -rn ' as ' --include='*.ts' --include='*.tsx' src/` and compare against the same grep on the pre-migration code (use `git stash` or `git show HEAD:path`). **The migration should add no more than a small handful of new casts** (ideally zero). If you added more than ~5 new `as` casts across the entire migration, go back and fix them — you are almost certainly using the new API incorrectly.
-2. **Review every cast you added**: For each new `as` cast, verify it's truly necessary by checking whether `as const`, `satisfies`, generic type parameters, or module augmentation could replace it. Remove or replace any that have a cleaner alternative.
-3. **Verify no stubs or dead code**: If you stubbed out removed APIs (e.g., replaced a removed function with a no-op), make sure the calling code doesn't depend on the return value. If it does, find the proper replacement in the changelog or docs.
+1. **Count typed `as` casts added by this migration.** A naive `grep ' as '` overcounts because it includes `as const` (the recommended narrowing pattern) and `as` in import paths. Drive off the diff and filter:
+
+   ```sh
+   git diff -- '<source-dir>/**/*.ts' '<source-dir>/**/*.tsx' \
+     | grep -E '^\+' | grep -v '^+++' \
+     | grep -E '\bas\s+[A-Z]' | grep -v 'as const'
+   ```
+
+   **The migration should add no more than a small handful of new typed casts** (ideally zero, with `as TLShapePartial[]` / `as TLCreateShapePartial[]` for heterogeneous `createShapes`/`updateShapes` arrays as the main legitimate exception). If you added more than ~5 across the whole migration, go back and fix them — you are almost certainly using the new API incorrectly.
+2. **Review every typed cast you added**: For each, verify it's truly necessary by checking whether `as const`, `satisfies`, generic type parameters, or module augmentation could replace it. Remove or replace any that have a cleaner alternative.
+3. **Audit module augmentations.** Module augmentation is correct for `TLGlobalShapePropsMap` / `TLGlobalBindingPropsMap` registration and for adding genuinely-missing public types. It is **not** correct for re-exposing symbols that the SDK demoted to `@internal` — that's a workaround, not a fix. Find the public replacement instead (the migration block usually names it).
+4. **Verify no stubs or dead code**: If you stubbed out removed APIs (e.g., replaced a removed function with a no-op), make sure the calling code doesn't depend on the return value. If it does, find the proper replacement in the migration blocks or docs.
 
 ## Quality checks
 
@@ -146,10 +207,10 @@ After all errors are resolved, do a quick audit:
 - **Prefer TypeScript's narrowing features over casts.** Use `as const` for literal types, `satisfies` for type-checking without widening, generic parameters for call sites, and module augmentation for extending interfaces. These are the right tools for a migration — `as` casts are not.
 - Use parallel agents for fixing large batches of files with the same pattern.
 - **Don't just make errors go away — understand the new API.** When a method signature changes (e.g., new parameters added, property renamed to a richer type), read the changelog AND the current type definitions to understand _why_ it changed. A fix that compiles but passes hardcoded/dummy values where the new API expects real data is worse than a type error — it silently degrades behavior. For example, if a function gains new required parameters, check what shape props or editor state should feed those parameters rather than passing `0` or `1`.
-- **When unsure about an API pattern**, grep the full docs (`${CLAUDE_SKILL_DIR}/references/tldraw-full-docs.txt`) for usage examples of that specific API. The docs contain code samples that show the canonical way to use each API.
+- **When unsure about an API pattern**, grep the full docs (`${SKILL_DIR}/references/tldraw-full-docs.txt`) for usage examples of that specific API. The docs contain code samples that show the canonical way to use each API.
 
 ## Tips
 
-- Read `${CLAUDE_SKILL_DIR}/references/tldraw-releases.txt` for the filtered changelog — this is the primary source for what changed
-- Grep `${CLAUDE_SKILL_DIR}/references/tldraw-full-docs.txt` when you need docs on a specific API
+- Read `${SKILL_DIR}/references/tldraw-releases.txt` for the filtered changelog — this is the primary source for what changed
+- Grep `${SKILL_DIR}/references/tldraw-full-docs.txt` when you need docs on a specific API
 - When searching tldraw types, try multiple paths — the dist directory structure varies by version and package manager
diff --git a/skills/tldraw-migrate/detect-target.mjs b/skills/tldraw-migrate/detect-target.mjs
new file mode 100644
index 000000000000..fc84e2f0ec99
--- /dev/null
+++ b/skills/tldraw-migrate/detect-target.mjs
@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Resolves the migration *target* (what version/tag to upgrade TO) from
+ * the skill's $ARGUMENTS, and writes it to stdout.
+ *
+ * Argument forms supported:
+ *   /tldraw-migrate                       → "latest"
+ *   /tldraw-migrate 4.4.0                 → "latest" (single semver = from-version)
+ *   /tldraw-migrate canary                → "canary" (single tag/pre-release = target)
+ *   /tldraw-migrate 4.4.0 canary          → "canary" (two args: <from> <target>)
+ *   /tldraw-migrate 4.4.0 4.6.0-canary.x  → "4.6.0-canary.x"
+ *
+ * Outputs just the resolved target with no trailing newline so it can be
+ * interpolated directly in shell.
+ */
+
+const args = process.argv
+	.slice(2)
+	.map((a) => a.trim())
+	.filter(Boolean)
+
+const STABLE_SEMVER = /^v?\d+\.\d+\.\d+$/
+
+function emit(target) {
+	process.stdout.write(target)
+	process.exit(0)
+}
+
+if (args.length === 0) emit('latest')
+if (args.length >= 2) emit(args[args.length - 1])
+
+// Single arg: stable semver = from-version (target defaults), anything else = target.
+const only = args[0]
+emit(STABLE_SEMVER.test(only) ? 'latest' : only)
diff --git a/skills/write-release-notes/SKILL.md b/skills/write-release-notes/SKILL.md
index 94b6bb6caba8..bf4b97faed24 100644
--- a/skills/write-release-notes/SKILL.md
+++ b/skills/write-release-notes/SKILL.md
@@ -82,7 +82,46 @@ Create `apps/docs/content/releases/vX.Y.0.mdx` following the style guide.
 5. Add patch release sections if applicable
 6. Add GitHub release links
 
-### 6. Verify
+### 6. Write a migration guide for every breaking change
+
+Every `💥` in the article needs a migration recipe. The `tldraw-migrate` skill drives off these recipes — it intentionally does not duplicate them in its own SKILL.md, because version-specific knowledge belongs next to the breaking change that introduced it. If the recipe is missing, agents and contributors performing the upgrade have to reverse-engineer it from type defs.
+
+There are two acceptable forms:
+
+**For breaking changes with their own featured section** (renames, replaced APIs, new patterns), add a `<details><summary>Migration guide</summary>` block under the section. Include before/after code and call out any silent-compile traps (props the typecheck won't reject, signatures with optional new parameters, etc.):
+
+````mdx
+### 💥 Custom themes with display values
+
+[Description of what changed and why]
+
+<details>
+<summary>Migration guide</summary>
+
+`getDefaultColorTheme()` and `DefaultColorThemePalette` have been removed. Use `editor.getCurrentTheme().colors[colorMode]` instead:
+
+```tsx
+// Before
+const theme = getDefaultColorTheme({ isDarkMode })
+
+// After
+const theme = editor.getCurrentTheme()
+const colors = theme.colors[editor.getColorMode()]
+```
+
+</details>
+````
+
+**For one-line `💥` entries in the API changes list**, the bullet itself must contain the recipe — name the replacement and any caveats inline:
+
+- ✅ `💥 Replace TLDrawShapeSegment.points with the helper getPointsFromDrawSegment(segment, scaleX, scaleY) so segment points respect the shape's current scale.`
+- ❌ `💥 Remove TLDrawShapeSegment.points.` (no replacement → reader has to guess)
+
+A symbol that is removed without a replacement is a documentation bug — find the public alternative or, if there genuinely isn't one, say so explicitly so readers know to drop the call site rather than searching for a rename.
+
+**Special case — `@public` → `@internal` demotions:** these compile but disappear from public types. They are still breaking changes for consumers who imported the symbol. Treat them like a removal: mark with `💥`, name the public replacement, and explicitly tell readers *not* to reach for module augmentation to re-expose the demoted symbol.
+
+### 7. Verify
 
 Check that:
 
@@ -90,6 +129,7 @@ Check that:
 - PR links are correct and formatted properly
 - Community contributors are credited
 - Breaking changes are marked with 💥
+- **Every `💥` has either a migration guide block or an inline replacement** (run `grep -nE '💥' apps/docs/content/releases/<file>.mdx` and verify each bullet/section)
 - Sections are in the correct order
 
 ## References

From febe9b9e3ddbc1eaa69f9c4994ccf1e77011c6a3 Mon Sep 17 00:00:00 2001
From: angrycaptain19 <53473467+angrycaptain19@users.noreply.github.com>
Date: Wed, 6 May 2026 12:09:03 +0100
Subject: [PATCH 09/11] docs: fixes pre 5.0 (#8580)

I went through all of our docs pages to check for things that seemed to
be out of date with changes from 4.0 -> now and which will have changed
by 5.0. Mainly changing a few examples where methods have changed, but
also fixes a few example code blocks that caused errors



### Change type

- [ ] `bugfix`
- [ ] `improvement`
- [ ] `feature`
- [ ] `api`
- [x] `other`

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 apps/docs/content/docs/handles.mdx            |  24 ++-
 apps/docs/content/docs/sync.mdx               |  64 +++++++
 apps/docs/content/sdk-features/assets.mdx     |  84 ++++++++-
 apps/docs/content/sdk-features/bindings.mdx   |   4 +-
 apps/docs/content/sdk-features/camera.mdx     |   2 +-
 apps/docs/content/sdk-features/clipboard.mdx  |   6 +
 apps/docs/content/sdk-features/deep-links.mdx |   8 +-
 .../content/sdk-features/default-shapes.mdx   |   9 +-
 apps/docs/content/sdk-features/draw-shape.mdx |  28 +--
 .../docs/content/sdk-features/embed-shape.mdx |  14 +-
 .../docs/content/sdk-features/environment.mdx |  22 +++
 .../docs/content/sdk-features/frame-shape.mdx | 160 ++++++++++++++++--
 apps/docs/content/sdk-features/geo-shape.mdx  |  80 +++++++--
 apps/docs/content/sdk-features/handles.mdx    |  24 ++-
 .../content/sdk-features/image-export.mdx     |  18 +-
 .../sdk-features/internationalization.mdx     |  10 +-
 apps/docs/content/sdk-features/note-shape.mdx |   7 +
 apps/docs/content/sdk-features/options.mdx    |  58 +++++--
 .../docs/content/sdk-features/performance.mdx |  24 +++
 .../content/sdk-features/shape-transforms.mdx |   2 +-
 apps/docs/content/sdk-features/shapes.mdx     |   4 +-
 apps/docs/content/sdk-features/store.mdx      | 109 ++++++++++++
 apps/docs/content/sdk-features/styles.mdx     |   3 +-
 apps/docs/content/sdk-features/themes.mdx     |   4 +-
 .../content/sdk-features/ui-components.mdx    |   1 +
 .../docs/content/starter-kits/multiplayer.mdx |  55 ++++--
 .../configuration/camera-options/README.md    |   2 +-
 27 files changed, 703 insertions(+), 123 deletions(-)

diff --git a/apps/docs/content/docs/handles.mdx b/apps/docs/content/docs/handles.mdx
index d605ed6f7d14..76043a91c445 100644
--- a/apps/docs/content/docs/handles.mdx
+++ b/apps/docs/content/docs/handles.mdx
@@ -168,7 +168,15 @@ The `HandleSnapGeometry` object has these properties:
 Here's a speech bubble shape with a draggable tail handle:
 
 ```tsx
-import { Polygon2d, ShapeUtil, TLHandle, TLHandleDragInfo, TLShape, ZERO_INDEX_KEY } from 'tldraw'
+import {
+	Polygon2d,
+	ShapeUtil,
+	TLHandle,
+	TLHandleDragInfo,
+	TLShape,
+	Vec,
+	ZERO_INDEX_KEY,
+} from 'tldraw'
 
 const SPEECH_BUBBLE_TYPE = 'speech-bubble'
 
@@ -191,13 +199,13 @@ class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
 		const { w, h, tailX, tailY } = shape.props
 		return new Polygon2d({
 			points: [
-				{ x: 0, y: 0 },
-				{ x: w, y: 0 },
-				{ x: w, y: h },
-				{ x: w * 0.7, y: h },
-				{ x: tailX, y: tailY },
-				{ x: w * 0.3, y: h },
-				{ x: 0, y: h },
+				new Vec(0, 0),
+				new Vec(w, 0),
+				new Vec(w, h),
+				new Vec(w * 0.7, h),
+				new Vec(tailX, tailY),
+				new Vec(w * 0.3, h),
+				new Vec(0, h),
 			],
 			isFilled: true,
 		})
diff --git a/apps/docs/content/docs/sync.mdx b/apps/docs/content/docs/sync.mdx
index 05d279e6a4da..25ca943c8c7b 100644
--- a/apps/docs/content/docs/sync.mdx
+++ b/apps/docs/content/docs/sync.mdx
@@ -181,6 +181,70 @@ const room = new TLSocketRoom({ storage })
 	`tablePrefix` option to avoid conflicts if you're sharing a database with other data.
 </Callout>
 
+### WebSocket hibernation
+
+Some serverless platforms let WebSocket connections survive while the surrounding object hibernates. [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/best-practices/websockets/) is the most common example. The platform keeps the sockets open, but your in-memory state (including the `TLSocketRoom`) is gone when the object wakes back up. Every wake would force every client to reconnect from scratch.
+
+`TLSocketRoom` exposes three APIs for hibernation. The `onSessionSnapshot` callback fires when a session has had no message activity for about 5 seconds, so you can persist its state. [TLSocketRoom#getSessionSnapshot](?) returns that snapshot on demand. [TLSocketRoom#handleSocketResume](?) restores a session straight into `Connected` state when the object wakes back up.
+
+Here's the pattern in a Cloudflare Durable Object that uses the WebSocket Hibernation API:
+
+```tsx
+import {
+	DurableObjectSqliteSyncWrapper,
+	type SessionStateSnapshot,
+	SQLiteSyncStorage,
+	TLSocketRoom,
+} from '@tldraw/sync-core'
+import { TLRecord } from '@tldraw/tlschema'
+import { DurableObject } from 'cloudflare:workers'
+
+interface SocketAttachment {
+	sessionId: string
+	snapshot?: SessionStateSnapshot
+}
+
+export class TldrawDurableObject extends DurableObject {
+	private room: TLSocketRoom<TLRecord, void> | null = null
+
+	private getOrCreateRoom() {
+		if (this.room) return this.room
+
+		const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage)
+		const storage = new SQLiteSyncStorage<TLRecord>({ sql })
+
+		this.room = new TLSocketRoom<TLRecord, void>({
+			storage,
+			// Cloudflare keeps WebSockets alive across hibernation, so let it manage timeouts.
+			clientTimeout: Infinity,
+			// Persist each session's snapshot to its WebSocket attachment when it goes idle.
+			onSessionSnapshot: (sessionId, snapshot) => {
+				const ws = this.sessionIdToWs.get(sessionId)
+				if (ws) ws.serializeAttachment({ sessionId, snapshot })
+			},
+		})
+
+		// Resume any sessions whose sockets survived hibernation.
+		for (const ws of this.ctx.getWebSockets()) {
+			const attachment = ws.deserializeAttachment() as SocketAttachment | null
+			if (attachment?.snapshot) {
+				this.room.handleSocketResume({
+					sessionId: attachment.sessionId,
+					socket: ws,
+					snapshot: attachment.snapshot,
+				})
+			}
+		}
+
+		return this.room
+	}
+}
+```
+
+Three pieces make this work. The `onSessionSnapshot` callback persists each session's state to its WebSocket's attachment so the snapshot is still around after hibernation. When the object wakes up with sockets still open, `handleSocketResume` replays each saved snapshot and the session lands straight in `Connected` state without the client noticing. Setting `clientTimeout: Infinity` disables the room's idle timer; hibernating platforms handle keep-alive themselves and would otherwise see the room disconnect perfectly fine clients.
+
+For non-hibernating environments (Node servers, long-lived processes), you don't need any of this. The in-memory `TLSocketRoom` outlives individual sockets, and the default `clientTimeout` keeps idle sessions tidy.
+
 ### Asset storage
 
 Tldraw also needs a way to store and retrieve large binary assets like images and videos.
diff --git a/apps/docs/content/sdk-features/assets.mdx b/apps/docs/content/sdk-features/assets.mdx
index 84b80f6133fc..2035232e8971 100644
--- a/apps/docs/content/sdk-features/assets.mdx
+++ b/apps/docs/content/sdk-features/assets.mdx
@@ -288,9 +288,89 @@ const assetStore: TLAssetStore = {
 
 ### Custom asset types
 
-You can define custom asset types by extending [TLBaseAsset](?). Create a validator with [createAssetValidator](?), then implement shapes that reference your custom assets.
+Custom asset types let you store domain-specific media alongside images, videos, and bookmarks. Each asset type has a corresponding [AssetUtil](?) that defines type-specific behavior: which MIME types it accepts, how to derive an asset record from a dropped file, and what default props new instances start with. The built-in `ImageAssetUtil`, `VideoAssetUtil`, and `BookmarkAssetUtil` follow this pattern and live in `defaultAssetUtils`.
 
-Custom asset types follow the same storage lifecycle as built-in types. Your upload, resolve, and remove handlers need to support them, and your custom shapes handle the rendering.
+`AssetUtil` is the asset-side counterpart to `ShapeUtil`. You register one util per type on the editor at startup, and the editor calls its methods whenever a file enters the system.
+
+Register your asset's props on `TLGlobalAssetPropsMap` via TypeScript module augmentation, then implement an `AssetUtil` for it:
+
+```typescript
+import { AssetUtil, TLAsset, TLAssetId } from 'tldraw'
+
+const AUDIO_TYPE = 'audio'
+
+declare module 'tldraw' {
+	export interface TLGlobalAssetPropsMap {
+		[AUDIO_TYPE]: {
+			src: string | null
+			mimeType: string | null
+			name: string
+		}
+	}
+}
+
+type TLAudioAsset = TLAsset<typeof AUDIO_TYPE>
+
+class AudioAssetUtil extends AssetUtil<TLAudioAsset> {
+	static override type = AUDIO_TYPE
+
+	override getDefaultProps(): TLAudioAsset['props'] {
+		return { src: null, mimeType: null, name: '' }
+	}
+
+	override getSupportedMimeTypes() {
+		return ['audio/mpeg', 'audio/wav', 'audio/ogg']
+	}
+
+	override async getAssetFromFile(file: File, assetId: TLAssetId): Promise<TLAudioAsset | null> {
+		return {
+			id: assetId,
+			typeName: 'asset',
+			type: AUDIO_TYPE,
+			props: {
+				src: null, // populated by the asset store after upload
+				mimeType: file.type,
+				name: file.name,
+			},
+			meta: {},
+		}
+	}
+}
+```
+
+Pass the util to the `<Tldraw>` component alongside whichever defaults you still want:
+
+```tsx
+import { Tldraw, defaultAssetUtils } from 'tldraw'
+
+const assetUtils = [...defaultAssetUtils, AudioAssetUtil]
+
+export default function App() {
+	return <Tldraw assetUtils={assetUtils} />
+}
+```
+
+When a file is dropped or pasted, the editor finds the first registered util whose `getSupportedMimeTypes()` includes the file's MIME type and calls its `getAssetFromFile()`. The returned asset record then flows through your `TLAssetStore.upload` handler, which assigns the final `src`. Custom shape utils that render audio (or whatever else you registered) read the resolved URL through `editor.resolveAssetUrl()` like the built-in shapes do.
+
+### Configuring built-in asset utils
+
+Use [AssetUtil#configure](?) to tweak options on a built-in util without subclassing it. For example, lock image uploads down to PNG:
+
+```tsx
+import { ImageAssetUtil, defaultAssetUtils, Tldraw } from 'tldraw'
+
+const PngOnlyImageAssetUtil = ImageAssetUtil.configure({
+	supportedMimeTypes: ['image/png'],
+})
+
+const assetUtils = defaultAssetUtils.map((util) =>
+	util === ImageAssetUtil ? PngOnlyImageAssetUtil : util
+)
+
+<Tldraw assetUtils={assetUtils} />
+```
+
+`ImageAssetUtil` and `VideoAssetUtil` both expose `maxDimension` and `supportedMimeTypes` options.
 
 ### Asset validation and migrations
 
diff --git a/apps/docs/content/sdk-features/bindings.mdx b/apps/docs/content/sdk-features/bindings.mdx
index 6a94c20aaeda..47afc9c0ad1a 100644
--- a/apps/docs/content/sdk-features/bindings.mdx
+++ b/apps/docs/content/sdk-features/bindings.mdx
@@ -142,9 +142,9 @@ Shapes control whether they accept bindings by implementing `canBind()` in their
 
 ```typescript
 class MyShapeUtil extends ShapeUtil<MyShape> {
-	canBind({ fromShapeType, toShapeType, bindingType }: TLShapeUtilCanBindOpts) {
+	canBind({ fromShape, toShape, bindingType }: TLShapeUtilCanBindOpts) {
 		// Only allow arrow bindings where this shape is the target
-		return bindingType === 'arrow' && toShapeType === this.type
+		return bindingType === 'arrow' && toShape.type === this.type
 	}
 }
 ```
diff --git a/apps/docs/content/sdk-features/camera.mdx b/apps/docs/content/sdk-features/camera.mdx
index 0c4bcf9af697..bf4e6ed304ae 100644
--- a/apps/docs/content/sdk-features/camera.mdx
+++ b/apps/docs/content/sdk-features/camera.mdx
@@ -147,7 +147,7 @@ Zoom in or out. Both methods accept an optional screen point to zoom toward:
 ```typescript
 editor.zoomIn()
 editor.zoomOut()
-editor.zoomIn(editor.inputs.currentScreenPoint, { animation: { duration: 200 } })
+editor.zoomIn(editor.inputs.getCurrentScreenPoint(), { animation: { duration: 200 } })
 ```
 
 ### Zoom to content
diff --git a/apps/docs/content/sdk-features/clipboard.mdx b/apps/docs/content/sdk-features/clipboard.mdx
index b7e501402ce0..49364734a37f 100644
--- a/apps/docs/content/sdk-features/clipboard.mdx
+++ b/apps/docs/content/sdk-features/clipboard.mdx
@@ -81,6 +81,12 @@ This embeds images and videos directly in the clipboard data rather than relying
 
 Cut combines copy and delete. The editor first copies the selected shapes to the clipboard, then deletes the originals. This order ensures the clipboard has the data before shapes disappear, preventing data loss if the copy fails.
 
+### Plain text paste
+
+`Cmd+Shift+V` (or `Ctrl+Shift+V` on Windows and Linux) pastes the clipboard as plain text. HTML and rich formatting are stripped. This is the standard "paste without formatting" shortcut. It's handy when styled text from a browser or word processor would otherwise bring its fonts and colors onto the canvas with it.
+
+To extend or override this behavior, use the `onClipboardPasteRaw` hook on [TldrawOptions](?). It fires before tldraw parses the clipboard, so you can read the raw `ClipboardEvent` data yourself. Return `false` to short-circuit the default pipeline, or `void` to let it continue.
+
 ## Content structure
 
 The [TLContent](?) type defines the clipboard payload:
diff --git a/apps/docs/content/sdk-features/deep-links.mdx b/apps/docs/content/sdk-features/deep-links.mdx
index 70de4b71df46..44791acfb422 100644
--- a/apps/docs/content/sdk-features/deep-links.mdx
+++ b/apps/docs/content/sdk-features/deep-links.mdx
@@ -19,7 +19,7 @@ notes: ''
 
 Deep links serialize editor state into URL-safe strings. They let users share links that open the editor at specific locations: individual shapes, viewport positions, or entire pages.
 
-The simplest way to enable deep links is with the `deepLinks` prop:
+The simplest way to enable deep links is with the `deepLinks` option:
 
 ```tsx
 import { Tldraw } from 'tldraw'
@@ -28,7 +28,7 @@ import 'tldraw/tldraw.css'
 export default function App() {
 	return (
 		<div style={{ position: 'fixed', inset: 0 }}>
-			<Tldraw persistenceKey="example" deepLinks />
+			<Tldraw persistenceKey="example" options={{ deepLinks: true }} />
 		</div>
 	)
 }
@@ -117,8 +117,8 @@ const unlisten = editor.registerDeepLinkListener({
 unlisten()
 ```
 
-You can also enable this via the `deepLinks` prop on the Tldraw component instead of calling this method directly.
+You can also enable this via the `deepLinks` option on the Tldraw component instead of calling this method directly.
 
 ## Related examples
 
-- **[Deep links](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/deep-links)** - Demonstrates how to use the `deepLinks` prop to enable URL-based navigation and how to create, parse, and handle deep links manually using the editor methods.
+- **[Deep links](https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples/configuration/deep-links)** - Demonstrates how to use the `deepLinks` option to enable URL-based navigation and how to create, parse, and handle deep links manually using the editor methods.
diff --git a/apps/docs/content/sdk-features/default-shapes.mdx b/apps/docs/content/sdk-features/default-shapes.mdx
index 7231940be247..5dc0f7b6c610 100644
--- a/apps/docs/content/sdk-features/default-shapes.mdx
+++ b/apps/docs/content/sdk-features/default-shapes.mdx
@@ -225,13 +225,14 @@ Configuration options:
 | ------------------- | -------- | ------- | ------------------------------------------------------------------------- |
 | `maxPointsPerShape` | `number` | `600`   | Maximum points before starting a new shape. Same behavior as draw shapes. |
 
-The highlight's `underlayOpacity` (default `0.82`) and `overlayOpacity` (default `0.35`) are display values that can be overridden via `getCustomDisplayValues`.
+The highlight's `underlayOpacity` (default `0.82`) and `overlayOpacity` (default `0.35`) are display values that can be overridden via `getCustomDisplayValues`:
 
 ```tsx
 const ConfiguredHighlightUtil = HighlightShapeUtil.configure({
 	maxPointsPerShape: 800,
-	underlayOpacity: 0.7,
-	overlayOpacity: 0.4,
+	getCustomDisplayValues() {
+		return { underlayOpacity: 0.7, overlayOpacity: 0.4 }
+	},
 })
 ```
 
@@ -424,6 +425,8 @@ const ConfiguredFrameUtil = FrameShapeUtil.configure({
 })
 ```
 
+To build your own container shape that behaves like a frame, extend `BaseFrameLikeShapeUtil` rather than re-implementing every behavior on `FrameShapeUtil`. The base class provides defaults for clipping children, full-brush selection, blocking erasure from inside, and drag-and-drop reparenting — see [Shapes](/sdk-features/shapes#frames) for details and the [portal shapes example](/examples/shapes/tools/portal-shapes) for a working implementation.
+
 ### Group
 
 The group shape logically combines multiple shapes without visual representation. Groups let you move and transform shapes together while preserving their relative positions. The group's geometry is computed as the union of all child shapes' geometries. Groups are created through the editor API rather than directly, and they delete themselves automatically when their last child is removed or ungrouped.
diff --git a/apps/docs/content/sdk-features/draw-shape.mdx b/apps/docs/content/sdk-features/draw-shape.mdx
index 794959698481..0057a4e1ca70 100644
--- a/apps/docs/content/sdk-features/draw-shape.mdx
+++ b/apps/docs/content/sdk-features/draw-shape.mdx
@@ -108,26 +108,26 @@ Access dynamic resize mode through [Editor#user](?):
 const isDynamic = editor.user.getIsDynamicResizeMode()
 
 // Enable dynamic resize mode
-editor.user.updateUserPreferences({ isDynamicResizeMode: true })
+editor.user.updateUserPreferences({ isDynamicSizeMode: true })
 ```
 
 ## Shape properties
 
 Draw shapes store their path data in an efficient delta-encoded base64 format. The first point uses full Float32 precision (12 bytes), with subsequent points stored as Float16 deltas (6 bytes each).
 
-| Property     | Type                   | Description                                                |
-| ------------ | ---------------------- | ---------------------------------------------------------- |
-| `color`      | `TLDefaultColorStyle`  | Stroke color                                               |
-| `fill`       | `TLDefaultFillStyle`   | Fill style (applies when `isClosed` is true)               |
-| `dash`       | `TLDefaultDashStyle`   | Stroke pattern: `draw`, `solid`, `dashed`, `dotted`        |
-| `size`       | `TLDefaultSizeStyle`   | Stroke width preset: `s`, `m`, `l`, `xl`                   |
-| `segments`   | `TLDrawShapeSegment[]` | Array of segments with `type` and base64-encoded `path`    |
-| `isComplete` | `boolean`              | Whether the user has finished drawing this stroke          |
-| `isClosed`   | `boolean`              | Whether the path forms a closed shape                      |
-| `isPen`      | `boolean`              | Whether drawn with a stylus (enables pressure-based width) |
-| `scale`      | `number`               | Scale factor applied to the shape                          |
-| `scaleX`     | `number`               | Horizontal scale factor for lazy resize                    |
-| `scaleY`     | `number`               | Vertical scale factor for lazy resize                      |
+| Property     | Type                   | Description                                                 |
+| ------------ | ---------------------- | ----------------------------------------------------------- |
+| `color`      | `TLDefaultColorStyle`  | Stroke color                                                |
+| `fill`       | `TLDefaultFillStyle`   | Fill style (applies when `isClosed` is true)                |
+| `dash`       | `TLDefaultDashStyle`   | Stroke pattern: `draw`, `solid`, `dashed`, `dotted`, `none` |
+| `size`       | `TLDefaultSizeStyle`   | Stroke width preset: `s`, `m`, `l`, `xl`                    |
+| `segments`   | `TLDrawShapeSegment[]` | Array of segments with `type` and base64-encoded `path`     |
+| `isComplete` | `boolean`              | Whether the user has finished drawing this stroke           |
+| `isClosed`   | `boolean`              | Whether the path forms a closed shape                       |
+| `isPen`      | `boolean`              | Whether drawn with a stylus (enables pressure-based width)  |
+| `scale`      | `number`               | Scale factor applied to the shape                           |
+| `scaleX`     | `number`               | Horizontal scale factor for lazy resize                     |
+| `scaleY`     | `number`               | Vertical scale factor for lazy resize                       |
 
 Each segment has a `type` of `'free'` or `'straight'` and a `path` containing the encoded point data with x, y, and z (pressure) values.
 
diff --git a/apps/docs/content/sdk-features/embed-shape.mdx b/apps/docs/content/sdk-features/embed-shape.mdx
index 9aa154692fee..02ea33547ba0 100644
--- a/apps/docs/content/sdk-features/embed-shape.mdx
+++ b/apps/docs/content/sdk-features/embed-shape.mdx
@@ -37,6 +37,12 @@ editor.createShape({
 
 The embed system recognizes URLs from supported services and converts them to their embeddable equivalents. A YouTube watch URL becomes an embed URL automatically.
 
+### Pasting iframe code
+
+You can also paste raw `<iframe>` HTML directly onto the canvas to create an embed shape, even when the source URL doesn't match a known provider. tldraw extracts the iframe's `src` attribute and creates an embed pointing at it. If the iframe element is missing `width` and `height`, the embed uses default dimensions instead.
+
+This covers services tldraw doesn't know about — OpenStreetMap, SoundCloud, Loom, internal tools — without a custom embed definition. Iframes pasted this way receive a stricter sandbox than the built-in providers (no `allow-same-origin`, no top navigation), since tldraw can't make any safety guarantees about the source.
+
 ## Supported services
 
 | Service         | Hostnames                    | Resizable | Aspect ratio locked |
@@ -58,6 +64,7 @@ The embed system recognizes URLs from supported services and converts them to th
 | Vimeo           | vimeo.com, player.vimeo.com  | Yes       | Yes                 |
 | Observable      | observablehq.com             | Yes       | No                  |
 | Desmos          | desmos.com                   | Yes       | No                  |
+| Canva           | canva.com                    | Yes       | No                  |
 
 Each service has default dimensions appropriate for its content type. YouTube embeds default to 800×450 (16:9), while Spotify defaults to 720×500.
 
@@ -124,7 +131,7 @@ GitHub Gist embeds receive special handling: they use `srcDoc` instead of `src`
 
 ## Custom embed definitions
 
-Replace or extend the default embed definitions using `EmbedShapeUtil.setEmbedDefinitions()`:
+Replace or extend the default embed definitions using `EmbedShapeUtil.configure()`:
 
 ```tsx
 import { Tldraw, EmbedShapeUtil, DEFAULT_EMBED_DEFINITIONS } from 'tldraw'
@@ -158,13 +165,12 @@ const myEmbedDefinitions = [
 	},
 ]
 
-// Set before mounting the editor
-EmbedShapeUtil.setEmbedDefinitions(myEmbedDefinitions)
+const shapeUtils = [EmbedShapeUtil.configure({ embedDefinitions: myEmbedDefinitions })]
 
 export default function App() {
 	return (
 		<div style={{ position: 'fixed', inset: 0 }}>
-			<Tldraw />
+			<Tldraw shapeUtils={shapeUtils} />
 		</div>
 	)
 }
diff --git a/apps/docs/content/sdk-features/environment.mdx b/apps/docs/content/sdk-features/environment.mdx
index 738f343957d1..a5ba6d969d71 100644
--- a/apps/docs/content/sdk-features/environment.mdx
+++ b/apps/docs/content/sdk-features/environment.mdx
@@ -110,6 +110,28 @@ react('pointer type changed', () => {
 
 Note: We force fine pointer mode on Firefox desktop regardless of the actual input device, since Firefox's coarse pointer reporting is unreliable there.
 
+## Cross-window contexts
+
+When the editor is mounted inside an iframe, an Electron pop-out window, or an Obsidian plugin, the global `document` and `window` aren't necessarily the ones the editor's DOM lives in. Reading `document.activeElement` or attaching a listener to the global `window` will silently fail or target the wrong frame.
+
+Use the editor's container helpers instead of bare globals:
+
+```typescript
+const doc = editor.getContainerDocument() // the document the editor is mounted in
+const win = editor.getContainerWindow() // the window the editor is mounted in
+```
+
+When you have a DOM node and want the document or window that owns it (rather than where the editor lives), use the standalone helpers:
+
+```typescript
+import { getOwnerDocument, getOwnerWindow } from 'tldraw'
+
+const doc = getOwnerDocument(node)
+const win = getOwnerWindow(node)
+```
+
+These are what the editor uses internally for export, measurement, focus tracking, and event listeners. Custom shapes and tools that touch the DOM directly should use them too — anything that calls `document` or `window` directly will break the moment your app is embedded in a context with multiple realms.
+
 ## Browser quirks we handle
 
 Here's a sample of what we use environment detection for internally.
diff --git a/apps/docs/content/sdk-features/frame-shape.mdx b/apps/docs/content/sdk-features/frame-shape.mdx
index 22bf8ae4c374..2e032f771f2c 100644
--- a/apps/docs/content/sdk-features/frame-shape.mdx
+++ b/apps/docs/content/sdk-features/frame-shape.mdx
@@ -1,24 +1,160 @@
 ---
 title: Frame shape
 created_at: 1/31/2026
-updated_at: 1/31/2026
+updated_at: 5/6/2026
 keywords:
   - frame
   - container
   - artboard
   - clipping
   - frame tool
-status: draft
-date: 1/31/2026
+  - BaseFrameLikeShapeUtil
+status: published
+date: 5/6/2026
 ---
 
-TODO: Document the frame shape including:
+The frame shape is a container with a labeled header that holds other shapes. Children of a frame are clipped to its bounds, follow the frame when it moves, and export together as a single image. Frames are useful for laying out artboards, screen mockups, slides, and any visual region that should travel as one unit.
 
-- Creating frames programmatically
-- Frame properties (name, color, dimensions)
-- Child clipping behavior
-- Frame header and naming
-- Configuration options (showColors, resizeChildren)
-- Frame tool interactions
-- Exporting frames
-- Difference between frames and groups
+```tsx
+editor.createShape({
+	type: 'frame',
+	x: 100,
+	y: 100,
+	props: {
+		w: 800,
+		h: 600,
+		name: 'Login screen',
+		color: 'black',
+	},
+})
+```
+
+## Creating frames
+
+You can create a frame programmatically with `editor.createShape`, or interactively with the frame tool. The frame tool ships in the default toolbar; users can also press `F` to switch to it.
+
+When the user drags a frame around existing shapes, the frame tool reparents any sibling shapes that fall fully inside the frame's bounds. Locked shapes are skipped. This is what makes "draw a frame around the things I want to group" work as a single gesture.
+
+Children inside a frame use coordinates relative to the frame's origin. Moving the frame moves every descendant; rotating the frame rotates them too.
+
+## Frame header
+
+Every frame renders a heading above its top edge that displays the frame's `name` property. Double-click the heading to start editing the name. The heading rotates with the frame to stay above whichever edge is currently "up", so it remains readable.
+
+Empty names render as `Frame` in exports so unnamed frames still get a label. The shape's `name` is also exposed via [ShapeUtil#getAriaDescriptor](?) so screen readers announce it during keyboard navigation.
+
+## Child clipping
+
+Frames clip their children to the frame's rectangle during rendering. A shape that extends past the frame edge is rendered up to the boundary and then cut off. Clipping is purely visual — the shape's geometry, hit testing, and bounds are unchanged.
+
+The `BaseFrameLikeShapeUtil` base class implements clipping via `getClipPath`. If you need clipping for a custom container shape, see the [Frames](/sdk-features/shapes#frames) section in the Shapes guide.
+
+## Shape properties
+
+| Property | Type                  | Description                                          |
+| -------- | --------------------- | ---------------------------------------------------- |
+| `w`      | `number`              | Frame width in pixels (default: `320`)               |
+| `h`      | `number`              | Frame height in pixels (default: `180`)              |
+| `name`   | `string`              | Label displayed in the frame header                  |
+| `color`  | `TLDefaultColorStyle` | Color for the border and heading (when `showColors`) |
+
+## Configuration options
+
+`FrameShapeUtil` exposes two configuration options:
+
+| Option           | Type      | Default | Description                                                                                             |
+| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `showColors`     | `boolean` | `false` | When true, frames display a colored border and header background based on the frame's `color` property. |
+| `resizeChildren` | `boolean` | `false` | When true, resizing a frame scales its children proportionally instead of leaving them in place.        |
+
+```tsx
+import { FrameShapeUtil, Tldraw } from 'tldraw'
+import 'tldraw/tldraw.css'
+
+const ConfiguredFrameUtil = FrameShapeUtil.configure({
+	showColors: true,
+	resizeChildren: true,
+})
+
+export default function App() {
+	return (
+		<div style={{ position: 'fixed', inset: 0 }}>
+			<Tldraw shapeUtils={[ConfiguredFrameUtil]} />
+		</div>
+	)
+}
+```
+
+When `showColors` is on, `color` becomes a real style property — users can change it from the style panel and it syncs across selections like other styles. With `showColors` off (the default), `color` still validates and persists, but the frame renders with a neutral palette so it doesn't compete visually with the shapes inside it.
+
+## Frame helpers
+
+The editor exposes helpers that work with frames and any other shape that opts into frame-like behavior.
+
+### Detecting frames
+
+```tsx
+// Check whether a shape is a frame (or a custom frame-like shape)
+const shape = editor.getShape(shapeId)
+if (shape && editor.isShapeFrameLike(shape)) {
+	// ...
+}
+```
+
+### Fitting a frame to its content
+
+`fitFrameToContent` resizes a frame so it tightly wraps its children, with a configurable padding. Use it after the user has finished arranging shapes inside an artboard:
+
+```tsx
+import { fitFrameToContent } from 'tldraw'
+
+fitFrameToContent(editor, frameId)
+
+// Or with a custom padding
+fitFrameToContent(editor, frameId, { padding: 24 })
+```
+
+### Removing a frame
+
+`removeFrame` deletes a frame but preserves its children — they're moved out of the frame and reselected so they survive:
+
+```tsx
+import { removeFrame } from 'tldraw'
+
+removeFrame(editor, [frameId])
+```
+
+This is also wired up to the **Remove frame** action (`Cmd/Ctrl+Shift+F`) and the **Fit frame to content** action in the actions menu and context menu when a frame is selected.
+
+## Exporting frames
+
+Frames are export bounds containers — `FrameShapeUtil.isExportBoundsContainer()` returns `true`. When a frame contains all the other shapes in an export, the export pipeline skips the usual padding around the result and uses the frame's bounds exactly. The export still includes every descendant of the frame.
+
+This makes frames ideal for mockup-style workflows where you need pixel-perfect output at a specific aspect ratio — design the frame, drop content inside, export.
+
+## Frames vs. groups
+
+Frames and groups both contain other shapes, but they solve different problems:
+
+|                              | Frame                                   | Group                            |
+| ---------------------------- | --------------------------------------- | -------------------------------- |
+| Visible on the canvas        | Yes — bordered rectangle with a heading | No — no visual representation    |
+| Clips children to its bounds | Yes                                     | No                               |
+| Has a fixed size and shape   | Yes (`w`, `h`, position)                | No (geometry follows children)   |
+| Used for export bounds       | Yes                                     | No                               |
+| Auto-deletes when empty      | No                                      | Yes (when last child is removed) |
+| Created by                   | Frame tool or `editor.createShape`      | `editor.groupShapes(...)`        |
+
+Reach for a frame when you want a labeled, bounded region — a slide, a screen, an artboard. Reach for a group when you just need to move several shapes together without changing their visual layout.
+
+## Related articles
+
+- [Shapes](/sdk-features/shapes#frames) — How to build your own container shape with `BaseFrameLikeShapeUtil`
+- [Default shapes](/sdk-features/default-shapes#frame) — Overview of all built-in shapes
+- [Shape clipping](/sdk-features/shape-clipping) — How custom shapes can clip their children
+- [Image export](/sdk-features/image-export) — Exporting frames and selections as images
+- [Parenting](/sdk-features/parenting) — How shapes are nested inside containers
+
+## Related examples
+
+- [Portal shapes](/examples/shapes/tools/portal-shapes) — A custom frame-like shape that teleports children between instances
diff --git a/apps/docs/content/sdk-features/geo-shape.mdx b/apps/docs/content/sdk-features/geo-shape.mdx
index fa3c40e802bb..1e396d777415 100644
--- a/apps/docs/content/sdk-features/geo-shape.mdx
+++ b/apps/docs/content/sdk-features/geo-shape.mdx
@@ -169,23 +169,23 @@ When tool lock is enabled (via the toolbar or [Editor#setCurrentTool](?)), you c
 
 ## Shape properties
 
-| Property        | Type                            | Description                                         |
-| --------------- | ------------------------------- | --------------------------------------------------- |
-| `geo`           | `TLGeoShapeGeoStyle`            | The geometric form                                  |
-| `w`             | `number`                        | Width in pixels                                     |
-| `h`             | `number`                        | Height in pixels                                    |
-| `richText`      | `TLRichText`                    | Text label displayed inside the shape               |
-| `color`         | `TLDefaultColorStyle`           | Stroke/outline color                                |
-| `labelColor`    | `TLDefaultColorStyle`           | Text label color (separate from stroke)             |
-| `fill`          | `TLDefaultFillStyle`            | Fill style: `none`, `semi`, `solid`, `pattern`      |
-| `dash`          | `TLDefaultDashStyle`            | Stroke pattern: `draw`, `solid`, `dashed`, `dotted` |
-| `size`          | `TLDefaultSizeStyle`            | Size preset affecting stroke width                  |
-| `font`          | `TLDefaultFontStyle`            | Font family for the label                           |
-| `align`         | `TLDefaultHorizontalAlignStyle` | Horizontal text alignment                           |
-| `verticalAlign` | `TLDefaultVerticalAlignStyle`   | Vertical text alignment                             |
-| `growY`         | `number`                        | Additional vertical space for text overflow         |
-| `url`           | `string`                        | Optional hyperlink URL                              |
-| `scale`         | `number`                        | Scale factor applied to the shape                   |
+| Property        | Type                            | Description                                                 |
+| --------------- | ------------------------------- | ----------------------------------------------------------- |
+| `geo`           | `TLGeoShapeGeoStyle`            | The geometric form                                          |
+| `w`             | `number`                        | Width in pixels                                             |
+| `h`             | `number`                        | Height in pixels                                            |
+| `richText`      | `TLRichText`                    | Text label displayed inside the shape                       |
+| `color`         | `TLDefaultColorStyle`           | Stroke/outline color                                        |
+| `labelColor`    | `TLDefaultColorStyle`           | Text label color (separate from stroke)                     |
+| `fill`          | `TLDefaultFillStyle`            | Fill style: `none`, `semi`, `solid`, `pattern`              |
+| `dash`          | `TLDefaultDashStyle`            | Stroke pattern: `draw`, `solid`, `dashed`, `dotted`, `none` |
+| `size`          | `TLDefaultSizeStyle`            | Size preset affecting stroke width                          |
+| `font`          | `TLDefaultFontStyle`            | Font family for the label                                   |
+| `align`         | `TLDefaultHorizontalAlignStyle` | Horizontal text alignment                                   |
+| `verticalAlign` | `TLDefaultVerticalAlignStyle`   | Vertical text alignment                                     |
+| `growY`         | `number`                        | Additional vertical space for text overflow                 |
+| `url`           | `string`                        | Optional hyperlink URL                                      |
+| `scale`         | `number`                        | Scale factor applied to the shape                           |
 
 ## Configuration options
 
@@ -209,6 +209,50 @@ Pass the configured utility to the `shapeUtils` prop:
 <Tldraw shapeUtils={[ConfiguredGeoUtil]} />
 ```
 
+## Custom geo types
+
+Register custom geo types via `customGeoTypes` to add new shapes that inherit all standard geo behavior — labels, fill/dash/color styling, resizing, SVG export, and hyperlinks — while providing their own path geometry, snap behavior, creation size, and style panel icon. This lets you extend the built-in geo enum without forking `GeoShapeUtil`.
+
+```tsx
+import { GeoShapeUtil, PathBuilder } from 'tldraw'
+
+const MyGeoShapeUtil = GeoShapeUtil.configure({
+	customGeoTypes: {
+		'rounded-rect': {
+			getPath: (w, h, shape, strokeWidth) => {
+				const r = Math.min(w, h) * 0.2
+				return new PathBuilder()
+					.moveTo(r, 0, { geometry: { isFilled: shape.props.fill !== 'none' } })
+					.lineTo(w - r, 0)
+					.circularArcTo(r, false, true, w, r)
+					.lineTo(w, h - r)
+					.circularArcTo(r, false, true, w - r, h)
+					.lineTo(r, h)
+					.circularArcTo(r, false, true, 0, h - r)
+					.lineTo(0, r)
+					.circularArcTo(r, false, true, r, 0)
+					.close()
+			},
+			snapType: 'polygon',
+			icon: 'geo-rectangle',
+			defaultSize: { w: 200, h: 150 },
+		},
+	},
+})
+```
+
+Each entry in `customGeoTypes` is a `GeoTypeDefinition`:
+
+| Field           | Type                                        | Description                                                                                          |
+| --------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `getPath`       | `(w, h, shape, strokeWidth) => PathBuilder` | Returns the path geometry for this type at the given dimensions.                                     |
+| `snapType`      | `'polygon' \| 'blobby'`                     | `'polygon'` snaps to vertices and center; `'blobby'` snaps to center only.                           |
+| `icon`          | `string`                                    | Icon name used in the style panel's geo picker.                                                      |
+| `defaultSize`   | `{ w: number; h: number }` (optional)       | Size used when the shape is created via click rather than drag. Defaults to 200 × 200.               |
+| `onDoubleClick` | `(shape) => { props } \| void` (optional)   | Custom double-click handler. Return a partial props update to mutate the shape, or nothing to no-op. |
+
+Custom types appear in the style panel's geo picker alongside the built-in shapes. See the [custom geo types example](/examples/shapes/tools/custom-geo-types) for a full implementation.
+
 ## Label positioning
 
 The `align` and `verticalAlign` properties control where labels appear within the shape:
@@ -262,7 +306,7 @@ When dynamic resize mode is enabled in user preferences, new geo shapes scale in
 
 ```tsx
 // Enable dynamic resize mode
-editor.user.updateUserPreferences({ isDynamicResizeMode: true })
+editor.user.updateUserPreferences({ isDynamicSizeMode: true })
 ```
 
 ## Hyperlinks
diff --git a/apps/docs/content/sdk-features/handles.mdx b/apps/docs/content/sdk-features/handles.mdx
index 2f81a127535a..698ddf63755a 100644
--- a/apps/docs/content/sdk-features/handles.mdx
+++ b/apps/docs/content/sdk-features/handles.mdx
@@ -167,7 +167,15 @@ The `HandleSnapGeometry` object has these properties:
 Here's a speech bubble shape with a draggable tail handle:
 
 ```tsx
-import { Polygon2d, ShapeUtil, TLHandle, TLHandleDragInfo, TLShape, ZERO_INDEX_KEY } from 'tldraw'
+import {
+	Polygon2d,
+	ShapeUtil,
+	TLHandle,
+	TLHandleDragInfo,
+	TLShape,
+	Vec,
+	ZERO_INDEX_KEY,
+} from 'tldraw'
 
 const SPEECH_BUBBLE_TYPE = 'speech-bubble'
 
@@ -190,13 +198,13 @@ class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
 		const { w, h, tailX, tailY } = shape.props
 		return new Polygon2d({
 			points: [
-				{ x: 0, y: 0 },
-				{ x: w, y: 0 },
-				{ x: w, y: h },
-				{ x: w * 0.7, y: h },
-				{ x: tailX, y: tailY },
-				{ x: w * 0.3, y: h },
-				{ x: 0, y: h },
+				new Vec(0, 0),
+				new Vec(w, 0),
+				new Vec(w, h),
+				new Vec(w * 0.7, h),
+				new Vec(tailX, tailY),
+				new Vec(w * 0.3, h),
+				new Vec(0, h),
 			],
 			isFilled: true,
 		})
diff --git a/apps/docs/content/sdk-features/image-export.mdx b/apps/docs/content/sdk-features/image-export.mdx
index f919c6c545b5..721779b01de6 100644
--- a/apps/docs/content/sdk-features/image-export.mdx
+++ b/apps/docs/content/sdk-features/image-export.mdx
@@ -56,15 +56,15 @@ SVG export methods (`getSvgElement`, `getSvgString`) accept [TLSvgExportOptions]
 
 **Shared options (all export methods):**
 
-| Option                | Description                                                                                                                                                                                                                     |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bounds`              | The bounding box in page coordinates to export. If omitted, the editor calculates bounds from the shapes.                                                                                                                       |
-| `scale`               | Logical scale multiplier. A scale of 2 doubles the SVG size.                                                                                                                                                                    |
-| `pixelRatio`          | For SVG exports, passed to the asset store so it can provide appropriately sized assets. For raster exports, multiplies output dimensions. Defaults to `undefined` for SVG and `2` for raster formats.                          |
-| `background`          | Whether to include the background color. If `false`, the export is transparent (for formats that support it).                                                                                                                   |
-| `padding`             | Space in pixels around the shape bounds. Defaults to 32. When exporting a single frame, padding is not applied (the frame itself serves as the boundary). When exporting shapes inside an image shape, padding is also skipped. |
-| `darkMode`            | Whether to render in dark mode. Defaults to the current theme setting.                                                                                                                                                          |
-| `preserveAspectRatio` | The SVG `preserveAspectRatio` attribute.                                                                                                                                                                                        |
+| Option                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bounds`              | The bounding box in page coordinates to export. If omitted, the editor calculates bounds from the shapes.                                                                                                                                                                                                                                                                                                                                                                 |
+| `scale`               | Logical scale multiplier. A scale of 2 doubles the SVG size.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `pixelRatio`          | For SVG exports, passed to the asset store so it can provide appropriately sized assets. For raster exports, multiplies output dimensions. Defaults to `undefined` for SVG and `2` for raster formats.                                                                                                                                                                                                                                                                    |
+| `background`          | Whether to include the background color. If `false`, the export is transparent (for formats that support it).                                                                                                                                                                                                                                                                                                                                                             |
+| `padding`             | Space around the shape bounds. Accepts `number` (fixed pixels) or `'auto'` (default). In `'auto'` mode, the export trims to visual content bounds, capturing overflow like thick strokes and arrowheads without extra whitespace. A numeric value adds fixed padding and clips overflow beyond it. When exporting a single frame, padding is not applied (the frame itself serves as the boundary). When exporting shapes inside an image shape, padding is also skipped. |
+| `darkMode`            | Whether to render in dark mode. Defaults to the current theme setting.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `preserveAspectRatio` | The SVG `preserveAspectRatio` attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 **Raster-only options (toImage, toImageDataUrl):**
 
diff --git a/apps/docs/content/sdk-features/internationalization.mdx b/apps/docs/content/sdk-features/internationalization.mdx
index c18e4bcaafa6..6987dffb77fc 100644
--- a/apps/docs/content/sdk-features/internationalization.mdx
+++ b/apps/docs/content/sdk-features/internationalization.mdx
@@ -183,19 +183,21 @@ The supported languages include: English, Spanish, French, German, Italian, Port
 
 ## Right-to-left support
 
-Languages like Arabic, Hebrew, Farsi, and Urdu automatically set `dir: 'rtl'` in the translation object. The tldraw UI respects this direction, mirroring layout and text alignment.
+Languages like Arabic, Hebrew, Farsi, and Urdu automatically set `dir: 'rtl'` in the translation object. The tldraw UI respects this direction. Layout and text alignment mirror automatically. The `dir` attribute is set on the editor's root container, and the built-in components use CSS logical properties (`margin-inline-start`, `inset-inline-end`, and so on) so they flip without per-component code.
 
-When building custom UI components, use the `dir` property from the translation context:
+When building custom UI components, use the `useDirection` hook to get the current text direction. It returns `'ltr'` or `'rtl'` from the active translation context — the same value you'd read from `useCurrentTranslation().dir`, but without pulling the rest of the translation object into the component:
 
 ```tsx
-import { useCurrentTranslation } from 'tldraw'
+import { useDirection } from 'tldraw'
 
 function CustomPanel() {
-	const { dir } = useCurrentTranslation()
+	const dir = useDirection()
 	return <aside dir={dir}>{/* Panel content */}</aside>
 }
 ```
 
+Use `useCurrentTranslation` instead when you also need the locale, label, or `messages` from the same render.
+
 ## Building a language picker
 
 Here's a language picker that updates the user's locale preference:
diff --git a/apps/docs/content/sdk-features/note-shape.mdx b/apps/docs/content/sdk-features/note-shape.mdx
index 0012378b7afe..36aa0134f0cc 100644
--- a/apps/docs/content/sdk-features/note-shape.mdx
+++ b/apps/docs/content/sdk-features/note-shape.mdx
@@ -139,3 +139,10 @@ When `editor.user.getIsDynamicResizeMode()` is true, new notes are created at a
 // If zoom is 0.5x, new notes get scale: 2
 const scale = editor.user.getIsDynamicResizeMode() ? 1 / editor.getZoomLevel() : 1
 ```
+
+## Related articles
+
+- [Attribution](/sdk-features/attribution) — How notes display "first edited by" labels in multiplayer sessions
+- [Default shapes](/sdk-features/default-shapes) — Overview of all built-in shapes
+- [Rich text](/sdk-features/rich-text) — Working with formatted text content
+- [Styles](/sdk-features/styles) — Working with shape styles like color and size
diff --git a/apps/docs/content/sdk-features/options.mdx b/apps/docs/content/sdk-features/options.mdx
index 064b37494f25..f75ecd581ada 100644
--- a/apps/docs/content/sdk-features/options.mdx
+++ b/apps/docs/content/sdk-features/options.mdx
@@ -123,6 +123,7 @@ Control camera movement and viewport behavior:
 | `cameraMovingTimeoutMs`   | 64      | Time before camera is considered stopped          |
 | `followChaseViewportSnap` | 2       | Snap threshold when following collaborators       |
 | `spacebarPanning`         | true    | Enable spacebar to activate pan mode              |
+| `rightClickPanning`       | true    | Enable right-click and drag to pan the camera     |
 | `zoomToFitPadding`        | 128     | Padding around content when zooming to fit bounds |
 
 ### Snapping
@@ -198,6 +199,8 @@ When `debouncedZoom` is enabled and the page has more shapes than `debouncedZoom
 | `actionShortcutsLocation`        | 'swap'    | Where to show keyboard shortcuts in menus      |
 | `tooltipDelayMs`                 | 700       | Delay before showing tooltips                  |
 | `laserDelayMs`                   | 1200      | Duration laser pointer remains visible         |
+| `laserFadeoutMs`                 | 500       | Duration for laser pointer fadeout animation   |
+| `quickZoomPreservesScreenBounds` | true      | Whether quick zoom brush keeps viewport scale  |
 | `branding`                       | undefined | App name for accessibility labels              |
 | `nonce`                          | undefined | CSP nonce for inline styles                    |
 
@@ -214,6 +217,24 @@ The `actionShortcutsLocation` option controls where keyboard shortcuts appear:
 | `temporaryAssetPreviewLifetimeMs` | 180000  | How long temporary asset previews persist (3 min) |
 | `adjacentShapeMargin`             | 10      | Margin between auto-positioned shapes             |
 
+### Clipboard hooks
+
+These callbacks let you intercept and customize clipboard operations:
+
+| Option                       | Description                                                                                                                                                                                          |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onBeforeCopyToClipboard`    | Called before content is written to the clipboard during copy or cut. Return modified `TLContent` to transform, `false` to cancel, or `void` to pass through.                                        |
+| `onBeforePasteFromClipboard` | Called before pasted content is processed and shapes are created. Return `false` to cancel, a modified content object to transform, or `void` to pass through. Only fires for paste, not file drops. |
+| `onClipboardPasteRaw`        | Called first for keyboard and menu paste, before tldraw parses clipboard data. Return `false` to cancel default paste handling, or `void` to continue.                                               |
+
+See [Clipboard](/sdk-features/clipboard) for more details on clipboard operations.
+
+### Drop handling
+
+| Option                         | Description                                                                                                                              |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `experimental__onDropOnCanvas` | Called when content is dropped on the canvas. Receives the page position and drag event. Return `true` to prevent default drop handling. |
+
 ## Default values
 
 The `defaultTldrawOptions` export provides all default values:
@@ -285,29 +306,36 @@ function App() {
 
 ### Embeds
 
-The `embeds` prop customizes which embed types the editor recognizes:
+Customize which embed types the editor recognizes using `EmbedShapeUtil.configure()`:
 
 ```tsx
-import { Tldraw, TLEmbedDefinition } from 'tldraw'
-
-const customEmbeds: TLEmbedDefinition[] = [
-	{
-		type: 'custom-video',
-		title: 'Custom Video',
-		hostnames: ['videos.example.com'],
-		width: 560,
-		height: 315,
-		doesResize: true,
-		toEmbedUrl: (url) => url.replace('/watch/', '/embed/'),
-		fromEmbedUrl: (url) => url.replace('/embed/', '/watch/'),
-	},
+import { Tldraw, EmbedShapeUtil, DEFAULT_EMBED_DEFINITIONS } from 'tldraw'
+
+const shapeUtils = [
+	EmbedShapeUtil.configure({
+		embedDefinitions: [
+			...DEFAULT_EMBED_DEFINITIONS,
+			{
+				type: 'custom-video',
+				title: 'Custom Video',
+				hostnames: ['videos.example.com'],
+				width: 560,
+				height: 315,
+				doesResize: true,
+				toEmbedUrl: (url) => url.replace('/watch/', '/embed/'),
+				fromEmbedUrl: (url) => url.replace('/embed/', '/watch/'),
+			},
+		],
+	}),
 ]
 
 function App() {
-	return <Tldraw embeds={customEmbeds} />
+	return <Tldraw shapeUtils={shapeUtils} />
 }
 ```
 
+See [Embed shape](/sdk-features/embed-shape#custom-embed-definitions) for the full embed definition API.
+
 ### Editor setup
 
 These props configure how the editor initializes:
diff --git a/apps/docs/content/sdk-features/performance.mdx b/apps/docs/content/sdk-features/performance.mdx
index 631049f361b6..b9676dbc791a 100644
--- a/apps/docs/content/sdk-features/performance.mdx
+++ b/apps/docs/content/sdk-features/performance.mdx
@@ -257,6 +257,30 @@ If performance degrades with many shapes, look for:
 - Expensive calculations inside component render functions
 - Continuous animations on many shapes
 
+### Subscribing to performance events
+
+For programmatic monitoring — telemetry, RUM, or in-app dashboards — the editor exposes [PerformanceManager](?) at `editor.performance`. Subscribe to events and you'll get aggregated frame-time stats from real interactions, with no overhead when no listeners are attached:
+
+```ts
+const unsub = editor.performance.on('interaction-end', (event) => {
+	console.log(`${event.name}: ${event.fps.toFixed(1)} fps, p95=${event.p95FrameTime.toFixed(1)}ms`)
+})
+// later: unsub()
+```
+
+The `'interaction-end'` event fires when an interaction state exits, with `fps`, `p95FrameTime`, and (in supporting browsers) Long Animation Frame attribution. `'camera-end'` fires after pan/zoom debounce with the same shape. `'shapes-created'`, `'shapes-updated'`, and `'shapes-deleted'` carry per-type counts. `'frame'` fires every animation frame while a listener is attached. See [TLPerfEventMap](?) for the full set.
+
+Custom tools opt into interaction tracking by setting [StateNode#trackPerformance](?) on the state node class. When the state is entered, the manager starts a tracking window; when it exits, it emits `'interaction-start'` / `'interaction-end'` with the state path. Built-in interactions like `select.translating` and `draw.drawing` already track, so you only need this for custom states.
+
+If you're profiling in Chrome DevTools, [PerformanceApiAdapter](?) wires the same events into native `performance.mark()` / `performance.measure()` calls so they show up on the Performance timeline:
+
+```ts
+import { PerformanceApiAdapter } from 'tldraw'
+
+const adapter = new PerformanceApiAdapter(editor.performance)
+// later: adapter.dispose()
+```
+
 ## Related
 
 - [Culling](/sdk-features/culling) — How viewport culling works and how to control it
diff --git a/apps/docs/content/sdk-features/shape-transforms.mdx b/apps/docs/content/sdk-features/shape-transforms.mdx
index 02e431ba7cb7..c500fbd835b1 100644
--- a/apps/docs/content/sdk-features/shape-transforms.mdx
+++ b/apps/docs/content/sdk-features/shape-transforms.mdx
@@ -138,7 +138,7 @@ Shape utilities can control whether their shapes participate in transforms throu
 
 ```typescript
 canBeLaidOut(shape: MyShape, info: TLShapeUtilCanBeLaidOutOpts): boolean {
-  // type is one of: 'align' | 'distribute' | 'pack' | 'stack' | 'flip' | 'stretch'
+  // type is one of: 'align' | 'distribute' | 'pack' | 'stack' | 'flip' | 'stretch' | 'resize_to_bounds'
   return true
 }
 ```
diff --git a/apps/docs/content/sdk-features/shapes.mdx b/apps/docs/content/sdk-features/shapes.mdx
index fc21e6d7f07b..6dd08543a594 100644
--- a/apps/docs/content/sdk-features/shapes.mdx
+++ b/apps/docs/content/sdk-features/shapes.mdx
@@ -55,7 +55,7 @@ editor.createShape({
 const shape = editor.getShape(shapeId)
 
 // Update a shape's position
-editor.updateShape({ id: shape.id, x: 200 })
+editor.updateShape({ id: shape.id, type: shape.type, x: 200 })
 ```
 
 Shapes are immutable records. When you update a shape, the editor creates a new record with the changes and stores it, replacing the old one. This immutability enables efficient change detection and undo/redo.
@@ -220,6 +220,8 @@ Shapes can be parented to pages or other shapes. This creates a hierarchy used f
 
 Frames are container shapes that clip their children and provide a visual boundary. Shapes inside a frame position relative to the frame's origin. Moving the frame moves all its children. The frame clips content at its boundaries during rendering. See [Shape clipping](/sdk-features/shape-clipping) for details on implementing custom clipping shapes.
 
+To build your own container shape that behaves like a frame, extend `BaseFrameLikeShapeUtil` instead of `ShapeUtil` directly. It provides defaults for the full set of frame behaviors (clipping children, full-brush selection, blocking erasure from inside, drag-and-drop reparenting, providing a background for children) and any of them can be overridden. Custom shapes that don't extend the base class can still opt into the same behavior by overriding the `isFrameLike()` capability method to return `true`. See the [portal shapes example](/examples/shapes/tools/portal-shapes) for a custom shape that behaves like a frame and teleports its children between instances.
+
 ### Groups
 
 Groups are logical containers without visual representation. Group selected shapes with `groupShapes`. Ungroup with `ungroupShapes`. Groups exist only to organize shapes. Their geometry is the union of their children's geometry. When you delete the last child of a group, the group deletes itself.
diff --git a/apps/docs/content/sdk-features/store.mdx b/apps/docs/content/sdk-features/store.mdx
index 8c6f08c88a6f..de0f448e201a 100644
--- a/apps/docs/content/sdk-features/store.mdx
+++ b/apps/docs/content/sdk-features/store.mdx
@@ -58,6 +58,115 @@ Records have a scope that determines how they're persisted and synchronized:
 
 Document records are your actual drawing data—saved to storage and synced across instances. Session records are local to one editor instance, like which page you're viewing. Presence records sync to other users in real-time but aren't saved—they're for showing cursors and selections in multiplayer.
 
+## Custom record types
+
+Shapes, bindings, and assets cover most drawing use cases, but some data doesn't fit any of them—comments threaded against a shape, per-user annotations, application state that should ride along with the document. Register a custom record type and these records live in the store like any other: validated, migrated, persisted, and synced according to the scope you pick.
+
+Pass record definitions to [createTLSchema](?) under the `records` option:
+
+```ts
+import { createTLSchema, T, defaultShapeSchemas } from 'tldraw'
+
+const schema = createTLSchema({
+	shapes: defaultShapeSchemas,
+	records: {
+		comment: {
+			scope: 'document',
+			validator: T.object({
+				id: T.string,
+				typeName: T.literal('comment'),
+				shapeId: T.string,
+				authorId: T.string,
+				text: T.string,
+				createdAt: T.number,
+			}),
+			createDefaultProperties: () => ({ createdAt: Date.now() }),
+		},
+	},
+})
+```
+
+Each entry is a [CustomRecordInfo](?):
+
+| Field                     | Type                                     | Description                                                                                                                 |
+| ------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `scope`                   | `'document' \| 'session' \| 'presence'`  | Same scopes as built-in records — `document` for synced/persisted data, `session` for local-only, `presence` for ephemeral. |
+| `validator`               | `T.Validatable`                          | Validates the full record (including `id` and `typeName`) on every write.                                                   |
+| `createDefaultProperties` | `() => Record<string, unknown>`          | Optional. Default props applied when a record is created without them.                                                      |
+| `migrations`              | `MigrationSequence \| TLPropsMigrations` | Optional. Schema evolution for the record type. An empty sequence is created automatically if you omit it.                  |
+
+For type-safe IDs and TypeScript narrowing across your app, augment [TLGlobalRecordPropsMap](?) so the rest of the SDK's `TLRecord` union knows about your record types:
+
+```ts
+import { BaseRecord, RecordId } from 'tldraw'
+
+interface TLComment extends BaseRecord<'comment', RecordId<TLComment>> {
+	shapeId: string
+	authorId: string
+	text: string
+	createdAt: number
+}
+
+declare module 'tldraw' {
+	export interface TLGlobalRecordPropsMap {
+		comment: TLComment
+	}
+}
+```
+
+### Creating and reading custom records
+
+Use [createCustomRecordId](?) to mint IDs that match the `typeName:suffix` convention the store expects. The companion guards [isCustomRecordId](?) and [isCustomRecord](?) narrow values to your custom type:
+
+```ts
+import { createCustomRecordId, isCustomRecord } from 'tldraw'
+
+const commentId = createCustomRecordId('comment')
+
+editor.store.put([
+	{
+		id: commentId,
+		typeName: 'comment',
+		shapeId: 'shape:abc123',
+		authorId: 'user:alice',
+		text: 'Looks good',
+		createdAt: Date.now(),
+	},
+])
+
+for (const record of editor.store.allRecords()) {
+	if (isCustomRecord('comment', record)) {
+		console.log(record.text) // narrowed to your comment shape
+	}
+}
+```
+
+Custom records appear in `store.listen` diffs, can be queried via `store.query.records('comment')`, and participate in undo/redo when written through the usual store APIs. Sync clients automatically include `document`-scoped records in the synced document; `presence`-scoped records are broadcast but not persisted.
+
+### Custom record migrations
+
+Define migrations the same way you would for shape props. Use [createCustomRecordMigrationIds](?) to generate the canonical `com.tldraw.<type>/<version>` IDs, then [createCustomRecordMigrationSequence](?) for the sequence itself:
+
+```ts
+import { createCustomRecordMigrationIds, createCustomRecordMigrationSequence } from 'tldraw'
+
+const commentVersions = createCustomRecordMigrationIds('comment', {
+	AddAuthorId: 1,
+})
+
+const commentMigrations = createCustomRecordMigrationSequence({
+	sequence: [
+		{
+			id: commentVersions.AddAuthorId,
+			up: (record) => ({ ...record, authorId: record.authorId ?? 'unknown' }),
+			down: ({ authorId, ...rest }) => rest,
+		},
+	],
+})
+```
+
+Pass `commentMigrations` as the `migrations` field on the comment's `CustomRecordInfo` and the store will run them when loading older snapshots.
+
 ## Basic operations
 
 ### Reading records
diff --git a/apps/docs/content/sdk-features/styles.mdx b/apps/docs/content/sdk-features/styles.mdx
index 82957d4468e4..4aad17920054 100644
--- a/apps/docs/content/sdk-features/styles.mdx
+++ b/apps/docs/content/sdk-features/styles.mdx
@@ -142,12 +142,11 @@ The `@tldraw/tlschema` package provides a set of default style properties that t
 **Color styles** control the visual color of shapes and their labels. Colors reference theme values rather than raw hex codes, allowing shapes to adapt to light and dark modes.
 
 - [DefaultColorStyle](?) - Primary shape color (black, red, blue, green, etc.)
-- `DefaultLabelColorStyle` - Label text color for shapes
 
 **Appearance styles** affect how shapes are drawn and filled. These work together to create the hand-drawn aesthetic that defines tldraw's visual style.
 
 - [DefaultFillStyle](?) - Fill pattern (none, semi, solid, pattern, fill, lined-fill)
-- [DefaultDashStyle](?) - Stroke style (draw, solid, dashed, dotted)
+- [DefaultDashStyle](?) - Stroke style (draw, solid, dashed, dotted, none)
 - [DefaultSizeStyle](?) - Relative size scale (s, m, l, xl)
 
 **Text styles** control typography for text shapes and labels. The alignment styles handle both the text itself and how content positions within shape bounds.
diff --git a/apps/docs/content/sdk-features/themes.mdx b/apps/docs/content/sdk-features/themes.mdx
index 8246437e4164..9251b5e23458 100644
--- a/apps/docs/content/sdk-features/themes.mdx
+++ b/apps/docs/content/sdk-features/themes.mdx
@@ -124,7 +124,7 @@ Each color in the palette is a [TLDefaultColor](?) with variants for different c
 | `highlightSrgb`      | Highlighter color in sRGB color space          |
 | `highlightP3`        | Highlighter color in Display P3 color space    |
 
-The palette also includes six base properties: `text` for default text color, `background` for the canvas background color used in SVG exports, `negativeSpace` for areas that should appear to "cut through" to the background (e.g. frame heading knockouts and text outlines), `solid` for the default solid surface color, `cursor` for the cursor color, and `noteBorder` for note shape borders. In the default themes, `background` and `negativeSpace` have the same value, but custom themes can set them independently.
+The palette also includes thirteen base properties: `text` for default text color, `background` for the canvas background color used in SVG exports, `negativeSpace` for areas that should appear to "cut through" to the background (e.g. frame heading knockouts and text outlines), `solid` for the default solid surface color, `cursor` for the cursor color, `noteBorder` for note shape borders, `selectionStroke` and `selectionFill` for the selection box, `selectedContrast` for indicators drawn on top of selected shapes, `brushStroke` and `brushFill` for the selection-brush rectangle, `snap` for snap guides, and `laser` for the laser pointer. In the default themes, `background` and `negativeSpace` have the same value, but custom themes can set them independently.
 
 > Note: The `background` property is used in SVG exports to set the canvas background, but the actual visible canvas background is set separately via the `--tl-color-background` CSS variable. If you customize `background` in your theme, make sure the CSS variable matches — otherwise exports may use a different background color than what's shown on the canvas.
 
@@ -328,7 +328,7 @@ const {
 } = DEFAULT_THEME.colors.light
 ```
 
-Colors removed this way won't appear in the style panel. UI infrastructure colors (`text`, `background`, `solid`, `cursor`, `noteBorder`, `negativeSpace`) cannot be removed.
+Colors removed this way won't appear in the style panel. UI infrastructure colors (`text`, `background`, `solid`, `cursor`, `noteBorder`, `negativeSpace`, `selectionStroke`, `selectionFill`, `selectedContrast`, `brushStroke`, `brushFill`, `snap`, `laser`) cannot be removed.
 
 ## Using themes in shape utils
 
diff --git a/apps/docs/content/sdk-features/ui-components.mdx b/apps/docs/content/sdk-features/ui-components.mdx
index 1fb74c57a763..feede5856ac3 100644
--- a/apps/docs/content/sdk-features/ui-components.mdx
+++ b/apps/docs/content/sdk-features/ui-components.mdx
@@ -323,6 +323,7 @@ Note that `onUiEvent` only fires for UI interactions. Calling [Editor#alignShape
 ## Related articles
 
 - [UI primitives](/sdk-features/ui-primitives) - Use tldraw's button, menu, dialog, and other UI components in your custom interfaces
+- [Overlay utils](/sdk-features/overlay-utils) - Customize canvas overlays like brushes, indicators, snaps, scribbles, and collaborator cursors
 - [Internationalization](/sdk-features/internationalization) - Customize translations and add new languages
 - [Tools](/sdk-features/tools) - Learn how tools work and create your own
 
diff --git a/apps/docs/content/starter-kits/multiplayer.mdx b/apps/docs/content/starter-kits/multiplayer.mdx
index 5a6c67aabf7f..5f39d2c1f0dd 100644
--- a/apps/docs/content/starter-kits/multiplayer.mdx
+++ b/apps/docs/content/starter-kits/multiplayer.mdx
@@ -7,7 +7,7 @@ date: 9/16/2024
 order: 6
 description: The Multiplayer Starter Kit demonstrates how to build self-hosted tldraw applications with real-time multiplayer collaboration using Cloudflare Durable Objects. It features production-ready backend infrastructure that handles WebSocket connections, automatic persistence, and asset management. You can use this foundation to create collaborative whiteboards, design tools, or any multi-user canvas application.
 embed: multiplayer
-githubLink: https://github.com/tldraw/tldraw/tree/main/templates/multiplayer
+githubLink: https://github.com/tldraw/tldraw/tree/main/templates/sync-cloudflare
 keywords:
   - multiplayer
   - sync
@@ -190,21 +190,52 @@ zone_name = "myapp.com"
 
 Room data is automatically persisted via SQLite storage in the Durable Object. The `SQLiteSyncStorage` class handles all persistence logic. You don't need to implement custom save logic.
 
-See `worker/TldrawDurableObject.ts` as an example. The storage is initialized in the constructor:
+See `worker/TldrawDurableObject.ts` as an example. The room is created lazily and supports WebSocket hibernation:
 
 ```tsx
-import { DurableObjectSqliteSyncWrapper, SQLiteSyncStorage, TLSocketRoom } from '@tldraw/sync-core'
+import {
+	DurableObjectSqliteSyncWrapper,
+	type SessionStateSnapshot,
+	SQLiteSyncStorage,
+	TLSocketRoom,
+} from '@tldraw/sync-core'
+import { DurableObject } from 'cloudflare:workers'
 
 export class TldrawDurableObject extends DurableObject {
-	private room: TLSocketRoom<TLRecord, void>
-
-	constructor(ctx: DurableObjectState, env: Env) {
-		super(ctx, env)
-		// SQLite storage persists automatically to Durable Object storage
-		const sql = new DurableObjectSqliteSyncWrapper(ctx.storage)
-		const storage = new SQLiteSyncStorage<TLRecord>({ sql })
-
-		this.room = new TLSocketRoom<TLRecord, void>({ schema, storage })
+	// Room is created lazily on first connection
+	private room: TLSocketRoom<TLRecord, void> | null = null
+
+	private getOrCreateRoom(): TLSocketRoom<TLRecord, void> {
+		if (!this.room) {
+			const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage)
+			const storage = new SQLiteSyncStorage<TLRecord>({ sql })
+
+			this.room = new TLSocketRoom<TLRecord, void>({
+				schema,
+				storage,
+				// Disable idle timeout — Cloudflare handles keep-alive via auto-response
+				clientTimeout: Infinity,
+				// Persist session state to WebSocket attachments for hibernation recovery
+				onSessionSnapshot: (sessionId, snapshot) => {
+					const ws = this.sessionIdToWs.get(sessionId)
+					if (ws) ws.serializeAttachment({ sessionId, snapshot })
+				},
+			})
+
+			// Resume any sessions that survived hibernation
+			for (const ws of this.ctx.getWebSockets()) {
+				const attachment = ws.deserializeAttachment() as SocketAttachment | null
+				if (!attachment?.sessionId) continue
+				if (attachment.snapshot) {
+					this.room.handleSocketResume({
+						sessionId: attachment.sessionId,
+						socket: ws,
+						snapshot: attachment.snapshot,
+					})
+				}
+			}
+		}
+		return this.room
 	}
 }
 ```
diff --git a/apps/examples/src/examples/configuration/camera-options/README.md b/apps/examples/src/examples/configuration/camera-options/README.md
index a90c6a88df54..6b24ba9be622 100644
--- a/apps/examples/src/examples/configuration/camera-options/README.md
+++ b/apps/examples/src/examples/configuration/camera-options/README.md
@@ -20,4 +20,4 @@ Configure the camera's options and constraints.
 
 ---
 
-The `Tldraw` component provides a prop, `cameraOptions`, that can be used to set the camera's constraints, zoom behavior, and other options. This example lets you modify those options to see how they affect the camera's behavior.
+The `Tldraw` component accepts camera configuration via `options={{ camera: { ... } }}`, which can be used to set the camera's constraints, zoom behavior, and other options. This example lets you modify those options to see how they affect the camera's behavior.

From a02e41a838498bd9f0e14a2dca2a3b1115c75321 Mon Sep 17 00:00:00 2001
From: Max Drake <maxdrake46@gmail.com>
Date: Wed, 6 May 2026 14:39:17 +0100
Subject: [PATCH 10/11] fix(editor): respect canReceiveNewChildrenOfType when
 dragging shapes (#8777)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to make container acceptance rules apply consistently during
pointer drag (not only on paste or create), this PR filters drag targets
and drag callback arguments using `canReceiveNewChildrenOfType` when
shape utils override it, and fixes the geometric reparent helper to
consider child types when picking candidate parents.

### Change type

- [x] `bugfix`

### Test plan

1. Override `canReceiveNewChildrenOfType` on a frame-like or container
shape to reject a type (e.g. `geo`).
2. Drag a shape of that type over the container; it should not reparent
until release, and should stay on the page when dropped.
3. Drag an accepted type; behavior should match prior frame drag-in
behavior.
4. Run `yarn test run src/test/frames.test.ts` in `packages/tldraw`.

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

### Release notes

- Fix drag-and-drop so shapes that override
`canReceiveNewChildrenOfType` reject disallowed child types during drag,
not only on paste or create.

### Code changes

| Area | Description | Additions | Deletions |
| --- | --- | ---: | ---: |
| `packages/editor` | `getDraggingOverShape` skips targets that reject
all dragged types | 9 | 0 |
| `packages/editor` | `getDroppedShapesToNewParents` parent prefilter by
child types | 11 | 5 |
| `packages/tldraw` | `DragAndDropManager` filters shapes passed to drag
callbacks | 62 | 23 |
| `packages/tldraw` | Frame regression test for rejecting util | 34 | 0
|
| **Total** | | **116** | **28** |

Made with [Cursor](https://cursor.com)

### API changes

- adds `canRemoveChildrenOfType` for frame-like shapes

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Mime Čuvalo <mimecuvalo@gmail.com>
---
 apps/docs/content/releases/next.mdx           |   2 +-
 .../content/sdk-features/drag-and-drop.mdx    |  17 +-
 .../drag-and-drop/DragAndDropExample.tsx      |  93 +++--
 packages/editor/api-report.api.md             |   3 +
 .../editor/shapes/BaseFrameLikeShapeUtil.tsx  |   5 +
 .../editor/src/lib/editor/shapes/ShapeUtil.ts |  20 +-
 packages/editor/src/lib/utils/reparenting.ts  |  31 +-
 .../tools/SelectTool/DragAndDropManager.ts    |  76 +++-
 packages/tldraw/src/test/dragAndDrop.test.ts  | 341 ++++++++++++++++++
 packages/tldraw/src/test/frames.test.ts       |  62 ++++
 10 files changed, 583 insertions(+), 67 deletions(-)
 create mode 100644 packages/tldraw/src/test/dragAndDrop.test.ts

diff --git a/apps/docs/content/releases/next.mdx b/apps/docs/content/releases/next.mdx
index dd198da81364..11393b13c5f9 100644
--- a/apps/docs/content/releases/next.mdx
+++ b/apps/docs/content/releases/next.mdx
@@ -298,7 +298,7 @@ class AudioAssetUtil extends AssetUtil<TLAudioAsset> {
 
 Custom shapes can now opt into frame-like behavior: clipping children, acting as a parent on paste and drag-in, blocking erasure from inside, and supporting full-brush selection. Previously, frame behavior was hardcoded to the built-in `frame` type; the editor and tools now route frame checks through `editor.getShapeUtil(shape).isFrameLike(shape)`.
 
-The easiest way to build one is to extend the new `BaseFrameLikeShapeUtil` abstract class, which provides sensible defaults for `isFrameLike`, `providesBackgroundForChildren`, `canReceiveNewChildrenOfType`, `getClipPath`, `onDragShapesIn`, and `onDragShapesOut`:
+The easiest way to build one is to extend the new `BaseFrameLikeShapeUtil` abstract class, which provides sensible defaults for `isFrameLike`, `providesBackgroundForChildren`, `canReceiveNewChildrenOfType`, `canRemoveChildrenOfType`, `getClipPath`, `onDragShapesIn`, and `onDragShapesOut`:
 
 ```tsx
 import { BaseFrameLikeShapeUtil, SVGContainer } from '@tldraw/editor'
diff --git a/apps/docs/content/sdk-features/drag-and-drop.mdx b/apps/docs/content/sdk-features/drag-and-drop.mdx
index ec78bc5df365..d686b6785f69 100644
--- a/apps/docs/content/sdk-features/drag-and-drop.mdx
+++ b/apps/docs/content/sdk-features/drag-and-drop.mdx
@@ -169,7 +169,7 @@ Only shapes that implement drag callbacks are considered as drop targets. If you
 
 ## Controlling which shapes can be dropped
 
-Use the [ShapeUtil#canReceiveNewChildrenOfType](?) method to control which shape types your container accepts:
+Use the [ShapeUtil#canReceiveNewChildrenOfType](?) method to control which shape types your container accepts. The editor uses it to decide whether `onDragShapesIn` and `onDropShapesOver` fire for a dragged shape:
 
 ```typescript
 override canReceiveNewChildrenOfType(shape: MyContainerShape, type: TLShape['type']) {
@@ -178,7 +178,20 @@ override canReceiveNewChildrenOfType(shape: MyContainerShape, type: TLShape['typ
 }
 ```
 
-You must check this yourself in your drag callbacks. The editor does not call it automatically.
+The default is `false`, so any shape that should accept dropped children must override this method. `onDragShapesOver` is not gated by this method, which lets you provide visual feedback even when the target won't accept the drop.
+
+## Controlling which shapes can be dragged out
+
+Use the [ShapeUtil#canRemoveChildrenOfType](?) method to control which child shape types can be dragged out of your container. The editor uses it to decide whether `onDragShapesOut` fires for a child shape, and to decide whether the editor should automatically reparent a child that has moved outside its parent's geometry:
+
+```typescript
+override canRemoveChildrenOfType(shape: MyContainerShape, type: TLShape['type']) {
+	// Pin certain children in place; allow others to be removed
+	return type !== 'pinned-item'
+}
+```
+
+The default is `true`, so children can be dragged out of any container unless this method is overridden.
 
 ## Example: slot container
 
diff --git a/apps/examples/src/examples/shapes/tools/drag-and-drop/DragAndDropExample.tsx b/apps/examples/src/examples/shapes/tools/drag-and-drop/DragAndDropExample.tsx
index f5159bbe2b20..fcc27c9045b3 100644
--- a/apps/examples/src/examples/shapes/tools/drag-and-drop/DragAndDropExample.tsx
+++ b/apps/examples/src/examples/shapes/tools/drag-and-drop/DragAndDropExample.tsx
@@ -1,12 +1,15 @@
 import {
+	BaseFrameLikeShapeUtil,
 	Circle2d,
 	Geometry2d,
+	Group2d,
 	HTMLContainer,
 	Rectangle2d,
 	ShapeUtil,
-	TLDragShapesOutInfo,
+	TLBaseBoxShape,
 	TLShape,
 	Tldraw,
+	Vec,
 } from 'tldraw'
 import 'tldraw/tldraw.css'
 
@@ -16,13 +19,15 @@ const MY_COUNTER_SHAPE_TYPE = 'my-counter-shape'
 // [1]
 declare module 'tldraw' {
 	export interface TLGlobalShapePropsMap {
-		[MY_GRID_SHAPE_TYPE]: Record<string, never>
+		[MY_GRID_SHAPE_TYPE]: { w: number; h: number }
 		[MY_COUNTER_SHAPE_TYPE]: Record<string, never>
 	}
 }
 
 // [2]
-type MyGridShape = TLShape<typeof MY_GRID_SHAPE_TYPE>
+type MyGridShape = TLBaseBoxShape & {
+	type: typeof MY_GRID_SHAPE_TYPE
+}
 type MyCounterShape = TLShape<typeof MY_COUNTER_SHAPE_TYPE>
 
 // [3]
@@ -65,52 +70,57 @@ class MyCounterShapeUtil extends ShapeUtil<MyCounterShape> {
 }
 
 // [4]
-class MyGridShapeUtil extends ShapeUtil<MyGridShape> {
+class MyGridShapeUtil extends BaseFrameLikeShapeUtil<MyGridShape> {
 	static override type = MY_GRID_SHAPE_TYPE
 
 	getDefaultProps(): MyGridShape['props'] {
-		return {}
+		return {
+			w: SLOT_SIZE * 5,
+			h: SLOT_SIZE * 2,
+		}
 	}
 
-	getGeometry(): Geometry2d {
-		return new Rectangle2d({
-			width: SLOT_SIZE * 5,
-			height: SLOT_SIZE * 2,
-			isFilled: true,
+	override getGeometry(shape: MyGridShape): Geometry2d {
+		return new Group2d({
+			children: [
+				new Rectangle2d({
+					width: shape.props.w,
+					height: shape.props.h,
+					isFilled: true,
+				}),
+			],
 		})
 	}
 
-	override canResize(shape: MyGridShape) {
+	override canResize(_shape: MyGridShape) {
 		return false
 	}
-	override hideResizeHandles(shape: MyGridShape) {
+
+	override hideResizeHandles(_shape: MyGridShape) {
 		return true
 	}
 
 	// [5]
-	override onDragShapesIn(shape: MyGridShape, draggingShapes: TLShape[]): void {
-		const { editor } = this
-		const reparentingShapes = draggingShapes.filter(
-			(s) => s.parentId !== shape.id && s.type === 'my-counter-shape'
-		)
-		if (reparentingShapes.length === 0) return
-		editor.reparentShapes(reparentingShapes, shape.id)
+	override canReceiveNewChildrenOfType(_shape: MyGridShape, type: TLShape['type']) {
+		return type === MY_COUNTER_SHAPE_TYPE
 	}
 
 	// [6]
-	override onDragShapesOut(
-		shape: MyGridShape,
-		draggingShapes: TLShape[],
-		info: TLDragShapesOutInfo
-	): void {
-		const { editor } = this
-		const reparentingShapes = draggingShapes.filter((s) => s.parentId !== shape.id)
-		if (!info.nextDraggingOverShapeId) {
-			editor.reparentShapes(reparentingShapes, editor.getCurrentPageId())
-		}
+	override canRemoveChildrenOfType(_shape: MyGridShape, type: TLShape['type']) {
+		return type !== MY_COUNTER_SHAPE_TYPE
 	}
 
-	component() {
+	// [7]
+	override getClipPath(_shape: MyGridShape): Vec[] {
+		return [
+			new Vec(0, 0),
+			new Vec(SLOT_SIZE * 5, 0),
+			new Vec(SLOT_SIZE * 5, SLOT_SIZE * 2),
+			new Vec(0, SLOT_SIZE * 2),
+		]
+	}
+
+	component(shape: MyGridShape) {
 		return (
 			<HTMLContainer
 				style={{
@@ -118,6 +128,8 @@ class MyGridShapeUtil extends ShapeUtil<MyGridShape> {
 					borderRight: '1px solid #ccc',
 					borderBottom: '1px solid #ccc',
 					backgroundSize: `${SLOT_SIZE}px ${SLOT_SIZE}px`,
+					width: shape.props.w,
+					height: shape.props.h,
 					backgroundImage: `
 						linear-gradient(to right, #ccc 1px, transparent 1px),
 						linear-gradient(to bottom, #ccc 1px, transparent 1px)
@@ -127,9 +139,9 @@ class MyGridShapeUtil extends ShapeUtil<MyGridShape> {
 		)
 	}
 
-	getIndicatorPath() {
+	override getIndicatorPath(shape: MyGridShape) {
 		const path = new Path2D()
-		path.rect(0, 0, SLOT_SIZE * 5, SLOT_SIZE * 2)
+		path.rect(0, 0, shape.props.w, shape.props.h)
 		return path
 	}
 }
@@ -170,10 +182,19 @@ Create a ShapeUtil for the grid shape. This creates a rectangular grid that can
 Rectangle2d geometry and render it with CSS grid lines using background gradients.
 
 [5]
-Override onDragShapesIn to handle when shapes are dragged into the grid. We filter for counter shapes that
-aren't already children of this grid, then reparent them to become children. This makes them move with the grid.
+Override canReceiveNewChildrenOfType to gate which shape types can be dragged into the grid. The editor only
+fires onDragShapesIn for shapes that pass this check. The default is false, so any container that wants to
+receive dragged shapes must override this. Here we accept counter shapes only.
 
 [6]
-Override onDragShapesOut to handle when shapes are dragged out of the grid. If they're not being dragged to
-another shape, we reparent them back to the page level, making them independent again.
+Override canRemoveChildrenOfType to gate which child shape types are allowed to be dragged out. The editor
+only fires onDragShapesOut for shapes that pass this check, and it also won't auto-reparent ("kick out") a
+child of a blocked type when it's moved outside the parent's geometry. The default is true. Here, we don't 
+allow any child counter shapes to be dragged out.
+
+[7]
+Override getClipPath so children are visually clipped to the grid's bounds while they're parented to it.
+This is independent of the drag-and-drop callbacks above; it just makes it visually obvious that a counter
+"belongs" to the grid while it's a child. Try dragging a counter outside the grid — because counters are
+pinned, the counter stays a child of the grid and the clip path keeps it inside.
 */
diff --git a/packages/editor/api-report.api.md b/packages/editor/api-report.api.md
index dfc1aec5204a..b6a7b3d7989e 100644
--- a/packages/editor/api-report.api.md
+++ b/packages/editor/api-report.api.md
@@ -196,6 +196,8 @@ export abstract class BaseFrameLikeShapeUtil<Shape extends TLBaseBoxShape> exten
     // (undocumented)
     canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
     // (undocumented)
+    canRemoveChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
+    // (undocumented)
     getClipPath(shape: Shape): undefined | Vec[];
     // (undocumented)
     isFrameLike(_shape: Shape): boolean;
@@ -2996,6 +2998,7 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
     canEditInReadonly(shape: Shape): boolean;
     canEditWhileLocked(shape: Shape): boolean;
     canReceiveNewChildrenOfType(shape: Shape, type: TLShape['type']): boolean;
+    canRemoveChildrenOfType(shape: Shape, type: TLShape['type']): boolean;
     canResize(shape: Shape): boolean;
     canResizeChildren(shape: Shape): boolean;
     canScroll(shape: Shape): boolean;
diff --git a/packages/editor/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx b/packages/editor/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx
index ed33d519b2a3..708823834e0f 100644
--- a/packages/editor/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx
+++ b/packages/editor/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx
@@ -15,6 +15,7 @@ import { TLDragShapesInInfo, TLDragShapesOutInfo } from './ShapeUtil'
  * - `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
@@ -60,6 +61,10 @@ export abstract class BaseFrameLikeShapeUtil<
 		return !shape.isLocked
 	}
 
+	override canRemoveChildrenOfType(shape: Shape, _type: TLShape['type']): boolean {
+		return !shape.isLocked
+	}
+
 	override getClipPath(shape: Shape): Vec[] | undefined {
 		return this.editor.getShapeGeometry(shape.id).vertices
 	}
diff --git a/packages/editor/src/lib/editor/shapes/ShapeUtil.ts b/packages/editor/src/lib/editor/shapes/ShapeUtil.ts
index d5a25625df30..76af660d1884 100644
--- a/packages/editor/src/lib/editor/shapes/ShapeUtil.ts
+++ b/packages/editor/src/lib/editor/shapes/ShapeUtil.ts
@@ -546,7 +546,9 @@ export 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.
@@ -556,6 +558,22 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 		return false
 	}
 
+	/**
+	 * 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']) {
+		return true
+	}
+
 	/**
 	 * Get the shape as an SVG object.
 	 *
diff --git a/packages/editor/src/lib/utils/reparenting.ts b/packages/editor/src/lib/utils/reparenting.ts
index f045ad80c667..0149830e724f 100644
--- a/packages/editor/src/lib/utils/reparenting.ts
+++ b/packages/editor/src/lib/utils/reparenting.ts
@@ -42,10 +42,17 @@ export function kickoutOccludedShapes(
 		} else {
 			const overlappingChildren = getOverlappingShapes(editor, parent.id, childIds)
 			if (overlappingChildren.length < childIds.length) {
-				parentsToLostChildren.set(
-					parent,
-					childIds.filter((id) => !overlappingChildren.includes(id))
-				)
+				const parentUtil = editor.getShapeUtil(parent)
+				const lostChildIds = childIds.filter((id) => {
+					if (overlappingChildren.includes(id)) return false
+					const child = editor.getShape(id)
+					if (!child) return false
+					// Respect the parent's removal gate: if it pins this child type, don't kick it out.
+					return parentUtil.canRemoveChildrenOfType(parent, child.type)
+				})
+				if (lostChildIds.length > 0) {
+					parentsToLostChildren.set(parent, lostChildIds)
+				}
 			}
 		}
 	}
@@ -238,11 +245,17 @@ export function getDroppedShapesToNewParents(
 	const potentialParentShapes = editor
 		.getCurrentPageShapesSorted()
 		// filter out any shapes that aren't frames or that are included among the provided shapes
-		.filter(
-			(s) =>
-				editor.getShapeUtil(s).canReceiveNewChildrenOfType?.(s, s.type) &&
-				!remainingShapesToReparent.has(s)
-		)
+		.filter((parentShape) => {
+			if (remainingShapesToReparent.has(parentShape)) return false
+
+			const parentUtil = editor.getShapeUtil(parentShape)
+			for (const childShape of remainingShapesToReparent) {
+				if (parentUtil.canReceiveNewChildrenOfType(parentShape, childShape.type)) {
+					return true
+				}
+			}
+			return false
+		})
 
 	parentCheck: for (let i = potentialParentShapes.length - 1; i >= 0; i--) {
 		const parentShape = potentialParentShapes[i]
diff --git a/packages/tldraw/src/lib/tools/SelectTool/DragAndDropManager.ts b/packages/tldraw/src/lib/tools/SelectTool/DragAndDropManager.ts
index 23f4011c8596..8187b53d548c 100644
--- a/packages/tldraw/src/lib/tools/SelectTool/DragAndDropManager.ts
+++ b/packages/tldraw/src/lib/tools/SelectTool/DragAndDropManager.ts
@@ -113,11 +113,14 @@ export class DragAndDropManager {
 
 		if (draggingOverShape) {
 			const util = editor.getShapeUtil(draggingOverShape)
-			util.onDropShapesOver?.(draggingOverShape, shapes, {
-				initialDraggingOverShapeId: this.initialDraggingOverShape?.id ?? null,
-				initialParentIds: this.initialParentIds,
-				initialIndices: this.initialIndices,
-			})
+			const receivableShapes = getReceivableShapesForTarget(editor, draggingOverShape, shapes)
+			if (receivableShapes.length > 0) {
+				util.onDropShapesOver?.(draggingOverShape, receivableShapes, {
+					initialDraggingOverShapeId: this.initialDraggingOverShape?.id ?? null,
+					initialParentIds: this.initialParentIds,
+					initialIndices: this.initialIndices,
+				})
+			}
 		}
 
 		this.dispose()
@@ -176,23 +179,42 @@ export class DragAndDropManager {
 
 			if (this.prevDraggingOverShape) {
 				const util = editor.getShapeUtil(this.prevDraggingOverShape)
-				util.onDragShapesOut?.(this.editor.getShape(this.prevDraggingOverShape)!, draggingShapes, {
-					nextDraggingOverShapeId: nextDraggingOverShape?.id ?? null,
-					initialDraggingOverShapeId: this.initialDraggingOverShape?.id ?? null,
-					initialParentIds: this.initialParentIds,
-					initialIndices: this.initialIndices,
-				})
+				const prevDraggingOverShape = this.editor.getShape(this.prevDraggingOverShape)!
+				const removableShapes = getRemovableShapesForTarget(
+					editor,
+					prevDraggingOverShape,
+					draggingShapes
+				)
+				if (removableShapes.length > 0) {
+					util.onDragShapesOut?.(prevDraggingOverShape, removableShapes, {
+						nextDraggingOverShapeId: nextDraggingOverShape?.id ?? null,
+						initialDraggingOverShapeId: this.initialDraggingOverShape?.id ?? null,
+						initialParentIds: this.initialParentIds,
+						initialIndices: this.initialIndices,
+					})
+				}
 			}
 
 			if (nextDraggingOverShape) {
 				const util = editor.getShapeUtil(nextDraggingOverShape)
-				util.onDragShapesIn?.(nextDraggingOverShape, draggingShapes, {
-					initialDraggingOverShapeId: this.initialDraggingOverShape?.id ?? null,
-					prevDraggingOverShapeId: this.prevDraggingOverShape?.id ?? null,
-					initialParentIds: this.initialParentIds,
-					initialIndices: this.initialIndices,
-				})
-				editor.setHintingShapes([nextDraggingOverShape.id])
+				const receivableShapes = getReceivableShapesForTarget(
+					editor,
+					nextDraggingOverShape,
+					draggingShapes
+				)
+				if (receivableShapes.length > 0) {
+					util.onDragShapesIn?.(nextDraggingOverShape, receivableShapes, {
+						initialDraggingOverShapeId: this.initialDraggingOverShape?.id ?? null,
+						prevDraggingOverShapeId: this.prevDraggingOverShape?.id ?? null,
+						initialParentIds: this.initialParentIds,
+						initialIndices: this.initialIndices,
+					})
+					editor.setHintingShapes([nextDraggingOverShape.id])
+				} else if (this.prevDraggingOverShape) {
+					// The new target won't accept anything; clear any stale hint left on the
+					// previous target.
+					editor.setHintingShapes([])
+				}
 			} else if (this.prevDraggingOverShape) {
 				editor.setHintingShapes([])
 			}
@@ -204,3 +226,21 @@ export class DragAndDropManager {
 		this.prevDraggingOverShape = nextDraggingOverShape
 	}
 }
+
+function getReceivableShapesForTarget(
+	editor: Editor,
+	targetShape: TLShape,
+	draggingShapes: TLShape[]
+) {
+	const util = editor.getShapeUtil(targetShape)
+	return draggingShapes.filter((shape) => util.canReceiveNewChildrenOfType(targetShape, shape.type))
+}
+
+function getRemovableShapesForTarget(
+	editor: Editor,
+	targetShape: TLShape,
+	draggingShapes: TLShape[]
+) {
+	const util = editor.getShapeUtil(targetShape)
+	return draggingShapes.filter((shape) => util.canRemoveChildrenOfType(targetShape, shape.type))
+}
diff --git a/packages/tldraw/src/test/dragAndDrop.test.ts b/packages/tldraw/src/test/dragAndDrop.test.ts
new file mode 100644
index 000000000000..d0a3ee4cf5a0
--- /dev/null
+++ b/packages/tldraw/src/test/dragAndDrop.test.ts
@@ -0,0 +1,341 @@
+import {
+	createShapeId,
+	Geometry2d,
+	kickoutOccludedShapes,
+	Rectangle2d,
+	ShapeUtil,
+	TLBaseShape,
+	TLDragShapesOutInfo,
+	TLDropShapesOverInfo,
+	TLShape,
+} from '@tldraw/editor'
+import { vi } from 'vitest'
+import { TestEditor } from './TestEditor'
+
+vi.useFakeTimers()
+
+const GRID_TYPE = 'my-grid-shape'
+const COUNTER_TYPE = 'my-counter-shape'
+
+declare module '@tldraw/tlschema' {
+	export interface TLGlobalShapePropsMap {
+		[GRID_TYPE]: { w: number; h: number }
+		[COUNTER_TYPE]: Record<string, never>
+	}
+}
+
+type MyGridShape = TLBaseShape<typeof GRID_TYPE, { w: number; h: number }>
+type MyCounterShape = TLBaseShape<typeof COUNTER_TYPE, Record<string, never>>
+
+class CounterShapeUtil extends ShapeUtil<MyCounterShape> {
+	static override type = COUNTER_TYPE
+	override getDefaultProps(): MyCounterShape['props'] {
+		return {} as MyCounterShape['props']
+	}
+	override getGeometry(_: MyCounterShape): Geometry2d {
+		return new Rectangle2d({ width: 50, height: 50, isFilled: true })
+	}
+	override component() {
+		return null as any
+	}
+	override getIndicatorPath() {
+		return undefined
+	}
+}
+
+const onDropSpy =
+	vi.fn<(shape: MyGridShape, shapes: TLShape[], info: TLDropShapesOverInfo) => void>()
+
+class GridShapeUtil extends ShapeUtil<MyGridShape> {
+	static override type = GRID_TYPE
+	override getDefaultProps(): MyGridShape['props'] {
+		return { w: 500, h: 200 }
+	}
+	override getGeometry(shape: MyGridShape): Geometry2d {
+		return new Rectangle2d({ width: shape.props.w, height: shape.props.h, isFilled: true })
+	}
+	override component() {
+		return null as any
+	}
+	override getIndicatorPath() {
+		return undefined
+	}
+
+	override canReceiveNewChildrenOfType(_shape: MyGridShape, type: TLShape['type']) {
+		return type === COUNTER_TYPE
+	}
+	override canRemoveChildrenOfType(_shape: MyGridShape, type: TLShape['type']) {
+		// Pin counter shapes; everything else can leave.
+		return type !== COUNTER_TYPE
+	}
+	override onDragShapesIn(shape: MyGridShape, draggingShapes: TLShape[]): void {
+		const reparenting = draggingShapes.filter((s) => s.parentId !== shape.id)
+		if (reparenting.length === 0) return
+		this.editor.reparentShapes(reparenting, shape.id)
+	}
+	override onDragShapesOut(
+		shape: MyGridShape,
+		draggingShapes: TLShape[],
+		info: TLDragShapesOutInfo
+	): void {
+		if (info.nextDraggingOverShapeId) return
+		const reparenting = draggingShapes.filter((s) => s.parentId === shape.id)
+		this.editor.reparentShapes(reparenting, this.editor.getCurrentPageId())
+	}
+	override onDropShapesOver(
+		shape: MyGridShape,
+		shapes: TLShape[],
+		info: TLDropShapesOverInfo
+	): void {
+		onDropSpy(shape, shapes, info)
+	}
+}
+
+let editor: TestEditor
+
+const ids = {
+	grid: createShapeId('grid'),
+	counter: createShapeId('counter'),
+}
+
+beforeEach(() => {
+	onDropSpy.mockReset()
+	editor = new TestEditor({ shapeUtils: [GridShapeUtil, CounterShapeUtil] })
+})
+afterEach(() => {
+	editor?.dispose()
+})
+
+describe('canRemoveChildrenOfType for non-frame containers', () => {
+	it('pins children whose type the parent refuses to remove', () => {
+		// Grid at (100, 100) covers (100, 100) to (600, 300)
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+
+		// Counter starts on the page outside the grid
+		editor.createShape({ id: ids.counter, type: COUNTER_TYPE, x: 700, y: 100 })
+		expect(editor.getShape(ids.counter)!.parentId).toBe(editor.getCurrentPageId())
+
+		// Drag the counter onto the grid; it should reparent to the grid
+		editor.setCurrentTool('select')
+		editor.pointerDown(725, 125, ids.counter).pointerMove(300, 200)
+		vi.advanceTimersByTime(300)
+		editor.pointerUp(300, 200)
+		expect(editor.getShape(ids.counter)!.parentId).toBe(ids.grid)
+
+		// Now drag the counter back off the grid
+		editor.pointerDown(300, 200, ids.counter).pointerMove(800, 800)
+		vi.advanceTimersByTime(300)
+		editor.pointerUp(800, 800)
+
+		// Counter should still be parented to the grid because the grid pins counter shapes
+		expect(editor.getShape(ids.counter)!.parentId).toBe(ids.grid)
+	})
+
+	it('still allows children whose type the parent does allow to be removed', () => {
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+
+		// Programmatically place a non-counter (geo) shape inside the grid; canRemove allows
+		// non-counter types to be removed via drag/kickout.
+		const geoId = createShapeId('geo')
+		editor.createShape({
+			id: geoId,
+			type: 'geo',
+			parentId: ids.grid,
+			x: 50,
+			y: 50,
+			props: { w: 50, h: 50 },
+		})
+		expect(editor.getShape(geoId)!.parentId).toBe(ids.grid)
+
+		// Drag the geo entirely out of the grid
+		editor.setCurrentTool('select')
+		editor.pointerDown(175, 175, geoId).pointerMove(800, 800)
+		vi.advanceTimersByTime(300)
+		editor.pointerUp(800, 800)
+
+		// Geo should be reparented to the page (canRemove returns true for non-counter types)
+		expect(editor.getShape(geoId)!.parentId).toBe(editor.getCurrentPageId())
+	})
+})
+
+describe('kickoutOccludedShapes respects canRemoveChildrenOfType', () => {
+	it('keeps a pinned child parented when it no longer overlaps its parent', () => {
+		// Grid covers (100, 100) to (600, 300)
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+
+		// Counter created inside the grid
+		editor.createShape({
+			id: ids.counter,
+			type: COUNTER_TYPE,
+			parentId: ids.grid,
+			x: 50,
+			y: 50,
+		})
+		expect(editor.getShape(ids.counter)!.parentId).toBe(ids.grid)
+
+		// Move the counter (in parent-local space) so it sits outside the grid's geometry
+		editor.updateShape({
+			id: ids.counter,
+			type: COUNTER_TYPE,
+			x: 1000,
+			y: 1000,
+		})
+
+		// Trigger kickout directly (no drag involved)
+		kickoutOccludedShapes(editor, [ids.counter])
+
+		// Counter should still be parented to the grid because the grid pins counter shapes
+		expect(editor.getShape(ids.counter)!.parentId).toBe(ids.grid)
+	})
+
+	it('kicks out a non-pinned child that no longer overlaps its parent', () => {
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+
+		const geoId = createShapeId('geo')
+		editor.createShape({
+			id: geoId,
+			type: 'geo',
+			parentId: ids.grid,
+			x: 50,
+			y: 50,
+			props: { w: 50, h: 50 },
+		})
+		expect(editor.getShape(geoId)!.parentId).toBe(ids.grid)
+
+		// Move the geo (in parent-local space) so it sits outside the grid's geometry
+		editor.updateShape({
+			id: geoId,
+			type: 'geo',
+			x: 1000,
+			y: 1000,
+		})
+
+		kickoutOccludedShapes(editor, [geoId])
+
+		// Geo should be reparented to the page since the grid does not pin non-counter children
+		expect(editor.getShape(geoId)!.parentId).toBe(editor.getCurrentPageId())
+	})
+
+	it('still kicks out a pinned child when its parent is being filtered out (e.g. removed)', () => {
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+
+		editor.createShape({
+			id: ids.counter,
+			type: COUNTER_TYPE,
+			parentId: ids.grid,
+			x: 50,
+			y: 50,
+		})
+		expect(editor.getShape(ids.counter)!.parentId).toBe(ids.grid)
+
+		// Simulate the parent being removed by passing a filter that rejects the grid. In this
+		// branch kickout intentionally bypasses canRemoveChildrenOfType; otherwise children of a
+		// pinned parent could not survive their parent being deleted.
+		kickoutOccludedShapes(editor, [ids.counter], {
+			filter: (parent) => parent.id !== ids.grid,
+		})
+
+		expect(editor.getShape(ids.counter)!.parentId).toBe(editor.getCurrentPageId())
+	})
+})
+
+describe('onDropShapesOver gating by canReceiveNewChildrenOfType', () => {
+	it('fires with only the shapes whose type passes the gate', () => {
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+		editor.createShape({ id: ids.counter, type: COUNTER_TYPE, x: 700, y: 100 })
+
+		// Drag the counter onto the grid and drop it
+		editor.setCurrentTool('select')
+		editor.pointerDown(725, 125, ids.counter).pointerMove(300, 200)
+		vi.advanceTimersByTime(300)
+		editor.pointerUp(300, 200)
+
+		expect(onDropSpy).toHaveBeenCalledTimes(1)
+		const [, droppedShapes] = onDropSpy.mock.calls[0]
+		expect(droppedShapes.map((s) => s.id)).toEqual([ids.counter])
+	})
+
+	it('does not fire when no dragged shape passes the gate', () => {
+		editor.createShape({ id: ids.grid, type: GRID_TYPE, x: 100, y: 100 })
+
+		// A geo shape is rejected by the grid's canReceiveNewChildrenOfType
+		const geoId = createShapeId('geo')
+		editor.createShape({
+			id: geoId,
+			type: 'geo',
+			x: 700,
+			y: 100,
+			props: { w: 50, h: 50 },
+		})
+
+		editor.setCurrentTool('select')
+		editor.pointerDown(725, 125, geoId).pointerMove(300, 200)
+		vi.advanceTimersByTime(300)
+		editor.pointerUp(300, 200)
+
+		expect(onDropSpy).not.toHaveBeenCalled()
+	})
+})
+
+const REJECT_TYPE = 'my-reject-shape'
+
+declare module '@tldraw/tlschema' {
+	export interface TLGlobalShapePropsMap {
+		[REJECT_TYPE]: { w: number; h: number }
+	}
+}
+
+type MyRejectShape = TLBaseShape<typeof REJECT_TYPE, { w: number; h: number }>
+
+// A container that's a valid drag target (it has drag callbacks) but rejects every dragged
+// type via canReceiveNewChildrenOfType.
+class RejectAllShapeUtil extends ShapeUtil<MyRejectShape> {
+	static override type = REJECT_TYPE
+	override getDefaultProps(): MyRejectShape['props'] {
+		return { w: 500, h: 200 }
+	}
+	override getGeometry(shape: MyRejectShape): Geometry2d {
+		return new Rectangle2d({ width: shape.props.w, height: shape.props.h, isFilled: true })
+	}
+	override component() {
+		return null as any
+	}
+	override getIndicatorPath() {
+		return undefined
+	}
+	override canReceiveNewChildrenOfType(_shape: MyRejectShape, _type: TLShape['type']) {
+		return false
+	}
+	override onDropShapesOver(_shape: MyRejectShape) {
+		// Present so getDraggingOverShape considers this a valid drag target.
+	}
+}
+
+describe('drag-over hinting respects canReceiveNewChildrenOfType', () => {
+	it('clears the hint when moving from an accepting target to a rejecting one', () => {
+		editor.dispose()
+		editor = new TestEditor({
+			shapeUtils: [GridShapeUtil, CounterShapeUtil, RejectAllShapeUtil],
+		})
+
+		const gridId = createShapeId('grid')
+		const rejectId = createShapeId('reject')
+		editor.createShape({ id: gridId, type: GRID_TYPE, x: 0, y: 0 })
+		editor.createShape({ id: rejectId, type: REJECT_TYPE, x: 700, y: 0 })
+		editor.createShape({ id: ids.counter, type: COUNTER_TYPE, x: 1500, y: 100 })
+
+		editor.setCurrentTool('select')
+
+		// Drag the counter over the grid (accepts) — hint should be set on the grid.
+		editor.pointerDown(1525, 125, ids.counter).pointerMove(250, 100)
+		vi.advanceTimersByTime(300)
+		expect(editor.getHintingShapeIds()).toEqual([gridId])
+
+		// Move the counter over the rejecting container — hint should clear, not linger on grid.
+		editor.pointerMove(950, 100)
+		vi.advanceTimersByTime(300)
+		expect(editor.getHintingShapeIds()).toEqual([])
+
+		editor.pointerUp(950, 100)
+	})
+})
diff --git a/packages/tldraw/src/test/frames.test.ts b/packages/tldraw/src/test/frames.test.ts
index 1bb6dea1fee6..11f0b439e1b3 100644
--- a/packages/tldraw/src/test/frames.test.ts
+++ b/packages/tldraw/src/test/frames.test.ts
@@ -4,6 +4,7 @@ import {
 	TLArrowShape,
 	TLFrameShape,
 	TLGeoShape,
+	TLShape,
 	TLShapeId,
 	createShapeId,
 	toRichText,
@@ -29,6 +30,22 @@ const ids = {
 	boxA: createShapeId('boxA'),
 }
 
+class GeoRejectingFrameShapeUtil extends FrameShapeUtil {
+	static override type = 'frame' as const
+
+	override canReceiveNewChildrenOfType(_shape: TLFrameShape, type: TLShape['type']) {
+		return type !== 'geo'
+	}
+}
+
+class GeoPinningFrameShapeUtil extends FrameShapeUtil {
+	static override type = 'frame' as const
+
+	override canRemoveChildrenOfType(_shape: TLFrameShape, type: TLShape['type']) {
+		return type !== 'geo'
+	}
+}
+
 describe('creating frames', () => {
 	it('can be done', () => {
 		editor.setCurrentTool('frame')
@@ -444,6 +461,51 @@ describe('frame shapes', () => {
 		expect(editor.getOnlySelectedShape()!.parentId).toBe(frameId)
 	})
 
+	it("doesn't drag shapes into a frame that rejects their type", () => {
+		editor.dispose()
+		editor = new TestEditor({ shapeUtils: [GeoRejectingFrameShapeUtil] })
+
+		const frameId = dragCreateFrame({ down: [0, 0], move: [200, 200], up: [200, 200] })
+
+		editor.createShapes([
+			{ type: 'geo', id: ids.boxA, x: 250, y: 250, props: { w: 50, h: 50, fill: 'solid' } },
+		])
+
+		expect(editor.getShape(ids.boxA)!.parentId).toBe(editor.getCurrentPageId())
+
+		editor.setCurrentTool('select')
+		editor.pointerDown(275, 275, ids.boxA).pointerMove(100, 100)
+		vi.advanceTimersByTime(300)
+
+		expect(editor.getShape(ids.boxA)!.parentId).toBe(editor.getCurrentPageId())
+		expect(editor.getHintingShapeIds()).toHaveLength(0)
+
+		editor.pointerUp(100, 100)
+
+		expect(editor.getShape(ids.boxA)!.parentId).toBe(editor.getCurrentPageId())
+		expect(editor.getShape(frameId)!.parentId).toBe(editor.getCurrentPageId())
+	})
+
+	it("doesn't drag shapes out of a frame that pins their type", () => {
+		editor.dispose()
+		editor = new TestEditor({ shapeUtils: [GeoPinningFrameShapeUtil] })
+
+		// Create a frame and a geo shape that extends partially outside the frame so we
+		// can grab it by its outside portion (clicking inside the frame would select the frame).
+		const frameId = dragCreateFrame({ down: [0, 0], move: [100, 100], up: [100, 100] })
+		const rectId = dragCreateRect({ down: [80, 50], move: [120, 60], up: [120, 60] })
+		expect(editor.getShape(rectId)!.parentId).toBe(frameId)
+
+		// Drag the rect entirely out of the frame by clicking on the part that's outside
+		editor.pointerDown(110, 50)
+		editor.pointerMove(140, 50)
+		expect(editor.getShape(rectId)!.parentId).toBe(frameId)
+		editor.pointerUp(140, 50)
+
+		// The rect should still be parented to the frame because the frame pins geo shapes
+		expect(editor.getShape(rectId)!.parentId).toBe(frameId)
+	})
+
 	it('can be snapped to when dragging other shapes', () => {
 		editor.setCurrentTool('frame')
 		editor.pointerDown(100, 100).pointerMove(200, 200).pointerUp(200, 200)

From 7ea68e5d3c367557036abdc626e1e112f4b9188f Mon Sep 17 00:00:00 2001
From: Steve Ruiz <steveruizok@gmail.com>
Date: Wed, 6 May 2026 15:49:16 +0100
Subject: [PATCH 11/11] chore(skills): tldraw-migrate sources release notes
 from github (#8779)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to keep the tldraw-migrate skill's release-notes view aligned
with what's actually on `main`, this PR switches the changelog source
from `tldraw.dev/llms-releases.txt` to GitHub's
`apps/docs/content/releases/` directory. A few smaller improvements ride
along to make the skill easier to distribute across agents.

Previously the skill `curl`'d the published `llms-releases.txt` from
tldraw.dev, which meant pre-release notes (`next.mdx`) and recently
merged but unpublished release-note edits were invisible to the
migration workflow. The skill now lists `apps/docs/content/releases/`
via the GitHub contents API and fetches each `.mdx` directly from
`raw.githubusercontent.com`. GitHub is the source of truth.

Other changes:

- Pre-release semver suffixes (e.g. `4.7.0-canary.abc`) are now
preserved in `detect-versions.mjs` and compared correctly in the new
fetcher, so a user on a canary gets the right version range and the
upcoming `next.mdx` content.
- The `${SKILL_DIR}` probe gained `.codex/skills/`.
- Removed `disable-model-invocation: true` from the frontmatter so any
agent that respects skill metadata can auto-invoke after copying.
- Added a one-line cross-agent note above the auto-fetch blocks for
agents that don't auto-run Claude Code's `!`-prefix syntax (Cursor,
Codex, plain Claude API, etc.).
- Replaced `filter-changelog.mjs` with `fetch-release-notes.mjs`
(filtering happens at fetch time).

The motivation is partly to support distributing the skill via a
one-shot prompt — "copy `skills/tldraw-migrate` from this repo into your
repo and follow it" — across different coding agents.

### Change type

- [x] `improvement`

### Test plan

1. From a project on tldraw 4.4.0, run `/tldraw-migrate` — should fetch
v4.5.0 notes from GitHub and skip `next.mdx` (stable target).
2. From a project on a pre-release like `4.7.0-canary.abc` with target
`canary`, run `/tldraw-migrate` — should fetch `next.mdx` into
`references/tldraw-next.mdx`.
3. Pin a stable upper bound: `node
skills/tldraw-migrate/fetch-release-notes.mjs 4.0.0 4.2.0` — should
include v4.1.0 and v4.2.0 only.
4. Place the skill folder under each of `.claude/skills/`,
`.agents/skills/`, `.codex/skills/`, `.cursor/skills/`, `skills/` —
auto-fetch blocks resolve `SKILL_DIR` correctly in each case.
---
 skills/tldraw-migrate/README.md               |  82 +++++++++
 skills/tldraw-migrate/SKILL.md                |  42 +++--
 skills/tldraw-migrate/detect-versions.mjs     |   7 +-
 skills/tldraw-migrate/fetch-release-notes.mjs | 163 ++++++++++++++++++
 skills/tldraw-migrate/filter-changelog.mjs    |  79 ---------
 5 files changed, 280 insertions(+), 93 deletions(-)
 create mode 100644 skills/tldraw-migrate/README.md
 create mode 100644 skills/tldraw-migrate/fetch-release-notes.mjs
 delete mode 100644 skills/tldraw-migrate/filter-changelog.mjs

diff --git a/skills/tldraw-migrate/README.md b/skills/tldraw-migrate/README.md
new file mode 100644
index 000000000000..4dcae12af03d
--- /dev/null
+++ b/skills/tldraw-migrate/README.md
@@ -0,0 +1,82 @@
+# tldraw-migrate skill
+
+> Note: Are you human? You should probably not be. Pass a link to this file to your agent of choice and have them take it from here.
+
+A portable agent skill that walks an AI coding agent through upgrading a project to a newer version of the tldraw SDK.
+
+This README documents distribution and installation. The skill itself lives in [`SKILL.md`](./SKILL.md).
+
+## Distribution
+
+The canonical source of truth is `skills/tldraw-migrate/` on `main` in the [tldraw monorepo](https://github.com/tldraw/tldraw). Distribute the skill by copying the entire folder into the agent-skills directory of the project being migrated. The skill is self-contained — `SKILL.md`, the three `.mjs` helpers, and a `references/` cache.
+
+### Where to install
+
+Copy `skills/tldraw-migrate/` into one of the following paths in the target project. The skill probes them in this order and uses the first one it finds:
+
+| Path | Harness |
+| --- | --- |
+| `.claude/skills/tldraw-migrate/` | Claude Code |
+| `.agents/skills/tldraw-migrate/` | Generic / open agent-skills spec |
+| `.codex/skills/tldraw-migrate/` | OpenAI Codex |
+| `.cursor/skills/tldraw-migrate/` | Cursor |
+| `skills/tldraw-migrate/` | Fallback / vendored alongside source |
+
+If multiple harnesses share a project, install once and symlink the others to the same folder (this is what the tldraw monorepo itself does — see `AGENTS.md`).
+
+### One-shot install from GitHub
+
+```sh
+DEST=.claude/skills/tldraw-migrate   # or .agents/skills/tldraw-migrate, .cursor/skills/tldraw-migrate, etc.
+mkdir -p "$DEST"
+curl -fsSL https://github.com/tldraw/tldraw/archive/refs/heads/main.tar.gz \
+  | tar -xz --strip-components=3 -C "$DEST" tldraw-main/skills/tldraw-migrate
+```
+
+### Updating an installed copy
+
+The skill changes whenever migration patterns shift in the SDK (new error categories, new helpers, edge-case fixes). Re-run the one-shot install command above to overwrite `SKILL.md` and the helper scripts, or pull the latest from `tldraw/tldraw` main. The skill's *content* — release notes and docs — is auto-refreshed on every invocation, so updating `SKILL.md` itself is only needed when the workflow changes.
+
+### Skill-location override
+
+If the skill is installed somewhere outside the probed locations, export `SKILL_DIR` before invocation:
+
+```sh
+SKILL_DIR=/abs/path/to/tldraw-migrate
+```
+
+The auto-fetch blocks and all internal grep examples honor this variable.
+
+## Requirements
+
+- **Node ≥ 20** for the three helper scripts (`detect-versions.mjs`, `detect-target.mjs`, `fetch-release-notes.mjs`). No npm dependencies — they are zero-dep ES modules.
+- **`curl`** for the docs fetch.
+- **`git`** is optional but improves from-version detection (the skill compares `main`, `HEAD~1`, and the working tree).
+- **`GITHUB_TOKEN`** env var is optional; setting it raises the unauthenticated GitHub API rate limit (60/hr) so re-runs and long version ranges don't fail.
+
+## What gets fetched on invocation
+
+The skill writes three files into `references/` at run time. None of them is committed to the skill's source — they are recreated on demand.
+
+| File | Source | When fetched |
+| --- | --- | --- |
+| `tldraw-releases.txt` | `github.com/tldraw/tldraw` → `apps/docs/content/releases/v*.mdx`, filtered to versions strictly greater than the detected from-version | Always |
+| `tldraw-full-docs.txt` | `tldraw.dev/llms-full.txt` | Cached locally, 30-day TTL — delete the file or wait 30 days to refresh |
+| `tldraw-next.mdx` | `github.com/tldraw/tldraw` → `apps/docs/content/releases/next.mdx` | Pre-release targets only (`canary`, `next`, `beta`, or pre-release semver) |
+
+GitHub is the source of truth, deliberately. `next.mdx` does not exist on npm, and tldraw.dev can lag behind main. This means migration recipes for unreleased versions are available to the skill the moment they land in `main`.
+
+## Harness compatibility
+
+The `!`-prefix bash blocks at the top of `SKILL.md` are written for Claude Code's auto-execute syntax. Other harnesses (Cursor, Codex, plain Claude API, etc.) must run each block as a shell command before continuing the workflow. The skill flags this explicitly at the top of the resources section.
+
+For agent harnesses without slash-command support, the skill still works as a plain workflow document — point the agent at `SKILL.md` and the same step-by-step process applies.
+
+## Files in this folder
+
+- `SKILL.md` — the skill workflow itself
+- `detect-versions.mjs` — resolves the from-version (explicit arg → `main` → `HEAD~1` → working tree)
+- `detect-target.mjs` — resolves the target version (default `latest`; accepts a dist-tag or semver)
+- `fetch-release-notes.mjs` — pulls release notes between two versions from `tldraw/tldraw` main
+- `references/` — auto-populated cache of fetched references (gitignored or freshly recreated)
+- `README.md` — this file
diff --git a/skills/tldraw-migrate/SKILL.md b/skills/tldraw-migrate/SKILL.md
index b1c7bbf580de..0eb944b704af 100644
--- a/skills/tldraw-migrate/SKILL.md
+++ b/skills/tldraw-migrate/SKILL.md
@@ -2,7 +2,6 @@
 name: tldraw-migrate
 description: Migrate a project to a newer version of the tldraw SDK. Use when upgrading tldraw packages, fixing TypeScript errors after a tldraw upgrade, or when the user mentions tldraw migration.
 argument-hint: '[from-version] [target]'
-disable-model-invocation: true
 user-invocable: true
 ---
 
@@ -10,32 +9,36 @@ user-invocable: true
 
 You are helping migrate a project to a newer version of the tldraw SDK. Follow this process carefully.
 
-Throughout this skill, `${SKILL_DIR}` refers to this skill's own directory (where `SKILL.md`, the helper `.mjs` scripts, and the cached `references/` folder live). The auto-fetch blocks below resolve it from the `SKILL_DIR` env var if set, otherwise probe the common skill locations (`.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `skills/`). When you run shell commands later in the workflow that reference `${SKILL_DIR}`, substitute the same absolute path.
+Throughout this skill, `${SKILL_DIR}` refers to this skill's own directory (where `SKILL.md`, the helper `.mjs` scripts, and the cached `references/` folder live). The auto-fetch blocks below resolve it from the `SKILL_DIR` env var if set, otherwise probe the common skill locations (`.claude/skills/`, `.agents/skills/`, `.codex/skills/`, `.cursor/skills/`, `skills/`). When you run shell commands later in the workflow that reference `${SKILL_DIR}`, substitute the same absolute path. If you placed this skill somewhere else, set `SKILL_DIR` before running the auto-fetch blocks.
 
 **Arguments**: `/tldraw-migrate [from-version] [target]`. Both optional. `from-version` defaults to the previous tldraw version detected from git history. `target` defaults to `latest` (the latest stable release on npm); pass a dist-tag (`canary`, `next`, `beta`) or a pre-release semver (e.g. `4.6.0-canary.abc123`) to migrate to a pre-release.
 
-Resolved migration: !`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && FROM=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS) && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && echo "from $FROM → target $TARGET"`
+Resolved migration: !`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && FROM=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS || true) && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && if [ -z "$FROM" ]; then echo "ERROR: could not detect previous tldraw version. Pass it explicitly: /tldraw-migrate <from-version> [target]" >&2; else echo "from $FROM → target $TARGET"; fi`
 
 ## Resources (auto-fetched on invocation)
 
-!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && CHANGELOG="$SKILL_DIR/references/tldraw-releases.txt" && PREV=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS) && [ -n "$PREV" ] && curl --fail -sS https://tldraw.dev/llms-releases.txt | node "$SKILL_DIR/filter-changelog.mjs" "$PREV" > "$CHANGELOG" && echo "Saved changelog (from $PREV) to $CHANGELOG ($(wc -l < "$CHANGELOG") lines)"`
+The three blocks below are written for Claude Code's `!`-prefix auto-execute syntax. **If you are an agent that doesn't auto-run these (Cursor, Codex, plain Claude, etc.), execute each one as a shell command before continuing** — they download the changelog, full docs, and (for pre-release targets) next-release notes that the rest of the workflow depends on.
 
-!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && DOCS="$SKILL_DIR/references/tldraw-full-docs.txt" && if [ -s "$DOCS" ]; then echo "Using cached full docs at $DOCS ($(wc -l < "$DOCS") lines) — delete the file to refresh"; else curl --fail -sS https://tldraw.dev/llms-full.txt -o "$DOCS" && echo "Saved full docs to $DOCS ($(wc -l < "$DOCS") lines)"; fi`
+!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && CHANGELOG="$SKILL_DIR/references/tldraw-releases.txt" && PREV=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS || true) && if [ -z "$PREV" ]; then echo "ERROR: could not detect previous tldraw version — skipping changelog fetch. Pass it explicitly: /tldraw-migrate <from-version> [target]" >&2; else node "$SKILL_DIR/fetch-release-notes.mjs" "$PREV" > "$CHANGELOG" && echo "Saved changelog (from $PREV, sourced from github.com/tldraw/tldraw) to $CHANGELOG ($(wc -l < "$CHANGELOG") lines)"; fi`
 
-!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && case "$TARGET" in canary|next|beta|alpha|rc|*-canary*|*-next*|*-beta*|*-alpha*|*-rc*) NEXT="$SKILL_DIR/references/tldraw-next.mdx" && curl --fail -sS https://raw.githubusercontent.com/tldraw/tldraw/main/apps/docs/content/releases/next.mdx -o "$NEXT" && echo "Pre-release target ($TARGET) — saved next-release notes to $NEXT ($(wc -l < "$NEXT") lines)" ;; *) echo "Stable target ($TARGET) — skipping next-release notes" ;; esac`
+!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && DOCS="$SKILL_DIR/references/tldraw-full-docs.txt" && STALE=$(find "$DOCS" -mtime +30 2>/dev/null) && if [ -s "$DOCS" ] && [ -z "$STALE" ]; then echo "Using cached full docs at $DOCS ($(wc -l < "$DOCS") lines) — delete the file or wait 30 days to refresh"; else curl --fail -sS https://tldraw.dev/llms-full.txt -o "$DOCS" && echo "Saved full docs to $DOCS ($(wc -l < "$DOCS") lines)"; fi`
 
-- **[Filtered changelog](references/tldraw-releases.txt)** — release notes for stable versions between the previous version and now. Each breaking change (marked `💥`) carries a `<details><summary>Migration guide</summary>` block with a before/after recipe. **These migration blocks are the primary source for version-specific fixes** — this skill intentionally does not duplicate them. When you hit a TS error, grep for the relevant API name in this file and read its migration block.
+!`SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && case "$TARGET" in canary|next|beta|alpha|rc|*-canary*|*-next*|*-beta*|*-alpha*|*-rc*) NEXT="$SKILL_DIR/references/tldraw-next.mdx" && curl --fail -sS https://raw.githubusercontent.com/tldraw/tldraw/main/apps/docs/content/releases/next.mdx -o "$NEXT" && echo "Pre-release target ($TARGET) — saved next-release notes to $NEXT ($(wc -l < "$NEXT") lines)" ;; *) echo "Stable target ($TARGET) — skipping next-release notes" ;; esac`
+
+- **[Filtered changelog](references/tldraw-releases.txt)** — release notes for stable versions between the previous version and now, pulled directly from `apps/docs/content/releases/` on `tldraw/tldraw` main (GitHub is the source of truth, not tldraw.dev). Each breaking change (marked `💥`) carries a `<details><summary>Migration guide</summary>` block with a before/after recipe. **These migration blocks are the primary source for version-specific fixes** — this skill intentionally does not duplicate them. When you hit a TS error, grep for the relevant API name in this file and read its migration block.
 - **[Full docs](references/tldraw-full-docs.txt)** — complete tldraw SDK docs (~1.5MB). Do NOT read this upfront. Use Grep or Read with line ranges to search for specific topics as needed (e.g., custom shapes, TLTextOptions).
 - **[Next-release notes](references/tldraw-next.mdx)** — *only present when the target is a pre-release.* The in-progress release notes (raw MDX from `main`) for the upcoming version. Same `<details><summary>Migration guide</summary>` structure. The stable changelog won't cover canary/next deltas; this file is where you'll find them.
 
 **Searching for migration recipes:**
 
+Always grep *both* the stable changelog and `next.mdx` (the latter only exists for pre-release targets — `2>/dev/null` swallows the missing-file warning). Migration blocks routinely run 40–80 lines, so use `-A60` as the default after-context.
+
 ```sh
 # List every breaking change with a migration block
-grep -nE '💥|<summary>Migration guide' ${SKILL_DIR}/references/tldraw-next.mdx
+grep -nE '💥|<summary>Migration guide' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx 2>/dev/null
 
 # Find the migration recipe for a specific symbol
-grep -n -B2 -A20 'getIndicatorPath\|TLUserStore\|EmbedShapeUtil' ${SKILL_DIR}/references/tldraw-next.mdx
+grep -n -B2 -A60 'getIndicatorPath\|TLUserStore\|EmbedShapeUtil' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx 2>/dev/null
 ```
 
 ## Step 1: Understand the environment
@@ -58,6 +61,8 @@ Using the detected package manager, upgrade all tldraw packages that are already
 - For a stable target (`latest` or a stable semver): install at that tag/version, e.g. `yarn add tldraw@latest` or `npm install tldraw@4.5.10`.
 - For a pre-release target (`canary`, `next`, `beta`, or a pre-release semver): install at that tag/version, e.g. `yarn add tldraw@canary`. If multiple `@tldraw/*` packages are listed, pin them all to the same target to avoid version skew.
 
+**Commit the version bump on its own.** Stage and commit only `package.json` and the lockfile before fixing types. Source-code changes from later steps stay in their own commit, so the eventual `git diff` is reviewable as "what the migration touched" rather than mixed with the dependency change.
+
 ## Step 3: Identify all TypeScript errors
 
 Run the project's typecheck command (from Step 1) and categorize the errors:
@@ -82,7 +87,7 @@ Fix in this order (each fix eliminates many downstream errors). After each sub-s
 
 If you see TS2786 "bigint not assignable to ReactNode" errors, upgrade `@types/react` AND `@types/react-dom` together to match tldraw's bundled version. Bumping only `@types/react` will leave a transitive dependency on the old `@types/react-dom` and the same errors will reappear from a different path (e.g. inside `TldrawUiToolbarButton`).
 
-**Verify**: re-run typecheck — TS2786 errors should be gone.
+**Verify**: re-run typecheck — TS2786 errors caused by `bigint not assignable to ReactNode` should be gone. (TS2786 can also fire from genuine JSX usage problems unrelated to types skew; those remain for later sub-steps.)
 
 ### 4b. Register custom shapes and bindings
 
@@ -105,7 +110,7 @@ This is where the version-specific work happens, and it's driven entirely by the
 For each TS2305 / TS2724 / TS2339 / TS2515 error:
 
 1. Pull the symbol name out of the error.
-2. Grep the migration blocks for it: `grep -n -B2 -A20 'SymbolName' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx`.
+2. Grep the migration blocks for it: `grep -n -B2 -A60 'SymbolName' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx 2>/dev/null` (the `2>/dev/null` swallows the missing-file warning when `next.mdx` isn't present for stable targets).
 3. Apply the recipe shown in the matching `Migration guide` block. Migration blocks contain before/after code snippets; copy the structure.
 
 If the symbol isn't in any migration block:
@@ -201,11 +206,24 @@ After all errors are resolved, do a quick audit:
 3. **Audit module augmentations.** Module augmentation is correct for `TLGlobalShapePropsMap` / `TLGlobalBindingPropsMap` registration and for adding genuinely-missing public types. It is **not** correct for re-exposing symbols that the SDK demoted to `@internal` — that's a workaround, not a fix. Find the public replacement instead (the migration block usually names it).
 4. **Verify no stubs or dead code**: If you stubbed out removed APIs (e.g., replaced a removed function with a no-op), make sure the calling code doesn't depend on the return value. If it does, find the proper replacement in the migration blocks or docs.
 
+## Step 7: Report
+
+End the migration with a single summary message to the user. Don't pad it — just the facts:
+
+- **From → target version**, and the resolved target version if it was a tag (`canary` → `4.7.0-canary.abc123`).
+- **Files modified** (count, plus the list if it's small).
+- **TypeScript errors fixed**, broken down by code (e.g., `TS2786 ×12, TS2344 ×3, TS2305 ×1`). Use the before/after counts you collected during Step 4.
+- **Typed `as` casts added** (count and one-line rationale per cast — should be zero or close to it; flag any you weren't sure about).
+- **Module augmentations added** (what they cover — `TLGlobalShapePropsMap`, `TLGlobalBindingPropsMap`, `@tiptap/core` chain commands, etc.).
+- **Deprecations migrated** (count and the symbols).
+- **Anything flagged as undocumented** — symbols you couldn't find in any migration block, gaps in the changelog, or recipes that didn't match the actual API surface. These are worth filing back to the tldraw team.
+- **Anything skipped or deferred** — if you punted on a hard rename or left a `TODO`, say so explicitly so the user knows what's still on them.
+
 ## Quality checks
 
 - **Type safety is paramount.** The goal is a migration that is as type-safe as the original code. Do NOT add `as any`, `as unknown`, or broad type casts. Do NOT add `@ts-ignore` or `@ts-expect-error`. These are never acceptable — if you can't make the types work, you don't understand the new API yet. Stop and read the changelog and type definitions before continuing.
 - **Prefer TypeScript's narrowing features over casts.** Use `as const` for literal types, `satisfies` for type-checking without widening, generic parameters for call sites, and module augmentation for extending interfaces. These are the right tools for a migration — `as` casts are not.
-- Use parallel agents for fixing large batches of files with the same pattern.
+- **Use parallel agents for large batches with the same pattern.** Apply the recipe to one file by hand first to confirm it works, then spawn one Agent per remaining file in a single message (multiple Agent tool calls in parallel). Pass each agent: (1) the path of the file to migrate, (2) the before/after diff from your template file, (3) the relevant migration block from `tldraw-releases.txt`. This is most useful in 4b (mechanical `TLBaseShape` → `TLGlobalShapePropsMap` migration across many shape files) and 4c (one symbol rename rippling across the project).
 - **Don't just make errors go away — understand the new API.** When a method signature changes (e.g., new parameters added, property renamed to a richer type), read the changelog AND the current type definitions to understand _why_ it changed. A fix that compiles but passes hardcoded/dummy values where the new API expects real data is worse than a type error — it silently degrades behavior. For example, if a function gains new required parameters, check what shape props or editor state should feed those parameters rather than passing `0` or `1`.
 - **When unsure about an API pattern**, grep the full docs (`${SKILL_DIR}/references/tldraw-full-docs.txt`) for usage examples of that specific API. The docs contain code samples that show the canonical way to use each API.
 
diff --git a/skills/tldraw-migrate/detect-versions.mjs b/skills/tldraw-migrate/detect-versions.mjs
index a5b60c27a775..beb298360ee3 100644
--- a/skills/tldraw-migrate/detect-versions.mjs
+++ b/skills/tldraw-migrate/detect-versions.mjs
@@ -48,7 +48,10 @@ function extractTldrawVersion(packageJsonStr) {
 			const raw = deps[name]
 			if (!raw) continue
 			const cleaned = String(raw).replace(/[\^~>=<\s]/g, '')
-			const match = cleaned.match(/(\d+\.\d+\.\d+)/)
+			// Preserve pre-release suffixes (e.g., 4.7.0-canary.abc) so the
+			// release-notes filter can compare them correctly against stable
+			// versions.
+			const match = cleaned.match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)
 			if (match) return match[1]
 		}
 		return null
@@ -73,7 +76,7 @@ function emit(version) {
 const explicit = process.argv[2]?.trim()
 if (explicit) {
 	const cleaned = explicit.replace(/^v/, '')
-	const match = cleaned.match(/^(\d+\.\d+\.\d+)/)
+	const match = cleaned.match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)
 	if (match) emit(match[1])
 }
 
diff --git a/skills/tldraw-migrate/fetch-release-notes.mjs b/skills/tldraw-migrate/fetch-release-notes.mjs
new file mode 100644
index 000000000000..8d9246a8d668
--- /dev/null
+++ b/skills/tldraw-migrate/fetch-release-notes.mjs
@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Fetches tldraw stable release notes directly from GitHub
+ * (apps/docs/content/releases/vX.Y.Z.mdx on `tldraw/tldraw` main) and
+ * concatenates them into a single text file filtered by version range.
+ * GitHub is the source of truth, so the output reflects whatever is on
+ * main — not whatever tldraw.dev has deployed.
+ *
+ * `next.mdx` is intentionally NOT included here. The skill fetches it
+ * separately, conditionally on a pre-release target, into its own file
+ * (`references/tldraw-next.mdx`).
+ *
+ * Usage:
+ *   node fetch-release-notes.mjs <from-version> [to-version] > output.txt
+ *
+ * Honors a `GITHUB_TOKEN` env var to avoid the unauthenticated API rate limit.
+ */
+
+const REPO = process.env.TLDRAW_RELEASES_REPO || 'tldraw/tldraw'
+const RELEASES_PATH = 'apps/docs/content/releases'
+const BRANCH = process.env.TLDRAW_RELEASES_BRANCH || 'main'
+
+const [, , fromArg, toArg] = process.argv
+
+if (!fromArg) {
+	process.stderr.write(
+		'Usage: node fetch-release-notes.mjs <from-version> [to-version]\n' +
+			'  e.g.: node fetch-release-notes.mjs 4.0.0 > releases.txt\n'
+	)
+	process.exit(1)
+}
+
+function parseVersion(str) {
+	const m = String(str)
+		.trim()
+		.replace(/^v/, '')
+		.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/)
+	if (!m) return null
+	return { main: [+m[1], +m[2], +m[3]], pre: m[4] || null }
+}
+
+function comparePrerelease(a, b) {
+	if (!a && !b) return 0
+	if (!a) return 1
+	if (!b) return -1
+	const aParts = a.split('.')
+	const bParts = b.split('.')
+	for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+		const ap = aParts[i]
+		const bp = bParts[i]
+		if (ap === undefined) return -1
+		if (bp === undefined) return 1
+		const aNum = /^\d+$/.test(ap)
+		const bNum = /^\d+$/.test(bp)
+		if (aNum && bNum) {
+			const d = +ap - +bp
+			if (d !== 0) return d
+		} else if (aNum !== bNum) {
+			return aNum ? -1 : 1
+		} else if (ap !== bp) {
+			return ap < bp ? -1 : 1
+		}
+	}
+	return 0
+}
+
+function compareVersions(a, b) {
+	for (let i = 0; i < 3; i++) {
+		if (a.main[i] !== b.main[i]) return a.main[i] - b.main[i]
+	}
+	return comparePrerelease(a.pre, b.pre)
+}
+
+const fromVer = parseVersion(fromArg)
+if (!fromVer) {
+	process.stderr.write(`Invalid from-version: ${fromArg}\n`)
+	process.exit(1)
+}
+
+const toVer = toArg ? parseVersion(toArg) : null
+if (toArg && !toVer) {
+	process.stderr.write(`Invalid to-version: ${toArg}\n`)
+	process.exit(1)
+}
+
+const headers = {
+	'User-Agent': 'tldraw-migrate-skill',
+	Accept: 'application/vnd.github.v3+json',
+}
+if (process.env.GITHUB_TOKEN) {
+	headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`
+}
+
+const apiUrl = `https://api.github.com/repos/${REPO}/contents/${RELEASES_PATH}?ref=${BRANCH}`
+const listing = await fetch(apiUrl, { headers })
+	.then(async (r) => {
+		if (!r.ok) {
+			const body = await r.text().catch(() => '')
+			throw new Error(`HTTP ${r.status} ${r.statusText}: ${body.slice(0, 200)}`)
+		}
+		return r.json()
+	})
+	.catch((err) => {
+		process.stderr.write(`Failed to list ${REPO}/${RELEASES_PATH}: ${err.message}\n`)
+		process.exit(1)
+	})
+
+if (!Array.isArray(listing)) {
+	process.stderr.write(`Unexpected GitHub API response: ${JSON.stringify(listing).slice(0, 200)}\n`)
+	process.exit(1)
+}
+
+const files = listing
+	.filter((f) => f.type === 'file' && f.name.endsWith('.mdx') && f.name !== 'next.mdx')
+	.map((f) => ({
+		name: f.name,
+		url: f.download_url,
+		version: parseVersion(f.name.replace(/\.mdx$/, '')),
+	}))
+	.filter((f) => f.version !== null)
+
+const relevant = files
+	.filter((f) => {
+		const afterFrom = compareVersions(f.version, fromVer) > 0
+		const beforeTo = toVer ? compareVersions(f.version, toVer) <= 0 : true
+		return afterFrom && beforeTo
+	})
+	.sort((a, b) => compareVersions(a.version, b.version))
+
+if (relevant.length === 0) {
+	process.stderr.write(`No release notes found between ${fromArg} and ${toArg || 'latest'}\n`)
+	process.exit(0)
+}
+
+const sections = ['# tldraw SDK releases', '', '--------', '']
+const failed = []
+
+for (const file of relevant) {
+	const text = await fetch(file.url, { headers: { 'User-Agent': 'tldraw-migrate-skill' } })
+		.then(async (r) => {
+			if (!r.ok) throw new Error(`HTTP ${r.status} ${r.statusText}`)
+			return r.text()
+		})
+		.catch((err) => {
+			process.stderr.write(`Warning: failed to fetch ${file.name}: ${err.message}\n`)
+			failed.push(file.name)
+			return null
+		})
+	if (text === null) continue
+
+	const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n+/, '').trim()
+	sections.push(`# ${file.name.replace(/\.mdx$/, '')}`, '', body, '', '--------', '')
+}
+
+process.stdout.write(sections.join('\n'))
+
+if (failed.length > 0) {
+	process.stderr.write(
+		`\nERROR: ${failed.length} of ${relevant.length} release files failed to fetch (${failed.join(', ')}). ` +
+			`Output is incomplete — re-run, or set GITHUB_TOKEN to avoid the unauthenticated rate limit.\n`
+	)
+	process.exit(2)
+}
diff --git a/skills/tldraw-migrate/filter-changelog.mjs b/skills/tldraw-migrate/filter-changelog.mjs
deleted file mode 100644
index fb2e2cdb832f..000000000000
--- a/skills/tldraw-migrate/filter-changelog.mjs
+++ /dev/null
@@ -1,79 +0,0 @@
-#!/usr/bin/env node
-/**
- * Filters tldraw changelog to only versions between `from` and `to` (inclusive of `to`).
- * Usage: node filter-changelog.mjs <from-version> [to-version]
- *
- * If to-version is omitted, includes everything newer than from-version.
- * Versions should be semver like "4.0.0" or "v4.0.0" (the "v" prefix is optional).
- *
- * Reads changelog from stdin, writes filtered output to stdout.
- */
-
-const [, , fromArg, toArg] = process.argv
-
-if (!fromArg) {
-	console.error('Usage: node filter-changelog.mjs <from-version> [to-version]')
-	console.error(
-		'  e.g.: curl -s https://tldraw.dev/llms-releases.txt | node filter-changelog.mjs 4.0.0 4.6.0'
-	)
-	process.exit(1)
-}
-
-function parseVersion(str) {
-	const m = str.replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)/)
-	if (!m) return null
-	return [+m[1], +m[2], +m[3]]
-}
-
-function compareVersions(a, b) {
-	for (let i = 0; i < 3; i++) {
-		if (a[i] !== b[i]) return a[i] - b[i]
-	}
-	return 0
-}
-
-const fromVer = parseVersion(fromArg)
-const toVer = toArg ? parseVersion(toArg) : null
-
-if (!fromVer) {
-	console.error(`Invalid from-version: ${fromArg}`)
-	process.exit(1)
-}
-if (toArg && !toVer) {
-	console.error(`Invalid to-version: ${toArg}`)
-	process.exit(1)
-}
-
-let input = ''
-process.stdin.setEncoding('utf8')
-process.stdin.on('data', (chunk) => (input += chunk))
-process.stdin.on('end', () => {
-	// Split into sections by top-level headings (# vX.Y.Z)
-	const sections = []
-	let current = null
-
-	for (const line of input.split('\n')) {
-		const headingMatch = line.match(/^# (v?\d+\.\d+\.\d+)/)
-		if (headingMatch) {
-			if (current) sections.push(current)
-			current = { version: parseVersion(headingMatch[1]), lines: [line] }
-		} else if (current) {
-			current.lines.push(line)
-		}
-	}
-	if (current) sections.push(current)
-
-	// Filter: include versions where from < version <= to
-	const filtered = sections.filter((s) => {
-		const afterFrom = compareVersions(s.version, fromVer) > 0
-		const beforeTo = toVer ? compareVersions(s.version, toVer) <= 0 : true
-		return afterFrom && beforeTo
-	})
-
-	if (filtered.length === 0) {
-		console.error(`No versions found between ${fromArg} and ${toArg || 'latest'}`)
-		process.exit(0)
-	}
-
-	process.stdout.write(filtered.map((s) => s.lines.join('\n')).join('\n\n'))
-})