@tldraw/tlschema 4.1.0-next.1b89b40eff1c → 4.1.0-next.9f145d10c7d0

package/src/records/TLPointer.ts

@@ -10,7 +10,25 @@ import { T } from '@tldraw/validate'
 import { idValidator } from '../misc/id-validator'
 
 /**
- * TLPointer
+ * Represents the current pointer/cursor position and activity state.
+ * This record tracks the mouse or touch pointer coordinates and when
+ * the pointer was last active, useful for cursor synchronization in
+ * collaborative environments.
+ *
+ * There is typically one pointer record per browser tab that gets updated
+ * as the user moves their mouse or touches the screen.
+ *
+ * @example
+ * ```ts
+ * const pointer: TLPointer = {
+ *   id: 'pointer:pointer',
+ *   typeName: 'pointer',
+ *   x: 150,
+ *   y: 200,
+ *   lastActivityTimestamp: Date.now(),
+ *   meta: {}
+ * }
+ * ```
  *
  * @public
  */
@@ -21,10 +39,40 @@ export interface TLPointer extends BaseRecord<'pointer', TLPointerId> {
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * A unique identifier for TLPointer records.
+ *
+ * Pointer IDs follow the format 'pointer:' followed by a unique identifier.
+ * Typically there is one pointer record with a constant ID per session.
+ *
+ * @example
+ * ```ts
+ * const pointerId: TLPointerId = 'pointer:pointer'
+ * ```
+ *
+ * @public
+ */
 export type TLPointerId = RecordId<TLPointer>
 
-/** @public */
+/**
+ * Runtime validator for TLPointer records. Validates the structure
+ * and types of all pointer properties to ensure data integrity.
+ *
+ * @example
+ * ```ts
+ * const pointer = {
+ *   id: 'pointer:pointer',
+ *   typeName: 'pointer',
+ *   x: 100,
+ *   y: 200,
+ *   lastActivityTimestamp: Date.now(),
+ *   meta: {}
+ * }
+ * const isValid = pointerValidator.isValid(pointer) // true
+ * ```
+ *
+ * @public
+ */
 export const pointerValidator: T.Validator<TLPointer> = T.model(
 	'pointer',
 	T.object({
@@ -37,12 +85,30 @@ export const pointerValidator: T.Validator<TLPointer> = T.model(
 	})
 )
 
-/** @public */
+/**
+ * Migration version identifiers for TLPointer records. Each version
+ * represents a schema change that requires data transformation when
+ * loading older documents.
+ *
+ * @public
+ */
 export const pointerVersions = createMigrationIds('com.tldraw.pointer', {
 	AddMeta: 1,
 })
 
-/** @public */
+/**
+ * Migration sequence for TLPointer records. Defines how to transform
+ * pointer records between different schema versions, ensuring data
+ * compatibility when loading documents created with different versions.
+ *
+ * @example
+ * ```ts
+ * // Migrations are applied automatically when loading documents
+ * const migratedPointer = pointerMigrations.migrate(oldPointer, targetVersion)
+ * ```
+ *
+ * @public
+ */
 export const pointerMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.pointer',
 	recordType: 'pointer',
@@ -56,7 +122,24 @@ export const pointerMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * The RecordType definition for TLPointer records. Defines validation,
+ * scope, and default properties for pointer records in the tldraw store.
+ *
+ * Pointer records are scoped to the session level, meaning they are
+ * specific to a browser tab and don't persist across sessions.
+ *
+ * @example
+ * ```ts
+ * const pointer = PointerRecordType.create({
+ *   id: 'pointer:pointer',
+ *   x: 0,
+ *   y: 0
+ * })
+ * ```
+ *
+ * @public
+ */
 export const PointerRecordType = createRecordType<TLPointer>('pointer', {
 	validator: pointerValidator,
 	scope: 'session',
@@ -69,5 +152,20 @@ export const PointerRecordType = createRecordType<TLPointer>('pointer', {
 	})
 )
 
-/** @public */
+/**
+ * The constant ID used for the singleton TLPointer record.
+ *
+ * Since each browser tab typically has one pointer, this constant ID
+ * is used universally across the application.
+ *
+ * @example
+ * ```ts
+ * const pointer = store.get(TLPOINTER_ID)
+ * if (pointer) {
+ *   console.log('Pointer at:', pointer.x, pointer.y)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const TLPOINTER_ID = PointerRecordType.createId('pointer')

package/src/records/TLPresence.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from 'vitest'
+import {
+	instancePresenceMigrations,
+	instancePresenceValidator,
+	instancePresenceVersions,
+	TLInstancePresenceID,
+} from './TLPresence'
+
+describe('instancePresenceValidator', () => {
+	it('should validate valid instance presence records', () => {
+		const validPresence = {
+			typeName: 'instance_presence',
+			id: 'instance_presence:test' as TLInstancePresenceID,
+			userId: 'user123',
+			userName: 'Test User',
+			lastActivityTimestamp: null,
+			color: '#007AFF',
+			camera: null,
+			selectedShapeIds: [],
+			currentPageId: 'page:main' as any,
+			brush: null,
+			scribbles: [],
+			screenBounds: null,
+			followingUserId: null,
+			cursor: null,
+			chatMessage: '',
+			meta: {},
+		}
+
+		expect(() => instancePresenceValidator.validate(validPresence)).not.toThrow()
+		const validated = instancePresenceValidator.validate(validPresence)
+		expect(validated).toEqual(validPresence)
+	})
+
+	it('should validate presence with complete data', () => {
+		const complexPresence = {
+			typeName: 'instance_presence',
+			id: 'instance_presence:complex' as TLInstancePresenceID,
+			userId: 'user456',
+			userName: 'Complex User',
+			lastActivityTimestamp: Date.now(),
+			color: '#FF3B30',
+			camera: { x: -100, y: 200, z: 0.75 },
+			selectedShapeIds: ['shape:1' as any, 'shape:2' as any],
+			currentPageId: 'page:design' as any,
+			brush: { x: 50, y: 75, w: 150, h: 100 },
+			scribbles: [
+				{
+					id: 'scribble:1',
+					points: [{ x: 0, y: 0, z: 0.5 }],
+					size: 4,
+					color: 'black',
+					opacity: 1,
+					state: 'starting',
+					delay: 0,
+					shrink: 0,
+					taper: false,
+				},
+			],
+			screenBounds: { x: 0, y: 0, w: 2560, h: 1440 },
+			followingUserId: 'leader123',
+			cursor: { x: 300, y: 400, type: 'pointer', rotation: 45 },
+			chatMessage: 'Working on design!',
+			meta: { team: 'design', role: 'designer' },
+		}
+
+		expect(() => instancePresenceValidator.validate(complexPresence)).not.toThrow()
+	})
+
+	it('should reject invalid typeName', () => {
+		const invalidPresence = {
+			typeName: 'not-instance-presence',
+			id: 'instance_presence:test' as TLInstancePresenceID,
+			userId: 'user123',
+			userName: 'Test',
+			lastActivityTimestamp: null,
+			color: '#000000',
+			camera: null,
+			selectedShapeIds: [],
+			currentPageId: 'page:main' as any,
+			brush: null,
+			scribbles: [],
+			screenBounds: null,
+			followingUserId: null,
+			cursor: null,
+			chatMessage: '',
+			meta: {},
+		}
+
+		expect(() => instancePresenceValidator.validate(invalidPresence)).toThrow()
+	})
+})
+
+describe('instancePresenceMigrations', () => {
+	it('should migrate AddScribbleDelay correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.AddScribbleDelay
+		)!
+
+		const oldRecordWithScribble: any = {
+			scribble: { points: [], size: 4, color: 'black' },
+		}
+		migration.up(oldRecordWithScribble)
+		expect(oldRecordWithScribble.scribble.delay).toBe(0)
+
+		const oldRecordWithoutScribble: any = {
+			scribble: null,
+		}
+		migration.up(oldRecordWithoutScribble)
+		expect(oldRecordWithoutScribble.scribble).toBe(null)
+	})
+
+	it('should migrate RemoveInstanceId correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.RemoveInstanceId
+		)!
+		const oldRecord: any = {
+			instanceId: 'instance:removed',
+			otherProp: 'keep-me',
+		}
+		migration.up(oldRecord)
+
+		expect(oldRecord.instanceId).toBeUndefined()
+		expect(oldRecord.otherProp).toBe('keep-me')
+	})
+
+	it('should migrate AddChatMessage correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.AddChatMessage
+		)!
+		const oldRecord: any = { id: 'instance_presence:test' }
+		migration.up(oldRecord)
+
+		expect(oldRecord.chatMessage).toBe('')
+	})
+
+	it('should migrate AddMeta correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.AddMeta
+		)!
+		const oldRecord: any = { id: 'instance_presence:test' }
+		migration.up(oldRecord)
+
+		expect(oldRecord.meta).toEqual({})
+	})
+
+	it('should handle RenameSelectedShapeIds migration (noop)', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.RenameSelectedShapeIds
+		)!
+		const oldRecord: any = { selectedShapeIds: ['shape:1'] }
+		const originalRecord = { ...oldRecord }
+		migration.up(oldRecord)
+
+		// Should be a noop
+		expect(oldRecord).toEqual(originalRecord)
+	})
+
+	it('should handle NullableCameraCursor migration up (noop)', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.NullableCameraCursor
+		)!
+		const record: any = { camera: null, cursor: null }
+		const originalRecord = { ...record }
+		migration.up(record)
+
+		// Should be a noop
+		expect(record).toEqual(originalRecord)
+	})
+
+	it('should handle NullableCameraCursor migration down', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.NullableCameraCursor
+		)!
+		expect(migration.down).toBeDefined()
+
+		const record: any = {
+			camera: null,
+			lastActivityTimestamp: null,
+			cursor: null,
+			screenBounds: null,
+		}
+		migration.down!(record)
+
+		expect(record.camera).toEqual({ x: 0, y: 0, z: 1 })
+		expect(record.lastActivityTimestamp).toBe(0)
+		expect(record.cursor).toEqual({ type: 'default', x: 0, y: 0, rotation: 0 })
+		expect(record.screenBounds).toEqual({ x: 0, y: 0, w: 1, h: 1 })
+	})
+})

package/src/records/TLPresence.ts

@@ -14,7 +14,30 @@ import { scribbleValidator, TLScribble } from '../misc/TLScribble'
 import { TLPageId } from './TLPage'
 import { TLShapeId } from './TLShape'
 
-/** @public */
+/**
+ * Represents the presence state of a user in a collaborative tldraw session.
+ * This record tracks what another user is doing: their cursor position, selected
+ * shapes, current page, and other real-time activity indicators.
+ *
+ * Instance presence records are used in multiplayer environments to show
+ * where other collaborators are working and what they're doing.
+ *
+ * @example
+ * ```ts
+ * const presence: TLInstancePresence = {
+ *   id: 'instance_presence:user123',
+ *   typeName: 'instance_presence',
+ *   userId: 'user123',
+ *   userName: 'Alice',
+ *   color: '#FF6B6B',
+ *   cursor: { x: 100, y: 150, type: 'default', rotation: 0 },
+ *   currentPageId: 'page:main',
+ *   selectedShapeIds: ['shape:rect1']
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLInstancePresence extends BaseRecord<'instance_presence', TLInstancePresenceID> {
 	userId: string
 	userName: string
@@ -37,10 +60,42 @@ export interface TLInstancePresence extends BaseRecord<'instance_presence', TLIn
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * A unique identifier for TLInstancePresence records.
+ *
+ * Instance presence IDs follow the format 'instance_presence:' followed
+ * by a unique identifier, typically the user ID.
+ *
+ * @example
+ * ```ts
+ * const presenceId: TLInstancePresenceID = 'instance_presence:user123'
+ * ```
+ *
+ * @public
+ */
 export type TLInstancePresenceID = RecordId<TLInstancePresence>
 
-/** @public */
+/**
+ * Runtime validator for TLInstancePresence records. Validates the structure
+ * and types of all instance presence properties to ensure data integrity.
+ *
+ * @example
+ * ```ts
+ * const presence = {
+ *   id: 'instance_presence:user1',
+ *   typeName: 'instance_presence',
+ *   userId: 'user1',
+ *   userName: 'John',
+ *   color: '#007AFF',
+ *   cursor: { x: 0, y: 0, type: 'default', rotation: 0 },
+ *   currentPageId: 'page:main',
+ *   selectedShapeIds: []
+ * }
+ * const isValid = instancePresenceValidator.isValid(presence) // true
+ * ```
+ *
+ * @public
+ */
 export const instancePresenceValidator: T.Validator<TLInstancePresence> = T.model(
 	'instance_presence',
 	T.object({
@@ -72,7 +127,13 @@ export const instancePresenceValidator: T.Validator<TLInstancePresence> = T.mode
 	})
 )
 
-/** @public */
+/**
+ * Migration version identifiers for TLInstancePresence records. Each version
+ * represents a schema change that requires data transformation when loading
+ * older documents.
+ *
+ * @public
+ */
 export const instancePresenceVersions = createMigrationIds('com.tldraw.instance_presence', {
 	AddScribbleDelay: 1,
 	RemoveInstanceId: 2,
@@ -82,6 +143,19 @@ export const instancePresenceVersions = createMigrationIds('com.tldraw.instance_
 	NullableCameraCursor: 6,
 } as const)
 
+/**
+ * Migration sequence for TLInstancePresence records. Defines how to transform
+ * instance presence records between different schema versions, ensuring data
+ * compatibility when loading documents created with different versions.
+ *
+ * @example
+ * ```ts
+ * // Migrations are applied automatically when loading documents
+ * const migrated = instancePresenceMigrations.migrate(oldPresence, targetVersion)
+ * ```
+ *
+ * @public
+ */
 export const instancePresenceMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.instance_presence',
 	recordType: 'instance_presence',
@@ -141,7 +215,27 @@ export const instancePresenceMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * The RecordType definition for TLInstancePresence records. Defines validation,
+ * scope, and default properties for instance presence records.
+ *
+ * Instance presence records are scoped to the presence level, meaning they
+ * represent real-time collaborative state that is ephemeral and tied to
+ * active user sessions.
+ *
+ * @example
+ * ```ts
+ * const presence = InstancePresenceRecordType.create({
+ *   id: 'instance_presence:user1',
+ *   userId: 'user1',
+ *   userName: 'Alice',
+ *   color: '#FF6B6B',
+ *   currentPageId: 'page:main'
+ * })
+ * ```
+ *
+ * @public
+ */
 export const InstancePresenceRecordType = createRecordType<TLInstancePresence>(
 	'instance_presence',
 	{

package/src/records/TLRecord.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { TLRecord } from './TLRecord'
+
+describe('TLRecord', () => {
+	it('should support type discrimination by typeName', () => {
+		function processRecord(record: TLRecord): string {
+			// TypeScript should be able to narrow types based on typeName
+			switch (record.typeName) {
+				case 'shape':
+					return `Shape at (${record.x}, ${record.y})`
+				case 'page':
+					return `Page: ${record.name}`
+				case 'asset':
+					return `Asset: ${record.type}`
+				case 'binding':
+					return `Binding from ${record.fromId} to ${record.toId}`
+				case 'camera':
+					return `Camera at (${record.x}, ${record.y}) zoom: ${record.z}`
+				case 'document':
+					return `Document: ${record.name}, grid: ${record.gridSize}`
+				case 'instance':
+					return `Instance on page ${record.currentPageId}`
+				case 'instance_page_state':
+					return `Page state for ${record.pageId}`
+				case 'instance_presence':
+					return `Presence of ${record.userName}`
+				case 'pointer':
+					return `Pointer at (${record.x}, ${record.y})`
+				default:
+					// This should never be reached if all cases are handled
+					return 'Unknown record type'
+			}
+		}
+
+		// Test that the discriminated union works correctly
+		const shapeRecord: TLRecord = {
+			id: 'shape:test' as any,
+			typeName: 'shape',
+			type: 'geo',
+			x: 50,
+			y: 100,
+			rotation: 0,
+			index: 'a1' as any,
+			parentId: 'page:main' as any,
+			isLocked: false,
+			opacity: 1,
+			props: {
+				geo: 'rectangle',
+				w: 80,
+				h: 80,
+				color: 'black',
+				fill: 'none',
+				dash: 'draw',
+				size: 'm',
+			},
+			meta: {},
+		}
+
+		const pageRecord: TLRecord = {
+			id: 'page:test' as any,
+			typeName: 'page',
+			name: 'Test Page',
+			index: 'a1' as any,
+			meta: {},
+		}
+
+		expect(processRecord(shapeRecord)).toBe('Shape at (50, 100)')
+		expect(processRecord(pageRecord)).toBe('Page: Test Page')
+	})
+})

package/src/records/TLRecord.ts

@@ -9,7 +9,49 @@ import { TLPointer } from './TLPointer'
 import { TLInstancePresence } from './TLPresence'
 import { TLShape } from './TLShape'
 
-/** @public */
+/**
+ * Union type representing all possible record types in a tldraw store.
+ * This includes both persistent records (documents, pages, shapes, assets, bindings)
+ * and session/presence records (cameras, instances, pointers, page states).
+ *
+ * Records are organized by scope:
+ * - **document**: Persisted across sessions (shapes, pages, assets, bindings, documents)
+ * - **session**: Local to current session (cameras, instances, page states)
+ * - **presence**: Ephemeral user presence data (pointers, instance presence)
+ *
+ * @example
+ * ```ts
+ * // Function that works with any record type
+ * function processRecord(record: TLRecord) {
+ *   switch (record.typeName) {
+ *     case 'shape':
+ *       console.log(`Shape: ${record.type} at (${record.x}, ${record.y})`)
+ *       break
+ *     case 'page':
+ *       console.log(`Page: ${record.name}`)
+ *       break
+ *     case 'asset':
+ *       console.log(`Asset: ${record.type}`)
+ *       break
+ *     case 'camera':
+ *       console.log(`Camera at (${record.x}, ${record.y}) zoom: ${record.z}`)
+ *       break
+ *     // ... handle other record types
+ *   }
+ * }
+ *
+ * // Get all records from store
+ * const allRecords: TLRecord[] = store.allRecords()
+ *
+ * // Filter by record type using type guards
+ * import { isShape, isPage, isAsset } from '@tldraw/tlschema'
+ * const shapes = allRecords.filter(isShape)
+ * const pages = allRecords.filter(isPage)
+ * const assets = allRecords.filter(isAsset)
+ * ```
+ *
+ * @public
+ */
 export type TLRecord =
 	| TLAsset
 	| TLBinding