@tldraw/editor 5.2.0-next.ee0fa4d6244f → 5.2.0

package/src/lib/editor/shapes/ShapeUtil.ts

@@ -982,6 +982,47 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 * @public
 	 */
 	onEditEnd?(shape: Shape): void
+
+	/**
+	 * Provide an app-owned element to be rendered inside the shape, alongside the output of
+	 * {@link ShapeUtil.component}. While the shape remains mounted, tldraw guarantees the
+	 * element keeps the same DOM position: it is never unmounted, recreated, or relocated by
+	 * reordering, reparenting, culling, or re-renders. When adopting the element, tldraw uses
+	 * `Node.moveBefore` where available so stateful content like cross-origin iframes keeps
+	 * its state across the move, falling back to `appendChild` elsewhere.
+	 *
+	 * Pair this with {@link ShapeUtil.onReleaseAppOwnedElement} to reclaim the element before
+	 * the shape or editor unmounts.
+	 *
+	 * This is called once per shape mount, not on every prop change, so the adopted element is
+	 * not refreshed when the shape's props change. If the element's content depends on props,
+	 * return a stable element and mutate it in place (for example from {@link ShapeUtil.component}
+	 * or an effect) rather than returning a different element.
+	 *
+	 * @param shape - The shape.
+	 * @returns The element to adopt, or null to render nothing.
+	 * @public
+	 */
+	getAppOwnedElement?(shape: Shape): HTMLElement | null
+
+	/**
+	 * A callback called before the shape's app-owned element slot is destroyed: when the shape
+	 * unmounts (for example when it is deleted or the current page changes) or when the whole
+	 * editor unmounts, including error teardown. The slot is still connected to the document
+	 * when this is called, so the app can move the element to another connected parent with
+	 * `Node.moveBefore` to preserve its state. An element left in the slot is destroyed along
+	 * with it.
+	 *
+	 * This is not only a "shape deleted" signal: it also fires on page changes, editor unmount,
+	 * and (in dev under React StrictMode) on the throwaway mount/unmount cycle while the shape
+	 * still exists. Make it safe to call when the shape is still present, and check the store
+	 * (`this.editor.getShape(shape.id)`) if you need to distinguish deletion from a remount.
+	 *
+	 * @param shape - The shape.
+	 * @param element - The element returned by {@link ShapeUtil.getAppOwnedElement}.
+	 * @public
+	 */
+	onReleaseAppOwnedElement?(shape: Shape, element: HTMLElement): void
 }
 
 /**

package/src/lib/editor/tools/BaseBoxShapeTool/children/Pointing.ts

@@ -4,6 +4,7 @@ import { Vec } from '../../../../primitives/Vec'
 import type { Editor } from '../../../Editor'
 import { TLBaseBoxShape } from '../../../shapes/BaseBoxShapeUtil'
 import { TLPointerEventInfo } from '../../../types/event-types'
+import { cancelShapeCreationOnLongPress } from '../../cancelShapeCreationOnLongPress'
 import { StateNode } from '../../StateNode'
 import type { BaseBoxShapeTool } from '../BaseBoxShapeTool'
 
@@ -65,6 +66,10 @@ export class Pointing extends StateNode {
 		this.complete()
 	}
 
+	override onLongPress() {
+		cancelShapeCreationOnLongPress(this.editor, () => this.cancel())
+	}
+
 	override onCancel() {
 		this.cancel()
 	}

package/src/lib/editor/tools/StateNode.ts

@@ -268,8 +268,6 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 	onLongPress?(info: TLPointerEventInfo): void
 	onPointerUp?(info: TLPointerEventInfo): void
 	onDoubleClick?(info: TLClickEventInfo): void
-	onTripleClick?(info: TLClickEventInfo): void
-	onQuadrupleClick?(info: TLClickEventInfo): void
 	onRightClick?(info: TLPointerEventInfo): void
 	onMiddleClick?(info: TLPointerEventInfo): void
 	onKeyDown?(info: TLKeyboardEventInfo): void

package/src/lib/editor/tools/cancelShapeCreationOnLongPress.ts

@@ -0,0 +1,31 @@
+import type { Editor } from '../Editor'
+
+/**
+ * Shared handler for a long-press in a discrete shape-creation tool's pointing
+ * state (geo, note, line, text, arrow, frame). On a coarse pointer this cancels
+ * any pending creation so the long-press leaves no shape behind (issue #8277).
+ * It does not open a context menu — that is a select-tool surface, reached on
+ * touch only from the select tool, and on desktop from a right-click (which the
+ * editor routes through the select tool).
+ *
+ * Gated on `isCoarsePointer`: on a fine pointer (mouse) the long-press timer
+ * powers the deliberate "pause before drag to start a precise arrow" gesture,
+ * which we must not disturb. The bug only manifests on coarse pointers, because
+ * that is also where the browser fires `contextmenu` at the long-press mark.
+ *
+ * The `cancelPendingCreation` callback is the tool's own cleanup — it knows
+ * whether it needs to `bailToMark` a shape it created early or simply transition
+ * back to idle. Continuous-gesture tools (draw, highlight, eraser, laser) are
+ * excluded: their press is their own action, so they handle (or ignore) the
+ * long-press themselves.
+ *
+ * @internal
+ */
+export function cancelShapeCreationOnLongPress(
+	editor: Editor,
+	cancelPendingCreation: () => void
+): void {
+	if (!editor.getInstanceState().isCoarsePointer) return
+
+	cancelPendingCreation()
+}

package/src/lib/editor/types/event-types.ts

@@ -24,7 +24,7 @@ export type TLPointerEventName =
 	| 'middle_click'
 
 /** @public */
-export type TLCLickEventName = 'double_click' | 'triple_click' | 'quadruple_click'
+export type TLCLickEventName = 'double_click'
 
 /** @public */
 export type TLPinchEventName = 'pinch_start' | 'pinch' | 'pinch_end'
@@ -63,6 +63,13 @@ export type TLPointerEventInfo = TLBaseEventInfo & {
 	pointerId: number
 	button: number
 	isPen: boolean
+	/**
+	 * Whether this pen event appears to be direct manipulation on the display (e.g. Apple Pencil on
+	 * an iPad or a Surface Pen on a touchscreen) rather than indirect input from a desktop graphics
+	 * tablet (e.g. a Wacom Intuos). Only direct-display pens should auto-enable pen mode. Drawing and
+	 * pressure behavior is driven by `isPen` and applies to all pens regardless of this flag.
+	 */
+	isPenDirect?: boolean
 } & TLPointerEventTarget
 
 /** @public */
@@ -72,7 +79,7 @@ export type TLClickEventInfo = TLBaseEventInfo & {
 	point: VecLike
 	pointerId: number
 	button: number
-	phase: 'down' | 'up' | 'settle'
+	phase: 'down' | 'up' | 'settle-down' | 'settle-up'
 } & TLPointerEventTarget
 
 /** @public */
@@ -173,8 +180,6 @@ export interface TLEventHandlers {
 	onLongPress: TLPointerEvent
 	onRightClick: TLPointerEvent
 	onDoubleClick: TLClickEvent
-	onTripleClick: TLClickEvent
-	onQuadrupleClick: TLClickEvent
 	onMiddleClick: TLPointerEvent
 	onPointerUp: TLPointerEvent
 	onKeyDown: TLKeyboardEvent
@@ -206,7 +211,5 @@ export const EVENT_NAME_MAP: Record<
 	complete: 'onComplete',
 	interrupt: 'onInterrupt',
 	double_click: 'onDoubleClick',
-	triple_click: 'onTripleClick',
-	quadruple_click: 'onQuadrupleClick',
 	tick: 'onTick',
 }

package/src/lib/globals/environment.ts

@@ -17,6 +17,10 @@ const tlenv = {
 	isWebview: false,
 	isDarwin: false,
 	hasCanvasSupport: false,
+	// Whether the device has a touch screen (an integrated coarse pointer, e.g. an iPad or a
+	// touchscreen laptop). Unlike `isCoarsePointer`, this reflects the device's hardware rather than
+	// the pointer currently in use, so it stays stable when a pen or mouse is used.
+	isTouchDevice: false,
 }
 
 let isForcedFinePointer = false
@@ -32,6 +36,9 @@ if (typeof window !== 'undefined') {
 	}
 	tlenv.hasCanvasSupport = 'Promise' in window && 'HTMLCanvasElement' in window
 	isForcedFinePointer = tlenv.isFirefox && !tlenv.isAndroid && !tlenv.isIos
+	tlenv.isTouchDevice =
+		('navigator' in window && window.navigator.maxTouchPoints > 0) ||
+		(typeof window.matchMedia === 'function' && window.matchMedia('(any-pointer: coarse)').matches)
 }
 
 /**

package/src/lib/hooks/EditorComponentsContext.tsx

@@ -2,7 +2,6 @@ import { ComponentType, RefAttributes, createContext, useContext } from 'react'
 import type { TLCanvasComponentProps } from '../components/default-components/DefaultCanvas'
 import type { TLErrorFallbackComponent } from '../components/default-components/DefaultErrorFallback'
 import type { TLGridProps } from '../components/default-components/DefaultGrid'
-import type { TLSelectionBackgroundProps } from '../components/default-components/DefaultSelectionBackground'
 import type { TLShapeErrorFallbackComponent } from '../components/default-components/DefaultShapeErrorFallback'
 import type { TLShapeWrapperProps } from '../components/default-components/DefaultShapeWrapper'
 
@@ -14,7 +13,6 @@ export interface TLEditorComponents {
 	InFrontOfTheCanvas?: ComponentType | null
 	LoadingScreen?: ComponentType | null
 	OnTheCanvas?: ComponentType | null
-	SelectionBackground?: ComponentType<TLSelectionBackgroundProps> | null
 	ShapeWrapper?: ComponentType<TLShapeWrapperProps & RefAttributes<HTMLDivElement>> | null
 	Spinner?: ComponentType<React.SVGProps<SVGSVGElement>> | null
 	SvgDefs?: ComponentType | null

package/src/lib/hooks/useCanvasEvents.ts

@@ -8,6 +8,7 @@ import {
 	setPointerCapture,
 } from '../utils/dom'
 import { getPointerInfo } from '../utils/getPointerInfo'
+import { getPointerEventButton, isDirectDisplayPen, isSecondaryClickEvent } from '../utils/pointer'
 import { useEditor } from './useEditor'
 
 export function useCanvasEvents() {
@@ -17,12 +18,16 @@ export function useCanvasEvents() {
 
 	const events = useMemo(
 		function canvasEvents() {
+			let isSecondaryClickPointerDown = false
+
 			function onPointerDown(e: React.PointerEvent) {
 				if (editor.wasEventAlreadyHandled(e)) return
+				const button = getPointerEventButton(e)
+				isSecondaryClickPointerDown = button === 2
 
 				// With right-click panning disabled, fire right_click on press and let the
 				// native contextmenu through so the menu opens at the pointer-down location.
-				if (e.button === 2 && !editor.options.rightClickPanning) {
+				if (button === 2 && !editor.options.rightClickPanning) {
 					editor.dispatch({
 						type: 'pointer',
 						target: 'canvas',
@@ -32,7 +37,11 @@ export function useCanvasEvents() {
 					return
 				}
 
-				if (e.button !== 0 && e.button !== 1 && e.button !== 2 && e.button !== 5) return
+				if (button !== 0 && button !== 1 && button !== 2 && button !== 5) return
+
+				// Detect direct-display pen input (Apple Pencil, Surface Pen on a touchscreen) so we
+				// only auto-enable pen mode for it, not for an indirect desktop tablet stylus.
+				const isPenDirect = isDirectDisplayPen(e)
 
 				setPointerCapture(e.currentTarget, e)
 
@@ -41,17 +50,19 @@ export function useCanvasEvents() {
 					target: 'canvas',
 					name: 'pointer_down',
 					...getPointerInfo(editor, e),
+					isPenDirect,
 				})
 			}
 
 			function onPointerUp(e: React.PointerEvent) {
 				if (editor.wasEventAlreadyHandled(e)) return
-				if (e.button !== 0 && e.button !== 1 && e.button !== 2 && e.button !== 5) return
+				const button = isSecondaryClickPointerDown ? 2 : getPointerEventButton(e)
+				if (button !== 0 && button !== 1 && button !== 2 && button !== 5) return
 
 				const rightClickPanning = editor.options.rightClickPanning
 				// Check before dispatch (which resets isPanning)
 				const wasRightClickPanning =
-					rightClickPanning && e.button === 2 && editor.inputs.getIsPanning()
+					rightClickPanning && button === 2 && editor.inputs.getIsPanning()
 
 				releasePointerCapture(e.currentTarget, e)
 
@@ -60,10 +71,11 @@ export function useCanvasEvents() {
 					target: 'canvas',
 					name: 'pointer_up',
 					...getPointerInfo(editor, e),
+					button,
 				})
 
 				// Static right-click: fire contextmenu at the pointer-up location
-				if (rightClickPanning && e.button === 2 && !wasRightClickPanning) {
+				if (rightClickPanning && button === 2 && !wasRightClickPanning) {
 					const contextMenuEvent = new PointerEvent('contextmenu', {
 						bubbles: true,
 						clientX: e.clientX,
@@ -76,6 +88,7 @@ export function useCanvasEvents() {
 					})
 					e.currentTarget.dispatchEvent(contextMenuEvent)
 				}
+				isSecondaryClickPointerDown = false
 			}
 
 			function onPointerEnter(e: React.PointerEvent) {
@@ -171,16 +184,15 @@ export function useCanvasEvents() {
 				// Synthetic events — our own dispatch from onPointerUp, or tests using
 				// 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).
+				// Only suppress the native browser contextmenu when it follows a
+				// secondary click. 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
+				if (!isSecondaryClickEvent(e)) return
 				preventDefault(e)
 			}
 

package/src/lib/hooks/useEditorComponents.tsx

@@ -33,7 +33,6 @@ export function EditorComponentsProvider({
 			InFrontOfTheCanvas: null,
 			LoadingScreen: DefaultLoadingScreen,
 			OnTheCanvas: null,
-			SelectionBackground: null,
 			ShapeWrapper: DefaultShapeWrapper,
 			Spinner: DefaultSpinner,
 			SvgDefs: DefaultSvgDefs,

package/src/lib/hooks/usePresence.ts

@@ -1,5 +1,5 @@
 import { useValue } from '@tldraw/state-react'
-import { TLInstancePresence } from '@tldraw/tlschema'
+import { TLInstancePresence, TLUserId } from '@tldraw/tlschema'
 import { useEditor } from './useEditor'
 
 // TODO: maybe move this to a computed property on the App class?
@@ -7,7 +7,7 @@ import { useEditor } from './useEditor'
  * @returns The latest presence of the user matching userId
  * @public
  */
-export function usePresence(userId: string): TLInstancePresence | null {
+export function usePresence(userId: TLUserId): TLInstancePresence | null {
 	const editor = useEditor()
 
 	const latestPresence = useValue(

package/src/lib/hooks/useScreenBounds.ts

@@ -11,6 +11,9 @@ export function useScreenBounds(ref: React.RefObject<HTMLElement | null>) {
 		const updateBounds = throttle(
 			() => {
 				if (!ref.current) return
+				// If the container's document has been torn down (e.g. an iframe
+				// being removed), there's nothing to measure — bail.
+				if (!ref.current.ownerDocument.body) return
 				editor.updateViewportScreenBounds(ref.current)
 			},
 			200,

package/src/lib/license/LicenseManager.test.ts

@@ -60,22 +60,30 @@ describe('LicenseManager', () => {
 			expect(result).toMatchObject({ isLicenseParseable: false, reason: 'no-key-provided' })
 		})
 
-		it('Signals that it is development mode when localhost', async () => {
-			const schemes = ['http', 'https']
-			for (const scheme of schemes) {
-				// @ts-ignore
-				delete window.location
-				// @ts-ignore
-				window.location = new URL(`${scheme}://localhost:3000`)
-
-				const testEnvLicenseManager = new LicenseManager('', keyPair.publicKey)
-				const licenseKey = await generateLicenseKey(STANDARD_LICENSE_INFO, keyPair)
-				const result = await testEnvLicenseManager.getLicenseFromKey(licenseKey)
-				expect(result).toMatchObject({
-					isLicenseParseable: true,
-					isDomainValid: false,
-					isDevelopment: true,
-				})
+		it('Signals that it is development mode for loopback hosts', async () => {
+			process.env.NODE_ENV = 'production'
+			try {
+				const schemes = ['http', 'https']
+				const hosts = ['localhost', '127.0.0.1', '127.0.0.2', '[::1]']
+				for (const scheme of schemes) {
+					for (const host of hosts) {
+						// @ts-ignore
+						delete window.location
+						// @ts-ignore
+						window.location = new URL(`${scheme}://${host}:3000`)
+
+						const testEnvLicenseManager = new LicenseManager('', keyPair.publicKey)
+						const licenseKey = await generateLicenseKey(STANDARD_LICENSE_INFO, keyPair)
+						const result = await testEnvLicenseManager.getLicenseFromKey(licenseKey)
+						expect(result).toMatchObject({
+							isLicenseParseable: true,
+							isDomainValid: false,
+							isDevelopment: true,
+						})
+					}
+				}
+			} finally {
+				process.env.NODE_ENV = 'test'
 			}
 		})
 

package/src/lib/license/LicenseManager.ts

@@ -125,14 +125,20 @@ export class LicenseManager {
 	}
 
 	private getIsDevelopment() {
-		// If we are using https on a non-localhost domain we assume it's a production env and a development one otherwise
+		// If we are using https on a non-loopback domain we assume it's a production env and a development one otherwise
 		return (
 			!['https:', 'vscode-webview:'].includes(window.location.protocol) ||
-			window.location.hostname === 'localhost' ||
+			this.isLoopbackHost(window.location.hostname) ||
 			process.env.NODE_ENV !== 'production'
 		)
 	}
 
+	private isLoopbackHost(hostname: string) {
+		// localhost, IPv4 loopback (127.0.0.0/8) and IPv6 loopback (::1) are all local development hosts
+		const host = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+		return host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host)
+	}
+
 	private getTrackType(result: LicenseFromKeyResult, licenseState: LicenseState): TrackType {
 		// Track watermark for unlicensed production deployments
 		if (licenseState === 'unlicensed-production') {

package/src/lib/primitives/Vec.ts

@@ -1,5 +1,8 @@
 import { VecModel } from '@tldraw/tlschema'
 import { EASINGS } from './easings'
+
+const { easeInQuad, easeInOutQuad } = EASINGS
+
 function clamp(n: number, min: number, max?: number): number {
 	return Math.max(min, typeof max !== 'undefined' ? Math.min(n, max) : n)
 }
@@ -634,13 +637,13 @@ export class Vec {
 	 * @param steps - The number of points to return.
 	 * @param ease - The easing to use.
 	 */
-	static PointsBetween(A: VecModel, B: VecModel, steps = 6, ease = EASINGS.easeInQuad): Vec[] {
+	static PointsBetween(A: VecModel, B: VecModel, steps = 6, ease = easeInQuad): Vec[] {
 		const results: Vec[] = []
 
 		for (let i = 0; i < steps; i++) {
 			const t = ease(i / (steps - 1))
 			const point = Vec.Lrp(A, B, t)
-			point.z = Math.min(1, 0.5 + Math.abs(0.5 - EASINGS.easeInOutQuad(t)) * 0.65)
+			point.z = Math.min(1, 0.5 + Math.abs(0.5 - easeInOutQuad(t)) * 0.65)
 			results.push(point)
 		}
 

package/src/lib/test/ContentElementSlot.test.tsx

@@ -0,0 +1,201 @@
+import { act, render } from '@testing-library/react'
+import { BaseBoxShapeUtil, createShapeId, Editor, RecordProps, T, TLShape } from '../..'
+import { TldrawEditor } from '../TldrawEditor'
+
+const PERSISTENT_SHAPE_TYPE = 'test-persistent'
+
+declare module '@tldraw/tlschema' {
+	export interface TLGlobalShapePropsMap {
+		[PERSISTENT_SHAPE_TYPE]: { w: number; h: number }
+	}
+}
+
+type IPersistentShape = TLShape<typeof PERSISTENT_SHAPE_TYPE>
+
+// App-owned element registry and parking lot, the way an app using
+// getContentElement would keep elements alive across editor sessions.
+const elements = new Map<string, HTMLElement>()
+let parkingLot: HTMLDivElement
+const releaseCalls: Array<{ shapeId: string; element: HTMLElement; slotWasConnected: boolean }> = []
+
+class PersistentShapeUtil extends BaseBoxShapeUtil<IPersistentShape> {
+	static override type = PERSISTENT_SHAPE_TYPE
+	static override props: RecordProps<IPersistentShape> = {
+		w: T.number,
+		h: T.number,
+	}
+	getDefaultProps(): IPersistentShape['props'] {
+		return { w: 100, h: 100 }
+	}
+	getIndicatorPath() {
+		return undefined
+	}
+	component() {
+		return null
+	}
+	override getAppOwnedElement(shape: IPersistentShape) {
+		let element = elements.get(shape.id)
+		if (!element) {
+			element = document.createElement('div')
+			element.dataset.testElementFor = shape.id
+			elements.set(shape.id, element)
+		}
+		return element
+	}
+	override onReleaseAppOwnedElement(shape: IPersistentShape, element: HTMLElement) {
+		releaseCalls.push({
+			shapeId: shape.id,
+			element,
+			slotWasConnected: element.parentElement?.isConnected ?? false,
+		})
+		parkingLot.appendChild(element)
+	}
+}
+
+function getSlotFor(shapeId: string) {
+	return document.querySelector(`[data-shape-id="${shapeId}"] .tl-content-slot`)
+}
+
+describe('content element slot', () => {
+	beforeEach(() => {
+		elements.clear()
+		releaseCalls.length = 0
+		parkingLot = document.createElement('div')
+		document.body.appendChild(parkingLot)
+	})
+
+	afterEach(() => {
+		parkingLot.remove()
+	})
+
+	async function renderEditor() {
+		let editor!: Editor
+		const result = await act(async () =>
+			render(
+				<TldrawEditor
+					shapeUtils={[PersistentShapeUtil]}
+					onMount={(e) => {
+						editor = e
+					}}
+				/>
+			)
+		)
+		return { ...result, editor }
+	}
+
+	it('adopts the app-owned element into the shape and releases it before editor unmount', async () => {
+		const { editor, unmount } = await renderEditor()
+		const id = createShapeId()
+
+		await act(async () => {
+			editor.createShape<IPersistentShape>({ id, type: PERSISTENT_SHAPE_TYPE, x: 0, y: 0 })
+		})
+
+		const element = elements.get(id)!
+		expect(element).toBeDefined()
+		expect(element.parentElement).toBe(getSlotFor(id))
+		expect(element.isConnected).toBe(true)
+
+		await act(async () => {
+			unmount()
+		})
+
+		// The release callback fired exactly once, while the slot was still
+		// connected to the document, so a state-preserving move was possible.
+		expect(releaseCalls).toHaveLength(1)
+		expect(releaseCalls[0]).toMatchObject({ shapeId: id, element, slotWasConnected: true })
+		// The app reclaimed the element into its parking lot and it survived teardown.
+		expect(element.parentElement).toBe(parkingLot)
+		expect(element.isConnected).toBe(true)
+	})
+
+	it('releases the element when the shape is deleted', async () => {
+		const { editor, unmount } = await renderEditor()
+		const id = createShapeId()
+
+		await act(async () => {
+			editor.createShape<IPersistentShape>({ id, type: PERSISTENT_SHAPE_TYPE, x: 0, y: 0 })
+		})
+
+		const element = elements.get(id)!
+		expect(element.parentElement).toBe(getSlotFor(id))
+
+		await act(async () => {
+			editor.deleteShape(id)
+		})
+
+		expect(releaseCalls).toHaveLength(1)
+		expect(releaseCalls[0]).toMatchObject({ shapeId: id, element, slotWasConnected: true })
+		expect(element.parentElement).toBe(parkingLot)
+
+		await act(async () => {
+			unmount()
+		})
+
+		// The slot is gone; no second release for the deleted shape.
+		expect(releaseCalls).toHaveLength(1)
+	})
+
+	it('re-adopts a parked element when the editor remounts, without recreating it', async () => {
+		const first = await renderEditor()
+		const id = createShapeId()
+
+		await act(async () => {
+			first.editor.createShape<IPersistentShape>({ id, type: PERSISTENT_SHAPE_TYPE, x: 0, y: 0 })
+		})
+
+		const element = elements.get(id)!
+
+		await act(async () => {
+			first.unmount()
+		})
+		expect(element.parentElement).toBe(parkingLot)
+
+		const second = await renderEditor()
+		await act(async () => {
+			second.editor.createShape<IPersistentShape>({ id, type: PERSISTENT_SHAPE_TYPE, x: 0, y: 0 })
+		})
+
+		// The same element instance was adopted into the new editor's slot.
+		expect(elements.get(id)).toBe(element)
+		expect(element.parentElement).toBe(getSlotFor(id))
+
+		await act(async () => {
+			second.unmount()
+		})
+		expect(element.parentElement).toBe(parkingLot)
+	})
+
+	it('keeps the element in the same DOM position when z-order changes', async () => {
+		const { editor, unmount } = await renderEditor()
+		const id = createShapeId()
+		const otherId = createShapeId()
+
+		await act(async () => {
+			editor.createShape<IPersistentShape>({ id, type: PERSISTENT_SHAPE_TYPE, x: 0, y: 0 })
+			editor.createShape<IPersistentShape>({
+				id: otherId,
+				type: PERSISTENT_SHAPE_TYPE,
+				x: 50,
+				y: 50,
+			})
+		})
+
+		const element = elements.get(id)!
+		const slot = getSlotFor(id)
+		expect(element.parentElement).toBe(slot)
+
+		await act(async () => {
+			editor.sendToBack([id])
+			editor.bringToFront([id])
+		})
+
+		// No release fired and the element is still in the same slot node.
+		expect(releaseCalls).toHaveLength(0)
+		expect(element.parentElement).toBe(slot)
+
+		await act(async () => {
+			unmount()
+		})
+	})
+})

package/src/lib/utils/dom.ts

@@ -100,6 +100,40 @@ export function setStyleProperty(
 	elm.style.setProperty(property, String(value))
 }
 
+/**
+ * Move an element into a new parent, preserving its state where the platform allows it.
+ *
+ * Uses `Node.moveBefore` (Chromium 133+, Firefox 144+) when both the element and parent are
+ * connected to the same document — this moves the element without resetting its state, so
+ * iframes don't reload and media keeps playing. Otherwise (older browsers, disconnected nodes,
+ * or a cross-document move) it falls back to `appendChild`, which moves the element but resets
+ * its state like an iframe reload.
+ *
+ * This is the primitive tldraw uses to adopt `ShapeUtil.getAppOwnedElement` elements, exposed so
+ * apps can perform symmetric state-preserving moves from `ShapeUtil.onReleaseAppOwnedElement` —
+ * for example moving an element to an off-canvas parking lot between editor sessions.
+ *
+ * @param parent - The element to move `element` into, as its last child.
+ * @param element - The element to move.
+ * @public
+ */
+export function moveElementInto(parent: HTMLElement, element: HTMLElement) {
+	if (
+		element.isConnected &&
+		parent.isConnected &&
+		typeof (parent as any).moveBefore === 'function' &&
+		element.ownerDocument === parent.ownerDocument
+	) {
+		try {
+			;(parent as any).moveBefore(element, null)
+			return
+		} catch {
+			// fall through to appendChild
+		}
+	}
+	parent.appendChild(element)
+}
+
 /** @internal */
 export function elementShouldCaptureKeys(el: Element | null, includeButtonsAndMenus = true) {
 	if (!el) return false