docs: fixes pre 5.0 (tldraw#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>

Author: angrycaptain19

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,
 		})

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.

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
 

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
 	}
 }
 ```

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

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:

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.

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.

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.
 

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>
 	)
 }