@tldraw/editor 5.3.0-next.fc37bd96825b → 5.3.1

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>
 	)
 })

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>
+	)
+})

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/managers/CollaboratorsManager/CollaboratorsManager.test.ts

@@ -33,7 +33,7 @@ function createPresence(userId: TLUserId): TLInstancePresence {
 }
 
 function createEditor(presences: TLInstancePresence[] = []) {
-	const setInterval = vi.fn(() => 123)
+	const setInterval = vi.fn((_fn: () => void, _ms: number) => 123)
 	const getInstanceState = vi.fn(() => ({
 		followingUserId: null,
 		highlightedUserIds: [],
@@ -67,6 +67,7 @@ function createEditor(presences: TLInstancePresence[] = []) {
 describe(CollaboratorsManager, () => {
 	afterEach(() => {
 		vi.clearAllMocks()
+		vi.useRealTimers()
 	})
 
 	it('starts the visibility clock on the first visible collaborators read', () => {
@@ -143,6 +144,50 @@ describe(CollaboratorsManager, () => {
 		expect(manager.getVisibleCollaborators()).toHaveLength(1)
 	})
 
+	it('keeps array identity when a presence update leaves the derived lists unchanged', () => {
+		const peerHere = createPresence(createUserId('peer-here'))
+		const peerElsewhere = createPresence(createUserId('peer-elsewhere'))
+		peerElsewhere.currentPageId = PageRecordType.createId('other-page')
+		const { editor } = createEditor([peerHere, peerElsewhere])
+		const manager = new CollaboratorsManager(editor)
+
+		const onPage = manager.getCollaboratorsOnCurrentPage()
+		const visibleOnPage = manager.getVisibleCollaboratorsOnCurrentPage()
+		expect(onPage).toEqual([peerHere])
+
+		// The off-page peer sends a presence update: the current-page lists are unaffected, so
+		// they keep the exact same array identity and don't invalidate downstream subscribers.
+		editor.store.put([{ ...peerElsewhere, chatMessage: 'hello from another page' }])
+		expect(manager.getCollaboratorsOnCurrentPage()).toBe(onPage)
+		expect(manager.getVisibleCollaboratorsOnCurrentPage()).toBe(visibleOnPage)
+	})
+
+	it('keeps array identity across a visibility-clock tick that changes nothing', () => {
+		vi.useFakeTimers()
+		const peer = createPresence(createUserId('peer'))
+		const { editor, setInterval, getInstanceState } = createEditor([peer])
+		const manager = new CollaboratorsManager(editor)
+
+		const visible = manager.getVisibleCollaborators()
+		const visibleOnPage = manager.getVisibleCollaboratorsOnCurrentPage()
+		expect(visible).toEqual([peer])
+		expect(getInstanceState).toHaveBeenCalledTimes(1)
+
+		// The clock ticks on a fixed interval whether or not anything changed. Advance far enough
+		// to move the clock atom, but not far enough to change anyone's activity state.
+		const tick = setInterval.mock.calls[0][0]
+		vi.advanceTimersByTime(1000)
+		tick()
+
+		// The tick really did invalidate the query — it re-evaluates and re-reads instance state —
+		// but the result is element-wise identical, so it keeps the previous array's identity. An
+		// idle room therefore doesn't re-render the cursor layer once per interval.
+		const revisited = manager.getVisibleCollaborators()
+		expect(getInstanceState).toHaveBeenCalledTimes(2)
+		expect(revisited).toBe(visible)
+		expect(manager.getVisibleCollaboratorsOnCurrentPage()).toBe(visibleOnPage)
+	})
+
 	it('shows newly-joined collaborators that have not recorded any activity yet', () => {
 		// A peer who has joined but not moved their pointer broadcasts the default
 		// `lastActivityTimestamp` of 0. They should still be treated as active so

package/src/lib/editor/managers/CollaboratorsManager/CollaboratorsManager.ts

@@ -1,6 +1,6 @@
 import { EMPTY_ARRAY, atom, computed } from '@tldraw/state'
 import type { TLInstancePresence } from '@tldraw/tlschema'
-import { maxBy } from '@tldraw/utils'
+import { areArraysShallowEqual, maxBy } from '@tldraw/utils'
 import type { Editor } from '../../Editor'
 
 /**
@@ -41,11 +41,16 @@ export class CollaboratorsManager {
 		}))
 	}
 
+	// These queries all derive fresh arrays with map/filter, so they compare results with
+	// shallow (element-identity) equality: a presence update that leaves a derived list's
+	// elements unchanged — e.g. a peer moving on another page — keeps the previous array's
+	// identity and doesn't invalidate downstream subscribers such as the cursor layer.
+
 	/**
 	 * Returns a list of presence records for all peer collaborators.
 	 * This will return the latest presence record for each connected user.
 	 */
-	@computed
+	@computed({ isEqual: areArraysShallowEqual })
 	getCollaborators(): TLInstancePresence[] {
 		const allPresenceRecords = this._getCollaboratorsQuery().get()
 		if (!allPresenceRecords.length) return EMPTY_ARRAY
@@ -63,7 +68,7 @@ export class CollaboratorsManager {
 	 * Returns a list of presence records for all peer collaborators on the current page.
 	 * This will return the latest presence record for each connected user.
 	 */
-	@computed
+	@computed({ isEqual: areArraysShallowEqual })
 	getCollaboratorsOnCurrentPage(): TLInstancePresence[] {
 		const currentPageId = this.editor.getCurrentPageId()
 		return this.getCollaborators().filter((c) => c.currentPageId === currentPageId)
@@ -76,7 +81,7 @@ export class CollaboratorsManager {
 	 * highlighted users. Re-evaluates on the visibility clock, so callers don't need to
 	 * drive their own activity timer.
 	 */
-	@computed
+	@computed({ isEqual: areArraysShallowEqual })
 	getVisibleCollaborators(): TLInstancePresence[] {
 		const { editor } = this
 		const { collaboratorInactiveTimeoutMs, collaboratorIdleTimeoutMs } = editor.options
@@ -121,7 +126,7 @@ export class CollaboratorsManager {
 	 * Returns a list of presence records for peer collaborators who should currently be
 	 * shown in the UI, filtered to those on the current page.
 	 */
-	@computed
+	@computed({ isEqual: areArraysShallowEqual })
 	getVisibleCollaboratorsOnCurrentPage(): TLInstancePresence[] {
 		const currentPageId = this.editor.getCurrentPageId()
 		return this.getVisibleCollaborators().filter((c) => c.currentPageId === 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/editor/types/external-content.ts

@@ -37,6 +37,11 @@ export type TLExternalContentSource =
 
 /** @public */
 export 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
 }

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/useDocumentEvents.ts

@@ -240,19 +240,20 @@ export function useDocumentEvents() {
 
 		function handleTouchStart(e: TouchEvent) {
 			if (container.contains(e.target as Node)) {
-				// Center point of the touch area
-				const touchXPosition = e.touches[0].pageX
+				// Center point of the touch area, measured from the edge of the window the touch
+				// has to reach to trigger the navigation
+				const touchXPosition = e.touches[0].clientX
 				// Size of the touch area
 				const touchXRadius = e.touches[0].radiusX || 0
 
-				// We set a threshold (10px) on both sizes of the screen,
-				// if the touch area overlaps with the screen edges
-				// it's likely to trigger the navigation. We prevent the
-				// touchstart event in that case.
-				// todo: make this relative to the actual window, not the editor's screen bounds
+				// If the touch area overlaps with the screen edges it's likely to trigger the
+				// navigation. We prevent the touchstart event in that case. The gesture belongs to
+				// the window, so an editor inset from the window's edges — beside a sidebar, say —
+				// is not near an edge the system reacts to.
+				const windowWidth = editor.getContainerWindow().innerWidth
 				if (
 					touchXPosition - touchXRadius < 10 ||
-					touchXPosition + touchXRadius > editor.getViewportScreenBounds().width - 10
+					touchXPosition + touchXRadius > windowWidth - 10
 				) {
 					if ((e.target as HTMLElement)?.tagName === 'BUTTON') {
 						// Force a click before bailing

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,