tldraw 5.2.0-next.e2b8d10bf10e → 5.2.0

package/src/lib/ui/context/actions.tsx

@@ -3,6 +3,7 @@ import {
 	DefaultColorStyle,
 	DefaultFillStyle,
 	Editor,
+	GeoShapeGeoStyle,
 	HALF_PI,
 	PageRecordType,
 	Result,
@@ -583,10 +584,68 @@ export function ActionsProvider({ overrides, children }: ActionsProviderProps) {
 					}
 				},
 			},
+			{
+				id: 'frame-selection',
+				label: 'action.frame-selection',
+				kbd: 'cmd+alt+g',
+				onSelect(source) {
+					if (!canApplySelectionAction()) return
+					if (mustGoBackToSelectToolFirst()) return
+
+					const selectedShapes = editor.getSelectedShapes()
+
+					// If all selected shapes are frames, remove them (toggle behavior)
+					if (
+						selectedShapes.length > 0 &&
+						selectedShapes.every((shape) => editor.isShapeOfType(shape, 'frame'))
+					) {
+						trackEvent('remove-frame', { source })
+						editor.markHistoryStoppingPoint('remove-frame')
+						removeFrame(
+							editor,
+							selectedShapes.map((shape) => shape.id)
+						)
+						return
+					}
+
+					const ids = editor.getSelectedShapeIds()
+					if (ids.length < 2) return
+
+					const shapes = compact(ids.map((id) => editor.getShape(id)))
+					const pageBounds = editor.getSelectionPageBounds()
+					if (!pageBounds) return
+
+					trackEvent('frame-selection', { source })
+					editor.markHistoryStoppingPoint('frame-selection')
+
+					const parentId = editor.findCommonAncestor(shapes) ?? editor.getCurrentPageId()
+
+					const frameId = createShapeId()
+					const padding = 25 / editor.getZoomLevel()
+
+					editor.run(() => {
+						editor.createShapes([
+							{
+								id: frameId,
+								type: 'frame',
+								parentId,
+								x: pageBounds.x,
+								y: pageBounds.y,
+								props: {
+									w: pageBounds.w,
+									h: pageBounds.h,
+								},
+							},
+						])
+						editor.reparentShapes(ids, frameId)
+						fitFrameToContent(editor, frameId, { padding })
+						editor.select(frameId)
+					})
+				},
+			},
 			{
 				id: 'remove-frame',
 				label: 'action.remove-frame',
-				kbd: 'cmd+shift+f,ctrl+shift+f',
 				onSelect(source) {
 					if (!canApplySelectionAction()) return
 
@@ -1848,6 +1907,34 @@ export function ActionsProvider({ overrides, children }: ActionsProviderProps) {
 					trackEvent('download-original', { source })
 				},
 			},
+			{
+				id: 'copy-hovered-styles',
+				label: 'action.copy-hovered-styles',
+				kbd: 'shift+q',
+				async onSelect(source) {
+					const shape = editor.getShapeAtPoint(editor.inputs.getCurrentPagePoint(), {
+						hitInside: false,
+						hitLabels: false,
+						hitLocked: editor.options.selectLockedShapes,
+						margin: editor.options.hitTestMargin / editor.getZoomLevel(),
+					})
+
+					const path = editor.getPath()
+					if (!shape || !path.endsWith('.idle')) return
+
+					// Setting styles for the next shape is instance state, not document state, so it
+					// isn't undoable and doesn't need a history stopping point.
+					editor.run(() => {
+						for (const style of editor.styleProps[shape.type].keys()) {
+							const value = editor.getShapeStyleIfExists(shape, style)
+							if (value === undefined || style === GeoShapeGeoStyle) continue
+							editor.setStyleForNextShapes(style, value)
+						}
+					})
+
+					trackEvent('copy-hovered-styles', { source })
+				},
+			},
 		]
 
 		if (showCollaborationUi) {

package/src/lib/ui/context/asset-urls.tsx

@@ -21,16 +21,17 @@ export interface AssetUrlsProviderProps {
  */
 export function AssetUrlsProvider({ assetUrls, children }: AssetUrlsProviderProps) {
 	useEffect(() => {
-		for (const src of Object.values(assetUrls.icons)) {
+		// Many icon URLs point at the same sprite sheet and differ only by their
+		// `#fragment` identifier (e.g. `0_merged.svg#tool-arrow`). The fragment
+		// doesn't change the underlying resource, so preload each unique resource
+		// once rather than creating hundreds of redundant Image decodes.
+		const preloaded = new Set<string>()
+		for (const src of [...Object.values(assetUrls.icons), ...Object.values(assetUrls.embedIcons)]) {
 			if (!src) continue
 
-			const image = Image()
-			image.crossOrigin = 'anonymous'
-			image.src = src
-			image.decode().catch(noop)
-		}
-		for (const src of Object.values(assetUrls.embedIcons)) {
-			if (!src) continue
+			const resource = src.split('#')[0]
+			if (preloaded.has(resource)) continue
+			preloaded.add(resource)
 
 			const image = Image()
 			image.crossOrigin = 'anonymous'

package/src/lib/ui/context/events.tsx

@@ -44,6 +44,7 @@ export interface TLUiEventMap {
 	'rename-document': null
 	'group-shapes': null
 	'ungroup-shapes': null
+	'frame-selection': null
 	'remove-frame': null
 	'fit-frame-to-content': null
 	'convert-to-embed': null
@@ -145,6 +146,7 @@ export interface TLUiEventMap {
 			| 'bulletList'
 	}
 	edit: null
+	'copy-hovered-styles': null
 }
 
 /** @public */

package/src/lib/ui/hooks/useKeyboardShortcuts.ts

@@ -141,12 +141,35 @@ export function useKeyboardShortcuts() {
 
 		const body = editor.getContainerDocument().body
 
+		// Track which registration each physically-held key first triggered, keyed by
+		// `event.code`. While a key is held down, releasing a modifier should not let the
+		// auto-repeat keydown events trigger an adjacent shortcut (e.g. releasing shift while
+		// still holding shift+q shouldn't start firing the plain `q` shortcut). The same
+		// registration is still allowed to repeat (e.g. holding `=` to keep zooming).
+		const heldKeyRegistrations = new Map<string, Registration>()
+
 		const handleKeyDown = (e: KeyboardEvent) => {
 			if (shouldSkipEvent(e)) return
+			const code = e.code
 			for (const reg of registry) {
 				if (!reg.onKeyDown) continue
 				for (const p of reg.parsed) {
 					if (matchesEvent(e, p)) {
+						if (code) {
+							// We only guard auto-repeat events. A fresh keypress (`e.repeat` is
+							// false) is always free to trigger whatever it matches, even on the same
+							// physical key — e.g. cmd+z (undo) then cmd+shift+z (redo), where macOS
+							// swallows the `z` keyup while cmd stays held, so we can't rely on keyup
+							// to clear the previous registration.
+							if (e.repeat) {
+								const prev = heldKeyRegistrations.get(code)
+								// The held key already triggered a different shortcut; don't fall back
+								// to this one (or anything else) just because a modifier was released.
+								if (prev && prev !== reg) return
+							} else {
+								heldKeyRegistrations.set(code, reg)
+							}
+						}
 						reg.onKeyDown(e)
 						break
 					}
@@ -155,6 +178,10 @@ export function useKeyboardShortcuts() {
 		}
 
 		const handleKeyUp = (e: KeyboardEvent) => {
+			// Always release the held-key tracking, even for events we'd otherwise skip (e.g. the
+			// key was released after focus moved into a text input), so a stale entry can't block
+			// later shortcuts.
+			if (e.code) heldKeyRegistrations.delete(e.code)
 			if (shouldSkipEvent(e)) return
 			for (const reg of registry) {
 				if (!reg.onKeyUp) continue
@@ -195,7 +222,10 @@ export function areShortcutsDisabled(editor: Editor) {
 // non-Latin layouts (Cyrillic, Greek, etc.) and macOS Option-letter dead-key combinations,
 // where `event.key` is a non-ASCII glyph.
 
-interface ParsedKbd {
+/**
+ * @internal
+ */
+export interface ParsedKbd {
 	key: string
 	shift: boolean
 	alt: boolean
@@ -319,7 +349,10 @@ const PHYSICAL_KEY_MAP: Record<string, string> = {
 	Backquote: '`',
 }
 
-function parseKbd(kbd: string): ParsedKbd[] {
+/**
+ * @internal
+ */
+export function parseKbd(kbd: string): ParsedKbd[] {
 	const out: ParsedKbd[] = []
 	for (const shortcut of getKeys(kbd)) {
 		const parsed = parseShortcut(shortcut)
@@ -411,11 +444,16 @@ function shouldSkipEvent(e: KeyboardEvent): boolean {
 	return false
 }
 
-// The "raw" kbd here will look something like "a" or a combination of keys "del,backspace".
-// We need to first split them up by comma, then parse each key to ensure backwards compatibility
-// with the old kbd format. We used to have symbols to denote cmd/alt/shift,
-// using ! for shift, $ for cmd, and ? for alt.
-function getHotkeysStringFromKbd(kbd: string) {
+/**
+ * The "raw" kbd here will look something like "a" or a combination of keys
+ * "del,backspace". We need to first split them up by comma, then parse each
+ * key to ensure backwards compatibility with the old kbd format. We used to
+ * have symbols to denote cmd/alt/shift, using ! for shift, $ for cmd, and ?
+ * for alt.
+ *
+ * @internal
+ */
+export function getHotkeysStringFromKbd(kbd: string) {
 	return getKeys(kbd)
 		.map((kbd) => {
 			let str = ''

package/src/lib/ui/hooks/useTools.tsx

@@ -367,6 +367,12 @@ export interface OnDragFromToolbarToCreateShapesOpts {
 	 * Called once the drag interaction has finished.
 	 */
 	onDragEnd?(id: TLShapeId): void
+	/**
+	 * The id of the toolbar tool to keep highlighted while dragging. Defaults to the created shape's
+	 * type. Set this when the dragged shape's type differs from the tool it's dragged from — for
+	 * example, dragging a `draw` shape out from the select tool.
+	 */
+	maskedToolId?: string
 }
 
 /**
@@ -405,5 +411,5 @@ export function onDragFromToolbarToCreateShape(
 		},
 	})
 
-	editor.getCurrentTool().setCurrentToolIdMask(shape.type)
+	editor.getCurrentTool().setCurrentToolIdMask(opts.maskedToolId ?? shape.type)
 }

package/src/lib/ui/hooks/useTranslation/TLUiTranslationKey.ts

@@ -29,6 +29,7 @@ export type TLUiTranslationKey =
 	| 'action.copy-as-svg.short'
 	| 'action.copy-as-svg'
 	| 'action.copy'
+	| 'action.copy-hovered-styles'
 	| 'action.cut'
 	| 'action.delete'
 	| 'action.unlock-all'
@@ -55,6 +56,7 @@ export type TLUiTranslationKey =
 	| 'action.flip-vertical.short'
 	| 'action.fork-project'
 	| 'action.fork-project-on-tldraw'
+	| 'action.frame-selection'
 	| 'action.group'
 	| 'action.insert-embed'
 	| 'action.insert-media'

package/src/lib/ui/hooks/useTranslation/defaultTranslation.ts

@@ -29,6 +29,7 @@ export const DEFAULT_TRANSLATION = {
 	'action.copy-as-svg.short': 'SVG',
 	'action.copy-as-svg': 'Copy as SVG',
 	'action.copy': 'Copy',
+	'action.copy-hovered-styles': 'Copy hovered styles',
 	'action.cut': 'Cut',
 	'action.delete': 'Delete',
 	'action.unlock-all': 'Unlock all',
@@ -55,6 +56,7 @@ export const DEFAULT_TRANSLATION = {
 	'action.flip-vertical.short': 'Flip V',
 	'action.fork-project': 'Fork this project',
 	'action.fork-project-on-tldraw': 'Fork project on tldraw',
+	'action.frame-selection': 'Frame selection',
 	'action.group': 'Group',
 	'action.insert-embed': 'Insert embed…',
 	'action.insert-media': 'Upload media…',

package/src/lib/ui/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '5.2.0-next.e2b8d10bf10e'
+export const version = '5.2.0'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-06-05T16:06:49.927Z',
-	patch: '2026-06-05T16:06:49.927Z',
+	minor: '2026-07-01T09:20:01.735Z',
+	patch: '2026-07-01T09:20:01.735Z',
 }

package/src/lib/ui.css

@@ -12,9 +12,8 @@
 	 * (which creates its own stacking context at z-index 300), so their
 	 * z-indices are relative to the layout, not the container.
 	 *
-	 * cursor and following-indicator are rendered inside canvas-in-front
-	 * (stacking context at z-index 250), so their z-indices are relative
-	 * to that context.
+	 * cursor is rendered inside canvas-in-front (stacking context at
+	 * z-index 250), so their z-indices are relative to that context.
 	 */
 	--tl-layer-above: 1;
 	--tl-layer-focused-input: 10;
@@ -24,7 +23,6 @@
 	--tl-layer-toasts: 650;
 	--tl-layer-cursor: 700;
 	--tl-layer-header-footer: 999;
-	--tl-layer-following-indicator: 1000;
 }
 
 /* Button */
@@ -54,14 +52,14 @@
 
 .tlui-button:disabled,
 .tlui-button[data-disabled] {
-	color: var(--tl-color-text-3);
+	color: var(--tl-color-text-disabled);
 	text-shadow: none;
 	cursor: default;
 }
 
 .tlui-button:disabled .tlui-kbd,
 .tlui-button[data-disabled] .tlui-kbd {
-	color: var(--tl-color-text-3);
+	color: var(--tl-color-text-disabled);
 }
 
 .tlui-button > * {
@@ -430,6 +428,11 @@
 	height: 15px;
 }
 
+.tlui-icon__tiny {
+	width: 12px;
+	height: 12px;
+}
+
 /* --------------------- Slider --------------------- */
 
 .tlui-slider__container {
@@ -1043,7 +1046,7 @@
 	left: 8px;
 }
 
-/* 
+/*
  * focusing skip-to-main-content hide top ui buttons to make sure we avoid
  * z-index clashes on hover (see issue #8328)
  */
@@ -1690,8 +1693,17 @@ tldraw? probably.
 	height: 100%;
 	z-index: var(--tl-layer-canvas-overlays);
 	background-color: var(--tl-color-overlay);
-	pointer-events: all;
 	animation: tl-fade-in 0.12s ease-out;
+}
+
+.tlui-dialog__positioner {
+	position: absolute;
+	top: 0px;
+	left: 0px;
+	width: 100%;
+	height: 100%;
+	z-index: var(--tl-layer-canvas-overlays);
+	pointer-events: all;
 	display: grid;
 	place-items: center;
 	overflow-y: auto;
@@ -2181,7 +2193,6 @@ tldraw? probably.
 	inset: 0px;
 	border-width: 2px;
 	border-style: solid;
-	z-index: var(--tl-layer-following-indicator);
 	pointer-events: none;
 }
 

package/src/lib/utils/embeds/embeds.test.ts

@@ -5,6 +5,9 @@ import {
 } from '../../defaultEmbedDefinitions'
 import { getEmbedInfo, matchEmbedUrl, matchUrl } from './embeds'
 
+const GOOGLE_MAPS_API_KEY = 'test-google-maps-api-key'
+const TEST_EMBED_CONFIG = { google_maps: { apiKey: GOOGLE_MAPS_API_KEY } }
+
 describe('embed sandbox permissions', () => {
 	function getSandboxString(permissions: Record<string, boolean | undefined>): string {
 		return Object.entries(permissions)
@@ -250,7 +253,7 @@ const MATCH_URL_TEST_URLS: (MatchUrlTestNoMatchDef | MatchUrlTestMatchDef)[] = [
 		match: true,
 		output: {
 			type: 'google_maps',
-			embedUrl: `https://google.com/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=52.2449313,0.0813192&zoom=14&maptype=roadmap`,
+			embedUrl: `https://google.com/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=52.2449313,0.0813192&zoom=14&maptype=roadmap`,
 		},
 	},
 	{
@@ -258,7 +261,7 @@ const MATCH_URL_TEST_URLS: (MatchUrlTestNoMatchDef | MatchUrlTestMatchDef)[] = [
 		match: true,
 		output: {
 			type: 'google_maps',
-			embedUrl: `https://google.co.uk/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=52.2449313,0.0813192&zoom=14&maptype=roadmap`,
+			embedUrl: `https://google.co.uk/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=52.2449313,0.0813192&zoom=14&maptype=roadmap`,
 		},
 	},
 	{
@@ -266,7 +269,7 @@ const MATCH_URL_TEST_URLS: (MatchUrlTestNoMatchDef | MatchUrlTestMatchDef)[] = [
 		match: true,
 		output: {
 			type: 'google_maps',
-			embedUrl: `https://google.com/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=51.5041626,-0.2468738&zoom=14&maptype=roadmap`,
+			embedUrl: `https://google.com/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=51.5041626,-0.2468738&zoom=14&maptype=roadmap`,
 		},
 	},
 	{
@@ -282,7 +285,7 @@ const MATCH_URL_TEST_URLS: (MatchUrlTestNoMatchDef | MatchUrlTestMatchDef)[] = [
 		match: true,
 		output: {
 			type: 'google_maps',
-			embedUrl: `https://google.com/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=52.2449313,0.0813192&zoom=17.313261121327326&maptype=satellite`,
+			embedUrl: `https://google.com/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=52.2449313,0.0813192&zoom=17.313261121327326&maptype=satellite`,
 		},
 	},
 	{
@@ -290,7 +293,7 @@ const MATCH_URL_TEST_URLS: (MatchUrlTestNoMatchDef | MatchUrlTestMatchDef)[] = [
 		match: true,
 		output: {
 			type: 'google_maps',
-			embedUrl: `https://google.co.uk/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=51.5074,0.1278&zoom=16.984468114035085&maptype=satellite`,
+			embedUrl: `https://google.co.uk/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=51.5074,0.1278&zoom=16.984468114035085&maptype=satellite`,
 		},
 	},
 	{
@@ -604,7 +607,7 @@ const MATCH_EMBED_TEST_URLS: (MatchEmbedTestMatchDef | MatchEmbedTestNoMatchDef)
 	},
 	// google_maps
 	{
-		embedUrl: `https://google.com/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=52.2449313,0.0813192&zoom=14`,
+		embedUrl: `https://google.com/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=52.2449313,0.0813192&zoom=14`,
 		match: true,
 		output: {
 			type: 'google_maps',
@@ -612,7 +615,7 @@ const MATCH_EMBED_TEST_URLS: (MatchEmbedTestMatchDef | MatchEmbedTestNoMatchDef)
 		},
 	},
 	{
-		embedUrl: `https://google.com/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=52.2449313,0.0813192&zoom=14&maptype=satellite`,
+		embedUrl: `https://google.com/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=52.2449313,0.0813192&zoom=14&maptype=satellite`,
 		match: true,
 		output: {
 			type: 'google_maps',
@@ -620,7 +623,7 @@ const MATCH_EMBED_TEST_URLS: (MatchEmbedTestMatchDef | MatchEmbedTestNoMatchDef)
 		},
 	},
 	{
-		embedUrl: `https://google.co.uk/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=51.5074,0.1278&zoom=12&maptype=roadmap`,
+		embedUrl: `https://google.co.uk/maps/embed/v1/view?key=${GOOGLE_MAPS_API_KEY}&center=51.5074,0.1278&zoom=12&maptype=roadmap`,
 		match: true,
 		output: {
 			type: 'google_maps',
@@ -628,8 +631,7 @@ const MATCH_EMBED_TEST_URLS: (MatchEmbedTestMatchDef | MatchEmbedTestNoMatchDef)
 		},
 	},
 	{
-		embedUrl:
-			'https://google.com/maps/embed?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=52.2449313,0.0813192&zoom=14',
+		embedUrl: 'https://google.com/maps/embed?key=KEY&center=52.2449313,0.0813192&zoom=14',
 		match: false,
 	},
 	// google_calendar
@@ -786,7 +788,7 @@ const MATCH_EMBED_TEST_URLS: (MatchEmbedTestMatchDef | MatchEmbedTestNoMatchDef)
 
 for (const testDef of MATCH_URL_TEST_URLS) {
 	test(`matchUrl("${testDef.url}")`, () => {
-		const result = matchUrl(DEFAULT_EMBED_DEFINITIONS, testDef.url)
+		const result = matchUrl(DEFAULT_EMBED_DEFINITIONS, testDef.url, TEST_EMBED_CONFIG)
 		if (testDef.match) {
 			expect(result).toBeDefined()
 			expect(result?.definition.type).toBe(testDef.output.type)
@@ -797,7 +799,7 @@ for (const testDef of MATCH_URL_TEST_URLS) {
 	})
 
 	test(`getEmbedInfo("${testDef.url}")`, () => {
-		const result = getEmbedInfo(DEFAULT_EMBED_DEFINITIONS, testDef.url)
+		const result = getEmbedInfo(DEFAULT_EMBED_DEFINITIONS, testDef.url, TEST_EMBED_CONFIG)
 		if (testDef.match) {
 			expect(result).toBeDefined()
 			expect(result?.definition.type).toBe(testDef.output.type)

package/src/lib/utils/embeds/embeds.ts

@@ -47,13 +47,17 @@ const checkHostnames = (hostnames: readonly string[], targetHostname: string) =>
 }
 
 /** @public */
-export function matchUrl(definitions: readonly TLEmbedDefinition[], url: string) {
+export function matchUrl(
+	definitions: readonly TLEmbedDefinition[],
+	url: string,
+	embedConfig?: Record<string, unknown>
+) {
 	const parsed = safeParseUrl(url)
 	if (!parsed) return undefined
 	const host = parsed.host.replace('www.', '')
 	for (const localEmbedDef of definitions) {
 		if (checkHostnames(localEmbedDef.hostnames, host)) {
-			const embedUrl = localEmbedDef.toEmbedUrl(url)
+			const embedUrl = localEmbedDef.toEmbedUrl(url, embedConfig?.[localEmbedDef.type])
 
 			if (embedUrl) {
 				return {
@@ -81,14 +85,16 @@ export type TLEmbedResult =
  * return undefined.
  *
  * @param inputUrl - The URL to match
+ * @param embedConfig - Optional per-embed config, keyed by embed type, passed to `toEmbedUrl`
  * @public
  */
 export function getEmbedInfo(
 	definitions: readonly TLEmbedDefinition[],
-	inputUrl: string
+	inputUrl: string,
+	embedConfig?: Record<string, unknown>
 ): TLEmbedResult {
 	try {
-		return matchUrl(definitions, inputUrl) ?? matchEmbedUrl(definitions, inputUrl)
+		return matchUrl(definitions, inputUrl, embedConfig) ?? matchEmbedUrl(definitions, inputUrl)
 	} catch {
 		return undefined
 	}

package/src/lib/utils/test-helpers.ts

@@ -24,14 +24,14 @@ export function pointsToBase64(points: VecModel[]): string {
  *
  * @example
  * ```ts
- * const points = base64ToPoints(shape.props.segments[0].path)
+ * const points = base64ToPoints(shape.props.segments[0].path, shape.props.segments[0].dim)
  * expect(points[0].x).toBe(0)
  * ```
  *
  * @public
  */
-export function base64ToPoints(base64: string): VecModel[] {
-	return b64Vecs.decodePoints(base64)
+export function base64ToPoints(base64: string, dim?: 2 | 3): VecModel[] {
+	return b64Vecs.decodePoints(base64, dim)
 }
 
 /**

package/src/lib/utils/text/richText.test.ts

@@ -0,0 +1,36 @@
+import { TLRichText, toRichText } from '@tldraw/editor'
+import { isEmptyRichText } from './richText'
+
+describe('isEmptyRichText', () => {
+	it('treats a paragraph with no content key as empty (interactive editor output)', () => {
+		expect(isEmptyRichText(toRichText(''))).toBe(true)
+	})
+
+	it('treats a paragraph with an empty content array as empty (programmatic authoring)', () => {
+		const richText: TLRichText = {
+			type: 'doc',
+			content: [{ type: 'paragraph', attrs: { dir: 'auto' }, content: [] }],
+		}
+		expect(isEmptyRichText(richText)).toBe(true)
+	})
+
+	it('treats a doc with an empty content array as empty (hand-authored / importer form)', () => {
+		const richText: TLRichText = { type: 'doc', content: [] }
+		expect(isEmptyRichText(richText)).toBe(true)
+	})
+
+	it('treats a paragraph with text as non-empty', () => {
+		expect(isEmptyRichText(toRichText('Hello'))).toBe(false)
+	})
+
+	it('treats multiple paragraphs as non-empty', () => {
+		const richText: TLRichText = {
+			type: 'doc',
+			content: [
+				{ type: 'paragraph', content: [] },
+				{ type: 'paragraph', content: [] },
+			],
+		}
+		expect(isEmptyRichText(richText)).toBe(false)
+	})
+})

package/src/lib/utils/text/richText.ts

@@ -107,8 +107,16 @@ export function renderHtmlFromRichTextForMeasurement(editor: Editor, richText: T
 const plainTextFromRichTextCache = new WeakCache<TLRichText, string>()
 
 export function isEmptyRichText(richText: TLRichText) {
+	// An empty document has no text. It can be encoded several equally-valid ways:
+	// an empty `content` array at the doc level, or a single paragraph whose own
+	// `content` is missing or an empty array. The interactive editor emits the
+	// single-paragraph / missing-`content` form; programmatic authoring (snapshot
+	// loads, and agents/importers emitting tldraw JSON) commonly emits the
+	// empty-array forms. Treat them all as empty.
+	if (richText.content.length === 0) return true
 	if (richText.content.length === 1) {
-		if (!(richText.content[0] as any).content) return true
+		const node = richText.content[0] as any
+		if (!node.content || node.content.length === 0) return true
 	}
 	return false
 }