@tldraw/editor 5.3.0-next.a6e6f66f8517 → 5.3.0-next.aefb8773a7eb

package/dist-cjs/lib/options.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/options.ts"],
-  "sourcesContent": ["import { Awaitable } from '@tldraw/utils'\nimport { ComponentType, Fragment } from 'react'\nimport { DEFAULT_CAMERA_OPTIONS } from './constants'\nimport type { Editor } from './editor/Editor'\nimport { TLContent } from './editor/types/clipboard-types'\nimport { TLExternalContent } from './editor/types/external-content'\nimport { TLCameraOptions } from './editor/types/misc-types'\nimport { VecLike } from './primitives/Vec'\nimport { TLDeepLinkOptions } from './utils/deepLinks'\nimport { TLTextOptions } from './utils/richText'\n\n/**\n * Identifies how a clipboard write was triggered (copy vs cut, keyboard vs menu).\n *\n * @public\n */\nexport interface TLClipboardWriteInfo {\n\treadonly operation: 'copy' | 'cut'\n\treadonly source: 'native' | 'menu'\n}\n\n/**\n * Raw clipboard paste payload, before tldraw parses clipboard contents into {@link TLExternalContent}.\n *\n * - `native-event`: from the `paste` event \u2014 `clipboardData` is available synchronously (unlike async\n *   `navigator.clipboard.read()`).\n * - `clipboard-read`: from an explicit `navigator.clipboard.read()` call \u2014 only `ClipboardItem[]`\n *   exists\n *   (no `DataTransfer`).\n *\n * @public\n */\nexport type TLClipboardPasteRawInfo =\n\t| {\n\t\t\treadonly editor: Editor\n\t\t\treadonly source: 'native-event'\n\t\t\treadonly event: ClipboardEvent\n\t\t\treadonly clipboardData: DataTransfer | null\n\t\t\treadonly point: VecLike | undefined\n\t  }\n\t| {\n\t\t\treadonly editor: Editor\n\t\t\treadonly source: 'clipboard-read'\n\t\t\treadonly clipboardItems: readonly ClipboardItem[]\n\t\t\treadonly point: VecLike | undefined\n\t  }\n\n/**\n * Options for configuring tldraw. For defaults, see {@link defaultTldrawOptions}.\n *\n * @example\n * ```tsx\n * const options: Partial<TldrawOptions> = {\n *     maxPages: 3,\n *     maxShapesPerPage: 1000,\n * }\n *\n * function MyTldrawComponent() {\n *     return <Tldraw options={options} />\n * }\n * ```\n *\n * @public\n */\nexport interface TldrawOptions {\n\treadonly maxShapesPerPage: number\n\treadonly maxFilesAtOnce: number\n\treadonly maxPages: number\n\treadonly animationMediumMs: number\n\treadonly followChaseViewportSnap: number\n\treadonly doubleClickDurationMs: number\n\treadonly multiClickDurationMs: number\n\treadonly coarseDragDistanceSquared: number\n\treadonly dragDistanceSquared: number\n\treadonly uiDragDistanceSquared: number\n\treadonly uiCoarseDragDistanceSquared: number\n\treadonly defaultSvgPadding: number\n\treadonly cameraSlideFriction: number\n\treadonly gridSteps: readonly {\n\t\treadonly min: number\n\t\treadonly mid: number\n\t\treadonly step: number\n\t}[]\n\treadonly collaboratorInactiveTimeoutMs: number\n\treadonly collaboratorIdleTimeoutMs: number\n\treadonly collaboratorCheckIntervalMs: number\n\treadonly cameraMovingTimeoutMs: number\n\treadonly hitTestMargin: number\n\treadonly edgeScrollDelay: number\n\treadonly edgeScrollEaseDuration: number\n\treadonly edgeScrollSpeed: number\n\treadonly edgeScrollDistance: number\n\treadonly coarsePointerWidth: number\n\treadonly coarseHandleRadius: number\n\treadonly handleRadius: number\n\treadonly longPressDurationMs: number\n\treadonly textShadowLod: number\n\treadonly adjacentShapeMargin: number\n\treadonly flattenImageBoundsExpand: number\n\treadonly flattenImageBoundsPadding: number\n\treadonly laserDelayMs: number\n\t/**\n\t * How long (in milliseconds) to fade all laser scribbles after the session ends.\n\t * The total points across all scribbles will be removed proportionally over this duration.\n\t * Defaults to 500ms (0.5 seconds).\n\t */\n\treadonly laserFadeoutMs: number\n\treadonly maxExportDelayMs: number\n\treadonly tooltipDelayMs: number\n\t/**\n\t * How long should previews created by {@link Editor.createTemporaryAssetPreview} last before\n\t * they expire? Defaults to 3 minutes.\n\t */\n\treadonly temporaryAssetPreviewLifetimeMs: number\n\treadonly actionShortcutsLocation: 'menu' | 'toolbar' | 'swap'\n\treadonly createTextOnCanvasDoubleClick: boolean\n\t/**\n\t * The react provider to use when exporting an image. This is useful if your shapes depend on\n\t * external context providers. By default, this is `React.Fragment`.\n\t */\n\treadonly exportProvider: ComponentType<{ children: React.ReactNode }>\n\t/**\n\t * By default, the toolbar items are accessible via number shortcuts according to their order. To disable this, set this option to false.\n\t */\n\treadonly enableToolbarKeyboardShortcuts: boolean\n\t/**\n\t * The maximum number of fonts that will be loaded while blocking the main rendering of the\n\t * canvas. If there are more than this number of fonts needed, we'll just show the canvas right\n\t * away and let the fonts load in in the background.\n\t */\n\treadonly maxFontsToLoadBeforeRender: number\n\t/**\n\t * If you have a CSP policy that blocks inline styles, you can use this prop to provide a\n\t * nonce to use in the editor's styles.\n\t */\n\treadonly nonce: string | undefined\n\t/**\n\t * Branding name of the app, currently only used for adding aria-label for the application.\n\t */\n\treadonly branding?: string\n\t/**\n\t * Whether to use debounced zoom level for certain rendering optimizations. When true,\n\t * `editor.getEfficientZoomLevel()` returns a cached zoom value while the camera is moving,\n\t * reducing re-renders. When false, it always returns the current zoom level.\n\t */\n\treadonly debouncedZoom: boolean\n\t/**\n\t * The number of shapes that must be on the page for the debounced zoom level to be used.\n\t * Defaults to 500 shapes.\n\t */\n\treadonly debouncedZoomThreshold: number\n\t/**\n\t * Whether to allow spacebar panning. When true, the spacebar will pan the camera when held down.\n\t * When false, the spacebar will not pan the camera.\n\t */\n\treadonly spacebarPanning: boolean\n\t/**\n\t * Whether to allow right-click + drag to pan the camera. When true, right-click + drag pans the\n\t * camera and a static right-click opens the context menu at the release position. When false,\n\t * right-click opens the context menu on press (no drag-to-pan).\n\t */\n\treadonly rightClickPanning: boolean\n\t/**\n\t * The default padding (in pixels) used when zooming to fit content in the viewport.\n\t * This affects methods like `zoomToFit()`, `zoomToSelection()`, and `zoomToBounds()`.\n\t * The actual padding used is the minimum of this value and 28% of the viewport width.\n\t * Defaults to 128 pixels.\n\t */\n\treadonly zoomToFitPadding: number\n\t/**\n\t * The distance (in screen pixels) at which shapes snap to guides and other shapes.\n\t */\n\treadonly snapThreshold: number\n\t/**\n\t * Whether locked shapes can be selected with a left click. When false (default), left-clicking\n\t * a locked shape is treated as a click on the canvas \u2014 only right-click selects it. When true,\n\t * locked shapes can be selected via left click and included in brush and scribble selections,\n\t * but the editor's lock guards still prevent moving, resizing, editing, or deleting them.\n\t */\n\treadonly selectLockedShapes: boolean\n\t/**\n\t * Options for the editor's camera. These are the initial camera options.\n\t * Use {@link Editor.setCameraOptions} to update camera options at runtime.\n\t */\n\treadonly camera: Partial<TLCameraOptions>\n\t/**\n\t * Options for the editor's text rendering. These include TipTap configuration and\n\t * font handling. These are the initial text options and cannot be changed at runtime.\n\t */\n\treadonly text: TLTextOptions\n\t/**\n\t * Options for syncing the editor's camera state with the URL. Set to `true` to enable\n\t * with default options, or pass an options object to customize behavior.\n\t *\n\t * @example\n\t * ```tsx\n\t * // Enable with defaults\n\t * <Tldraw options={{ deepLinks: true }} />\n\t *\n\t * // Enable with custom options\n\t * <Tldraw options={{ deepLinks: { param: 'd', debounceMs: 500 } }} />\n\t * ```\n\t */\n\treadonly deepLinks: true | TLDeepLinkOptions | undefined\n\t/**\n\t * Whether the quick-zoom brush preserves its screen-pixel size when the user\n\t * zooms the overview. When true, zooming in shrinks the target viewport (higher\n\t * return zoom); zooming out expands it. When false, the brush keeps the original\n\t * viewport's page dimensions regardless of overview zoom changes.\n\t */\n\treadonly quickZoomPreservesScreenBounds: boolean\n\t/**\n\t * Called before content is written to the clipboard during a copy or cut operation.\n\t * Receives the serialized content (shapes, bindings, assets) and can filter or transform\n\t * it before it reaches the clipboard.\n\t *\n\t * Return a modified `TLContent` object to change what is copied or cut. Return `false` to\n\t * cancel the clipboard write (for cut, the selected shapes are not removed). Return `void`\n\t * (or `undefined`) to pass through unchanged. You may return a `Promise` of those values if\n\t * the hook is async.\n\t *\n\t * @example\n\t * ```tsx\n\t * // Filter out \"locked\" shapes from copy\n\t * onBeforeCopyToClipboard({ content, operation }) {\n\t *     return {\n\t *         ...content,\n\t *         shapes: content.shapes.filter(s => !s.meta.locked),\n\t *         rootShapeIds: content.rootShapeIds.filter(id =>\n\t *             content.shapes.find(s => s.id === id && !s.meta.locked)\n\t *         ),\n\t *     }\n\t * }\n\t * ```\n\t */\n\tonBeforeCopyToClipboard?(\n\t\tinfo: { editor: Editor; content: TLContent } & TLClipboardWriteInfo\n\t): Awaitable<TLContent | false | void>\n\t/**\n\t * Called before pasted content is processed and shapes are created. Receives the parsed\n\t * external content from the clipboard and can filter, transform, or cancel it.\n\t *\n\t * Return `false` to cancel the paste. Return a modified content object to transform it.\n\t * Return `void` (or `undefined`) to pass through unchanged. You may return a `Promise` of\n\t * those values if the hook is async.\n\t *\n\t * This only fires for clipboard paste operations (keyboard shortcuts and menu actions),\n\t * not for file drops or programmatic `putExternalContent` calls.\n\t *\n\t * @example\n\t * ```tsx\n\t * // Block pasting of image files\n\t * onBeforePasteFromClipboard({ content }) {\n\t *     if (content.type === 'files') {\n\t *         const nonImages = content.files.filter(f => !f.type.startsWith('image/'))\n\t *         if (nonImages.length === 0) return false\n\t *         return { ...content, files: nonImages }\n\t *     }\n\t * }\n\t * ```\n\t */\n\tonBeforePasteFromClipboard?(info: {\n\t\teditor: Editor\n\t\tcontent: TLExternalContent<unknown>\n\t\tsource: 'native-event' | 'clipboard-read'\n\t\tpoint?: VecLike\n\t}): Awaitable<TLExternalContent<unknown> | false | void>\n\t/**\n\t * Called first for keyboard and menu paste, **before** tldraw handles or parses clipboard data\n\t * (and before {@link TldrawOptions.onBeforePasteFromClipboard}).\n\t *\n\t * Return `false` to cancel tldraw's default paste handling for this gesture (same convention as\n\t * {@link TldrawOptions.onBeforePasteFromClipboard}). Use this when you handle paste yourself from\n\t * raw clipboard data, or to block the gesture entirely. Return `void` (or `undefined`) to continue.\n\t */\n\tonClipboardPasteRaw?(info: TLClipboardPasteRawInfo): false | void\n\t/**\n\t * Called when content is dropped on the canvas. Provides the page position\n\t * where the drop occurred and the underlying drag event object.\n\t * Return true to prevent default drop handling (files, URLs, etc.)\n\t */\n\texperimental__onDropOnCanvas?(options: {\n\t\tpoint: VecLike\n\t\tevent: React.DragEvent<Element>\n\t}): boolean\n}\n\n/** @public */\nexport const defaultTldrawOptions = {\n\tmaxShapesPerPage: 4000,\n\tmaxFilesAtOnce: 100,\n\tmaxPages: 40,\n\tanimationMediumMs: 320,\n\tfollowChaseViewportSnap: 2,\n\tdoubleClickDurationMs: 450,\n\tmultiClickDurationMs: 200,\n\tcoarseDragDistanceSquared: 36, // 6 squared\n\tdragDistanceSquared: 16, // 4 squared\n\tuiDragDistanceSquared: 16, // 4 squared\n\t// it's really easy to accidentally drag from the toolbar on mobile, so we use a much larger\n\t// threshold than usual here to try and prevent accidental drags.\n\tuiCoarseDragDistanceSquared: 625, // 25 squared\n\tdefaultSvgPadding: 32,\n\tcameraSlideFriction: 0.09,\n\tgridSteps: [\n\t\t{ min: -1, mid: 0.15, step: 64 },\n\t\t{ min: 0.05, mid: 0.375, step: 16 },\n\t\t{ min: 0.15, mid: 1, step: 4 },\n\t\t{ min: 0.7, mid: 2.5, step: 1 },\n\t],\n\tcollaboratorInactiveTimeoutMs: 60000,\n\tcollaboratorIdleTimeoutMs: 3000,\n\tcollaboratorCheckIntervalMs: 1200,\n\tcameraMovingTimeoutMs: 64,\n\thitTestMargin: 8,\n\tedgeScrollDelay: 200,\n\tedgeScrollEaseDuration: 200,\n\tedgeScrollSpeed: 25,\n\tedgeScrollDistance: 8,\n\tcoarsePointerWidth: 12,\n\tcoarseHandleRadius: 20,\n\thandleRadius: 12,\n\tlongPressDurationMs: 500,\n\ttextShadowLod: 0.35,\n\tadjacentShapeMargin: 10,\n\tflattenImageBoundsExpand: 64,\n\tflattenImageBoundsPadding: 16,\n\tlaserDelayMs: 1200,\n\tlaserFadeoutMs: 500,\n\tmaxExportDelayMs: 5000,\n\ttooltipDelayMs: 700,\n\ttemporaryAssetPreviewLifetimeMs: 180000,\n\tactionShortcutsLocation: 'swap',\n\tcreateTextOnCanvasDoubleClick: true,\n\texportProvider: Fragment,\n\tenableToolbarKeyboardShortcuts: true,\n\tmaxFontsToLoadBeforeRender: Infinity,\n\tnonce: undefined,\n\tdebouncedZoom: true,\n\tdebouncedZoomThreshold: 500,\n\tspacebarPanning: true,\n\trightClickPanning: true,\n\tzoomToFitPadding: 128,\n\tsnapThreshold: 8,\n\tselectLockedShapes: false,\n\tcamera: DEFAULT_CAMERA_OPTIONS,\n\ttext: {},\n\tdeepLinks: undefined,\n\tquickZoomPreservesScreenBounds: true,\n\tonBeforeCopyToClipboard: undefined,\n\tonBeforePasteFromClipboard: undefined,\n\tonClipboardPasteRaw: undefined,\n\texperimental__onDropOnCanvas: undefined,\n} as const satisfies TldrawOptions\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,mBAAwC;AACxC,uBAAuC;AA8RhC,MAAM,uBAAuB;AAAA,EACnC,kBAAkB;AAAA,EAClB,gBAAgB;AAAA,EAChB,UAAU;AAAA,EACV,mBAAmB;AAAA,EACnB,yBAAyB;AAAA,EACzB,uBAAuB;AAAA,EACvB,sBAAsB;AAAA,EACtB,2BAA2B;AAAA;AAAA,EAC3B,qBAAqB;AAAA;AAAA,EACrB,uBAAuB;AAAA;AAAA;AAAA;AAAA,EAGvB,6BAA6B;AAAA;AAAA,EAC7B,mBAAmB;AAAA,EACnB,qBAAqB;AAAA,EACrB,WAAW;AAAA,IACV,EAAE,KAAK,IAAI,KAAK,MAAM,MAAM,GAAG;AAAA,IAC/B,EAAE,KAAK,MAAM,KAAK,OAAO,MAAM,GAAG;AAAA,IAClC,EAAE,KAAK,MAAM,KAAK,GAAG,MAAM,EAAE;AAAA,IAC7B,EAAE,KAAK,KAAK,KAAK,KAAK,MAAM,EAAE;AAAA,EAC/B;AAAA,EACA,+BAA+B;AAAA,EAC/B,2BAA2B;AAAA,EAC3B,6BAA6B;AAAA,EAC7B,uBAAuB;AAAA,EACvB,eAAe;AAAA,EACf,iBAAiB;AAAA,EACjB,wBAAwB;AAAA,EACxB,iBAAiB;AAAA,EACjB,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,cAAc;AAAA,EACd,qBAAqB;AAAA,EACrB,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,0BAA0B;AAAA,EAC1B,2BAA2B;AAAA,EAC3B,cAAc;AAAA,EACd,gBAAgB;AAAA,EAChB,kBAAkB;AAAA,EAClB,gBAAgB;AAAA,EAChB,iCAAiC;AAAA,EACjC,yBAAyB;AAAA,EACzB,+BAA+B;AAAA,EAC/B,gBAAgB;AAAA,EAChB,gCAAgC;AAAA,EAChC,4BAA4B;AAAA,EAC5B,OAAO;AAAA,EACP,eAAe;AAAA,EACf,wBAAwB;AAAA,EACxB,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,oBAAoB;AAAA,EACpB,QAAQ;AAAA,EACR,MAAM,CAAC;AAAA,EACP,WAAW;AAAA,EACX,gCAAgC;AAAA,EAChC,yBAAyB;AAAA,EACzB,4BAA4B;AAAA,EAC5B,qBAAqB;AAAA,EACrB,8BAA8B;AAC/B;",
+  "sourcesContent": ["import { Awaitable } from '@tldraw/utils'\nimport { ComponentType, Fragment } from 'react'\nimport { DEFAULT_CAMERA_OPTIONS } from './constants'\nimport type { Editor } from './editor/Editor'\nimport { TLContent } from './editor/types/clipboard-types'\nimport { TLExternalContent } from './editor/types/external-content'\nimport { TLCameraOptions } from './editor/types/misc-types'\nimport { VecLike } from './primitives/Vec'\nimport { TLDeepLinkOptions } from './utils/deepLinks'\nimport { TLTextOptions } from './utils/richText'\n\n/**\n * Identifies how a clipboard write was triggered (copy vs cut, keyboard vs menu).\n *\n * @public\n */\nexport interface TLClipboardWriteInfo {\n\treadonly operation: 'copy' | 'cut'\n\treadonly source: 'native' | 'menu'\n}\n\n/**\n * Raw clipboard paste payload, before tldraw parses clipboard contents into {@link TLExternalContent}.\n *\n * - `native-event`: from the `paste` event \u2014 `clipboardData` is available synchronously (unlike async\n *   `navigator.clipboard.read()`).\n * - `clipboard-read`: from an explicit `navigator.clipboard.read()` call \u2014 only `ClipboardItem[]`\n *   exists\n *   (no `DataTransfer`).\n *\n * @public\n */\nexport type TLClipboardPasteRawInfo =\n\t| {\n\t\t\treadonly editor: Editor\n\t\t\treadonly source: 'native-event'\n\t\t\treadonly event: ClipboardEvent\n\t\t\treadonly clipboardData: DataTransfer | null\n\t\t\treadonly point: VecLike | undefined\n\t  }\n\t| {\n\t\t\treadonly editor: Editor\n\t\t\treadonly source: 'clipboard-read'\n\t\t\treadonly clipboardItems: readonly ClipboardItem[]\n\t\t\treadonly point: VecLike | undefined\n\t  }\n\n/**\n * Options for configuring tldraw. For defaults, see {@link defaultTldrawOptions}.\n *\n * @example\n * ```tsx\n * const options: Partial<TldrawOptions> = {\n *     maxPages: 3,\n *     maxShapesPerPage: 1000,\n * }\n *\n * function MyTldrawComponent() {\n *     return <Tldraw options={options} />\n * }\n * ```\n *\n * @public\n */\nexport interface TldrawOptions {\n\treadonly maxShapesPerPage: number\n\treadonly maxFilesAtOnce: number\n\treadonly maxPages: number\n\treadonly animationMediumMs: number\n\treadonly followChaseViewportSnap: number\n\treadonly doubleClickDurationMs: number\n\treadonly multiClickDurationMs: number\n\treadonly coarseDragDistanceSquared: number\n\treadonly dragDistanceSquared: number\n\treadonly uiDragDistanceSquared: number\n\treadonly uiCoarseDragDistanceSquared: number\n\treadonly defaultSvgPadding: number\n\treadonly cameraSlideFriction: number\n\treadonly gridSteps: readonly {\n\t\treadonly min: number\n\t\treadonly mid: number\n\t\treadonly step: number\n\t}[]\n\treadonly collaboratorInactiveTimeoutMs: number\n\treadonly collaboratorIdleTimeoutMs: number\n\treadonly collaboratorCheckIntervalMs: number\n\treadonly cameraMovingTimeoutMs: number\n\treadonly hitTestMargin: number\n\treadonly coarseHitTestMargin: number\n\treadonly edgeScrollDelay: number\n\treadonly edgeScrollEaseDuration: number\n\treadonly edgeScrollSpeed: number\n\treadonly edgeScrollDistance: number\n\treadonly coarsePointerWidth: number\n\treadonly coarseHandleRadius: number\n\treadonly handleRadius: number\n\treadonly longPressDurationMs: number\n\treadonly textShadowLod: number\n\treadonly adjacentShapeMargin: number\n\treadonly flattenImageBoundsExpand: number\n\treadonly flattenImageBoundsPadding: number\n\treadonly laserDelayMs: number\n\t/**\n\t * How long (in milliseconds) to fade all laser scribbles after the session ends.\n\t * The total points across all scribbles will be removed proportionally over this duration.\n\t * Defaults to 500ms (0.5 seconds).\n\t */\n\treadonly laserFadeoutMs: number\n\treadonly maxExportDelayMs: number\n\treadonly tooltipDelayMs: number\n\t/**\n\t * How long should previews created by {@link Editor.createTemporaryAssetPreview} last before\n\t * they expire? Defaults to 3 minutes.\n\t */\n\treadonly temporaryAssetPreviewLifetimeMs: number\n\treadonly actionShortcutsLocation: 'menu' | 'toolbar' | 'swap'\n\treadonly createTextOnCanvasDoubleClick: boolean\n\t/**\n\t * The react provider to use when exporting an image. This is useful if your shapes depend on\n\t * external context providers. By default, this is `React.Fragment`.\n\t */\n\treadonly exportProvider: ComponentType<{ children: React.ReactNode }>\n\t/**\n\t * By default, the toolbar items are accessible via number shortcuts according to their order. To disable this, set this option to false.\n\t */\n\treadonly enableToolbarKeyboardShortcuts: boolean\n\t/**\n\t * The maximum number of fonts that will be loaded while blocking the main rendering of the\n\t * canvas. If there are more than this number of fonts needed, we'll just show the canvas right\n\t * away and let the fonts load in in the background.\n\t */\n\treadonly maxFontsToLoadBeforeRender: number\n\t/**\n\t * If you have a CSP policy that blocks inline styles, you can use this prop to provide a\n\t * nonce to use in the editor's styles.\n\t */\n\treadonly nonce: string | undefined\n\t/**\n\t * Branding name of the app, currently only used for adding aria-label for the application.\n\t */\n\treadonly branding?: string\n\t/**\n\t * Whether to use debounced zoom level for certain rendering optimizations. When true,\n\t * `editor.getEfficientZoomLevel()` returns a cached zoom value while the camera is moving,\n\t * reducing re-renders. When false, it always returns the current zoom level.\n\t */\n\treadonly debouncedZoom: boolean\n\t/**\n\t * The number of shapes that must be on the page for the debounced zoom level to be used.\n\t * Defaults to 500 shapes.\n\t */\n\treadonly debouncedZoomThreshold: number\n\t/**\n\t * Whether to allow spacebar panning. When true, the spacebar will pan the camera when held down.\n\t * When false, the spacebar will not pan the camera.\n\t */\n\treadonly spacebarPanning: boolean\n\t/**\n\t * Whether to allow right-click + drag to pan the camera. When true, right-click + drag pans the\n\t * camera and a static right-click opens the context menu at the release position. When false,\n\t * right-click opens the context menu on press (no drag-to-pan).\n\t */\n\treadonly rightClickPanning: boolean\n\t/**\n\t * The default padding (in pixels) used when zooming to fit content in the viewport.\n\t * This affects methods like `zoomToFit()`, `zoomToSelection()`, and `zoomToBounds()`.\n\t * The actual padding used is the minimum of this value and 28% of the viewport width.\n\t * Defaults to 128 pixels.\n\t */\n\treadonly zoomToFitPadding: number\n\t/**\n\t * The distance (in screen pixels) at which shapes snap to guides and other shapes.\n\t */\n\treadonly snapThreshold: number\n\t/**\n\t * Whether locked shapes can be selected with a left click. When false (default), left-clicking\n\t * a locked shape is treated as a click on the canvas \u2014 only right-click selects it. When true,\n\t * locked shapes can be selected via left click and included in brush and scribble selections,\n\t * but the editor's lock guards still prevent moving, resizing, editing, or deleting them.\n\t */\n\treadonly selectLockedShapes: boolean\n\t/**\n\t * Options for the editor's camera. These are the initial camera options.\n\t * Use {@link Editor.setCameraOptions} to update camera options at runtime.\n\t */\n\treadonly camera: Partial<TLCameraOptions>\n\t/**\n\t * Options for the editor's text rendering. These include TipTap configuration and\n\t * font handling. These are the initial text options and cannot be changed at runtime.\n\t */\n\treadonly text: TLTextOptions\n\t/**\n\t * Options for syncing the editor's camera state with the URL. Set to `true` to enable\n\t * with default options, or pass an options object to customize behavior.\n\t *\n\t * @example\n\t * ```tsx\n\t * // Enable with defaults\n\t * <Tldraw options={{ deepLinks: true }} />\n\t *\n\t * // Enable with custom options\n\t * <Tldraw options={{ deepLinks: { param: 'd', debounceMs: 500 } }} />\n\t * ```\n\t */\n\treadonly deepLinks: true | TLDeepLinkOptions | undefined\n\t/**\n\t * Whether the quick-zoom brush preserves its screen-pixel size when the user\n\t * zooms the overview. When true, zooming in shrinks the target viewport (higher\n\t * return zoom); zooming out expands it. When false, the brush keeps the original\n\t * viewport's page dimensions regardless of overview zoom changes.\n\t */\n\treadonly quickZoomPreservesScreenBounds: boolean\n\t/**\n\t * Called before content is written to the clipboard during a copy or cut operation.\n\t * Receives the serialized content (shapes, bindings, assets) and can filter or transform\n\t * it before it reaches the clipboard.\n\t *\n\t * Return a modified `TLContent` object to change what is copied or cut. Return `false` to\n\t * cancel the clipboard write (for cut, the selected shapes are not removed). Return `void`\n\t * (or `undefined`) to pass through unchanged. You may return a `Promise` of those values if\n\t * the hook is async.\n\t *\n\t * @example\n\t * ```tsx\n\t * // Filter out \"locked\" shapes from copy\n\t * onBeforeCopyToClipboard({ content, operation }) {\n\t *     return {\n\t *         ...content,\n\t *         shapes: content.shapes.filter(s => !s.meta.locked),\n\t *         rootShapeIds: content.rootShapeIds.filter(id =>\n\t *             content.shapes.find(s => s.id === id && !s.meta.locked)\n\t *         ),\n\t *     }\n\t * }\n\t * ```\n\t */\n\tonBeforeCopyToClipboard?(\n\t\tinfo: { editor: Editor; content: TLContent } & TLClipboardWriteInfo\n\t): Awaitable<TLContent | false | void>\n\t/**\n\t * Called before pasted content is processed and shapes are created. Receives the parsed\n\t * external content from the clipboard and can filter, transform, or cancel it.\n\t *\n\t * Return `false` to cancel the paste. Return a modified content object to transform it.\n\t * Return `void` (or `undefined`) to pass through unchanged. You may return a `Promise` of\n\t * those values if the hook is async.\n\t *\n\t * This only fires for clipboard paste operations (keyboard shortcuts and menu actions),\n\t * not for file drops or programmatic `putExternalContent` calls.\n\t *\n\t * @example\n\t * ```tsx\n\t * // Block pasting of image files\n\t * onBeforePasteFromClipboard({ content }) {\n\t *     if (content.type === 'files') {\n\t *         const nonImages = content.files.filter(f => !f.type.startsWith('image/'))\n\t *         if (nonImages.length === 0) return false\n\t *         return { ...content, files: nonImages }\n\t *     }\n\t * }\n\t * ```\n\t */\n\tonBeforePasteFromClipboard?(info: {\n\t\teditor: Editor\n\t\tcontent: TLExternalContent<unknown>\n\t\tsource: 'native-event' | 'clipboard-read'\n\t\tpoint?: VecLike\n\t}): Awaitable<TLExternalContent<unknown> | false | void>\n\t/**\n\t * Called first for keyboard and menu paste, **before** tldraw handles or parses clipboard data\n\t * (and before {@link TldrawOptions.onBeforePasteFromClipboard}).\n\t *\n\t * Return `false` to cancel tldraw's default paste handling for this gesture (same convention as\n\t * {@link TldrawOptions.onBeforePasteFromClipboard}). Use this when you handle paste yourself from\n\t * raw clipboard data, or to block the gesture entirely. Return `void` (or `undefined`) to continue.\n\t */\n\tonClipboardPasteRaw?(info: TLClipboardPasteRawInfo): false | void\n\t/**\n\t * Called when content is dropped on the canvas. Provides the page position\n\t * where the drop occurred and the underlying drag event object.\n\t * Return true to prevent default drop handling (files, URLs, etc.)\n\t */\n\texperimental__onDropOnCanvas?(options: {\n\t\tpoint: VecLike\n\t\tevent: React.DragEvent<Element>\n\t}): boolean\n}\n\n/** @public */\nexport const defaultTldrawOptions = {\n\tmaxShapesPerPage: 4000,\n\tmaxFilesAtOnce: 100,\n\tmaxPages: 40,\n\tanimationMediumMs: 320,\n\tfollowChaseViewportSnap: 2,\n\tdoubleClickDurationMs: 450,\n\tmultiClickDurationMs: 200,\n\tcoarseDragDistanceSquared: 36, // 6 squared\n\tdragDistanceSquared: 16, // 4 squared\n\tuiDragDistanceSquared: 16, // 4 squared\n\t// it's really easy to accidentally drag from the toolbar on mobile, so we use a much larger\n\t// threshold than usual here to try and prevent accidental drags.\n\tuiCoarseDragDistanceSquared: 625, // 25 squared\n\tdefaultSvgPadding: 32,\n\tcameraSlideFriction: 0.09,\n\tgridSteps: [\n\t\t{ min: -1, mid: 0.15, step: 64 },\n\t\t{ min: 0.05, mid: 0.375, step: 16 },\n\t\t{ min: 0.15, mid: 1, step: 4 },\n\t\t{ min: 0.7, mid: 2.5, step: 1 },\n\t],\n\tcollaboratorInactiveTimeoutMs: 60000,\n\tcollaboratorIdleTimeoutMs: 3000,\n\tcollaboratorCheckIntervalMs: 1200,\n\tcameraMovingTimeoutMs: 64,\n\thitTestMargin: 3,\n\tcoarseHitTestMargin: 4,\n\tedgeScrollDelay: 200,\n\tedgeScrollEaseDuration: 200,\n\tedgeScrollSpeed: 25,\n\tedgeScrollDistance: 8,\n\tcoarsePointerWidth: 12,\n\tcoarseHandleRadius: 20,\n\thandleRadius: 12,\n\tlongPressDurationMs: 500,\n\ttextShadowLod: 0.35,\n\tadjacentShapeMargin: 10,\n\tflattenImageBoundsExpand: 64,\n\tflattenImageBoundsPadding: 16,\n\tlaserDelayMs: 1200,\n\tlaserFadeoutMs: 500,\n\tmaxExportDelayMs: 5000,\n\ttooltipDelayMs: 700,\n\ttemporaryAssetPreviewLifetimeMs: 180000,\n\tactionShortcutsLocation: 'swap',\n\tcreateTextOnCanvasDoubleClick: true,\n\texportProvider: Fragment,\n\tenableToolbarKeyboardShortcuts: true,\n\tmaxFontsToLoadBeforeRender: Infinity,\n\tnonce: undefined,\n\tdebouncedZoom: true,\n\tdebouncedZoomThreshold: 500,\n\tspacebarPanning: true,\n\trightClickPanning: true,\n\tzoomToFitPadding: 128,\n\tsnapThreshold: 8,\n\tselectLockedShapes: false,\n\tcamera: DEFAULT_CAMERA_OPTIONS,\n\ttext: {},\n\tdeepLinks: undefined,\n\tquickZoomPreservesScreenBounds: true,\n\tonBeforeCopyToClipboard: undefined,\n\tonBeforePasteFromClipboard: undefined,\n\tonClipboardPasteRaw: undefined,\n\texperimental__onDropOnCanvas: undefined,\n} as const satisfies TldrawOptions\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,mBAAwC;AACxC,uBAAuC;AA+RhC,MAAM,uBAAuB;AAAA,EACnC,kBAAkB;AAAA,EAClB,gBAAgB;AAAA,EAChB,UAAU;AAAA,EACV,mBAAmB;AAAA,EACnB,yBAAyB;AAAA,EACzB,uBAAuB;AAAA,EACvB,sBAAsB;AAAA,EACtB,2BAA2B;AAAA;AAAA,EAC3B,qBAAqB;AAAA;AAAA,EACrB,uBAAuB;AAAA;AAAA;AAAA;AAAA,EAGvB,6BAA6B;AAAA;AAAA,EAC7B,mBAAmB;AAAA,EACnB,qBAAqB;AAAA,EACrB,WAAW;AAAA,IACV,EAAE,KAAK,IAAI,KAAK,MAAM,MAAM,GAAG;AAAA,IAC/B,EAAE,KAAK,MAAM,KAAK,OAAO,MAAM,GAAG;AAAA,IAClC,EAAE,KAAK,MAAM,KAAK,GAAG,MAAM,EAAE;AAAA,IAC7B,EAAE,KAAK,KAAK,KAAK,KAAK,MAAM,EAAE;AAAA,EAC/B;AAAA,EACA,+BAA+B;AAAA,EAC/B,2BAA2B;AAAA,EAC3B,6BAA6B;AAAA,EAC7B,uBAAuB;AAAA,EACvB,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,iBAAiB;AAAA,EACjB,wBAAwB;AAAA,EACxB,iBAAiB;AAAA,EACjB,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,cAAc;AAAA,EACd,qBAAqB;AAAA,EACrB,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,0BAA0B;AAAA,EAC1B,2BAA2B;AAAA,EAC3B,cAAc;AAAA,EACd,gBAAgB;AAAA,EAChB,kBAAkB;AAAA,EAClB,gBAAgB;AAAA,EAChB,iCAAiC;AAAA,EACjC,yBAAyB;AAAA,EACzB,+BAA+B;AAAA,EAC/B,gBAAgB;AAAA,EAChB,gCAAgC;AAAA,EAChC,4BAA4B;AAAA,EAC5B,OAAO;AAAA,EACP,eAAe;AAAA,EACf,wBAAwB;AAAA,EACxB,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,oBAAoB;AAAA,EACpB,QAAQ;AAAA,EACR,MAAM,CAAC;AAAA,EACP,WAAW;AAAA,EACX,gCAAgC;AAAA,EAChC,yBAAyB;AAAA,EACzB,4BAA4B;AAAA,EAC5B,qBAAqB;AAAA,EACrB,8BAA8B;AAC/B;",
   "names": []
 }

package/dist-cjs/lib/utils/collaborators.js

@@ -0,0 +1,27 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var collaborators_exports = {};
+__export(collaborators_exports, {
+  isCursorInViewport: () => isCursorInViewport
+});
+module.exports = __toCommonJS(collaborators_exports);
+function isCursorInViewport(cursor, viewport, zoom) {
+  return !(cursor.x < viewport.minX - 12 / zoom || cursor.y < viewport.minY - 16 / zoom || cursor.x > viewport.maxX - 12 / zoom || cursor.y > viewport.maxY - 16 / zoom);
+}
+//# sourceMappingURL=collaborators.js.map

package/dist-cjs/lib/utils/collaborators.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/utils/collaborators.ts"],
+  "sourcesContent": ["import { VecLike } from '../primitives/Vec'\n\n/**\n * Whether a collaborator's cursor (page coords) is inside the viewport, with a small margin for the\n * cursor glyph so it isn't culled the instant its hotspot crosses the edge.\n *\n * Single source of truth for the cursor/hint split: the DOM cursor layer renders a collaborator\n * when this is true, and `CollaboratorHintOverlayUtil` draws the viewport-edge hint when it's\n * false. Sharing the predicate keeps those two exhaustive and mutually exclusive \u2014 a margin change\n * can't open a dead zone (neither renders) or a double-render (both).\n *\n * @public\n */\nexport function isCursorInViewport(\n\tcursor: VecLike,\n\tviewport: { minX: number; minY: number; maxX: number; maxY: number },\n\tzoom: number\n): boolean {\n\treturn !(\n\t\tcursor.x < viewport.minX - 12 / zoom ||\n\t\tcursor.y < viewport.minY - 16 / zoom ||\n\t\tcursor.x > viewport.maxX - 12 / zoom ||\n\t\tcursor.y > viewport.maxY - 16 / zoom\n\t)\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAaO,SAAS,mBACf,QACA,UACA,MACU;AACV,SAAO,EACN,OAAO,IAAI,SAAS,OAAO,KAAK,QAChC,OAAO,IAAI,SAAS,OAAO,KAAK,QAChC,OAAO,IAAI,SAAS,OAAO,KAAK,QAChC,OAAO,IAAI,SAAS,OAAO,KAAK;AAElC;",
+  "names": []
+}

package/dist-cjs/lib/utils/getHtmlLayerTransform.js

@@ -0,0 +1,33 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var getHtmlLayerTransform_exports = {};
+__export(getHtmlLayerTransform_exports, {
+  getHtmlLayerTransform: () => getHtmlLayerTransform
+});
+module.exports = __toCommonJS(getHtmlLayerTransform_exports);
+var import_utils = require("@tldraw/utils");
+var import_utils2 = require("../primitives/utils");
+function getHtmlLayerTransform(editor) {
+  const { x, y, z } = editor.getCamera();
+  const offset = z >= 1 ? (0, import_utils.modulate)(z, [1, 8], [0.125, 0.5], true) : (0, import_utils.modulate)(z, [0.1, 1], [-2, 0.125], true);
+  return `scale(${(0, import_utils2.toDomPrecision)(z)}) translate(${(0, import_utils2.toDomPrecision)(x + offset)}px,${(0, import_utils2.toDomPrecision)(
+    y + offset
+  )}px)`;
+}
+//# sourceMappingURL=getHtmlLayerTransform.js.map

package/dist-cjs/lib/utils/getHtmlLayerTransform.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/utils/getHtmlLayerTransform.ts"],
+  "sourcesContent": ["import { modulate } from '@tldraw/utils'\nimport type { Editor } from '../editor/Editor'\nimport { toDomPrecision } from '../primitives/utils'\n\n/**\n * The CSS `transform` that puts a 1px-sized html layer into page space under the current camera.\n * Shared by every camera-tracked DOM layer (the canvas's shape layer, the collaborator cursor\n * layer) so they line up exactly and can't drift apart.\n *\n * The offset compensates for the layer's 1px width/height when zoomed, so it registers precisely\n * with the other layers.\n *\n * @internal\n */\nexport function getHtmlLayerTransform(editor: Editor): string {\n\tconst { x, y, z } = editor.getCamera()\n\tconst offset =\n\t\tz >= 1 ? modulate(z, [1, 8], [0.125, 0.5], true) : modulate(z, [0.1, 1], [-2, 0.125], true)\n\treturn `scale(${toDomPrecision(z)}) translate(${toDomPrecision(x + offset)}px,${toDomPrecision(\n\t\ty + offset\n\t)}px)`\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAyB;AAEzB,IAAAA,gBAA+B;AAYxB,SAAS,sBAAsB,QAAwB;AAC7D,QAAM,EAAE,GAAG,GAAG,EAAE,IAAI,OAAO,UAAU;AACrC,QAAM,SACL,KAAK,QAAI,uBAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,IAAI,QAAI,uBAAS,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI;AAC3F,SAAO,aAAS,8BAAe,CAAC,CAAC,mBAAe,8BAAe,IAAI,MAAM,CAAC,UAAM;AAAA,IAC/E,IAAI;AAAA,EACL,CAAC;AACF;",
+  "names": ["import_utils"]
+}

package/dist-cjs/version.js

@@ -22,10 +22,10 @@ __export(version_exports, {
   version: () => version
 });
 module.exports = __toCommonJS(version_exports);
-const version = "5.3.0-next.a6e6f66f8517";
+const version = "5.3.0-next.aefb8773a7eb";
 const publishDates = {
   major: "2026-05-06T16:28:18.473Z",
-  minor: "2026-07-01T09:35:37.719Z",
-  patch: "2026-07-01T09:35:37.719Z"
+  minor: "2026-08-05T09:54:21.039Z",
+  patch: "2026-08-05T09:54:21.039Z"
 };
 //# sourceMappingURL=version.js.map

package/dist-cjs/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/version.ts"],
-  "sourcesContent": ["// This file is automatically generated by internal/scripts/refresh-assets.ts.\n// Do not edit manually. Or do, I'm a comment, not a cop.\n\nexport const version = '5.3.0-next.a6e6f66f8517'\nexport const publishDates = {\n\tmajor: '2026-05-06T16:28:18.473Z',\n\tminor: '2026-07-01T09:35:37.719Z',\n\tpatch: '2026-07-01T09:35:37.719Z',\n}\n"],
+  "sourcesContent": ["// This file is automatically generated by internal/scripts/refresh-assets.ts.\n// Do not edit manually. Or do, I'm a comment, not a cop.\n\nexport const version = '5.3.0-next.aefb8773a7eb'\nexport const publishDates = {\n\tmajor: '2026-05-06T16:28:18.473Z',\n\tminor: '2026-08-05T09:54:21.039Z',\n\tpatch: '2026-08-05T09:54:21.039Z',\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGO,MAAM,UAAU;AAChB,MAAM,eAAe;AAAA,EAC3B,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AACR;",
   "names": []
 }

package/dist-esm/index.d.mts

@@ -19,12 +19,14 @@ import { JsonObject } from '@tldraw/utils';
 import { JSX } from 'react/jsx-runtime';
 import { LegacyMigrations } from '@tldraw/store';
 import { MigrationSequence } from '@tldraw/store';
+import { NamedExoticComponent } from 'react';
 import { Node as Node_2 } from '@tiptap/pm/model';
 import { PerformanceTracker } from '@tldraw/utils';
 import * as React_2 from 'react';
 import { default as React_3 } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
 import { RecordProps } from '@tldraw/tlschema';
 import { RecordsDiff } from '@tldraw/store';
 import { RefAttributes } from 'react';
@@ -219,7 +221,7 @@ export declare abstract class BaseBoxShapeUtil<Shape extends TLBaseBoxShape> ext
 }
 
 /**
- * A base class for frame-like shapes — containers that clip their children,
+ * A base class for frame-like shapes — containers that clip their children except arrows,
  * require full-brush selection, block erasure from inside, and support
  * drag-and-drop reparenting.
  *
@@ -231,6 +233,7 @@ export declare abstract class BaseBoxShapeUtil<Shape extends TLBaseBoxShape> ext
  * - `canReceiveNewChildrenOfType()` returns `true` unless the container is locked
  * - `canRemoveChildrenOfType()` returns `true` unless the container is locked
  * - `getClipPath()` returns the shape geometry's vertices
+ * - `shouldClipChild()` clips all children except arrows
  * - `onDragShapesIn()` reparents shapes into the frame (with index restoration)
  * - `onDragShapesOut()` reparents shapes back to the page
  *
@@ -266,6 +269,7 @@ export declare abstract class BaseFrameLikeShapeUtil<Shape extends TLBaseBoxShap
     canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
     canRemoveChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
     getClipPath(shape: Shape): undefined | Vec[];
+    shouldClipChild(child: TLShape): boolean;
     onDragShapesIn(shape: Shape, draggingShapes: TLShape[], { initialParentIds, initialIndices }: TLDragShapesInInfo): void;
     onDragShapesOut(shape: Shape, draggingShapes: TLShape[], info: TLDragShapesOutInfo): void;
 }
@@ -980,6 +984,15 @@ export declare function DefaultBackground(): JSX.Element;
 /** @public @react */
 export declare function DefaultCanvas({ className }: TLCanvasComponentProps): JSX.Element;
 
+/**
+ * The default collaborator cursor: the arrow glyph plus a name tag or chat bubble. The arrow is a
+ * `<use>` of a shared `<defs>` symbol that `LiveCollaborators` renders, so a `DefaultCursor`
+ * used outside that layer draws no arrow.
+ *
+ * @public @react
+ */
+export declare const DefaultCursor: NamedExoticComponent<TLCursorProps>;
+
 /** @public @react */
 export declare const DefaultErrorFallback: TLErrorFallbackComponent;
 
@@ -1005,6 +1018,7 @@ export declare const defaultTldrawOptions: {
     readonly cameraSlideFriction: 0.09;
     readonly coarseDragDistanceSquared: 36;
     readonly coarseHandleRadius: 20;
+    readonly coarseHitTestMargin: 4;
     readonly coarsePointerWidth: 12;
     readonly collaboratorCheckIntervalMs: 1200;
     readonly collaboratorIdleTimeoutMs: 3000;
@@ -1044,7 +1058,7 @@ export declare const defaultTldrawOptions: {
         readonly step: 1;
     }];
     readonly handleRadius: 12;
-    readonly hitTestMargin: 8;
+    readonly hitTestMargin: 3;
     readonly laserDelayMs: 1200;
     readonly laserFadeoutMs: 500;
     readonly longPressDurationMs: 500;
@@ -1218,6 +1232,19 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     isDisposed: boolean;
+    private readonly _isMounted;
+    /**
+     * Whether the editor is currently mounted. This is `true` while the editor's component is
+     * mounted in the DOM (after the `mount` event) and `false` before mount and after `unmount`.
+     *
+     * Unlike disposal, mounting is not terminal: the editor's component can unmount and remount
+     * (for example when the canvas is replaced by an error fallback and restored) without the
+     * editor itself being disposed. To react to the transitions, listen to the editor's `mount`
+     * and `unmount` events.
+     *
+     * @public
+     */
+    getIsMounted(): boolean;
     /* Excluded from this release type: _tickManager */
     /**
      * A manager for the editor's input state.
@@ -3086,6 +3113,17 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     getCurrentPageBounds(): Box | undefined;
+    /**
+     * Get the hit-test margin in page space—the distance in page units within which a pointer is
+     * considered to be touching a shape. This resolves to {@link TldrawOptions.hitTestMargin} (or
+     * {@link TldrawOptions.coarseHitTestMargin} when using a coarse pointer) divided by the current
+     * zoom level, so it stays a constant distance in screen space.
+     *
+     * @returns The hit-test margin in page space.
+     *
+     * @public
+     */
+    getHitTestMargin(): number;
     /**
      * Get the top-most selected shape at the given point, ignoring groups.
      *
@@ -4559,6 +4597,52 @@ export declare abstract class EditorManager {
     /* Excluded from this release type: dispose */
 }
 
+/**
+ * Renders its children into the end of the editor's container, escaping the canvas layer.
+ *
+ * Use this for anything anchored to canvas coordinates that also has to draw over the UI — a
+ * popover on a shape, a comment thread, an annotation panel. The `OnTheCanvas` and
+ * `InFrontOfTheCanvas` slots are fixed layers, each its own stacking context, so content mounted
+ * there can't paint above whatever outranks its layer whatever z-index it asks for. Mount in
+ * whichever slot suits your data flow, wrap the part that needs its own layer in this, and give
+ * that part a z-index.
+ *
+ * This package's own layers stop at 250 (`--tl-layer-canvas-in-front`); above that belongs to
+ * whatever renders the UI. In `tldraw` that's `--tl-layer-panels` (300) and `--tl-layer-menus`
+ * (400), defined by `tldraw`'s stylesheet rather than this one.
+ *
+ * Positioning still resolves against the editor's container, so a `position: absolute` child uses
+ * ordinary container coordinates.
+ *
+ * Prefer this over `createPortal(children, useContainer())`, which picks its DOM position from the
+ * commit that mounts it — landing the node ahead of the UI and of the "skip to main content" link
+ * that only works while nothing precedes it. This host is a real element placed last, so ordering
+ * is fixed rather than dependent on mount timing.
+ *
+ * @example
+ * ```tsx
+ * // 400 clears tldraw's menus layer; the bare editor's own layers stop at 250.
+ * function ShapeAnnotation({ point }: { point: VecLike }) {
+ * 	return (
+ * 		<EditorPortal>
+ * 			<div style={{ position: 'absolute', left: point.x, top: point.y, zIndex: 400 }}>
+ * 				Above the UI
+ * 			</div>
+ * 		</EditorPortal>
+ * 	)
+ * }
+ * ```
+ *
+ * @public
+ * @react
+ */
+export declare function EditorPortal({ children }: EditorPortalProps): ReactPortal | null;
+
+/** @public */
+export declare interface EditorPortalProps {
+    children: ReactNode;
+}
+
 /** @public @react */
 export declare function EditorProvider({ editor, children }: EditorProviderProps): JSX.Element;
 
@@ -5422,6 +5506,24 @@ export declare function intersectPolygonPolygon(polygonA: VecLike[], polygonB: V
 
 /* Excluded from this release type: isAccelKey */
 
+/**
+ * Whether a collaborator's cursor (page coords) is inside the viewport, with a small margin for the
+ * cursor glyph so it isn't culled the instant its hotspot crosses the edge.
+ *
+ * Single source of truth for the cursor/hint split: the DOM cursor layer renders a collaborator
+ * when this is true, and `CollaboratorHintOverlayUtil` draws the viewport-edge hint when it's
+ * false. Sharing the predicate keeps those two exhaustive and mutually exclusive — a margin change
+ * can't open a dead zone (neither renders) or a double-render (both).
+ *
+ * @public
+ */
+export declare function isCursorInViewport(cursor: VecLike, viewport: {
+    maxX: number;
+    maxY: number;
+    minX: number;
+    minY: number;
+}, zoom: number): boolean;
+
 /**
  * Check if a float is safe to use. ie: Not too big or small.
  * @public
@@ -5443,6 +5545,8 @@ export declare function kickoutOccludedShapes(editor: Editor, shapeIds: TLShapeI
 
 /* Excluded from this release type: LICENSE_TIMEOUT */
 
+/* Excluded from this release type: LicenseFeatureName */
+
 /* Excluded from this release type: LicenseFromKeyResult */
 
 /* Excluded from this release type: LicenseInfo */
@@ -6766,6 +6870,29 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      * @public
      */
     onBeforeCreate?(next: Shape): Shape | void;
+    /**
+     * A callback called when a shape is reproduced from an existing shape, either by duplicating
+     * ({@link Editor.duplicateShapes}) or by pasting/putting content onto the page
+     * ({@link Editor.putContentOntoCurrentPage}). This provides a last chance to modify the copy
+     * before it's created — for example, to re-stamp attribution so the copy is credited to the
+     * current user rather than the original author. It is not called when content is put with
+     * `preserveIds` (e.g. {@link Editor.moveShapesToPage}), since the shape keeps its identity
+     * and no copy is made.
+     *
+     * @example
+     *
+     * ```ts
+     * onBeforeDuplicate = (source, duplicate) => {
+     * 	return { ...duplicate, props: { ...duplicate.props, editedBy: this.editor.getAttributionUserId() } }
+     * }
+     * ```
+     *
+     * @param source - The shape being copied from.
+     * @param duplicate - The new copy (with its own id), before it's created.
+     * @returns The next shape or void.
+     * @public
+     */
+    onBeforeDuplicate?(source: Shape, duplicate: Shape): Shape | void;
     /**
      * A callback called just before a shape is updated. This method provides a last chance to modify
      * the updated shape.
@@ -7498,6 +7625,11 @@ export declare interface TLBaseEventInfo {
 
 /** @public */
 export declare interface TLBaseExternalContent {
+    /**
+     * The other content sources found on the clipboard alongside this content. For example, when
+     * pasting an image copied together with HTML and plain text, the `files` content will have
+     * text sources for the HTML and plain text parts.
+     */
     sources?: TLExternalContentSource[];
     point?: VecLike;
 }
@@ -7744,6 +7876,17 @@ export declare interface TLCurrentUser {
     readonly setUserPreferences: (userPreferences: TLUserPreferences) => void;
 }
 
+/** @public */
+export declare interface TLCursorProps {
+    userId: string;
+    className?: string;
+    point: null | VecModel;
+    zoom: number;
+    color?: string;
+    name: null | string;
+    chatMessage: string;
+}
+
 /** @public */
 export declare type TLDeepLink = {
     bounds: BoxModel;
@@ -8032,6 +8175,7 @@ export declare interface TldrawOptions {
     readonly collaboratorCheckIntervalMs: number;
     readonly cameraMovingTimeoutMs: number;
     readonly hitTestMargin: number;
+    readonly coarseHitTestMargin: number;
     readonly edgeScrollDelay: number;
     readonly edgeScrollEaseDuration: number;
     readonly edgeScrollSpeed: number;
@@ -8245,6 +8389,7 @@ export declare interface TLDropShapesOverInfo {
 export declare interface TLEditorComponents {
     Background?: ComponentType | null;
     Canvas?: ComponentType<TLCanvasComponentProps> | null;
+    CollaboratorCursor?: ComponentType<TLCursorProps> | null;
     Grid?: ComponentType<TLGridProps> | null;
     InFrontOfTheCanvas?: ComponentType | null;
     LoadingScreen?: ComponentType | null;
@@ -8462,6 +8607,7 @@ export declare type TLEventInfo = TLCancelEventInfo | TLClickEventInfo | TLCompl
 /** @public */
 export declare interface TLEventMap {
     mount: [];
+    unmount: [];
     'max-shapes': [{
         count: number;
         name: string;
@@ -9699,6 +9845,16 @@ export declare function useEditor(): Editor;
 /** @public */
 export declare function useEditorComponents(): Required<TLEditorComponents>;
 
+/**
+ * The DOM node that {@link EditorPortal} renders into: an empty `display: contents` element the
+ * editor renders last among its container's children, after the canvas and after the UI.
+ *
+ * Null until the container has mounted, so prefer {@link EditorPortal}, which handles that for you.
+ *
+ * @public
+ */
+export declare function useEditorPortalHost(): HTMLElement | null;
+
 /* Excluded from this release type: useEvent */
 
 /** @public */
@@ -9710,6 +9866,10 @@ export declare function useIsCropping(shapeId: TLShapeId): boolean;
 /** @public */
 export declare function useIsEditing(shapeId: TLShapeId): boolean;
 
+/* Excluded from this release type: useLicenseContext */
+
+/* Excluded from this release type: useLicenseFeatureFlag */
+
 /* Excluded from this release type: useLocalStore */
 
 /** @public */
@@ -9717,9 +9877,6 @@ export declare function useMaybeEditor(): Editor | null;
 
 /* Excluded from this release type: useOnMount */
 
-/** @public */
-export declare function usePassThroughMouseOverEvents(ref: RefObject<HTMLElement | null>): void;
-
 /** @public */
 export declare function usePassThroughWheelEvents(ref: RefObject<HTMLElement | null>): void;
 
@@ -9846,6 +10003,13 @@ export declare function useTLSchemaFromUtils(opts: TLStoreSchemaOptions): StoreS
 /** @public */
 export declare function useTLStore(opts: TLStoreOptions): TLStore;
 
+/**
+ * Position an element by writing its `transform` directly, outside React's render output — the
+ * cheap path for elements that move at pointer/presence frequency.
+ * @public
+ */
+export declare function useTransform(ref: React.RefObject<HTMLElement | null | SVGElement>, x?: number, y?: number, scale?: number, rotate?: number, additionalOffset?: VecLike): void;
+
 /**
  * React's useId hook returns a unique id for the component. However, it uses a colon in the id,
  * which is not valid for CSS selectors. This hook replaces the colon with an underscore.

package/dist-esm/index.mjs

@@ -9,6 +9,9 @@ import { DefaultBackground } from "./lib/components/default-components/DefaultBa
 import {
   DefaultCanvas
 } from "./lib/components/default-components/DefaultCanvas.mjs";
+import {
+  DefaultCursor
+} from "./lib/components/default-components/DefaultCursor.mjs";
 import {
   DefaultErrorFallback
 } from "./lib/components/default-components/DefaultErrorFallback.mjs";
@@ -18,6 +21,10 @@ import {
 } from "./lib/components/default-components/DefaultShapeWrapper.mjs";
 import { DefaultSpinner } from "./lib/components/default-components/DefaultSpinner.mjs";
 import { DefaultSvgDefs } from "./lib/components/default-components/DefaultSvgDefs.mjs";
+import {
+  EditorPortal,
+  useEditorPortalHost
+} from "./lib/components/EditorPortal.mjs";
 import {
   ErrorBoundary,
   OptionalErrorBoundary
@@ -144,7 +151,6 @@ import { useShallowArrayIdentity, useShallowObjectIdentity } from "./lib/hooks/u
 import { useIsCropping } from "./lib/hooks/useIsCropping.mjs";
 import { useIsEditing } from "./lib/hooks/useIsEditing.mjs";
 import { useLocalStore } from "./lib/hooks/useLocalStore.mjs";
-import { usePassThroughMouseOverEvents } from "./lib/hooks/usePassThroughMouseOverEvents.mjs";
 import { usePassThroughWheelEvents } from "./lib/hooks/usePassThroughWheelEvents.mjs";
 import { usePeerIds } from "./lib/hooks/usePeerIds.mjs";
 import { usePresence } from "./lib/hooks/usePresence.mjs";
@@ -155,12 +161,15 @@ import {
   useSharedSafeId,
   useUniqueSafeId
 } from "./lib/hooks/useSafeId.mjs";
+import { useTransform } from "./lib/hooks/useTransform.mjs";
+import { isCursorInViewport } from "./lib/utils/collaborators.mjs";
 import { useTLSchemaFromUtils, useTLStore } from "./lib/hooks/useTLStore.mjs";
 import { useViewportHeight } from "./lib/hooks/useViewportHeight.mjs";
 import {
   LicenseManager
 } from "./lib/license/LicenseManager.mjs";
-import { LICENSE_TIMEOUT } from "./lib/license/LicenseProvider.mjs";
+import { LICENSE_TIMEOUT, useLicenseContext } from "./lib/license/LicenseProvider.mjs";
+import { useLicenseFeatureFlag } from "./lib/license/useLicenseManagerState.mjs";
 import {
   defaultTldrawOptions
 } from "./lib/options.mjs";
@@ -296,7 +305,7 @@ import { LocalIndexedDb, Table } from "./lib/utils/sync/LocalIndexedDb.mjs";
 import { uniq } from "./lib/utils/uniq.mjs";
 registerTldrawLibraryVersion(
   "@tldraw/editor",
-  "5.3.0-next.a6e6f66f8517",
+  "5.3.0-next.aefb8773a7eb",
   "esm"
 );
 import { getColorValue } from "./lib/editor/managers/ThemeManager/defaultThemes.mjs";
@@ -320,6 +329,7 @@ export {
   DEFAULT_THEME,
   DefaultBackground,
   DefaultCanvas,
+  DefaultCursor,
   DefaultErrorFallback,
   DefaultGrid,
   DefaultShapeWrapper,
@@ -333,6 +343,7 @@ export {
   EditorAtom,
   EditorContext,
   EditorManager,
+  EditorPortal,
   EditorProvider,
   Ellipse2d,
   ErrorBoundary,
@@ -453,6 +464,7 @@ export {
   intersectPolygonBounds,
   intersectPolygonPolygon,
   isAccelKey,
+  isCursorInViewport,
   isSafeFloat,
   kickoutOccludedShapes,
   linesIntersect,
@@ -503,14 +515,16 @@ export {
   useDelaySvgExport,
   useEditor,
   useEditorComponents,
+  useEditorPortalHost,
   useEvent,
   useGlobalMenuIsOpen,
   useIsCropping,
   useIsEditing,
+  useLicenseContext,
+  useLicenseFeatureFlag,
   useLocalStore,
   useMaybeEditor,
   useOnMount,
-  usePassThroughMouseOverEvents,
   usePassThroughWheelEvents,
   usePeerIds,
   usePresence,
@@ -523,6 +537,7 @@ export {
   useTLSchemaFromUtils,
   useTLStore,
   useTldrawCurrentUser,
+  useTransform,
   useUniqueSafeId,
   useViewportHeight,
   userTypeValidator