feat(editor): add shape attribution, TLUserStore, and extensible user records (tldraw#8147)

In order to let developers track who created and last edited shapes —
and to display that information in the UI — this PR introduces a shape
attribution system built on a reactive `TLUserStore` provider interface,
note-specific "first edited by" labeling, and extensible user records
via `createTLSchema`.

### What's included

**`TLUserStore` interface** (`@tldraw/tlschema`)
A new optional `users` prop on the editor (and `<Tldraw />`) that
connects tldraw to your auth system. Both methods return reactive
`Signal`s so the editor automatically tracks changes to user data:
- `getCurrentUser()` — returns a `Signal<TLUser | null>` for the active
user (used for both presence broadcasting and shape attribution)
- `resolve(userId)` — returns a `Signal<TLUser | null>` to resolve any
user ID to display info (for rendering attribution labels)

When no provider is given, a default implementation falls back to
`UserPreferences` + the collaborator presence list.

**Unified `TLUser` record type** (`@tldraw/tlschema`)
Collapsed the previous `TLUser` + `TLUserInfo` types into a single
`TLUser` store record (following the `TLAsset` pattern). User records
are document-scoped and persist alongside shapes, assets, and pages —
surviving across boards, clipboard paste, and `.tldr` files.

**Extensible user metadata via `createTLSchema`**
SDK users can now extend user records with custom validated metadata:
```ts
const schema = createTLSchema({
  user: {
    meta: {
      isAdmin: T.boolean,
      department: T.string,
    },
  },
})
```
Custom meta fields are validated when present but treated as optional,
so existing user records remain valid. The new
`createUserRecordType(config?)` function builds the record type with
extended validators.

**Note shape "first edited by" label**
`NoteShapeUtil` now tracks `textFirstEditedBy` in its props and renders
a small attribution label (first name) in the bottom-right corner of the
note. The label resolves the display name through the user store and
shows a tooltip with the full name. This tracks who first added text to
the note — subsequent typo fixes by others don't change the attribution.
Includes a note shape migration (`AddFirstEditedBy`).

<img width="757" height="414" alt="Screenshot 2026-03-04 at 11 20 58"
src="https://github.com/user-attachments/assets/190ea36d-873e-44d7-aa3c-8fefebc7db56"
/>

**New editor methods**
- `editor.getAttributionUser(userId)` — resolves a user record by ID,
asking the `TLUserStore` first (the app's source of truth), falling back
to the `user:` record in the store
- `editor.getAttributionUserId()` — returns the current user's ID for
attribution purposes
- `editor.getAttributionDisplayName(userId)` — resolves a display name
for a user ID, with the same lookup order

**New "Users" example category with four examples**
- **Attribution** — demonstrates wiring up `TLUserStore` with a mock
user switcher and an attribution inspector panel
- **Attribution timeline** — shows a history scrubber that steps through
undo history and displays per-shape attribution metadata
- **Custom user metadata** — shows how to extend `TLUser` records with
custom meta fields (isAdmin, department)
- **Multiplayer sync with custom user data** — integrates custom user
data into tldraw sync



https://github.com/user-attachments/assets/bd476596-67ca-483b-8d1d-bec3f82e35d5



https://github.com/user-attachments/assets/c31f8db6-c7ae-4e21-b0d5-48e079eb5767


fixes tldraw#6115

**Unit tests**
New `attribution.test.ts` covering attribution user stamping, custom
user stores, note `textFirstEditedBy` tracking, and display name
resolution.

### Change type

- [x] `feature`

### Test plan

1. Open the Attribution example — switch between users and create/edit
shapes; verify attribution labels update in the inspector panel
2. Open the Attribution Timeline example — draw shapes, use the scrubber
to step through history, verify per-shape metadata display
3. Open the Custom User Metadata example — switch between users and
verify custom meta (department, admin badge) displays
4. Create note shapes — type text, verify the first name appears in the
bottom-right corner; hover for full name tooltip
5. Copy a note with attribution to a different board — verify the
attribution label persists

- [x] Unit tests

### API changes

- Added `TLUserStore` interface (with reactive `Signal`-based methods)
- Added `TLUser` record type (unified from previous `TLUser` +
`TLUserInfo`)
- Added `UserRecordType`, `createUserId`, `isUserId`, `userIdValidator`
- Added `createUserRecordType(config?)` for extensible user schemas
- Added `UserSchemaInfo` interface
- Added `user` parameter to `createTLSchema()`
- Added `textFirstEditedBy` prop to `TLNoteShapeProps`
- Added `Editor.getAttributionUser()`
- Added `Editor.getAttributionUserId()`
- Added `Editor.getAttributionDisplayName()`
- Removed `TLUserInfo` type (collapsed into `TLUser`)

### Release notes

- Add shape attribution system with `TLUserStore` for connecting tldraw
to your auth system.
- `TLUserStore` methods are reactive (`Signal`-based) so the editor
automatically tracks user data changes.
- Add extensible user records: pass custom meta validators to
`createTLSchema({ user: { meta: ... } })`.
- Add `createUserRecordType()` for building user record types with
custom validation.
- Note shapes now display a small "first edited by" label in the corner.
- New "Users" example category with attribution, attribution timeline,
custom user metadata, and sync examples.

Author: mimecuvalo

.gitignore

@@ -124,9 +124,10 @@ license-report.md
 opencode.json
 
 # PR walkthrough intermediate files
+.claude/worktrees
 .claude/skills/pr-walkthrough/tmp
 .claude/skills/pr-walkthrough/out
 .claude/skills/pr-walkthrough/video/node_modules
 .claude/skills/pr-walkthrough/video/dist
 .claude/skills/pr-walkthrough/video/public/audio-*
-.claude/skills/pr-walkthrough/video/public/manifest.json
+.claude/skills/pr-walkthrough/video/public/manifest.json

apps/docs/content/sdk-features/collaboration.mdx

@@ -117,47 +117,53 @@ See the [Assets](/docs/assets) documentation for more on implementing asset stor
 
 ## User identity
 
-By default, users get a random name and color. To customize this, pass `userInfo`:
+By default, users get a random name and color from localStorage. To customize this, pass a `users` store whose methods return reactive `Signal` values:
 
 ```tsx
-const store = useSyncDemo({
-	roomId: 'my-room',
-	userInfo: {
-		id: 'user-123',
+import { computed, UserRecordType, createUserId } from 'tldraw'
+
+const currentUser = computed('currentUser', () =>
+	UserRecordType.create({
+		id: createUserId('user-123'),
 		name: 'Alice',
 		color: '#ff0000',
+	})
+)
+
+const store = useSyncDemo({
+	roomId: 'my-room',
+	users: {
+		currentUser,
 	},
 })
 ```
 
-For dynamic user info that updates during the session, use an atom:
+The `users` store is also used for shape attribution — the same `currentUser` signal stamps shapes with user IDs. Provide a `resolve` method to look up other users by ID:
 
 ```tsx
-import { atom } from 'tldraw'
-
-const userInfo = atom('userInfo', {
-	id: 'user-123',
-	name: 'Alice',
-	color: '#ff0000',
-})
-
-// Later, update the user info
-userInfo.set({ ...userInfo.get(), name: 'Alice (away)' })
-
-const store = useSyncDemo({
-	roomId: 'my-room',
-	userInfo,
-})
+const users: TLUserStore = {
+	currentUser: myAuth.currentUser$,
+	resolve: (userId) => myUserCache.getSignal(userId),
+}
 ```
 
-### Integrating with useTldrawUser
+### Integrating with useTldrawCurrentUser
 
-If you need to let users edit their preferences through tldraw's UI, use `useTldrawUser`:
+If you need to let users edit their preferences through tldraw's UI, use `useTldrawCurrentUser`:
 
 ```tsx
 import { useSyncDemo } from '@tldraw/sync'
-import { useState } from 'react'
-import { TLUserPreferences, Tldraw, useTldrawUser } from 'tldraw'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import {
+	atom,
+	computed,
+	createUserId,
+	TLUserPreferences,
+	TLUserStore,
+	Tldraw,
+	UserRecordType,
+	useTldrawCurrentUser,
+} from 'tldraw'
 
 export default function App({ roomId }: { roomId: string }) {
 	const [userPreferences, setUserPreferences] = useState<TLUserPreferences>({
@@ -167,8 +173,25 @@ export default function App({ roomId }: { roomId: string }) {
 		colorScheme: 'dark',
 	})
 
-	const store = useSyncDemo({ roomId, userInfo: userPreferences })
-	const user = useTldrawUser({ userPreferences, setUserPreferences })
+	const userPrefsAtom = useRef(atom('userPrefs', userPreferences)).current
+	useEffect(() => {
+		userPrefsAtom.set(userPreferences)
+	}, [userPreferences, userPrefsAtom])
+
+	const users: TLUserStore = useMemo(() => {
+		const currentUser = computed('currentUser', () => {
+			const p = userPrefsAtom.get()
+			return UserRecordType.create({
+				id: createUserId(p.id),
+				name: p.name ?? '',
+				color: p.color ?? undefined,
+			})
+		})
+		return { currentUser }
+	}, [userPrefsAtom])
+
+	const store = useSyncDemo({ roomId, users })
+	const user = useTldrawCurrentUser({ userPreferences, setUserPreferences })
 
 	return (
 		<div style={{ position: 'fixed', inset: 0 }}>

apps/docs/content/sdk-features/options.mdx

@@ -324,7 +324,7 @@ These props configure how the editor initializes:
 | `textOptions`        | `TLTextOptions`                                         | Rich text editor configuration              |
 | `deepLinks`          | `true \| TLDeepLinkOptions`                             | Sync camera state with URL                  |
 | `getShapeVisibility` | `(shape, editor) => 'visible' \| 'hidden' \| 'inherit'` | Conditionally hide shapes                   |
-| `user`               | `TLUser`                                                | Current user information                    |
+| `user`               | `TLCurrentUser`                                         | Current user information                    |
 | `inferDarkMode`      | `boolean`                                               | Infer dark mode from OS preference          |
 | `licenseKey`         | `string`                                                | License key to remove watermark             |
 

apps/dotcom/client/src/pages/admin.tsx

@@ -10,9 +10,9 @@ import { RefObject, useCallback, useEffect, useRef, useState } from 'react'
 import { Navigate } from 'react-router-dom'
 import { fetch } from 'tldraw'
 import { TlaButton } from '../tla/components/TlaButton/TlaButton'
-import { useTldrawUser } from '../tla/hooks/useUser'
-import { saveMigrationLog } from './migrationLogsDB'
+import { useTldrawCurrentUser } from '../tla/hooks/useUser'
 import styles from './admin.module.css'
+import { saveMigrationLog } from './migrationLogsDB'
 
 // Helper component for structured data display.
 function StructuredDataDisplay({ data }: { data: ZStoreData }) {
@@ -81,7 +81,7 @@ function UserDataSummary({ data }: { data: ZStoreData }) {
 }
 
 export function Component() {
-	const user = useTldrawUser()
+	const user = useTldrawCurrentUser()
 	const [data, setData] = useState<any>(null)
 	const [error, setError] = useState(null as string | null)
 	const [replicatorData, setReplicatorData] = useState(null)

apps/dotcom/client/src/tla/app/TldrawApp.ts

@@ -56,8 +56,8 @@ import {
 	assertExists,
 	atom,
 	computed,
+	createTLCurrentUser,
 	createTLSchema,
-	createTLUser,
 	dataUrlToFile,
 	defaultUserPreferences,
 	getUserPreferences,
@@ -491,7 +491,7 @@ export class TldrawApp {
 		this.lastGroupFileOrderings.delete(groupId)
 	}
 
-	tlUser = createTLUser({
+	tlUser = createTLCurrentUser({
 		userPreferences: computed('user prefs', () => {
 			const user = this.getUser()
 			return {

apps/dotcom/client/src/tla/components/TlaEditor/TlaEditor.tsx

@@ -8,9 +8,13 @@ import {
 	TLComponents,
 	TLSessionStateSnapshot,
 	TLUiDialogsContextType,
+	TLUserStore,
 	Tldraw,
 	TldrawUiMenuItem,
+	UserRecordType,
+	computed,
 	createSessionStateSnapshotSignal,
+	createUserId,
 	parseDeepLinkString,
 	react,
 	throttle,
@@ -36,7 +40,7 @@ import { TldrawApp } from '../../app/TldrawApp'
 import { useMaybeApp } from '../../hooks/useAppState'
 import { ReadyWrapper, useSetIsReady } from '../../hooks/useIsReady'
 import { useNewRoomCreationTracking } from '../../hooks/useNewRoomCreationTracking'
-import { useTldrawUser } from '../../hooks/useUser'
+import { useTldrawCurrentUser } from '../../hooks/useUser'
 import { maybeSlurp } from '../../utils/slurping'
 import { TlaEditorErrorFallback } from './editor-components/TlaEditorErrorFallback'
 import { TlaEditorMenuPanel } from './editor-components/TlaEditorMenuPanel'
@@ -170,7 +174,7 @@ function TlaEditorInner({ fileSlug, deepLinks }: TlaEditorProps) {
 		[addDialog, trackRoomLoaded, trackNewRoomCreation, app, fileId, remountImageShapes, setIsReady]
 	)
 
-	const user = useTldrawUser()
+	const user = useTldrawCurrentUser()
 	const getUserToken = useEvent(async () => {
 		return (await user?.getToken()) ?? 'not-logged-in'
 	})
@@ -179,6 +183,22 @@ function TlaEditorInner({ fileSlug, deepLinks }: TlaEditorProps) {
 		return multiplayerAssetStore({ getFileId: () => fileId, getToken: getUserToken })
 	}, [fileId, getUserToken])
 
+	const users: TLUserStore | undefined = useMemo(() => {
+		const prefs = app?.tlUser.userPreferences
+		if (!prefs) return undefined
+		const currentUser = computed('currentUser', () => {
+			const p = prefs.get()
+			return UserRecordType.create({
+				id: createUserId(p.id),
+				name: p.name ?? '',
+				color: p.color ?? '',
+			})
+		})
+		return {
+			currentUser,
+		}
+	}, [app?.tlUser.userPreferences])
+
 	const store = useSync({
 		uri: useCallback(async () => {
 			const url = new URL(`${MULTIPLAYER_SERVER}/app/file/${fileSlug}`)
@@ -188,7 +208,7 @@ function TlaEditorInner({ fileSlug, deepLinks }: TlaEditorProps) {
 			return url.toString()
 		}, [fileSlug, hasUser, getUserToken]),
 		assets,
-		userInfo: app?.tlUser.userPreferences,
+		users,
 		onCustomMessageReceived: useCallback((message: TLCustomServerEvent) => {
 			trackEvent(message.type)
 		}, []),

apps/dotcom/client/src/tla/components/TlaFileShareMenu/Tabs/TlaInviteTab.tsx

@@ -5,7 +5,7 @@ import { routes } from '../../../../routeDefs'
 import { useApp } from '../../../hooks/useAppState'
 import { useEditorDeepLink } from '../../../hooks/useDeepLink'
 import { useHasFileAdminRights } from '../../../hooks/useIsFileOwner'
-import { useTldrawUser } from '../../../hooks/useUser'
+import { useTldrawCurrentUser } from '../../../hooks/useUser'
 import { useTldrawAppUiEvents } from '../../../utils/app-ui-events'
 import { copyTextToClipboard } from '../../../utils/copy'
 import { F, defineMessages, useMsg } from '../../../utils/i18n'
@@ -60,7 +60,7 @@ export function TlaInviteTab({ fileId }: { fileId: string }) {
 
 function TlaSharedToggle({ isShared, fileId }: { isShared: boolean; fileId: string }) {
 	const app = useApp()
-	const user = useTldrawUser()
+	const user = useTldrawCurrentUser()
 	const trackEvent = useTldrawAppUiEvents()
 	if (!user) throw Error('should have auth')
 
@@ -95,7 +95,7 @@ function TlaSharedToggle({ isShared, fileId }: { isShared: boolean; fileId: stri
 
 function TlaSelectSharedLinkType({ fileId }: { fileId: string }) {
 	const app = useApp()
-	const user = useTldrawUser()
+	const user = useTldrawCurrentUser()
 	const trackEvent = useTldrawAppUiEvents()
 	if (!user) throw Error('should have auth')
 

apps/dotcom/client/src/tla/hooks/useUser.tsx

@@ -57,12 +57,12 @@ export function UserProvider({ children }: { children: ReactNode }) {
 	return <UserContext.Provider value={value}>{children}</UserContext.Provider>
 }
 
-export function useTldrawUser() {
+export function useTldrawCurrentUser() {
 	return useContext(UserContext)
 }
 
 export function useLoggedInUser() {
-	const user = useTldrawUser()
+	const user = useTldrawCurrentUser()
 	if (!user) throw new Error('User not signed in')
 	return user
 }

apps/dotcom/client/src/utils/csp.ts

@@ -75,5 +75,10 @@ export const csp = Object.keys(cspDirectives)
 
 export const cspDev = Object.keys(cspDirectives)
 	.filter((key) => key !== 'report-uri')
-	.map((directive) => `${directive} ${cspDirectives[directive].join(' ')}`)
+	.map((directive) => {
+		const values = cspDirectives[directive]
+		// We allow data: urls for frame-src to allow debugging SVG embeds in dev.
+		if (directive === 'frame-src') return `${directive} ${[...values, 'data:'].join(' ')}`
+		return `${directive} ${values.join(' ')}`
+	})
 	.join('; ')

apps/examples/src/examples.tsx

@@ -20,6 +20,7 @@ const categories = [
 	['layout', 'Page layout'],
 	['events', 'Events & effects'],
 	['shapes/tools', 'Shapes & tools'],
+	['users', 'Users'],
 	['collaboration', 'Collaboration'],
 	['data/assets', 'Data & assets'],
 	['use-cases', 'Use cases'],