@tldraw/commenting 5.3.0-internal.c5c7f1d817d0 → 5.3.0-next.2fa9c61a8de6

package/dist-esm/ui/send-button.mjs

@@ -1,6 +1,25 @@
 import { jsx } from "react/jsx-runtime";
 function SendButton({ label, disabled, onClick }) {
-  return /* @__PURE__ */ jsx("button", { className: "tlui-cmt-send", type: "button", disabled, onClick, children: label });
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      className: "tlui-cmt-send",
+      type: "button",
+      disabled,
+      onClick,
+      "aria-label": label,
+      title: label,
+      children: /* @__PURE__ */ jsx("svg", { width: "15", height: "15", viewBox: "0 0 15 15", fill: "none", "aria-hidden": "true", children: /* @__PURE__ */ jsx(
+        "path",
+        {
+          d: "M7.14645 2.14645C7.34171 1.95118 7.65829 1.95118 7.85355 2.14645L11.8536 6.14645C12.0488 6.34171 12.0488 6.65829 11.8536 6.85355C11.6583 7.04882 11.3417 7.04882 11.1464 6.85355L8 3.70711L8 12.5C8 12.7761 7.77614 13 7.5 13C7.22386 13 7 12.7761 7 12.5L7 3.70711L3.85355 6.85355C3.65829 7.04882 3.34171 7.04882 3.14645 6.85355C2.95118 6.65829 2.95118 6.34171 3.14645 6.14645L7.14645 2.14645Z",
+          fill: "currentColor",
+          fillRule: "evenodd",
+          clipRule: "evenodd"
+        }
+      ) })
+    }
+  );
 }
 export {
   SendButton

package/dist-esm/ui/send-button.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/ui/send-button.tsx"],
-  "sourcesContent": ["/** @public */\nexport interface SendButtonProps {\n\tlabel: string\n\tdisabled?: boolean\n\tonClick?(): void\n}\n\n/** The button that posts a comment. @public @react */\nexport function SendButton({ label, disabled, onClick }: SendButtonProps) {\n\treturn (\n\t\t<button className=\"tlui-cmt-send\" type=\"button\" disabled={disabled} onClick={onClick}>\n\t\t\t{label}\n\t\t</button>\n\t)\n}\n"],
-  "mappings": "AAUE;AAFK,SAAS,WAAW,EAAE,OAAO,UAAU,QAAQ,GAAoB;AACzE,SACC,oBAAC,YAAO,WAAU,iBAAgB,MAAK,UAAS,UAAoB,SAClE,iBACF;AAEF;",
+  "sourcesContent": ["/** @public */\nexport interface SendButtonProps {\n\t/** The button's accessible name (e.g. \"Send\"). Shown as an up-arrow icon, so this is its label. */\n\tlabel: string\n\tdisabled?: boolean\n\tonClick?(): void\n}\n\n/** The button that posts a comment \u2014 an up arrow. @public @react */\nexport function SendButton({ label, disabled, onClick }: SendButtonProps) {\n\treturn (\n\t\t<button\n\t\t\tclassName=\"tlui-cmt-send\"\n\t\t\ttype=\"button\"\n\t\t\tdisabled={disabled}\n\t\t\tonClick={onClick}\n\t\t\taria-label={label}\n\t\t\ttitle={label}\n\t\t>\n\t\t\t<svg width=\"15\" height=\"15\" viewBox=\"0 0 15 15\" fill=\"none\" aria-hidden=\"true\">\n\t\t\t\t<path\n\t\t\t\t\td=\"M7.14645 2.14645C7.34171 1.95118 7.65829 1.95118 7.85355 2.14645L11.8536 6.14645C12.0488 6.34171 12.0488 6.65829 11.8536 6.85355C11.6583 7.04882 11.3417 7.04882 11.1464 6.85355L8 3.70711L8 12.5C8 12.7761 7.77614 13 7.5 13C7.22386 13 7 12.7761 7 12.5L7 3.70711L3.85355 6.85355C3.65829 7.04882 3.34171 7.04882 3.14645 6.85355C2.95118 6.65829 2.95118 6.34171 3.14645 6.14645L7.14645 2.14645Z\"\n\t\t\t\t\tfill=\"currentColor\"\n\t\t\t\t\tfillRule=\"evenodd\"\n\t\t\t\t\tclipRule=\"evenodd\"\n\t\t\t\t/>\n\t\t\t</svg>\n\t\t</button>\n\t)\n}\n"],
+  "mappings": "AAoBI;AAXG,SAAS,WAAW,EAAE,OAAO,UAAU,QAAQ,GAAoB;AACzE,SACC;AAAA,IAAC;AAAA;AAAA,MACA,WAAU;AAAA,MACV,MAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA,cAAY;AAAA,MACZ,OAAO;AAAA,MAEP,8BAAC,SAAI,OAAM,MAAK,QAAO,MAAK,SAAQ,aAAY,MAAK,QAAO,eAAY,QACvE;AAAA,QAAC;AAAA;AAAA,UACA,GAAE;AAAA,UACF,MAAK;AAAA,UACL,UAAS;AAAA,UACT,UAAS;AAAA;AAAA,MACV,GACD;AAAA;AAAA,EACD;AAEF;",
   "names": []
 }

package/dist-esm/ui/tooltip-button.mjs

@@ -0,0 +1,12 @@
+import { jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { TldrawUiTooltip } from "tldraw";
+const TooltipButton = forwardRef(
+  function TooltipButton2({ tooltip, children, ...props }, ref) {
+    return /* @__PURE__ */ jsx(TldrawUiTooltip, { content: tooltip, children: /* @__PURE__ */ jsx("button", { ref, type: "button", "aria-label": tooltip, ...props, children }) });
+  }
+);
+export {
+  TooltipButton
+};
+//# sourceMappingURL=tooltip-button.mjs.map

package/dist-esm/ui/tooltip-button.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ui/tooltip-button.tsx"],
+  "sourcesContent": ["import { type ButtonHTMLAttributes, forwardRef } from 'react'\nimport { TldrawUiTooltip } from 'tldraw'\n\ninterface TooltipButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {\n\ttooltip: string\n}\n\n/** An icon button labelled by a styled tooltip. Forwards ref and props to the underlying button\n *  so `asChild` triggers (dropdown, tooltip) both compose onto the real element. */\nexport const TooltipButton = forwardRef<HTMLButtonElement, TooltipButtonProps>(\n\tfunction TooltipButton({ tooltip, children, ...props }, ref) {\n\t\treturn (\n\t\t\t<TldrawUiTooltip content={tooltip}>\n\t\t\t\t<button ref={ref} type=\"button\" aria-label={tooltip} {...props}>\n\t\t\t\t\t{children}\n\t\t\t\t</button>\n\t\t\t</TldrawUiTooltip>\n\t\t)\n\t}\n)\n"],
+  "mappings": "AAaI;AAbJ,SAAoC,kBAAkB;AACtD,SAAS,uBAAuB;AAQzB,MAAM,gBAAgB;AAAA,EAC5B,SAASA,eAAc,EAAE,SAAS,UAAU,GAAG,MAAM,GAAG,KAAK;AAC5D,WACC,oBAAC,mBAAgB,SAAS,SACzB,8BAAC,YAAO,KAAU,MAAK,UAAS,cAAY,SAAU,GAAG,OACvD,UACF,GACD;AAAA,EAEF;AACD;",
+  "names": ["TooltipButton"]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/commenting",
   "description": "tldraw commenting UI components.",
-  "version": "5.3.0-internal.c5c7f1d817d0",
+  "version": "5.3.0-next.2fa9c61a8de6",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -28,7 +28,7 @@
     "test": "yarn run -T vitest --passWithNoTests",
     "test-coverage": "yarn run -T vitest run --coverage --passWithNoTests",
     "predev": "node ./scripts/copy-css-files.mjs",
-    "dev": "chokidar 'src/ui/comments.css' 'src/canvas/canvas.css' -c 'node ./scripts/copy-css-files.mjs'",
+    "dev": "chokidar '../mentions/mentions.css' 'src/ui/comments.css' 'src/canvas/canvas.css' -c 'node ./scripts/copy-css-files.mjs'",
     "prebuild": "node ./scripts/copy-css-files.mjs",
     "build": "yarn run -T tsx ../../internal/scripts/build-package.ts",
     "build-api": "yarn run -T tsx ../../internal/scripts/build-api.ts",
@@ -38,6 +38,7 @@
     "lint": "yarn run -T tsx ../../internal/scripts/lint.ts"
   },
   "devDependencies": {
+    "@tldraw/driver": "5.3.0-next.2fa9c61a8de6",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.1",
@@ -52,12 +53,11 @@
   },
   "dependencies": {
     "@tiptap/core": "^3.12.1",
-    "@tiptap/extension-mention": "3.13.0",
     "@tiptap/pm": "^3.12.1",
     "@tiptap/react": "^3.12.1",
-    "@tiptap/suggestion": "3.13.0",
-    "@tldraw/utils": "5.3.0-internal.c5c7f1d817d0",
-    "tldraw": "5.3.0-internal.c5c7f1d817d0"
+    "@tldraw/mentions": "5.3.0-next.2fa9c61a8de6",
+    "@tldraw/utils": "5.3.0-next.2fa9c61a8de6",
+    "tldraw": "5.3.0-next.2fa9c61a8de6"
   },
   "module": "dist-esm/index.mjs",
   "source": "src/index.ts",

package/src/canvas/anchor-lifecycle.test.ts

@@ -0,0 +1,290 @@
+import {
+	commentSchemaRecords,
+	createCommentThread,
+	createShapeId,
+	createTLSchema,
+	createTLStore,
+	defaultBindingUtils,
+	defaultShapeUtils,
+	defaultTools,
+	Editor,
+	toRichText,
+	createComment as tlCreateComment,
+	TLPageId,
+	TLShapeId,
+} from 'tldraw'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { registerCommentAnchorLifecycle } from './anchor-lifecycle'
+import { commitCommentMutation, putCommentRecords } from './comment-mutations'
+import { getCommentRecord, getComments } from './comment-store'
+import { CommentTool } from './comment-tool'
+
+/**
+ * These tests need a real editor: the behavior under test is the interplay between store
+ * side effects (the beforeDelete snapshot, operation-complete settlement) and real editor
+ * operations like `deleteShapes` and `moveShapesToPage` — exactly what a stub can't model.
+ */
+
+let editor: Editor
+let dispose: () => void
+
+beforeEach(() => {
+	editor = new Editor({
+		store: createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
+		shapeUtils: defaultShapeUtils,
+		bindingUtils: defaultBindingUtils,
+		tools: defaultTools,
+		getContainer: () => document.body,
+	})
+	dispose = registerCommentAnchorLifecycle(editor)
+})
+
+afterEach(() => {
+	dispose()
+	editor.dispose()
+})
+
+function makeShape(x = 100, y = 100, w = 100, h = 50): TLShapeId {
+	const id = createShapeId()
+	editor.createShape({ id, type: 'geo', x, y, props: { w, h } })
+	return id
+}
+
+function makeThread(shapeId: TLShapeId, anchorX = 0.5, anchorY = 0.5, isPrecise = true) {
+	const thread = createCommentThread({
+		pageId: editor.getCurrentPageId(),
+		anchor: { type: 'shape', shapeId, x: anchorX, y: anchorY, isPrecise },
+		createdBy: 'me',
+	})
+	const comment = tlCreateComment({
+		threadId: thread.id,
+		pageId: thread.pageId,
+		authorId: 'me',
+		body: toRichText('hello'),
+	})
+	putCommentRecords(editor, [thread, comment])
+	return { thread, comment }
+}
+
+function makeSecondPage(): TLPageId {
+	editor.createPage({ name: 'page 2' })
+	return editor.getPages()[1].id
+}
+
+describe('shape deletion', () => {
+	it('converts a precise shape anchor to a point anchor where the pin sat', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+
+		editor.deleteShape(shapeId)
+
+		const updated = getCommentRecord(editor, thread.id)!
+		expect(updated.typeName).toBe('comment-thread')
+		expect((updated as typeof thread).anchor).toEqual({ type: 'point', x: 150, y: 125 })
+	})
+
+	it('converts an imprecise shape anchor where the inset pin is drawn, not at the raw corner', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.2, 0.9, false)
+
+		editor.deleteShape(shapeId)
+
+		// Top-right corner (200, 100) plus the 20px screen inset toward the shape's centre.
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual({ type: 'point', x: 180, y: 120 })
+	})
+
+	it('resolves the imprecise spot from the commenting options when no override is passed', () => {
+		const configured = new Editor({
+			store: createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
+			shapeUtils: defaultShapeUtils,
+			bindingUtils: defaultBindingUtils,
+			tools: [...defaultTools, CommentTool.configure({ impreciseShapeAnchor: { x: 0, y: 1 } })],
+			getContainer: () => document.body,
+		})
+		const disposeConfigured = registerCommentAnchorLifecycle(configured)
+		try {
+			const shapeId = createShapeId()
+			configured.createShape({ id: shapeId, type: 'geo', x: 100, y: 100, props: { w: 100, h: 50 } })
+			const thread = createCommentThread({
+				pageId: configured.getCurrentPageId(),
+				anchor: { type: 'shape', shapeId, x: 0.5, y: 0.5, isPrecise: false },
+				createdBy: 'me',
+			})
+			putCommentRecords(configured, [thread])
+
+			configured.deleteShape(shapeId)
+
+			// Bottom-left corner (100, 150) plus the inset toward the shape's centre.
+			const updated = getCommentRecord(configured, thread.id) as typeof thread
+			expect(updated.anchor).toEqual({ type: 'point', x: 120, y: 130 })
+		} finally {
+			disposeConfigured()
+			configured.dispose()
+		}
+	})
+
+	it('converts anchors on children when their frame is deleted with them', () => {
+		const frameId = createShapeId()
+		editor.createShape({ id: frameId, type: 'frame', x: 0, y: 0, props: { w: 400, h: 400 } })
+		const childId = createShapeId()
+		editor.createShape({
+			id: childId,
+			type: 'geo',
+			parentId: frameId,
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100 },
+		})
+		const { thread } = makeThread(childId, 0.5, 0.5, true)
+
+		editor.deleteShape(frameId)
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual({ type: 'point', x: 100, y: 100 })
+	})
+
+	it('re-attaches the thread when the delete is undone', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+		editor.markHistoryStoppingPoint()
+
+		editor.deleteShape(shapeId)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).anchor.type).toBe('point')
+
+		editor.undo()
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual(thread.anchor)
+	})
+
+	it('keeps the restore when a returning shape cannot resolve its page yet', () => {
+		const frameId = createShapeId()
+		editor.createShape({ id: frameId, type: 'frame', x: 0, y: 0, props: { w: 400, h: 400 } })
+		const childId = createShapeId()
+		editor.createShape({
+			id: childId,
+			type: 'geo',
+			parentId: frameId,
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100 },
+		})
+		const { thread } = makeThread(childId, 0.5, 0.5, true)
+		const childRecord = editor.getShape(childId)!
+		const frameRecord = editor.getShape(frameId)!
+
+		editor.deleteShape(frameId)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).anchor.type).toBe('point')
+
+		// The child returns in an earlier operation than its parent, so its ancestor page can't
+		// resolve when it first reappears.
+		editor.store.put([childRecord])
+		editor.store.put([frameRecord])
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual(thread.anchor)
+	})
+
+	it('re-attaches on undo even when the lifecycle was re-registered in between', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+		editor.markHistoryStoppingPoint()
+
+		editor.deleteShape(shapeId)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).anchor.type).toBe('point')
+
+		// The registering effect re-runs whenever its inputs change identity; conversion memory
+		// must not live and die with any one registration.
+		dispose()
+		dispose = registerCommentAnchorLifecycle(editor)
+
+		editor.undo()
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual(thread.anchor)
+	})
+
+	it('does not re-attach on undo when the pin was moved after the conversion', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+		editor.markHistoryStoppingPoint()
+
+		editor.deleteShape(shapeId)
+		const converted = getCommentRecord(editor, thread.id) as typeof thread
+		commitCommentMutation(editor, () =>
+			putCommentRecords(editor, [{ ...converted, anchor: { type: 'point', x: 900, y: 900 } }])
+		)
+
+		editor.undo()
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual({ type: 'point', x: 900, y: 900 })
+	})
+
+	it('leaves threads on other shapes untouched', () => {
+		const shapeId = makeShape()
+		const otherId = makeShape(300, 300)
+		const { thread } = makeThread(otherId)
+
+		editor.deleteShape(shapeId)
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor.type).toBe('shape')
+	})
+})
+
+describe('moving a shape to another page', () => {
+	it('re-homes the thread and its comments to the new page, keeping the shape anchor', () => {
+		const shapeId = makeShape()
+		const { thread, comment } = makeThread(shapeId)
+		const page2 = makeSecondPage()
+
+		editor.moveShapesToPage([shapeId], page2)
+
+		const updatedThread = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updatedThread.pageId).toBe(page2)
+		expect(updatedThread.anchor).toEqual(thread.anchor)
+		const updatedComment = getComments(editor).find((c) => c.id === comment.id)!
+		expect(updatedComment.pageId).toBe(page2)
+	})
+
+	it('re-homes threads anchored to children of a moved frame', () => {
+		const frameId = createShapeId()
+		editor.createShape({ id: frameId, type: 'frame', x: 0, y: 0, props: { w: 400, h: 400 } })
+		const childId = createShapeId()
+		editor.createShape({
+			id: childId,
+			type: 'geo',
+			parentId: frameId,
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100 },
+		})
+		const { thread } = makeThread(childId)
+		const page2 = makeSecondPage()
+
+		editor.moveShapesToPage([frameId], page2)
+
+		const updatedThread = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updatedThread.pageId).toBe(page2)
+		expect(updatedThread.anchor.type).toBe('shape')
+	})
+
+	it('re-homes the thread back when the move is undone', () => {
+		const shapeId = makeShape()
+		const { thread } = makeThread(shapeId)
+		const page1 = editor.getCurrentPageId()
+		const page2 = makeSecondPage()
+		editor.markHistoryStoppingPoint()
+
+		editor.moveShapesToPage([shapeId], page2)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).pageId).toBe(page2)
+
+		editor.undo()
+
+		const updatedThread = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updatedThread.pageId).toBe(page1)
+		expect(updatedThread.anchor.type).toBe('shape')
+	})
+})

package/src/canvas/anchor-lifecycle.ts

@@ -0,0 +1,205 @@
+import { WeakCache } from '@tldraw/utils'
+import { Editor, TLCommentAnchor, TLCommentThread, TLPageId, TLShapeId, VecLike } from 'tldraw'
+import { commitCommentMutation, putRecordsInCommit } from './comment-mutations'
+import { getCommentRecord, getComments, getCommentThreads, TLCommentRecord } from './comment-store'
+import { anchorPagePoint, impreciseShapePinInset } from './thread-state'
+
+type ShapeAnchor = Extract<TLCommentAnchor, { type: 'shape' }>
+
+/**
+ * Threads converted to point anchors because their shape was deleted, kept so the anchor can be
+ * restored if the shape comes back (page move re-create, undo of the delete). Owned by the
+ * editor, not the registration closure: the registering effect can re-run (a prop identity
+ * change, a remount), and an undo can arrive arbitrarily long after the delete — the memory has
+ * to outlive any one registration.
+ */
+const convertedByShapeCache = new WeakCache<
+	Editor,
+	Map<TLShapeId, { threadId: string; anchor: ShapeAnchor; point: VecLike }[]>
+>()
+
+function isAnchoredToShape(
+	thread: TLCommentThread,
+	shapeId: TLShapeId
+): thread is TLCommentThread & { anchor: ShapeAnchor } {
+	const anchor = thread.anchor
+	return anchor.type === 'shape' && anchor.shapeId === shapeId
+}
+
+/**
+ * Keep shape-anchored threads alive across their shape's lifecycle:
+ *
+ * - When the shape is deleted, the thread converts to a `point` anchor at the spot its pin last
+ *   occupied, so the conversation outlives the shape instead of becoming invisible (a missing
+ *   shape has no bounds, which hides the pin).
+ * - When the shape moves to another page, the thread follows: its `pageId` and each comment's
+ *   denormalized `pageId` update to the shape's new page, and the anchor keeps riding the shape.
+ * - When a deleted shape comes back (a page move re-creates it with its id preserved; undoing a
+ *   delete restores it), the thread re-attaches — unless its pin was manually moved in the
+ *   meantime, in which case the manual placement wins.
+ *
+ * A page move is `deleteShapes` + re-create with preserved ids inside one `editor.run`, but each
+ * store write is its own operation — so at no single moment does "this shape is being moved"
+ * exist as an observable event. The handlers therefore cooperate across operations:
+ * `beforeDelete` snapshots where each affected pin sits (every record is still in the store at
+ * that point, so page bounds resolve even for children of a deleted frame); the
+ * operation-complete pass converts threads whose shape is really gone, remembering the original
+ * anchor; `afterCreate` notes a reappeared shape id, and the operation-complete pass restores
+ * the anchor once the store has settled (creation order within an operation is arbitrary, so a
+ * fresh shape may not resolve an ancestor page mid-operation). Undo/redo of a move
+ * replays as a `parentId` update (remove + add of one id squash to an update in the history
+ * diff), so an `afterChange` handler re-homes threads on cross-page reparents — including
+ * threads anchored to descendants, which move with their parent without change events of their
+ * own.
+ *
+ * Remote changes are ignored: the client that performed the operation runs this same
+ * maintenance and syncs the resulting thread updates. Writes honour the
+ * {@link CommentingOptions.history} option, so the consumer decides whether they're undoable.
+ *
+ * Registered by `CanvasComments` on mount; parts-built consumers can call this directly.
+ * Returns a cleanup function that unregisters all handlers.
+ *
+ * @public
+ */
+export function registerCommentAnchorLifecycle(editor: Editor): () => void {
+	// Pin positions snapshotted during the current operation: shape id -> (thread id -> pin page
+	// point).
+	const pendingByShape = new Map<TLShapeId, Map<string, VecLike | null>>()
+	const convertedByShape = convertedByShapeCache.get(editor, () => new Map())
+
+	function rehomeThread(thread: TLCommentThread, pageId: TLPageId, updates: TLCommentRecord[]) {
+		updates.push({ ...thread, pageId })
+		for (const comment of getComments(editor)) {
+			if (comment.threadId === thread.id) updates.push({ ...comment, pageId })
+		}
+	}
+
+	const disposeBeforeDelete = editor.sideEffects.registerBeforeDeleteHandler(
+		'shape',
+		(shape, source) => {
+			if (source === 'remote') return
+			for (const thread of getCommentThreads(editor)) {
+				if (!isAnchoredToShape(thread, shape.id)) continue
+				let snapshot = pendingByShape.get(shape.id)
+				if (!snapshot) {
+					snapshot = new Map()
+					pendingByShape.set(shape.id, snapshot)
+				}
+				// Snapshot where the pin is drawn, not just the anchor point: imprecise shape pins
+				// render inset toward the shape's centre, and the converted point pin renders at
+				// its point exactly — without the inset the pin would jump on deletion. The inset
+				// is screen-fixed, so bake it in at the current zoom.
+				let point = anchorPagePoint(editor, thread.anchor)
+				const inset = impreciseShapePinInset(editor, thread.anchor)
+				if (point && inset) {
+					const zoom = editor.getZoomLevel()
+					point = { x: point.x + inset.x / zoom, y: point.y + inset.y / zoom }
+				}
+				snapshot.set(thread.id, point)
+			}
+		}
+	)
+
+	// Shape ids from `convertedByShape` re-created during the current operation. Restores are
+	// settled at operation complete rather than in `afterCreate` itself: creation order within an
+	// operation is arbitrary, so a shape can appear before its parent and not resolve an ancestor
+	// page yet — and the conversion memory must outlive any such partial state.
+	const returnedShapeIds = new Set<TLShapeId>()
+
+	const disposeOperationComplete = editor.sideEffects.registerOperationCompleteHandler((source) => {
+		// Only user-sourced handlers populate the maps and only local operations should settle
+		// them; a remote operation completing leaves any (impossible-in-practice) leftovers for
+		// the next local settle rather than judging them against remote state.
+		if (source === 'remote') return
+		if (pendingByShape.size === 0 && returnedShapeIds.size === 0) return
+		const settled = [...pendingByShape.entries()]
+		pendingByShape.clear()
+		const returned = [...returnedShapeIds]
+		returnedShapeIds.clear()
+
+		const updates: TLCommentRecord[] = []
+		for (const [shapeId, threadPoints] of settled) {
+			if (editor.getShape(shapeId)) continue
+			for (const [threadId, point] of threadPoints) {
+				if (!point) continue
+				const thread = getCommentRecord(editor, threadId)
+				if (!thread || thread.typeName !== 'comment-thread') continue
+				if (!isAnchoredToShape(thread, shapeId)) continue
+				let converted = convertedByShape.get(shapeId)
+				if (!converted) {
+					converted = []
+					convertedByShape.set(shapeId, converted)
+				}
+				converted.push({ threadId, anchor: thread.anchor, point })
+				updates.push({ ...thread, anchor: { type: 'point', x: point.x, y: point.y } })
+			}
+		}
+
+		for (const shapeId of returned) {
+			const shape = editor.getShape(shapeId)
+			if (!shape) continue
+			const converted = convertedByShape.get(shapeId)
+			if (!converted) continue
+			convertedByShape.delete(shapeId)
+
+			const pageId = editor.getAncestorPageId(shape)
+			for (const { threadId, anchor, point } of converted) {
+				const thread = getCommentRecord(editor, threadId)
+				if (!thread || thread.typeName !== 'comment-thread') continue
+				// Re-attach only threads still sitting exactly where the conversion left them — a
+				// pin moved since then was placed deliberately, and that placement wins.
+				const current = thread.anchor
+				if (current.type !== 'point' || current.x !== point.x || current.y !== point.y) {
+					continue
+				}
+				if (!pageId || thread.pageId === pageId) {
+					updates.push({ ...thread, anchor })
+				} else {
+					rehomeThread({ ...thread, anchor }, pageId, updates)
+				}
+			}
+		}
+
+		if (updates.length > 0) {
+			commitCommentMutation(editor, () => putRecordsInCommit(editor, updates))
+		}
+	})
+
+	const disposeAfterCreate = editor.sideEffects.registerAfterCreateHandler(
+		'shape',
+		(shape, source) => {
+			if (source === 'remote') return
+			if (convertedByShape.has(shape.id)) returnedShapeIds.add(shape.id)
+		}
+	)
+
+	const disposeAfterChange = editor.sideEffects.registerAfterChangeHandler(
+		'shape',
+		(prev, next, source) => {
+			if (source === 'remote') return
+			if (prev.parentId === next.parentId) return
+			const pageId = editor.getAncestorPageId(next)
+			if (!pageId) return
+			// Descendants move with their parent without change events of their own.
+			const movedIds = editor.getShapeAndDescendantIds([next.id])
+			const updates: TLCommentRecord[] = []
+			for (const thread of getCommentThreads(editor)) {
+				const anchor = thread.anchor
+				if (anchor.type !== 'shape') continue
+				if (!movedIds.has(anchor.shapeId)) continue
+				if (thread.pageId === pageId) continue
+				rehomeThread(thread, pageId, updates)
+			}
+			if (updates.length > 0) {
+				commitCommentMutation(editor, () => putRecordsInCommit(editor, updates))
+			}
+		}
+	)
+
+	return () => {
+		disposeBeforeDelete()
+		disposeOperationComplete()
+		disposeAfterCreate()
+		disposeAfterChange()
+	}
+}