@tldraw/commenting 5.3.0-next.2fa9c61a8de6 → 5.3.0-next.7654e7ac2a02

package/src/canvas/pin-stacking.ts

@@ -55,3 +55,49 @@ export function computePinStacks(
 	}
 	return stacks
 }
+
+/**
+ * Value equality for pin-stack maps, so the overlay can hold the map's identity across a recompute
+ * that changed no grouping. Membership only: two equal maps can describe stacks at different page
+ * points, so anything keyed on a stack's *point* must read the anchors itself, as
+ * {@link isOpenStackKeyLive} does.
+ * @internal
+ */
+export function pinStacksEqual(
+	a: ReadonlyMap<string, readonly string[]>,
+	b: ReadonlyMap<string, readonly string[]>
+): boolean {
+	if (a === b) return true
+	if (a.size !== b.size) return false
+	for (const [id, group] of b) {
+		const prevGroup = a.get(id)
+		if (!prevGroup) return false
+		if (prevGroup === group) continue
+		if (prevGroup.length !== group.length) return false
+		for (let i = 0; i < group.length; i++) {
+			if (prevGroup[i] !== group[i]) return false
+		}
+	}
+	return true
+}
+
+/**
+ * Whether an open-stack key still names a stack on the canvas — false once that stack is emptied,
+ * moved, or off the page, at which point the caller must clear the key. Reads the anchors, so a
+ * reactive caller re-evaluates on a move that {@link pinStacksEqual} can't see.
+ * @internal
+ */
+export function isOpenStackKeyLive(
+	editor: Editor,
+	key: string,
+	stacks: ReadonlyMap<string, readonly string[]>,
+	threadsById: ReadonlyMap<string, TLCommentThread>
+): boolean {
+	for (const id of stacks.keys()) {
+		const thread = threadsById.get(id)
+		if (!thread) continue
+		const point = anchorPagePoint(editor, thread.anchor)
+		if (point && pinStackKey(point) === key) return true
+	}
+	return false
+}

package/src/canvas/region-box.tsx

@@ -0,0 +1,124 @@
+import { type PointerEvent as ReactPointerEvent, useRef } from 'react'
+import { type BoxModel, Editor, useValue, VecLike } from 'tldraw'
+import { regionDraft } from './state'
+
+/** A region's dashed box. Purely visual — a region moves by its pin and resizes from its corner
+ *  handles, so the box itself takes no pointer events. Positioned in viewport space, as a sibling
+ *  of the pins in the canvas layer. */
+export function RegionBox({ editor, box }: { editor: Editor; box: BoxModel }) {
+	const rect = useValue(
+		'region rect',
+		() => {
+			// Position from the page→viewport top-left; screen size scales with zoom, page size doesn't.
+			const topLeft = editor.pageToViewport({ x: box.x, y: box.y })
+			const zoom = editor.getZoomLevel()
+			return { left: topLeft.x, top: topLeft.y, width: box.w * zoom, height: box.h * zoom }
+		},
+		[editor, box.x, box.y, box.w, box.h]
+	)
+	return <div className="tlui-cmt-canvas-region" style={rect} />
+}
+
+/** The live region being dragged out by the comment tool, or nothing when not dragging. */
+export function RegionDraftBox({ editor }: { editor: Editor }) {
+	const box = useValue('region draft', () => regionDraft.get(editor), [editor])
+	if (!box) return null
+	return <RegionBox editor={editor} box={box} />
+}
+
+// A resize handle's normalized 0–1 spot on the box, and its cursor. An axis at 0.5 is *not*
+// controlled by that handle — the resize math reads the spot rather than special-casing corners.
+export interface RegionHandle {
+	x: number
+	y: number
+	cursor: string
+}
+
+// The four corners, each resizing both axes.
+export const REGION_CORNERS: readonly RegionHandle[] = [
+	{ x: 0, y: 0, cursor: 'nwse-resize' },
+	{ x: 1, y: 0, cursor: 'nesw-resize' },
+	{ x: 0, y: 1, cursor: 'nesw-resize' },
+	{ x: 1, y: 1, cursor: 'nwse-resize' },
+]
+
+// Screen-space slack around a region's bounds within which its box and handles stay revealed, so
+// the handles (which sit on the edge) are comfortably reachable.
+export const REGION_HANDLE_MARGIN_PX = 12
+
+/** Resize `box` by dragging `handle` to `cursor` (page coords). Each controlled axis spans from the
+ *  handle's fixed opposite edge to the cursor (normalized, so dragging past it flips); an axis the
+ *  handle doesn't control (a midpoint, at 0.5) keeps its original position and size. */
+function resizeRegion(box: BoxModel, handle: RegionHandle, cursor: VecLike): BoxModel {
+	const controlsX = handle.x !== 0.5
+	const controlsY = handle.y !== 0.5
+	const fixedX = box.x + (1 - handle.x) * box.w
+	const fixedY = box.y + (1 - handle.y) * box.h
+	return {
+		x: controlsX ? Math.min(fixedX, cursor.x) : box.x,
+		y: controlsY ? Math.min(fixedY, cursor.y) : box.y,
+		w: controlsX ? Math.abs(cursor.x - fixedX) : box.w,
+		h: controlsY ? Math.abs(cursor.y - fixedY) : box.h,
+	}
+}
+
+/** Draggable handles that resize a region — corners (both axes) or edges (one axis), per the resize
+ *  option. Previews live, commits on release. */
+export function RegionResizeHandles({
+	editor,
+	box,
+	handles,
+	onPreview,
+	onCommit,
+}: {
+	editor: Editor
+	box: BoxModel
+	handles: readonly RegionHandle[]
+	onPreview(bounds: BoxModel | null): void
+	onCommit(bounds: BoxModel): void
+}) {
+	// The box at pointer-down, captured so the box prop reflowing under the live preview doesn't move
+	// the fixed edges mid-drag.
+	const boxRef = useRef<BoxModel | null>(null)
+	const points = useValue(
+		'region handle points',
+		() =>
+			handles.map((h) => {
+				const p = editor.pageToViewport({ x: box.x + h.x * box.w, y: box.y + h.y * box.h })
+				return { ...h, key: `${h.x}-${h.y}`, left: p.x, top: p.y }
+			}),
+		[editor, box.x, box.y, box.w, box.h, handles]
+	)
+	const startResize = (e: ReactPointerEvent<HTMLDivElement>) => {
+		e.stopPropagation()
+		boxRef.current = box
+		e.currentTarget.setPointerCapture(e.pointerId)
+	}
+	const resizedTo = (h: RegionHandle, e: ReactPointerEvent<HTMLDivElement>): BoxModel =>
+		resizeRegion(boxRef.current!, h, editor.screenToPage({ x: e.clientX, y: e.clientY }))
+	const onResize = (h: RegionHandle) => (e: ReactPointerEvent<HTMLDivElement>) => {
+		if (boxRef.current) onPreview(resizedTo(h, e))
+	}
+	const endResize = (h: RegionHandle) => (e: ReactPointerEvent<HTMLDivElement>) => {
+		if (!boxRef.current) return
+		const bounds = resizedTo(h, e)
+		boxRef.current = null
+		if (e.currentTarget.hasPointerCapture(e.pointerId))
+			e.currentTarget.releasePointerCapture(e.pointerId)
+		onCommit(bounds)
+	}
+	return (
+		<>
+			{points.map((h) => (
+				<div
+					key={h.key}
+					className="tlui-cmt-canvas-region-handle"
+					style={{ left: h.left, top: h.top, cursor: h.cursor }}
+					onPointerDown={startResize}
+					onPointerMove={onResize(h)}
+					onPointerUp={endResize(h)}
+				/>
+			))}
+		</>
+	)
+}

package/src/canvas/state.ts

@@ -3,20 +3,19 @@ import type { PendingComment } from './comment-tool'
 import { DEFAULT_SIDEBAR_FILTERS, type SidebarFilters } from './sidebar-filters'
 
 /**
- * Transient commenting UI state, scoped per editor via {@link EditorAtom}. Editor-scoping (rather
- * than module-global atoms) keeps two editors on one page — or an editor and a second instance —
- * from sharing open-thread, visibility, and filter state. Reachable from both React (`useEditor()`)
- * and the comment tool (`this.editor`).
+ * Transient commenting UI state, scoped per editor via {@link EditorAtom} so two editors on one
+ * page don't share open-thread, visibility, and filter state. Reachable from both React
+ * (`useEditor()`) and the comment tool (`this.editor`).
  */
 
 /** The id of the one open thread (only one popover is open at a time), or null when all closed.
  * @public */
 export const openThreadId = new EditorAtom<string | null>('openThreadId', () => null)
 
-/** The coincident-pin stack whose thread list is showing (keyed by its oldest member's thread
- * id), or null. Editor state rather than component state: the stack pin remounts when its owning
- * render path changes (e.g. a member thread opens), and the open list must survive that.
- * @internal */
+/** The coincident-pin stack whose thread list is showing (keyed by its oldest member's thread id),
+ *  or null. Editor state rather than component state: the stack pin remounts when its owning render
+ *  path changes, and the open list must survive that.
+ *  @internal */
 export const openStackId = new EditorAtom<string | null>('openStackId', () => null)
 
 /** The comment currently being placed (composer open, not yet posted), or null.
@@ -32,13 +31,12 @@ export const pendingComment = new EditorAtom<PendingComment | null>('pendingComm
 export const revealThreadRequest = new EditorAtom<string | null>('revealThreadRequest', () => null)
 
 /**
- * Open a thread and bring it into view, given a thread id or the id of any comment in it. Use it
- * to jump to a thread from outside the canvas — a notification, a deep link, your own list.
+ * Open a thread and bring it into view, given a thread id or the id of any comment in it. Use it to
+ * jump to a thread from outside the canvas — a notification, a deep link, your own list.
  *
- * The request is served by `CanvasComments`, so it works before the records have arrived: the
- * layer waits for them to sync in, switches pages if it needs to, unhides pins, zooms in far
- * enough to split the thread out of any cluster it's folded into, and then opens it. That also
- * means nothing happens if `CanvasComments` isn't mounted.
+ * The request is served by `CanvasComments`, so it works before the records have arrived: the layer
+ * waits for them, switches pages, unhides pins, and zooms far enough to split the thread out of any
+ * cluster. That also means nothing happens if `CanvasComments` isn't mounted.
  *
  * To open a thread you already hold and skip the wait, see {@link focusThread}.
  *
@@ -55,12 +53,10 @@ export function revealThread(editor: Editor, threadOrCommentId: string): void {
 
 /**
  * The id passed to the most recent {@link revealThread} call that `CanvasComments` hasn't served
- * yet, or null when there's nothing outstanding. A request also clears when `CanvasComments`
- * unmounts, since nothing is left to serve it.
+ * yet, or null. A request also clears when `CanvasComments` unmounts.
  *
- * This is a plain, untracked read. In React, use {@link useRevealThreadPending} — but reach for
- * this one inside a timer or callback that needs the value as of *now* rather than as of the
- * render it closed over.
+ * This is a plain, untracked read — in React, use {@link useRevealThreadPending}, unless you need
+ * the value as of *now* rather than as of the render you closed over.
  *
  * @public
  */
@@ -71,11 +67,9 @@ export function getRevealThreadPending(editor: Editor): string | null {
 /**
  * Reactive React hook for {@link getRevealThreadPending}.
  *
- * Use it to notice a reveal that never lands — most often a deep link to a comment that has since
- * been deleted. Give it a grace period before you act: a request also sits here while its records
- * are still syncing in, which is the normal case on a cold load. Re-check with
- * {@link getRevealThreadPending} when the grace period elapses, since the request can clear inside
- * it without this hook's value having caught up yet.
+ * Use it to notice a reveal that never lands — usually a deep link to a deleted comment. Give it a
+ * grace period first, since a request also sits here while its records sync in, and re-check with
+ * {@link getRevealThreadPending} when it elapses.
  *
  * @public
  */
@@ -96,10 +90,8 @@ export const regionDraft = new EditorAtom<BoxModel | null>('regionDraft', () =>
 export const commentsHidden = new EditorAtom<boolean>('commentsHidden', () => false)
 
 /**
- * Whether the comments sidebar (the thread list) is open. Driven by an explicit control — a button
- * next to Share on dotcom — rather than by which tool is active, so browsing threads is separate
- * from placing them. The comment tool additionally closes it on enter, keeping placement
- * canvas-focused.
+ * Whether the comments sidebar (the thread list) is open. Driven by an explicit control rather than
+ * by which tool is active, so browsing threads is separate from placing them.
  * @public
  */
 export const commentsSidebarOpen = new EditorAtom<boolean>('commentsSidebarOpen', () => false)

package/src/canvas/thread-pin.tsx

@@ -0,0 +1,418 @@
+import { Avatar } from '@tldraw/mentions'
+import {
+	memo,
+	type PointerEvent as ReactPointerEvent,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'react'
+import {
+	type BoxModel,
+	Editor,
+	TLCommentThread,
+	useContainer,
+	usePassThroughWheelEvents,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import { CommentPin } from '../ui/comment-pin'
+import { forwardPointerEventToCanvas, isCanvasPanGesture } from './canvas-events'
+import { commitCommentMutation } from './comment-mutations'
+import { UNKNOWN_AUTHOR, UNKNOWN_COMMENT_AUTHOR } from './comment-render'
+import { type CommentingContext } from './context'
+import { useThreadComments } from './hooks'
+import { getCommentingOptions, useCanComment, useCommentingOptions } from './options'
+import {
+	REGION_CORNERS,
+	REGION_HANDLE_MARGIN_PX,
+	RegionBox,
+	RegionResizeHandles,
+} from './region-box'
+import { openThreadId } from './state'
+import { ThreadPreview, useMarkerPreview } from './thread-preview'
+import {
+	anchorPagePoint,
+	commentTargetShapeAt,
+	impreciseShapePinInset,
+	isBoxInInflatedViewport,
+	isInInflatedViewport,
+	REGION_PIN_CORNER,
+	regionAnchorPinCorner,
+	regionPinPoint,
+	shapeAnchorAt,
+} from './thread-state'
+import { POPOVER_OFFSET, ThreadPopover, ThreadView } from './thread-view'
+
+/** The opened popover has a header row the hover preview lacks, so it opens this much higher — the
+ *  first comment then lands where the preview's sat. Re-measure if the header height or the preview
+ *  panel padding changes. */
+const THREAD_HEADER_BLOCK = 36
+
+/**
+ * A single thread's pin: the marker at its anchor, the thread popover when it's open, the hover
+ * preview, and — for a region anchor — the dashed box and its resize handles. Dragging the marker
+ * re-anchors the thread.
+ *
+ * Memoized so a pin skips re-rendering when the layer re-renders for unrelated reasons; camera
+ * tracking still works, since the pin subscribes to its own viewport position via signals.
+ */
+export const ThreadPin = memo(function ThreadPin({
+	editor,
+	thread,
+	...props
+}: CommentingContext & {
+	editor: Editor
+	thread: TLCommentThread
+}) {
+	const { resolveAuthor } = props
+	const options = useCommentingOptions()
+	const canComment = useCanComment(props.currentUserId)
+	const container = useContainer()
+	const msg = useTranslation()
+	const comments = useThreadComments(editor, thread.id)
+	// Only one thread's popover is open at a time — shared across pins via the atom.
+	const open = useValue('thread open', () => openThreadId.get(editor) === thread.id, [
+		editor,
+		thread.id,
+	])
+	// While dragging the marker, its page point overrides the anchor's; committed on drop.
+	const [dragPagePoint, setDragPagePoint] = useState<{ x: number; y: number } | null>(null)
+	const [resizeBounds, setResizeBounds] = useState<BoxModel | null>(null)
+	// Hovering the marker previews the thread's opening comment, on the delay every marker uses.
+	const { previewShown, previewHandlers } = useMarkerPreview(editor, `pin:${thread.id}`)
+	const previewThreads = useMemo(() => [thread], [thread])
+	// The 'pointer' reveal mode: is the pointer within the region's bounds (plus a grab margin)?
+	// Driven by pointer position, not DOM hover, so moving from anywhere in the region out to a corner
+	// handle never loses the affordance — the box stays `pointer-events: none`.
+	const pointerInRegion = useValue(
+		'pointer in region',
+		() => {
+			if (thread.anchor.type !== 'region' || thread.pageId !== editor.getCurrentPageId())
+				return false
+			const m = REGION_HANDLE_MARGIN_PX / editor.getZoomLevel()
+			const p = editor.inputs.getCurrentPagePoint()
+			const a = thread.anchor
+			return p.x >= a.x - m && p.x <= a.x + a.w + m && p.y >= a.y - m && p.y <= a.y + a.h + m
+		},
+		[editor, thread.anchor, thread.pageId]
+	)
+	// A region's box and handles are revealed while open, mid-resize, or while the pointer is
+	// within the region.
+	const revealed = open || resizeBounds != null || pointerInRegion
+	// A region thread's pin corner is its own (the corner its creating drag released on), with
+	// the default as the fallback for older records.
+	const pinCorner =
+		thread.anchor.type === 'region' ? regionAnchorPinCorner(thread.anchor) : REGION_PIN_CORNER
+	// A region resizes from its corners — every corner but the pin's own, which the pin owns.
+	const resizeHandles = useMemo(
+		() => REGION_CORNERS.filter((c) => c.x !== pinCorner.x || c.y !== pinCorner.y),
+		[pinCorner]
+	)
+	const dragRef = useRef<{
+		startX: number
+		startY: number
+		moved: boolean
+		// The anchor's page-space offset from the grab point, so a drag translates the pin by the
+		// cursor's delta (like RegionBox's move) instead of snapping the anchor to the cursor.
+		offsetX: number
+		offsetY: number
+	} | null>(null)
+	const markerRef = useRef<HTMLButtonElement>(null)
+	// Wheel pass-through sits on the marker (which is never scrollable), not the layer root —
+	// see the note on the layer.
+	usePassThroughWheelEvents(markerRef)
+
+	// The drop-target hint is editor-global state with no automatic reset. If the pin unmounts
+	// mid-drag (e.g. Shift+C hides comments), no pointer event will ever reach the drag handlers —
+	// clear the hint here or it stays on the shape indefinitely.
+	useEffect(() => {
+		return () => {
+			if (dragRef.current) editor.setHintingShapes([])
+		}
+	}, [editor])
+
+	// Clicking outside the open popover closes the thread. Capture phase + a class check rather than
+	// stopPropagation, since the popover portals elsewhere in the DOM. The marker is excluded so its own
+	// click-to-toggle handles it instead of this closing and the toggle reopening.
+	useEffect(() => {
+		if (!open) return
+		const onPointerDown = (e: PointerEvent) => {
+			const target = e.target as HTMLElement | null
+			if (!target) return
+			if (target.closest('.tlui-cmt-canvas-popover')) return
+			const marker = markerRef.current
+			if (marker && marker.contains(target)) return
+			// A press on a region's resize handle edits this thread — don't dismiss it.
+			if (target.closest('.tlui-cmt-canvas-region-handle')) return
+			// A click inside a menu/popover layered above us (the sidebar's filter or overflow
+			// dropdown, or the composer's mention picker — all portaled elsewhere) belongs to that
+			// layer; defer to its own dismissal instead of closing the thread out from under it.
+			if (
+				target.closest('.tlui-menu, [data-radix-popper-content-wrapper], .tlui-cmt-mention-popup')
+			)
+				return
+			openThreadId.set(editor, null)
+		}
+		document.addEventListener('pointerdown', onPointerDown, true)
+		return () => document.removeEventListener('pointerdown', onPointerDown, true)
+	}, [open, editor])
+
+	// The pin must not unmount mid-interaction: an open thread's popover hangs off it, and a drag
+	// or resize holds pointer capture on it — so those states are exempt from the viewport cull.
+	const exemptFromCull = open || dragPagePoint != null || resizeBounds != null
+	const point = useValue(
+		'pin point',
+		() => {
+			if (thread.pageId !== editor.getCurrentPageId()) return null
+			const pagePoint = anchorPagePoint(editor, thread.anchor)
+			if (!pagePoint) return null
+			const viewportPoint = editor.pageToViewport(pagePoint)
+			const inset = impreciseShapePinInset(editor, thread.anchor)
+			const point = inset
+				? { x: viewportPoint.x + inset.x, y: viewportPoint.y + inset.y }
+				: viewportPoint
+			// Off-screen pins (plus a pre-mount margin) unmount rather than re-render every camera frame. A
+			// region thread stays mounted while any part of its box is on screen, since the box renders here too.
+			if (!exemptFromCull) {
+				const visible =
+					thread.anchor.type === 'region'
+						? isBoxInInflatedViewport(editor, thread.anchor)
+						: isInInflatedViewport(editor, point)
+				if (!visible) return null
+			}
+			return point
+		},
+		[editor, thread.anchor, thread.pageId, exemptFromCull]
+	)
+	if (!point) return null
+
+	const PinContent = options.components.PinContent
+	const threadAuthor = resolveAuthor(thread.createdBy)
+	const pinContent = PinContent ? (
+		<PinContent thread={thread} comments={comments} />
+	) : (
+		<Avatar author={threadAuthor ?? UNKNOWN_COMMENT_AUTHOR} />
+	)
+	const pinLabel = msg(
+		thread.resolved ? 'comments.pin-label-resolved' : 'comments.pin-label'
+	).replace('{name}', threadAuthor?.name ?? UNKNOWN_AUTHOR)
+
+	// Drag the marker to move the thread: position is overridden locally while dragging, then re-anchored
+	// on drop. A region translates keeping its size; a barely-moved pointer is a click.
+	const isRegion = thread.anchor.type === 'region'
+	// The marker is a button (so it's keyboard-reachable), so the drag handlers are typed to it.
+	const startDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
+		// A middle/right-button or space-held press over a pin is a camera pan, not a pin drag —
+		// hand it to the canvas untouched.
+		if (isCanvasPanGesture(editor, e)) {
+			forwardPointerEventToCanvas(container, e)
+			return
+		}
+		e.stopPropagation()
+		const grabPage = editor.screenToPage({ x: e.clientX, y: e.clientY })
+		const anchorPage = anchorPagePoint(editor, thread.anchor)
+		// The drag delta is taken from where the pin is drawn, which for an imprecise shape pin
+		// is inset from its anchor point — without this the pin jumps by the inset on drag start.
+		const inset = impreciseShapePinInset(editor, thread.anchor)
+		if (anchorPage && inset) {
+			const zoom = editor.getZoomLevel()
+			anchorPage.x += inset.x / zoom
+			anchorPage.y += inset.y / zoom
+		}
+		dragRef.current = {
+			startX: e.clientX,
+			startY: e.clientY,
+			moved: false,
+			offsetX: anchorPage ? anchorPage.x - grabPage.x : 0,
+			offsetY: anchorPage ? anchorPage.y - grabPage.y : 0,
+		}
+		e.currentTarget.setPointerCapture(e.pointerId)
+	}
+	const onDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
+		const drag = dragRef.current
+		if (!drag) return
+		// Moving a pin re-anchors the thread record — a commenting write. Without the permission the
+		// press stays a click (`moved` never sets, so release toggles the popover and never commits).
+		if (!canComment) return
+		if (!drag.moved && Math.hypot(e.clientX - drag.startX, e.clientY - drag.startY) < 4) return
+		drag.moved = true
+		const cursorPage = editor.screenToPage({ x: e.clientX, y: e.clientY })
+		const pagePoint = { x: cursorPage.x + drag.offsetX, y: cursorPage.y + drag.offsetY }
+		setDragPagePoint(pagePoint)
+		// Hint the shape the pin would re-anchor to on drop — the same hit-test endDrag resolves
+		// with. Regions translate rather than re-anchor, so they never hint.
+		if (!isRegion) {
+			const hit = commentTargetShapeAt(editor, pagePoint)
+			editor.setHintingShapes(hit ? [hit.id] : [])
+		}
+	}
+	// A cancelled pointer (touch gesture takeover, browser interruption) aborts the drag outright:
+	// no re-anchor commit, no click-toggle — the pin snaps back and the hint clears.
+	const cancelDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
+		const drag = dragRef.current
+		dragRef.current = null
+		if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+			e.currentTarget.releasePointerCapture(e.pointerId)
+		}
+		if (!drag) return
+		setDragPagePoint(null)
+		editor.setHintingShapes([])
+	}
+	const endDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
+		const drag = dragRef.current
+		dragRef.current = null
+		if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+			e.currentTarget.releasePointerCapture(e.pointerId)
+		}
+		if (!drag) return
+		editor.setHintingShapes([])
+		if (!drag.moved) {
+			openThreadId.set(editor, openThreadId.get(editor) === thread.id ? null : thread.id)
+			return
+		}
+		const cursorPage = editor.screenToPage({ x: e.clientX, y: e.clientY })
+		const pagePoint = { x: cursorPage.x + drag.offsetX, y: cursorPage.y + drag.offsetY }
+		setDragPagePoint(null)
+		let anchor: TLCommentThread['anchor']
+		if (thread.anchor.type === 'region') {
+			// Translate so the pin (the region's pin corner) lands at the drop; size unchanged.
+			anchor = {
+				...thread.anchor,
+				x: pagePoint.x - pinCorner.x * thread.anchor.w,
+				y: pagePoint.y - pinCorner.y * thread.anchor.h,
+			}
+		} else {
+			const hit = commentTargetShapeAt(editor, pagePoint)
+			anchor = hit
+				? shapeAnchorAt(
+						editor,
+						hit.id,
+						pagePoint,
+						getCommentingOptions(editor).shouldBePrecise(editor, {
+							shapeId: hit.id,
+							point: pagePoint,
+							altKey: e.altKey,
+						})
+					)
+				: { type: 'point', x: pagePoint.x, y: pagePoint.y }
+		}
+		commitCommentMutation(editor, ({ put }) => put([{ ...thread, anchor }]), 'drag')
+	}
+
+	// The pin (and its popover) track the live edit: a resize moves it to the region's pin corner, a
+	// move to the drag point; otherwise it sits at the stored anchor's viewport point.
+	const livePinPage = resizeBounds ? regionPinPoint(resizeBounds, pinCorner) : dragPagePoint
+	const renderPointBase = livePinPage ? editor.pageToViewport(livePinPage) : point
+	// A region's pin centres on its corner — overlapping the box — rather than hanging off it.
+	// The marker anchors bottom-left, so step half its 34px size left and down (screen px).
+	const renderPoint = isRegion
+		? { x: renderPointBase.x - 17, y: renderPointBase.y + 17 }
+		: renderPointBase
+
+	// A region's live box bounds, by priority: a corner resize, else a pin-drag translation (the pin
+	// corner tracks the cursor), else the stored anchor. Undefined for non-region threads.
+	const regionAnchor = thread.anchor.type === 'region' ? thread.anchor : undefined
+	const movedRegion =
+		regionAnchor && dragPagePoint
+			? {
+					...regionAnchor,
+					x: dragPagePoint.x - pinCorner.x * regionAnchor.w,
+					y: dragPagePoint.y - pinCorner.y * regionAnchor.h,
+				}
+			: regionAnchor
+	const regionBoxBounds = resizeBounds ?? movedRegion
+	const commitResize = (bounds: BoxModel) => {
+		setResizeBounds(null)
+		if (!canComment) return
+		// Same commit path as a pin drag, so the configured `dragHistory` governs both — going
+		// straight to `editor.run` here would make region resizes silently ignore the option.
+		commitCommentMutation(
+			editor,
+			// Spread the existing anchor first so the region's pin corner survives a resize.
+			({ put }) => put([{ ...thread, anchor: { ...regionAnchor!, ...bounds } }]),
+			'drag'
+		)
+	}
+
+	return (
+		<>
+			{regionBoxBounds && (dragPagePoint || revealed) && (
+				<RegionBox editor={editor} box={regionBoxBounds} />
+			)}
+			{regionBoxBounds && revealed && !dragPagePoint && canComment && (
+				<RegionResizeHandles
+					editor={editor}
+					box={regionBoxBounds}
+					handles={resizeHandles}
+					onPreview={setResizeBounds}
+					onCommit={commitResize}
+				/>
+			)}
+			<div
+				className={[
+					'tlui-cmt-canvas-pin',
+					open && 'tlui-cmt-canvas-pin--open',
+					dragPagePoint && 'tlui-cmt-canvas-pin--dragging',
+				]
+					.filter(Boolean)
+					.join(' ')}
+				style={{ left: renderPoint.x, top: renderPoint.y }}
+			>
+				<button
+					ref={markerRef}
+					type="button"
+					className="tlui-cmt-button tlui-cmt-canvas-pin__marker"
+					aria-label={pinLabel}
+					aria-expanded={open}
+					onPointerDown={startDrag}
+					onPointerMove={onDrag}
+					onPointerUp={endDrag}
+					onPointerCancel={cancelDrag}
+					// Pointer activation is already handled by endDrag (which distinguishes a click
+					// from a drag), so only take keyboard-synthesised clicks here — those report
+					// `detail === 0` — or the thread would toggle twice per mouse click.
+					onClick={(e) => {
+						if (e.detail !== 0) return
+						openThreadId.set(editor, openThreadId.get(editor) === thread.id ? null : thread.id)
+					}}
+					onPointerEnter={previewHandlers.onPointerEnter}
+					onPointerLeave={previewHandlers.onPointerLeave}
+					// Focus stands in for hover, so tabbing to a marker gets the same preview.
+					onFocus={previewHandlers.onPointerEnter}
+					onBlur={previewHandlers.onPointerLeave}
+				>
+					<CommentPin resolved={thread.resolved != null} open={open}>
+						{pinContent}
+					</CommentPin>
+				</button>
+				{/* The popover portals up to the menus layer (above the UI panels) so it isn't clipped;
+			    the pin itself stays in the canvas-in-front layer, beneath the UI. */}
+				{open && (
+					<ThreadPopover
+						base={{
+							x: renderPoint.x + POPOVER_OFFSET.thread.x,
+							y: renderPoint.y + POPOVER_OFFSET.thread.y - THREAD_HEADER_BLOCK,
+						}}
+					>
+						<ThreadView editor={editor} thread={thread} {...props} />
+					</ThreadPopover>
+				)}
+				{/* Not while dragging: the pin is being moved, not read, and a panel trailing the
+				    cursor would obscure the drop target. */}
+				{previewShown && !dragPagePoint && (
+					<ThreadPreview
+						editor={editor}
+						threads={previewThreads}
+						variant="thread"
+						point={renderPoint}
+						onSelectThread={() => openThreadId.set(editor, thread.id)}
+						{...previewHandlers}
+						currentUserId={props.currentUserId}
+						resolveAuthor={resolveAuthor}
+					/>
+				)}
+			</div>
+		</>
+	)
+})