@tldraw/editor 5.3.0-internal.fba91ed55f6c → 5.3.0-next.2fa9c61a8de6

package/src/lib/components/LiveCollaborators.tsx

@@ -0,0 +1,119 @@
+import { track, useQuickReactor } 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; per-cursor positioning writes `transform` directly (see `useTransform`), so pointer- and
+ * camera-frequency updates never re-render more than the moved cursor.
+ *
+ * @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 zoomLevel = editor.getZoomLevel()
+	const viewportPageBounds = editor.getViewportPageBounds()
+	const { userId, chatMessage, userName, cursor, color } = latestPresence
+
+	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 (!isCursorInViewport(cursor, viewportPageBounds, zoomLevel)) 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>
+	)
+})

package/src/lib/editor/Editor.ts

@@ -7145,7 +7145,11 @@ export class Editor extends EventEmitter<TLEventMap> {
 
 				shape.index = index
 			})
-			const shapesToCreate = shapesToCreateWithOriginals.map(({ shape }) => shape)
+			const shapesToCreate = shapesToCreateWithOriginals.map(({ shape, originalShape }) => {
+				// Give the shape util a chance to modify the duplicate, e.g. to re-stamp note
+				// attribution to the current user so we don't forge the original author's identity.
+				return this.getShapeUtil(shape).onBeforeDuplicate?.(originalShape, shape) ?? shape
+			})
 
 			if (!this.canCreateShapes(shapesToCreate)) {
 				alertMaxShapes(this)
@@ -10039,7 +10043,15 @@ export class Editor extends EventEmitter<TLEventMap> {
 			const newId = shapeIdMap.get(oldShape.id)!
 
 			// Create the new shape (new except for the id)
-			const newShape = { ...oldShape, id: newId }
+			let newShape = { ...oldShape, id: newId }
+
+			// Give the shape util a chance to modify the copy, e.g. to re-stamp note
+			// attribution to the current user so we don't forge the original author's identity.
+			// When ids are preserved the shape keeps its identity (e.g. moveShapesToPage
+			// relocating it), so it's not a duplicate and the hook must not run.
+			if (!preserveIds) {
+				newShape = this.getShapeUtil(newShape).onBeforeDuplicate?.(oldShape, newShape) ?? newShape
+			}
 
 			if (rootShapeIds.includes(oldShape.id)) {
 				newShape.parentId = currentPageId

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

@@ -669,6 +669,30 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 */
 	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.

package/src/lib/hooks/EditorComponentsContext.tsx

@@ -1,5 +1,6 @@
 import { ComponentType, RefAttributes, createContext, useContext } from 'react'
 import type { TLCanvasComponentProps } from '../components/default-components/DefaultCanvas'
+import type { TLCursorProps } from '../components/default-components/DefaultCursor'
 import type { TLErrorFallbackComponent } from '../components/default-components/DefaultErrorFallback'
 import type { TLGridProps } from '../components/default-components/DefaultGrid'
 import type { TLShapeErrorFallbackComponent } from '../components/default-components/DefaultShapeErrorFallback'
@@ -9,6 +10,7 @@ import type { TLShapeWrapperProps } from '../components/default-components/Defau
 export interface TLEditorComponents {
 	Background?: ComponentType | null
 	Canvas?: ComponentType<TLCanvasComponentProps> | null
+	CollaboratorCursor?: ComponentType<TLCursorProps> | null
 	Grid?: ComponentType<TLGridProps> | null
 	InFrontOfTheCanvas?: ComponentType | null
 	LoadingScreen?: ComponentType | null

package/src/lib/hooks/useCursor.ts

@@ -36,6 +36,7 @@ const STATIC_CURSORS = [
 	'default',
 	'pointer',
 	'cross',
+	'comment',
 	'move',
 	'grab',
 	'grabbing',

package/src/lib/hooks/useEditorComponents.tsx

@@ -1,6 +1,7 @@
 import { ReactNode, useMemo } from 'react'
 import { DefaultBackground } from '../components/default-components/DefaultBackground'
 import { DefaultCanvas } from '../components/default-components/DefaultCanvas'
+import { DefaultCursor } from '../components/default-components/DefaultCursor'
 import { DefaultErrorFallback } from '../components/default-components/DefaultErrorFallback'
 import { DefaultGrid } from '../components/default-components/DefaultGrid'
 import { DefaultLoadingScreen } from '../components/default-components/DefaultLoadingScreen'
@@ -29,6 +30,7 @@ export function EditorComponentsProvider({
 		(): Required<TLEditorComponents> => ({
 			Background: DefaultBackground,
 			Canvas: DefaultCanvas,
+			CollaboratorCursor: DefaultCursor,
 			Grid: DefaultGrid,
 			InFrontOfTheCanvas: null,
 			LoadingScreen: DefaultLoadingScreen,

package/src/lib/hooks/usePassThroughWheelEvents.ts

@@ -3,6 +3,48 @@ import { preventDefault } from '../utils/dom'
 import { useContainer } from './useContainer'
 import { useMaybeEditor } from './useEditor'
 
+function isScrollableOverflow(overflow: string) {
+	return overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay'
+}
+
+// An element only consumes a wheel event when it's a real scroll container: its content overflows
+// AND its computed overflow is scrollable. Checking scrollHeight/scrollWidth alone is not enough —
+// an `overflow: visible` element whose content merely overflows (e.g. a comment pin whose hover
+// `transform: scale()` inflates scrollHeight past clientHeight) never scrolls, so the wheel must
+// still pass through to the canvas.
+function isScrollable(elm: HTMLElement) {
+	// Cheap first: if nothing overflows, it can't scroll — skip the getComputedStyle read. This runs
+	// per ancestor on every wheel event, so avoid resolving styles for the common (non-overflowing) case.
+	const overflowsY = elm.scrollHeight > elm.clientHeight
+	const overflowsX = elm.scrollWidth > elm.clientWidth
+	if (!overflowsY && !overflowsX) return false
+
+	const style = getComputedStyle(elm)
+	return (
+		(overflowsY && isScrollableOverflow(style.overflowY)) ||
+		(overflowsX && isScrollableOverflow(style.overflowX))
+	)
+}
+
+// Walk from the wheeled element up to (and including) the pass-through root, looking for a scroll
+// container. If one is found, the wheel belongs to it — don't redispatch it to the canvas.
+function hasScrollableElement(target: EventTarget | null, root: HTMLElement) {
+	if (!(target instanceof Node)) {
+		return isScrollable(root)
+	}
+
+	let elm: Element | null = target instanceof Element ? target : target.parentElement
+	while (elm) {
+		if (elm instanceof HTMLElement && isScrollable(elm)) {
+			return true
+		}
+		if (elm === root) return false
+		elm = elm.parentElement
+	}
+
+	return false
+}
+
 /** @public */
 export function usePassThroughWheelEvents(ref: RefObject<HTMLElement | null>) {
 	if (!ref) throw Error('usePassThroughWheelEvents must be passed a ref')
@@ -16,9 +58,9 @@ export function usePassThroughWheelEvents(ref: RefObject<HTMLElement | null>) {
 
 			if ((e as any).isSpecialRedispatchedEvent) return
 
-			// if the element is scrollable, don't redispatch the event
+			// If the wheel is over a scrollable element, let it scroll instead of redispatching.
 			const elm = ref.current
-			if (elm && elm.scrollHeight > elm.clientHeight) {
+			if (elm && hasScrollableElement(e.target, elm)) {
 				return
 			}
 

package/src/lib/hooks/useTransform.ts

@@ -0,0 +1,38 @@
+import { useLayoutEffect } from 'react'
+import { VecLike } from '../primitives/Vec'
+
+/**
+ * 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 function useTransform(
+	ref: React.RefObject<HTMLElement | SVGElement | null>,
+	x?: number,
+	y?: number,
+	scale?: number,
+	rotate?: number,
+	additionalOffset?: VecLike
+) {
+	// Read the offset into primitives so the effect can depend on them, not the object identity.
+	const additionalOffsetX = additionalOffset?.x
+	const additionalOffsetY = additionalOffset?.y
+
+	useLayoutEffect(() => {
+		const elm = ref.current
+		if (!elm) return
+		if (x === undefined) return
+
+		let trans = `translate(${x}px, ${y}px)`
+		if (scale !== undefined) {
+			trans += ` scale(${scale})`
+		}
+		if (rotate !== undefined) {
+			trans += ` rotate(${rotate}rad)`
+		}
+		if (additionalOffsetX !== undefined && additionalOffsetY !== undefined) {
+			trans += ` translate(${additionalOffsetX}px, ${additionalOffsetY}px)`
+		}
+		elm.style.transform = trans
+	}, [additionalOffsetX, additionalOffsetY, ref, rotate, scale, x, y])
+}

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

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { isCursorInViewport } from './collaborators'
+
+// The viewport (page coords) all cases test against; zoom 1 so the 12/16px margins map 1:1.
+const viewport = { minX: 0, minY: 0, maxX: 100, maxY: 100 }
+
+describe('isCursorInViewport', () => {
+	it('is true for a cursor well inside the viewport', () => {
+		expect(isCursorInViewport({ x: 50, y: 50 }, viewport, 1)).toBe(true)
+	})
+
+	it('keeps a cursor just past the left/top edges (12/16px margin)', () => {
+		expect(isCursorInViewport({ x: -11, y: 50 }, viewport, 1)).toBe(true) // within 12 of left
+		expect(isCursorInViewport({ x: -13, y: 50 }, viewport, 1)).toBe(false) // past it
+		expect(isCursorInViewport({ x: 50, y: -15 }, viewport, 1)).toBe(true) // within 16 of top
+		expect(isCursorInViewport({ x: 50, y: -17 }, viewport, 1)).toBe(false) // past it
+	})
+
+	it('culls a cursor beyond the right/bottom edges', () => {
+		// Asymmetric with the left/top edges: the max checks subtract the margin rather than add
+		// it, so the cull starts *inside* the far edge (maxX - 12, maxY - 16) — a known quirk
+		// carried over from the pre-canvas implementation.
+		expect(isCursorInViewport({ x: 87, y: 50 }, viewport, 1)).toBe(true) // < maxX - 12 (88)
+		expect(isCursorInViewport({ x: 89, y: 50 }, viewport, 1)).toBe(false) // > 88, culled
+		expect(isCursorInViewport({ x: 50, y: 83 }, viewport, 1)).toBe(true) // < maxY - 16 (84)
+		expect(isCursorInViewport({ x: 50, y: 85 }, viewport, 1)).toBe(false) // > 84, culled
+	})
+
+	it('scales the margins by zoom', () => {
+		// At zoom 2 the left margin is 12/2 = 6px, so -7 is now culled where -11 survived at zoom 1.
+		expect(isCursorInViewport({ x: -5, y: 50 }, viewport, 2)).toBe(true)
+		expect(isCursorInViewport({ x: -7, y: 50 }, viewport, 2)).toBe(false)
+	})
+})

package/src/lib/utils/collaborators.ts

@@ -0,0 +1,25 @@
+import { VecLike } from '../primitives/Vec'
+
+/**
+ * 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 function isCursorInViewport(
+	cursor: VecLike,
+	viewport: { minX: number; minY: number; maxX: number; maxY: number },
+	zoom: number
+): boolean {
+	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
+	)
+}

package/src/lib/utils/getHtmlLayerTransform.ts

@@ -0,0 +1,22 @@
+import { modulate } from '@tldraw/utils'
+import type { Editor } from '../editor/Editor'
+import { toDomPrecision } from '../primitives/utils'
+
+/**
+ * The CSS `transform` that puts a 1px-sized html layer into page space under the current camera.
+ * Shared by every camera-tracked DOM layer (the canvas's shape layer, the collaborator cursor
+ * layer) so they line up exactly and can't drift apart.
+ *
+ * The offset compensates for the layer's 1px width/height when zoomed, so it registers precisely
+ * with the other layers.
+ *
+ * @internal
+ */
+export function getHtmlLayerTransform(editor: Editor): string {
+	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)`
+}

package/src/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '5.3.0-internal.fba91ed55f6c'
+export const version = '5.3.0-next.2fa9c61a8de6'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-07-17T10:57:42.512Z',
-	patch: '2026-07-17T10:57:42.512Z',
+	minor: '2026-07-30T11:28:48.528Z',
+	patch: '2026-07-30T11:28:48.528Z',
 }