[pull] main from tldraw:main

.claude/skills/shepherd-pr/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: shepherd-pr
+description: Keep an eye on this PR. Review and resolve pull request comments and fix build failures autonomously. Use when asked to review PR feedback, address reviewer comments, fix CI failures, resolve PR threads, or handle PR maintenance tasks like "review PR comments", "fix the build", "address PR feedback", "clean up PR", or "resolve comments". Handles comment triage (resolve false positives, fix trivial issues, flag complex ones), build/lint/type errors, and e2e snapshot updates.
+---
+
+# Review PR
+
+Autonomously review PR comments and build status, resolving what can be done with high confidence (>=80%) and flagging the rest for human review.
+
+## Workflow
+
+Note: this repository requires that you be using node 24. Use `nvm` to switch to node 24 before running any commands:
+
+```bash
+nvm use 24
+```
+
+### 1. Gather context
+
+```bash
+# Get PR number for current branch
+gh pr view --json number,headRefName,url
+
+# Get review threads with resolution status
+gh api graphql -f query='
+  query($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $number) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            comments(first: 50) {
+              nodes {
+                body
+                path
+                line
+                author { login }
+                createdAt
+                databaseId
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+'
+```
+
+Filter to unresolved threads only.
+
+### 2. Triage each unresolved comment
+
+Read the referenced code and investigate. Classify into:
+
+**A. False positive / already resolved** — The issue no longer exists in current code.
+
+- Reply explaining why, citing specific code or commit.
+- Resolve the thread.
+
+**B. Trivial fix (>=80% confidence)** — Obvious, mechanical fix. No design decisions or matters of opinion. Examples: typos, missing null checks, wrong variable names, off-by-one, missing imports.
+
+- Make the fix.
+- Reply describing what was changed.
+- Resolve the thread.
+
+**C. Needs human input (<80% confidence)** — Design question, significant refactor, or ambiguous fix.
+
+- Do NOT resolve.
+- Add to end-of-session summary.
+
+### 3. Reply and resolve threads
+
+Reply to a comment:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
+  -f body="<your reply>"
+```
+
+Resolve a thread:
+
+```bash
+gh api graphql -f query='
+  mutation($threadId: ID!) {
+    resolveReviewThread(input: {threadId: $threadId}) {
+      thread { isResolved }
+    }
+  }
+' -f threadId="$THREAD_ID"
+```
+
+Always push fixes, then reply, then resolve related threads (in that order).
+
+### 4. Check build status
+
+```bash
+gh pr checks --json name,status,conclusion
+```
+
+Investigate failures by category:
+
+**Lint errors** — Run `yarn lint-current`. Fix if mechanical (formatting, import order, unused vars). Flag if the lint rule itself is questionable.
+
+**Type errors** — Run `yarn typecheck` from repo root. Fix straightforward type mismatches. Flag if fix requires architectural decisions.
+
+**Unit test failures** — Run `yarn test run` in relevant workspace. Fix if test expectation is clearly outdated due to intentional code changes. Flag if failure reveals actual bug or design concern.
+
+**E2E snapshot failures** — Determine whether the PR's code changes _should_ cause visual differences:
+
+- If yes (UI changes, style updates): add the `update-snapshots` label to trigger the automated update workflow:
+  ```bash
+  gh pr edit --add-label "update-snapshots"
+  ```
+- If no: flag as unintended regression for human review.
+
+**Mysterious/unexpected failures** — Do not attempt to fix. Flag for human review with error output.
+
+### 5. Commit and push fixes
+
+```bash
+git add <specific files>
+git commit -m "Address PR review feedback
+
+- <summary of changes>"
+git push
+```
+
+Stage specific files only. Never force push. Never use `git add -A`.
+
+### 6. End-of-session summary
+
+Always end with:
+
+```
+## PR review summary
+
+### Resolved
+- <thread>: <what was done>
+
+### Fixed
+- <description of fix>
+
+### Needs your input
+- <thread>: <why it needs human judgment>
+
+### Build status
+- <status of each check, any actions taken>
+```
+
+Omit empty sections.
+
+## Guidelines
+
+- Conservative threshold: only act when >=80% confident the fix is correct and uncontroversial.
+- Never resolve comments raising design questions or matters of opinion.
+- Never resolve without replying first.
+- Read actual code before concluding a comment is a false positive.
+- Verify fixes don't break types (`yarn typecheck`) or lint (`yarn lint-current`).
+- Do not modify test expectations unless change is clearly intentional.

apps/examples/src/examples/data/assets/custom-records/CustomRecordsExample.tsx

@@ -0,0 +1,229 @@
+import { useCallback, useMemo } from 'react'
+import {
+	CustomRecordInfo,
+	T,
+	Tldraw,
+	Vec,
+	createCustomRecordId,
+	createCustomRecordMigrationIds,
+	createCustomRecordMigrationSequence,
+	createTLStore,
+	isCustomRecord,
+	track,
+	useEditor,
+} from 'tldraw'
+import 'tldraw/tldraw.css'
+
+// There's a guide at the bottom of this file!
+
+// [1]
+const MARKER_TYPE = 'marker'
+interface Marker {
+	id: string
+	typeName: typeof MARKER_TYPE
+	x: number
+	y: number
+	label: string
+	icon: string
+}
+
+// [2]
+const markerVersions = createCustomRecordMigrationIds(MARKER_TYPE, {
+	AddIcon: 1,
+})
+
+// [3]
+const markerRecord: CustomRecordInfo = {
+	scope: 'document',
+	validator: T.object({
+		id: T.string,
+		typeName: T.literal(MARKER_TYPE),
+		x: T.number,
+		y: T.number,
+		label: T.string,
+		icon: T.string,
+	}),
+	migrations: createCustomRecordMigrationSequence({
+		sequence: [
+			{
+				id: markerVersions.AddIcon,
+				up: (record) => {
+					record.icon = '📍'
+				},
+				down: (record) => {
+					delete record.icon
+				},
+			},
+		],
+	}),
+	createDefaultProperties: () => ({
+		x: 0,
+		y: 0,
+		label: '',
+		icon: '📍',
+	}),
+}
+
+// [4]
+function createMarkerId(id?: string) {
+	return createCustomRecordId(MARKER_TYPE, id)
+}
+
+const ICONS = ['📍', '⭐', '🏠', '🏢', '🎯', '⚠️']
+
+// [5]
+const MarkerOverlay = track(function MarkerOverlay() {
+	const editor = useEditor()
+
+	const markers = editor.store
+		.allRecords()
+		.filter((r) => isCustomRecord(MARKER_TYPE, r)) as any as Marker[]
+
+	const addMarker = useCallback(() => {
+		const label = prompt('Marker label:')
+		if (!label) return
+		const center = editor.getViewportScreenCenter()
+		const point = editor.screenToPage(center)
+		editor.store.put([
+			{
+				id: createMarkerId(),
+				typeName: MARKER_TYPE,
+				x: point.x,
+				y: point.y,
+				label,
+				icon: ICONS[Math.floor(Math.random() * ICONS.length)],
+			} as any,
+		])
+	}, [editor])
+
+	return (
+		<>
+			{markers.map((marker) => {
+				const screenPoint = editor.pageToViewport(new Vec(marker.x, marker.y))
+				return (
+					<div
+						key={marker.id}
+						style={{
+							position: 'absolute',
+							left: screenPoint.x,
+							top: screenPoint.y,
+							transform: 'translate(-50%, -100%)',
+							display: 'flex',
+							flexDirection: 'column',
+							alignItems: 'center',
+							pointerEvents: 'all',
+							cursor: 'pointer',
+						}}
+						title={marker.label}
+						onPointerDown={(e) => {
+							e.stopPropagation()
+							if (e.button === 2 || e.ctrlKey) {
+								editor.store.remove([marker.id as any])
+							}
+						}}
+					>
+						<span style={{ fontSize: 28 }}>{marker.icon}</span>
+						<span
+							style={{
+								fontSize: 11,
+								background: 'white',
+								border: '1px solid #ccc',
+								borderRadius: 4,
+								padding: '1px 4px',
+								whiteSpace: 'nowrap',
+								maxWidth: 120,
+								overflow: 'hidden',
+								textOverflow: 'ellipsis',
+							}}
+						>
+							{marker.label}
+						</span>
+					</div>
+				)
+			})}
+			<button
+				onClick={addMarker}
+				style={{
+					position: 'absolute',
+					top: 50,
+					right: 10,
+					zIndex: 1000,
+					padding: '6px 12px',
+					borderRadius: 6,
+					border: '1px solid #ccc',
+					background: 'white',
+					cursor: 'pointer',
+					fontSize: 14,
+				}}
+			>
+				+ Add marker
+			</button>
+		</>
+	)
+})
+
+// [6]
+export default function CustomRecordsExample() {
+	const store = useMemo(
+		() =>
+			createTLStore({
+				records: { [MARKER_TYPE]: markerRecord },
+			}),
+		[]
+	)
+
+	return (
+		<div className="tldraw__editor">
+			<Tldraw
+				store={store}
+				components={{
+					InFrontOfTheCanvas: MarkerOverlay,
+				}}
+			/>
+		</div>
+	)
+}
+
+/*
+Introduction:
+
+You can add custom record types to the tldraw store to persist and synchronize
+domain-specific data that doesn't fit into shapes, bindings, or assets. This example
+adds a "marker" record type — like a map pin that marks a location on the canvas.
+
+[1]
+Define your record's type name and TypeScript type. The record must have `id` and
+`typeName` fields — these are required by the store system.
+
+[2]
+Use `createCustomRecordMigrationIds` to define versioned migration IDs for your record
+type. These follow the convention `com.tldraw.{typeName}/{version}`.
+
+[3]
+Create a CustomRecordInfo configuration object. This tells the store how to handle
+your record type:
+- `scope`: 'document' records are persisted and synced. 'session' records are local only.
+- `validator`: Validates the record structure using tldraw's validation library.
+- `migrations`: Optional. Define how the record evolves over time using
+  `createCustomRecordMigrationSequence`. Each migration has an `id` (from the version ids),
+  an `up` function to add/transform fields, and an optional `down` function for backwards
+  compatibility. If omitted, an empty migration sequence is created automatically.
+- `createDefaultProperties`: Factory for default property values.
+
+[4]
+A helper to create properly formatted record IDs. Record IDs follow the pattern
+`typeName:uniqueId`.
+
+[5]
+A React component that renders markers on the canvas and provides a button to add new
+ones. We use the `track` wrapper so the component re-renders when the store changes.
+We use `isCustomRecord` to filter records by type, and `pageToViewport` to position
+the markers correctly as the camera moves. Right-click (or ctrl-click) a marker to
+remove it.
+
+[6]
+We create a store with our custom record type using `createTLStore` and pass it to
+Tldraw via the `store` prop. The `records` option registers our marker type alongside
+the built-in record types (shapes, assets, etc.).
+
+*/