feat(tldraw): show a loading placeholder for pasted bookmarks (tldraw#8663)

In order to make pasting URLs feel responsive even when bookmark
metadata is slow to fetch, this PR creates the bookmark shape
immediately as a placeholder and hydrates it with metadata in the
background. The placeholder shows a loading spinner overlay (similar to
image loading) so the loading state is visible at the paste location,
and once metadata resolves the asset is patched in. If the fetch fails,
the bookmark gracefully falls back to a URL-only card.

<img width="2272" height="1396" alt="Kapture 2026-06-18 at 12 28 53"
src="https://github.com/user-attachments/assets/f0b9516c-59b9-4cec-a9a8-755c0be0693d"
/>

Closes tldraw#8653

### Change type

- [x] `feature`

### Test plan

1. Run `yarn dev`, open the examples app, and paste a URL onto the
canvas — a bookmark placeholder should appear immediately at the paste
location.
2. Throttle the network in DevTools and paste again — the placeholder
with its loading spinner should be visible while metadata loads, then
resolve into the full bookmark preview.
3. Paste a recognized embed URL (e.g. a YouTube link) — it should still
create an embed shape, not a bookmark placeholder.
4. Paste a URL that fails to unfurl — the bookmark should remain visible
as a URL-only card rather than disappearing.
5. Paste a URL, then immediately undo — the placeholder should disappear
cleanly without leaving an extra "metadata loaded" undo step.

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

### Release notes

- Pasted bookmarks now show an immediate loading placeholder at the
paste location, with a loading spinner, instead of waiting for metadata
before appearing.

### API changes

- BookmarkShapeUtil now uses `getGeometry` to explicitly define its
geometry.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mimecuvalo

packages/tldraw/api-report.api.md

@@ -534,6 +534,8 @@ export class BookmarkShapeUtil extends BaseBoxShapeUtil<TLBookmarkShape> {
     // (undocumented)
     getDefaultProps(): TLBookmarkShape['props'];
     // (undocumented)
+    getGeometry(shape: TLBookmarkShape): Rectangle2d;
+    // (undocumented)
     getIndicatorPath(shape: TLBookmarkShape): Path2D;
     // (undocumented)
     getInterpolatedProps(startShape: TLBookmarkShape, endShape: TLBookmarkShape, t: number): TLBookmarkShapeProps;

packages/tldraw/src/lib/shapes/bookmark/BookmarkShapeUtil.tsx

@@ -2,6 +2,7 @@
 import {
 	BaseBoxShapeUtil,
 	HTMLContainer,
+	Rectangle2d,
 	T,
 	TLAssetId,
 	TLBookmarkAsset,
@@ -24,7 +25,9 @@ import { getRotatedBoxShadow } from '../shared/rotated-box-shadow'
 import {
 	BOOKMARK_HEIGHT,
 	BOOKMARK_WIDTH,
+	getBookmarkShapeHeight,
 	getHumanReadableAddress,
+	getResolvedBookmarkAssetId,
 	setBookmarkHeight,
 	updateBookmarkAssetOnUrlChange,
 } from './bookmarks'
@@ -87,16 +90,25 @@ export class BookmarkShapeUtil extends BaseBoxShapeUtil<TLBookmarkShape> {
 		}
 	}
 
+	override getGeometry(shape: TLBookmarkShape) {
+		return new Rectangle2d({
+			width: shape.props.w,
+			height: getBookmarkShapeHeight(this.editor, shape),
+			isFilled: true,
+		})
+	}
+
 	override component(shape: TLBookmarkShape) {
-		const { assetId, url, h } = shape.props
+		const { assetId, url } = shape.props
+		const h = getBookmarkShapeHeight(this.editor, shape)
 		const rotation = this.editor.getShapePageTransform(shape)!.rotation()
 
 		return <BookmarkShapeComponent assetId={assetId} url={url} h={h} rotation={rotation} />
 	}
 
 	override getIndicatorPath(shape: TLBookmarkShape): Path2D {
 		const path = new Path2D()
-		path.rect(0, 0, shape.props.w, shape.props.h)
+		path.rect(0, 0, shape.props.w, getBookmarkShapeHeight(this.editor, shape))
 		return path
 	}
 
@@ -147,7 +159,8 @@ export function BookmarkShapeComponent({
 }) {
 	const editor = useEditor()
 
-	const asset = assetId ? (editor.getAsset(assetId) as TLBookmarkAsset) : null
+	const resolvedAssetId = getResolvedBookmarkAssetId(editor, assetId, url)
+	const asset = resolvedAssetId ? (editor.getAsset(resolvedAssetId) as TLBookmarkAsset) : null
 
 	const isSafariExport = !!useSvgExportContext() && tlenv.isSafari
 

packages/tldraw/src/lib/shapes/bookmark/bookmarks.ts

@@ -5,6 +5,7 @@ import {
 	TLAssetId,
 	TLBookmarkAsset,
 	TLBookmarkShape,
+	TLShapeId,
 	TLShapePartial,
 	createShapeId,
 	debounce,
@@ -84,6 +85,44 @@ export function updateBookmarkAssetOnUrlChange(editor: Editor, shape: TLBookmark
 	}
 }
 
+/**
+ * Resolve the asset id to render for a bookmark. Bookmark assets are keyed
+ * deterministically by URL, so if the shape has no `assetId` but an asset for
+ * its URL already exists in the store, use that.
+ *
+ * This keeps a bookmark from staying stuck on its placeholder after the shape
+ * is recreated outside of the hydration flow — e.g. on redo, where the
+ * placeholder is restored with a null `assetId` but its hydrated asset (created
+ * with `history: 'ignore'`) still lives in the store.
+ */
+export function getResolvedBookmarkAssetId(
+	editor: Editor,
+	assetId: TLAssetId | null,
+	url: string
+): TLAssetId | null {
+	if (assetId) return assetId
+	if (!url) return null
+
+	const derivedId: TLAssetId = AssetRecordType.createId(getHashForString(url))
+	return editor.getAsset(derivedId) ? derivedId : null
+}
+
+/**
+ * The effective height to render and measure a bookmark at.
+ *
+ * Normally this is the stored `props.h`. But when the shape's `assetId` resolves
+ * to a different asset than it stores — e.g. a placeholder restored on redo with
+ * a null `assetId` whose asset already exists in the store — `props.h` is stale
+ * (it still holds the placeholder height). In that case recompute the height
+ * from the resolved asset so rendering, the indicator, and the geometry/selection
+ * bounds all stay in sync.
+ */
+export function getBookmarkShapeHeight(editor: Editor, shape: TLBookmarkShape): number {
+	const resolvedAssetId = getResolvedBookmarkAssetId(editor, shape.props.assetId, shape.props.url)
+	if (resolvedAssetId === shape.props.assetId) return shape.props.h
+	return getBookmarkHeight(editor, resolvedAssetId)
+}
+
 async function _createBookmarkAssetOnUrlChange(editor: Editor, shape: TLBookmarkShape) {
 	if (editor.isDisposed) return
 
@@ -128,12 +167,17 @@ function createBookmarkAssetOnUrlChange(editor: Editor, shape: TLBookmarkShape)
 }
 
 /**
- * Creates a bookmark shape from a URL with unfurled metadata.
+ * Creates a bookmark shape from a URL.
+ *
+ * The shape is created immediately as a placeholder so the user gets visible
+ * feedback at the paste location, and the bookmark metadata (title, description,
+ * image, favicon) is fetched in the background. Once metadata resolves, the
+ * shape is patched with the resulting asset. If the fetch fails, the shape is
+ * left as a URL-only bookmark.
  *
  * @returns A Result containing the created bookmark shape or an error
  * @public
  */
-
 export async function createBookmarkFromUrl(
 	editor: Editor,
 	{
@@ -145,10 +189,12 @@ export async function createBookmarkFromUrl(
 	}
 ): Promise<Result<TLBookmarkShape, string>> {
 	try {
-		// Create the bookmark asset with unfurled metadata
-		const asset = await editor.getAssetForExternalContent({ type: 'url', url })
+		// If we already have a bookmark asset for this URL (e.g. another bookmark
+		// shape was created from the same URL earlier), use it immediately rather
+		// than re-fetching.
+		const expectedAssetId: TLAssetId = AssetRecordType.createId(getHashForString(url))
+		const existingAsset = editor.getAsset(expectedAssetId) as TLBookmarkAsset | null
 
-		// Create the bookmark shape
 		const shapeId = createShapeId()
 		const shapePartial: TLShapePartial<TLBookmarkShape> = {
 			id: shapeId,
@@ -159,26 +205,70 @@ export async function createBookmarkFromUrl(
 			opacity: 1,
 			props: {
 				url,
-				assetId: asset?.id || null,
+				assetId: existingAsset?.id ?? null,
 				w: BOOKMARK_WIDTH,
-				h: getBookmarkHeight(editor, asset?.id),
+				h: getBookmarkHeight(editor, existingAsset?.id),
 			},
 		}
 
 		editor.run(() => {
-			// Create the asset if we have one
-			if (asset) {
-				editor.createAssets([asset])
-			}
-
-			// Create the shape
 			editor.createShapes([shapePartial])
 		})
 
-		// Get the created shape
-		const createdShape = editor.getShape(shapeId) as TLBookmarkShape
+		const createdShape = editor.getShape<TLBookmarkShape>(shapeId)
+		if (!createdShape) {
+			return Result.err('Failed to create bookmark shape')
+		}
+
+		// If we already had the asset, we're done — no metadata fetch needed.
+		if (existingAsset) {
+			return Result.ok(createdShape)
+		}
+
+		// Otherwise kick off the metadata fetch in the background. The shape is
+		// already visible as a placeholder; once the asset resolves we'll patch
+		// the shape with its assetId.
+		void hydrateBookmarkShape(editor, shapeId, url)
+
 		return Result.ok(createdShape)
 	} catch (error) {
 		return Result.err(error instanceof Error ? error.message : 'Failed to create bookmark')
 	}
 }
+
+async function hydrateBookmarkShape(editor: Editor, shapeId: TLShapeId, url: string) {
+	let asset
+	try {
+		asset = await editor.getAssetForExternalContent({ type: 'url', url })
+	} catch (error) {
+		console.error(error)
+		return
+	}
+
+	if (editor.isDisposed) return
+	if (!asset) return
+
+	// The shape may have been deleted (e.g. via undo), had its URL changed, or
+	// had its asset replaced before the fetch resolved. In any of those cases we
+	// don't want to attach metadata for the old URL.
+	const shape = editor.getShape<TLBookmarkShape>(shapeId)
+	if (!shape) return
+	if (shape.props.url !== url) return
+	if (shape.props.assetId) return
+
+	editor.run(
+		() => {
+			if (!editor.getAsset(asset.id)) {
+				editor.createAssets([asset])
+			}
+			editor.updateShapes([
+				{
+					id: shapeId,
+					type: 'bookmark',
+					props: { assetId: asset.id },
+				},
+			])
+		},
+		{ history: 'ignore' }
+	)
+}