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

package/dist-esm/lib/utils/collaborators.mjs

@@ -0,0 +1,7 @@
+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);
+}
+export {
+  isCursorInViewport
+};
+//# sourceMappingURL=collaborators.mjs.map

package/dist-esm/lib/utils/collaborators.mjs.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": "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-esm/lib/utils/getHtmlLayerTransform.mjs

@@ -0,0 +1,13 @@
+import { modulate } from "@tldraw/utils";
+import { toDomPrecision } from "../primitives/utils.mjs";
+function getHtmlLayerTransform(editor) {
+  const { x, y, z } = editor.getCamera();
+  const offset = z >= 1 ? modulate(z, [1, 8], [0.125, 0.5], true) : modulate(z, [0.1, 1], [-2, 0.125], true);
+  return `scale(${toDomPrecision(z)}) translate(${toDomPrecision(x + offset)}px,${toDomPrecision(
+    y + offset
+  )}px)`;
+}
+export {
+  getHtmlLayerTransform
+};
+//# sourceMappingURL=getHtmlLayerTransform.mjs.map

package/dist-esm/lib/utils/getHtmlLayerTransform.mjs.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,SAAS,gBAAgB;AAEzB,SAAS,sBAAsB;AAYxB,SAAS,sBAAsB,QAAwB;AAC7D,QAAM,EAAE,GAAG,GAAG,EAAE,IAAI,OAAO,UAAU;AACrC,QAAM,SACL,KAAK,IAAI,SAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,IAAI,IAAI,SAAS,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI;AAC3F,SAAO,SAAS,eAAe,CAAC,CAAC,eAAe,eAAe,IAAI,MAAM,CAAC,MAAM;AAAA,IAC/E,IAAI;AAAA,EACL,CAAC;AACF;",
+  "names": []
+}

package/dist-esm/version.mjs

@@ -1,8 +1,8 @@
-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"
 };
 export {
   publishDates,

package/dist-esm/version.mjs.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": "AAGO,MAAM,UAAU;AAChB,MAAM,eAAe;AAAA,EAC3B,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AACR;",
   "names": []
 }

package/editor.css

@@ -29,15 +29,20 @@
 	 * background, grid, shapes, overlays, and blocker are all children of .tl-canvas,
 	 * so their z-indices are relative to the canvas, not the container.
 	 *
-	 * watermark and canvas-in-front are siblings of .tl-canvas (outside it),
-	 * so they compete with the UI layer (.tlui-layout at z-index 300).
+	 * collaborators, watermark, and canvas-in-front are siblings of .tl-canvas
+	 * (outside it), so they compete with the UI layer (.tlui-layout at z-index 300).
 	 * canvas-in-front must be below the UI layer (300) to sit between
-	 * the canvas and the UI.
+	 * the canvas and the UI; collaborator cursors sit above canvas content
+	 * (and layers that anchor to it, like comment pins) but below the
+	 * in-front content and the UI panels. The watermark (a licensing element)
+	 * sits above that content so it can't be occluded, but still below the
+	 * in-front content and the UI.
 	 */
 	--tl-layer-canvas-hidden: -999999;
 	--tl-layer-canvas-background: 100;
 	--tl-layer-canvas-grid: 150;
-	--tl-layer-watermark: 200;
+	--tl-layer-collaborators: 245;
+	--tl-layer-watermark: 248;
 	--tl-layer-canvas-in-front: 250;
 	--tl-layer-canvas-shapes: 300;
 	--tl-layer-canvas-overlays: 500;
@@ -86,6 +91,10 @@
 		url("data:image/svg+xml,<svg height='32' width='32' viewBox='0 0 32 32' xmlns='http://www.w3.org/2000/svg' style='color: black;'><defs><filter id='shadow' y='-40%' x='-40%' width='180px' height='180%' color-interpolation-filters='sRGB'><feDropShadow dx='1' dy='1' stdDeviation='1.2' flood-opacity='.5'/></filter></defs><g fill='none' transform='rotate(0 16 16)' filter='url(%23shadow)'><path d='m25 16h-6.01v-6h-2.98v6h-6.01v3h6.01v6h2.98v-6h6.01z' fill='white'/><path d='m23.9902 17.0103h-6v-6.01h-.98v6.01h-6v.98h6v6.01h.98v-6.01h6z' fill='%23231f1f'/></g></svg>")
 			16 16,
 		crosshair;
+	--tl-cursor-comment:
+		url("data:image/svg+xml,<svg height='32' width='32' viewBox='0 0 32 32' xmlns='http://www.w3.org/2000/svg'><defs><filter id='shadow' y='-40%' x='-40%' width='180px' height='180%' color-interpolation-filters='sRGB'><feDropShadow dx='1' dy='1' stdDeviation='1.2' flood-opacity='.5'/></filter></defs><g filter='url(%23shadow)'><path d='M5 19.5 L5 11 A8 8 0 0 1 13 3 A8 8 0 0 1 21 11 A8 8 0 0 1 13 19 Z' fill='white' stroke='black' stroke-width='1' stroke-linejoin='round'/></g></svg>")
+			5 19,
+		crosshair;
 	--tl-cursor-move:
 		url("data:image/svg+xml,<svg height='32' width='32' viewBox='0 0 32 32' xmlns='http://www.w3.org/2000/svg' style='color: black;'><defs><filter id='shadow' y='-40%' x='-40%' width='180px' height='180%' color-interpolation-filters='sRGB'><feDropShadow dx='1' dy='1' stdDeviation='1.2' flood-opacity='.5'/></filter></defs><g fill='none' transform='rotate(0 16 16)' filter='url(%23shadow)'><path d='m19 14h1v1h-1zm1 6h-1v-1h1zm-5-5h-1v-1h1zm0 5h-1v-1h1zm2-10.987-7.985 7.988 5.222 5.221 2.763 2.763 7.984-7.985z' fill='white'/><g fill='black'><path d='m23.5664 16.9971-2.557-2.809v1.829h-4.009-4.001v-1.829l-2.571 2.809 2.572 2.808-.001-1.808h4.001 4.009l-.001 1.808z'/><path d='m17.9873 17h.013v-4.001l1.807.001-2.807-2.571-2.809 2.57h1.809v4.001h.008v4.002l-1.828-.001 2.807 2.577 2.805-2.576h-1.805z'/></g></g></svg>")
 			16 16,
@@ -286,6 +295,12 @@
 	outline: 1px solid var(--tl-color-low);
 }
 
+/* The host for <EditorPortal>, last among the container's children. It's a position in the DOM
+   rather than a box: `display: contents` keeps what it holds positioned against the container. */
+.tl-portal-host {
+	display: contents;
+}
+
 input,
 *[contenteditable],
 *[contenteditable] * {
@@ -372,6 +387,30 @@ input,
 	contain: layout style size;
 }
 
+/* The collaborator cursor layer: a sibling of .tl-canvas, above all canvas content, below the
+   in-front layer (250) and the UI panels (300). Display-only — pointer events pass through. */
+.tl-collaborators {
+	position: absolute;
+	inset: 0px;
+	z-index: var(--tl-layer-collaborators);
+	pointer-events: none;
+	overflow: clip;
+	contain: layout style size;
+}
+
+.tl-collaborators__item {
+	position: absolute;
+	top: 0px;
+	left: 0px;
+	overflow: visible;
+	pointer-events: none;
+	transform-origin: top left;
+}
+
+.tl-cursor {
+	overflow: visible;
+}
+
 /* --------------- Overlay Stack --------------- */
 
 /* -------------- Selection foreground -------------- */
@@ -785,6 +824,16 @@ input,
 .tl-rich-text h6 {
 	margin-top: 5px;
 	margin-bottom: 10px;
+	/**
+	 * Headings render at a larger font-size than the body text (via the browser's
+	 * default h1–h6 sizing), so they can't inherit the container's resolved
+	 * whole-pixel line-height — that value is derived from the base font size and
+	 * would cram the taller lines together. Instead, scale line-height with each
+	 * heading's own font-size using tldraw's unitless line-height multiplier, which
+	 * the rich-text render/measure paths expose here. The 1.35 fallback mirrors the
+	 * default theme line-height (see defaultThemes.ts).
+	 */
+	line-height: var(--tl-rich-text-heading-line-height, 1.35);
 }
 
 .tl-rich-text a {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/editor",
   "description": "tldraw infinite canvas SDK (editor).",
-  "version": "5.3.0-next.a6e6f66f8517",
+  "version": "5.3.0-next.aefb8773a7eb",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -49,12 +49,12 @@
     "@tiptap/core": "^3.12.1",
     "@tiptap/pm": "^3.12.1",
     "@tiptap/react": "^3.12.1",
-    "@tldraw/state": "5.3.0-next.a6e6f66f8517",
-    "@tldraw/state-react": "5.3.0-next.a6e6f66f8517",
-    "@tldraw/store": "5.3.0-next.a6e6f66f8517",
-    "@tldraw/tlschema": "5.3.0-next.a6e6f66f8517",
-    "@tldraw/utils": "5.3.0-next.a6e6f66f8517",
-    "@tldraw/validate": "5.3.0-next.a6e6f66f8517",
+    "@tldraw/state": "5.3.0-next.aefb8773a7eb",
+    "@tldraw/state-react": "5.3.0-next.aefb8773a7eb",
+    "@tldraw/store": "5.3.0-next.aefb8773a7eb",
+    "@tldraw/tlschema": "5.3.0-next.aefb8773a7eb",
+    "@tldraw/utils": "5.3.0-next.aefb8773a7eb",
+    "@tldraw/validate": "5.3.0-next.aefb8773a7eb",
     "classnames": "^2.5.1",
     "eventemitter3": "^4.0.7",
     "idb": "^7.1.1",

package/src/index.ts

@@ -18,6 +18,10 @@ export {
 	DefaultCanvas,
 	type TLCanvasComponentProps,
 } from './lib/components/default-components/DefaultCanvas'
+export {
+	DefaultCursor,
+	type TLCursorProps,
+} from './lib/components/default-components/DefaultCursor'
 export {
 	DefaultErrorFallback,
 	type TLErrorFallbackComponent,
@@ -30,6 +34,11 @@ export {
 } from './lib/components/default-components/DefaultShapeWrapper'
 export { DefaultSpinner } from './lib/components/default-components/DefaultSpinner'
 export { DefaultSvgDefs } from './lib/components/default-components/DefaultSvgDefs'
+export {
+	EditorPortal,
+	useEditorPortalHost,
+	type EditorPortalProps,
+} from './lib/components/EditorPortal'
 export {
 	ErrorBoundary,
 	OptionalErrorBoundary,
@@ -306,7 +315,6 @@ export { useShallowArrayIdentity, useShallowObjectIdentity } from './lib/hooks/u
 export { useIsCropping } from './lib/hooks/useIsCropping'
 export { useIsEditing } from './lib/hooks/useIsEditing'
 export { useLocalStore } from './lib/hooks/useLocalStore'
-export { usePassThroughMouseOverEvents } from './lib/hooks/usePassThroughMouseOverEvents'
 export { usePassThroughWheelEvents } from './lib/hooks/usePassThroughWheelEvents'
 export { usePeerIds } from './lib/hooks/usePeerIds'
 export { usePresence } from './lib/hooks/usePresence'
@@ -318,18 +326,22 @@ export {
 	useUniqueSafeId,
 	type SafeId,
 } from './lib/hooks/useSafeId'
+export { useTransform } from './lib/hooks/useTransform'
+export { isCursorInViewport } from './lib/utils/collaborators'
 export { useTLSchemaFromUtils, useTLStore } from './lib/hooks/useTLStore'
 export { useViewportHeight } from './lib/hooks/useViewportHeight'
 export {
 	LicenseManager,
 	type InvalidLicenseKeyResult,
 	type InvalidLicenseReason,
+	type LicenseFeatureName,
 	type LicenseFromKeyResult,
 	type LicenseInfo,
 	type LicenseState,
 	type ValidLicenseKeyResult,
 } from './lib/license/LicenseManager'
-export { LICENSE_TIMEOUT } from './lib/license/LicenseProvider'
+export { LICENSE_TIMEOUT, useLicenseContext } from './lib/license/LicenseProvider'
+export { useLicenseFeatureFlag } from './lib/license/useLicenseManagerState'
 export {
 	defaultTldrawOptions,
 	type TLClipboardPasteRawInfo,

package/src/lib/TldrawEditor.tsx

@@ -24,6 +24,7 @@ import React, {
 } from 'react'
 import { version } from '../version'
 import { DefaultErrorFallback } from './components/default-components/DefaultErrorFallback'
+import { EditorPortalProvider } from './components/EditorPortal'
 import { OptionalErrorBoundary } from './components/ErrorBoundary'
 import { createTLCurrentUser, TLCurrentUser } from './config/createTLCurrentUser'
 import { TLStoreBaseOptions } from './config/createTLStore'
@@ -304,6 +305,7 @@ export const TldrawEditor = memo(function TldrawEditor({
 	registerFontsFromThemes(resolvedThemes)
 
 	const [container, setContainer] = useState<HTMLElement | null>(null)
+	const [portalHost, setPortalHost] = useState<HTMLElement | null>(null)
 	const user = useMemo(() => _user ?? createTLCurrentUser(), [_user])
 
 	const ErrorFallback =
@@ -352,24 +354,30 @@ export const TldrawEditor = memo(function TldrawEditor({
 				{container && (
 					<LicenseProvider licenseKey={rest.licenseKey}>
 						<ContainerProvider container={container}>
-							<EditorComponentsProvider overrides={components}>
-								{store ? (
-									store instanceof Store ? (
-										// Store is ready to go, whether externally synced or not
-										<TldrawEditorWithReadyStore {...withDefaults} store={store} user={user} />
+							<EditorPortalProvider host={portalHost}>
+								<EditorComponentsProvider overrides={components}>
+									{store ? (
+										store instanceof Store ? (
+											// Store is ready to go, whether externally synced or not
+											<TldrawEditorWithReadyStore {...withDefaults} store={store} user={user} />
+										) : (
+											// Store is a synced store, so handle syncing stages internally
+											<TldrawEditorWithLoadingStore {...withDefaults} store={store} user={user} />
+										)
 									) : (
-										// Store is a synced store, so handle syncing stages internally
-										<TldrawEditorWithLoadingStore {...withDefaults} store={store} user={user} />
-									)
-								) : (
-									// We have no store (it's undefined) so create one and possibly sync it
-									<TldrawEditorWithOwnStore {...withDefaults} store={store} user={user} />
-								)}
-							</EditorComponentsProvider>
+										// We have no store (it's undefined) so create one and possibly sync it
+										<TldrawEditorWithOwnStore {...withDefaults} store={store} user={user} />
+									)}
+								</EditorComponentsProvider>
+							</EditorPortalProvider>
 						</ContainerProvider>
 					</LicenseProvider>
 				)}
 			</OptionalErrorBoundary>
+			{/* The host for <EditorPortal>, last among the container's children so that anything
+			    portaled through it lands after the canvas and the UI — behind the UI's "skip to main
+			    content" link in the tab order, which only works while nothing precedes it. */}
+			<div className="tl-portal-host" ref={setPortalHost} />
 		</div>
 	)
 })
@@ -801,7 +809,16 @@ export function useOnMount(onMount?: TLOnMountHandler) {
 			{ history: 'ignore' }
 		)
 		window.tldrawReady = true
-		return teardown
+		return () => {
+			teardown?.()
+			// The editor's component can unmount without the editor being disposed (for example when
+			// the canvas is swapped for an error fallback), so emit `unmount` here rather than relying
+			// on disposal. If the editor is being disposed, `dispose()` emits `unmount` itself, so we
+			// only emit here when it's still mounted and alive.
+			if (editor.getIsMounted() && !editor.isDisposed) {
+				editor.run(() => editor.emit('unmount'), { history: 'ignore' })
+			}
+		}
 	})
 
 	React.useLayoutEffect(() => {

package/src/lib/components/EditorPortal.tsx

@@ -0,0 +1,77 @@
+import { ReactNode, createContext, useContext } from 'react'
+import { createPortal } from 'react-dom'
+
+const EditorPortalContext = createContext<HTMLElement | null>(null)
+
+/** @internal */
+export function EditorPortalProvider({
+	host,
+	children,
+}: {
+	host: HTMLElement | null
+	children: ReactNode
+}) {
+	return <EditorPortalContext.Provider value={host}>{children}</EditorPortalContext.Provider>
+}
+
+/**
+ * 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 function useEditorPortalHost(): HTMLElement | null {
+	return useContext(EditorPortalContext)
+}
+
+/** @public */
+export interface EditorPortalProps {
+	children: ReactNode
+}
+
+/**
+ * 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 function EditorPortal({ children }: EditorPortalProps) {
+	const host = useEditorPortalHost()
+	if (!host) return null
+	return createPortal(children, host)
+}

package/src/lib/components/LiveCollaborators.tsx

@@ -0,0 +1,133 @@
+import { track, useQuickReactor, useValue } from '@tldraw/state-react'
+import { TLInstancePresence } from '@tldraw/tlschema'
+import { useLayoutEffect, useRef } from 'react'
+import { useEditorComponents } from '../hooks/EditorComponentsContext'
+import { useEditor } from '../hooks/useEditor'
+import { useSharedSafeId } from '../hooks/useSafeId'
+import { isCursorInViewport } from '../utils/collaborators'
+import { setStyleProperty } from '../utils/dom'
+import { getHtmlLayerTransform } from '../utils/getHtmlLayerTransform'
+
+/**
+ * The collaborator cursor layer: a DOM layer stacked as a sibling of the canvas — above all canvas
+ * content, below the in-front layer and the UI panels — hosting each visible collaborator's cursor
+ * (arrow, name tag, chat message). Off-viewport collaborators are the canvas-drawn hint arrows' job
+ * (CollaboratorHintOverlayUtil), not this layer's.
+ *
+ * Cursors are DOM rather than canvas-drawn so their chrome styles and composes like the rest of
+ * the UI. Re-render traffic is kept narrow: per-cursor positioning writes `transform` directly
+ * (see `useTransform`), so a pointer move re-renders only the moved cursor; the camera transform
+ * is written imperatively below, so a pure pan re-renders only cursors whose viewport visibility
+ * flips (an equality-gated boolean per cursor); a zoom change re-renders every visible cursor,
+ * because each one rescales by `1/zoom`.
+ *
+ * @public @react
+ */
+export const LiveCollaborators = track(function LiveCollaborators() {
+	const editor = useEditor()
+	const { CollaboratorCursor } = useEditorComponents()
+
+	// The inner layer carries the camera transform, so the cursor components position in page
+	// space exactly as canvas content does. Unlike the canvas's html layers this one unmounts
+	// while no collaborators are visible, so the transform is written at two moments: on every
+	// camera change (the reactor), and after every render (the layout effect, like useTransform
+	// does per cursor) — the reactor's last run hit a null ref while the layer was unmounted,
+	// and without the render-time write a reappearing layer would keep an identity transform
+	// until the next camera move.
+	const rHtmlLayer = useRef<HTMLDivElement | null>(null)
+	useLayoutEffect(() => {
+		const elm = rHtmlLayer.current
+		if (!elm) return
+		setStyleProperty(elm, 'transform', getHtmlLayerTransform(editor))
+	})
+	useQuickReactor(
+		'position collaborators layer',
+		function positionCollaboratorsWhenCameraMoves() {
+			// Reads the camera even while the layer is unmounted, keeping the subscription alive.
+			const transform = getHtmlLayerTransform(editor)
+			setStyleProperty(rHtmlLayer.current, 'transform', transform)
+		},
+		[editor]
+	)
+
+	// Visibility (activity state, following, highlighting) is handled by the editor.
+	const collaborators = editor.getVisibleCollaboratorsOnCurrentPage()
+	if (collaborators.length === 0) return null
+	if (!CollaboratorCursor) return null
+
+	return (
+		<div className="tl-collaborators">
+			<svg className="tl-svg-context" aria-hidden="true">
+				<defs>
+					<CursorDef />
+				</defs>
+			</svg>
+			<div ref={rHtmlLayer} className="tl-html-layer">
+				{collaborators.map((presence) => (
+					<Collaborator key={presence.userId} latestPresence={presence} />
+				))}
+			</div>
+		</div>
+	)
+})
+
+const Collaborator = track(function Collaborator({
+	latestPresence,
+}: {
+	latestPresence: TLInstancePresence
+}) {
+	const editor = useEditor()
+	const { CollaboratorCursor } = useEditorComponents()
+
+	const { userId, chatMessage, userName, cursor, color } = latestPresence
+
+	// The viewport read lives inside this equality-gated computed rather than the tracked render:
+	// pans move the viewport every frame, but this component only needs to know when the cursor
+	// crosses the edge, so it subscribes to the boolean and re-renders only when it flips.
+	const cursorInViewport = useValue(
+		'cursor in viewport',
+		() =>
+			!!cursor && isCursorInViewport(cursor, editor.getViewportPageBounds(), editor.getZoomLevel()),
+		[editor, cursor]
+	)
+	// The zoom read is tracked directly: the cursor scales by 1/zoom, so zoom changes must
+	// re-render it. Pure pans leave the zoom value unchanged, so they never invalidate this.
+	const zoomLevel = editor.getZoomLevel()
+
+	if (!cursor) return null
+
+	// Off-viewport collaborators show as the canvas-drawn hint arrows
+	// (CollaboratorHintOverlayUtil), which shares this predicate — only the cursor itself is DOM.
+	if (!cursorInViewport) return null
+	if (!CollaboratorCursor) return null
+	return (
+		<CollaboratorCursor
+			className="tl-collaborator__cursor"
+			userId={userId}
+			point={cursor}
+			color={color}
+			zoom={zoomLevel}
+			name={userName !== 'New User' ? userName : null}
+			chatMessage={chatMessage ?? ''}
+		/>
+	)
+})
+
+function CursorDef() {
+	return (
+		<g id={useSharedSafeId('cursor')}>
+			<g fill="rgba(0,0,0,.2)" transform="translate(-11,-11)">
+				<path d="m12 24.4219v-16.015l11.591 11.619h-6.781l-.411.124z" />
+				<path d="m21.0845 25.0962-3.605 1.535-4.682-11.089 3.686-1.553z" />
+			</g>
+			<g fill="white" transform="translate(-12,-12)">
+				<path d="m12 24.4219v-16.015l11.591 11.619h-6.781l-.411.124z" />
+				<path d="m21.0845 25.0962-3.605 1.535-4.682-11.089 3.686-1.553z" />
+			</g>
+			<g fill="currentColor" transform="translate(-12,-12)">
+				<path d="m19.751 24.4155-1.844.774-3.1-7.374 1.841-.775z" />
+				<path d="m13 10.814v11.188l2.969-2.866.428-.139h4.768z" />
+			</g>
+		</g>
+	)
+}

package/src/lib/components/default-components/DefaultCanvas.tsx

@@ -1,7 +1,7 @@
 import { react } from '@tldraw/state'
 import { useQuickReactor, useValue } from '@tldraw/state-react'
 import { TLShapeId } from '@tldraw/tlschema'
-import { modulate, objectMapValues } from '@tldraw/utils'
+import { objectMapValues } from '@tldraw/utils'
 import classNames from 'classnames'
 import { Fragment, JSX, useEffect, useRef, useState } from 'react'
 import { tlenv } from '../../globals/environment'
@@ -16,9 +16,10 @@ import { useGestureEvents } from '../../hooks/useGestureEvents'
 import { useScreenBounds } from '../../hooks/useScreenBounds'
 import { ShapeCullingProvider, useShapeCulling } from '../../hooks/useShapeCulling'
 import { Box } from '../../primitives/Box'
-import { toDomPrecision } from '../../primitives/utils'
 import { debugFlags } from '../../utils/debug-flags'
 import { setStyleProperty } from '../../utils/dom'
+import { getHtmlLayerTransform } from '../../utils/getHtmlLayerTransform'
+import { LiveCollaborators } from '../LiveCollaborators'
 import { MenuClickCapture } from '../MenuClickCapture'
 import { Shape } from '../Shape'
 import { CanvasOverlays } from './CanvasOverlays'
@@ -94,21 +95,7 @@ export function DefaultCanvas({ className }: TLCanvasComponentProps) {
 	useQuickReactor(
 		'position layers',
 		function positionLayersWhenCameraMoves() {
-			const { x, y, z } = editor.getCamera()
-
-			// Because the html container has a width/height of 1px, we
-			// need to create a small offset when zoomed to ensure that
-			// the html container and svg container are lined up exactly.
-			const offset =
-				z >= 1 ? modulate(z, [1, 8], [0.125, 0.5], true) : modulate(z, [0.1, 1], [-2, 0.125], true)
-
-			setStyleProperty(
-				rHtmlLayer.current,
-				'transform',
-				`scale(${toDomPrecision(z)}) translate(${toDomPrecision(
-					x + offset
-				)}px,${toDomPrecision(y + offset)}px)`
-			)
+			setStyleProperty(rHtmlLayer.current, 'transform', getHtmlLayerTransform(editor))
 		},
 		[editor, container]
 	)
@@ -166,6 +153,7 @@ export function DefaultCanvas({ className }: TLCanvasComponentProps) {
 				<MovingCameraHitTestBlocker />
 			</div>
 			<InFrontOfTheCanvasWrapper />
+			<LiveCollaborators />
 			<MenuClickCapture />
 		</>
 	)

package/src/lib/components/default-components/DefaultCursor.tsx

@@ -0,0 +1,65 @@
+import { VecModel } from '@tldraw/tlschema'
+import classNames from 'classnames'
+import { memo, useRef } from 'react'
+import { useSharedSafeId } from '../../hooks/useSafeId'
+import { useTransform } from '../../hooks/useTransform'
+
+/** @public */
+export interface TLCursorProps {
+	userId: string
+	className?: string
+	point: VecModel | null
+	zoom: number
+	color?: string
+	name: string | null
+	chatMessage: string
+}
+
+/**
+ * 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 const DefaultCursor = memo(function DefaultCursor({
+	className,
+	zoom,
+	point,
+	color,
+	name,
+	chatMessage,
+}: TLCursorProps) {
+	const rCursor = useRef<HTMLDivElement>(null)
+	useTransform(rCursor, point?.x, point?.y, 1 / zoom)
+
+	const cursorId = useSharedSafeId('cursor')
+
+	if (!point) return null
+
+	return (
+		<div ref={rCursor} className={classNames('tl-collaborators__item', className)}>
+			<svg className="tl-cursor" aria-hidden="true">
+				<use href={`#${cursorId}`} color={color} />
+			</svg>
+			{chatMessage ? (
+				<>
+					{name && (
+						<div className="tl-nametag-title" style={{ color }}>
+							{name}
+						</div>
+					)}
+					<div className="tl-nametag-chat" style={{ backgroundColor: color }}>
+						{chatMessage}
+					</div>
+				</>
+			) : (
+				name && (
+					<div className="tl-nametag" style={{ backgroundColor: color }}>
+						{name}
+					</div>
+				)
+			)}
+		</div>
+	)
+})