@tldraw/tlschema 4.1.0-canary.e653ec63c99b → 4.1.0-canary.f2f81cd6fe2c

package/src/TLStore.ts

@@ -6,7 +6,7 @@ import {
 	StoreSnapshot,
 	StoreValidationFailure,
 } from '@tldraw/store'
-import { IndexKey, JsonObject, annotateError, structuredClone } from '@tldraw/utils'
+import { IndexKey, JsonObject, annotateError, sortByIndex, structuredClone } from '@tldraw/utils'
 import { TLAsset, TLAssetId } from './records/TLAsset'
 import { CameraRecordType, TLCameraId } from './records/TLCamera'
 import { DocumentRecordType, TLDOCUMENT_ID } from './records/TLDocument'
@@ -16,16 +16,14 @@ import { InstancePageStateRecordType, TLInstancePageStateId } from './records/TL
 import { PointerRecordType, TLPOINTER_ID } from './records/TLPointer'
 import { TLRecord } from './records/TLRecord'
 
-function sortByIndex<T extends { index: string }>(a: T, b: T) {
-	if (a.index < b.index) {
-		return -1
-	} else if (a.index > b.index) {
-		return 1
-	}
-	return 0
-}
-
-function redactRecordForErrorReporting(record: any) {
+/**
+ * Redacts the source of an asset record for error reporting.
+ *
+ * @param record - The asset record to redact
+ * @returns The redacted record
+ * @internal
+ */
+export function redactRecordForErrorReporting(record: any) {
 	if (record.typeName === 'asset') {
 		if ('src' in record) {
 			record.src = '<redacted>'
@@ -37,16 +35,75 @@ function redactRecordForErrorReporting(record: any) {
 	}
 }
 
-/** @public */
+/**
+ * The complete schema type for a tldraw store, defining the structure and validation rules
+ * for all tldraw records and store properties.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { createTLSchema } from '@tldraw/tlschema'
+ *
+ * const schema = createTLSchema()
+ * const storeSchema: TLStoreSchema = schema
+ * ```
+ */
 export type TLStoreSchema = StoreSchema<TLRecord, TLStoreProps>
 
-/** @public */
+/**
+ * A serialized representation of a tldraw store that can be persisted or transmitted.
+ * Contains all store records in a JSON-serializable format.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Serialize a store
+ * const serializedStore: TLSerializedStore = store.serialize()
+ *
+ * // Save to localStorage
+ * localStorage.setItem('drawing', JSON.stringify(serializedStore))
+ * ```
+ */
 export type TLSerializedStore = SerializedStore<TLRecord>
 
-/** @public */
+/**
+ * A snapshot of a tldraw store at a specific point in time, containing all records
+ * and metadata. Used for persistence, synchronization, and creating store backups.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Create a snapshot
+ * const snapshot: TLStoreSnapshot = store.getSnapshot()
+ *
+ * // Restore from snapshot
+ * store.loadSnapshot(snapshot)
+ * ```
+ */
 export type TLStoreSnapshot = StoreSnapshot<TLRecord>
 
-/** @public */
+/**
+ * Context information provided when resolving asset URLs, containing details about
+ * the current rendering environment and user's connection to optimize asset delivery.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const assetStore: TLAssetStore = {
+ *   async resolve(asset, context: TLAssetContext) {
+ *     // Use low resolution for slow connections
+ *     if (context.networkEffectiveType === 'slow-2g') {
+ *       return `${asset.props.src}?quality=low`
+ *     }
+ *     // Use high DPI version for retina displays
+ *     if (context.dpr > 1) {
+ *       return `${asset.props.src}@2x`
+ *     }
+ *     return asset.props.src
+ *   }
+ * }
+ * ```
+ */
 export interface TLAssetContext {
 	/**
 	 * The scale at which the asset is being rendered on-screen relative to its native dimensions.
@@ -76,6 +133,9 @@ export interface TLAssetContext {
 }
 
 /**
+ * Interface for storing and managing assets (images, videos, etc.) in tldraw.
+ * Provides methods for uploading, resolving, and removing assets from storage.
+ *
  * A `TLAssetStore` sits alongside the main {@link TLStore} and is responsible for storing and
  * retrieving large assets such as images. Generally, this should be part of a wider sync system:
  *
@@ -87,6 +147,24 @@ export interface TLAssetContext {
  *   e.g. an S3 bucket.
  *
  * @public
+ * @example
+ * ```ts
+ * // Simple in-memory asset store
+ * const assetStore: TLAssetStore = {
+ *   async upload(asset, file) {
+ *     const dataUrl = await fileToDataUrl(file)
+ *     return { src: dataUrl }
+ *   },
+ *
+ *   async resolve(asset, context) {
+ *     return asset.props.src
+ *   },
+ *
+ *   async remove(assetIds) {
+ *     // Clean up if needed
+ *   }
+ * }
+ * ```
  */
 export interface TLAssetStore {
 	/**
@@ -122,24 +200,106 @@ export interface TLAssetStore {
 	remove?(assetIds: TLAssetId[]): Promise<void>
 }
 
-/** @public */
+/**
+ * Configuration properties for a tldraw store, defining its behavior and integrations.
+ * These props are passed when creating a new store instance.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const storeProps: TLStoreProps = {
+ *   defaultName: 'My Drawing',
+ *   assets: myAssetStore,
+ *   onMount: (editor) => {
+ *     console.log('Editor mounted')
+ *     return () => console.log('Editor unmounted')
+ *   },
+ *   collaboration: {
+ *     status: statusSignal,
+ *     mode: modeSignal
+ *   }
+ * }
+ *
+ * const store = new Store({ schema, props: storeProps })
+ * ```
+ */
 export interface TLStoreProps {
+	/** Default name for new documents created in this store */
 	defaultName: string
+	/** Asset store implementation for handling file uploads and storage */
 	assets: Required<TLAssetStore>
 	/**
-	 * Called an {@link @tldraw/editor#Editor} connected to this store is mounted.
+	 * Called when an {@link @tldraw/editor#Editor} connected to this store is mounted.
+	 * Can optionally return a cleanup function that will be called when unmounted.
+	 *
+	 * @param editor - The editor instance that was mounted
+	 * @returns Optional cleanup function
 	 */
 	onMount(editor: unknown): void | (() => void)
+	/** Optional collaboration configuration for multiplayer features */
 	collaboration?: {
+		/** Signal indicating online/offline collaboration status */
 		status: Signal<'online' | 'offline'> | null
+		/** Signal indicating collaboration mode permissions */
 		mode?: Signal<'readonly' | 'readwrite'> | null
 	}
 }
 
-/** @public */
+/**
+ * The main tldraw store type, representing a reactive database of tldraw records
+ * with associated store properties. This is the central data structure that holds
+ * all shapes, assets, pages, and user state.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { Store } from '@tldraw/store'
+ * import { createTLSchema } from '@tldraw/tlschema'
+ *
+ * const schema = createTLSchema()
+ * const store: TLStore = new Store({
+ *   schema,
+ *   props: {
+ *     defaultName: 'Untitled',
+ *     assets: myAssetStore,
+ *     onMount: () => console.log('Store mounted')
+ *   }
+ * })
+ * ```
+ */
 export type TLStore = Store<TLRecord, TLStoreProps>
 
-/** @public */
+/**
+ * Default validation failure handler for tldraw stores. This function is called
+ * when a record fails validation during store operations. It annotates errors
+ * with debugging information and determines whether to allow invalid records
+ * during store initialization.
+ *
+ * @param options - The validation failure details
+ *   - error - The validation error that occurred
+ *   - phase - The store operation phase when validation failed
+ *   - record - The invalid record that caused the failure
+ *   - recordBefore - The previous state of the record (if applicable)
+ * @returns The record to use (typically throws the annotated error)
+ * @throws The original validation error with additional debugging context
+ *
+ * @public
+ * @example
+ * ```ts
+ * const store = new Store({
+ *   schema,
+ *   props: storeProps,
+ *   onValidationFailure // Use this as the validation failure handler
+ * })
+ *
+ * // The handler will be called automatically when validation fails
+ * try {
+ *   store.put([invalidRecord])
+ * } catch (error) {
+ *   // Error will contain debugging information added by onValidationFailure
+ * }
+ * ```
+ */
 export function onValidationFailure({
 	error,
 	phase,
@@ -179,7 +339,32 @@ function getDefaultPages() {
 	]
 }
 
-/** @internal */
+/**
+ * Creates an integrity checker function that ensures the tldraw store maintains
+ * a consistent and usable state. The checker validates that required records exist
+ * and relationships between records are maintained.
+ *
+ * The integrity checker ensures:
+ * - Document and pointer records exist
+ * - At least one page exists
+ * - Instance state references valid pages
+ * - Page states and cameras exist for all pages
+ * - Shape references in page states are valid
+ *
+ * @param store - The tldraw store to check for integrity
+ * @returns A function that when called, validates and fixes store integrity
+ *
+ * @internal
+ * @example
+ * ```ts
+ * const checker = createIntegrityChecker(store)
+ *
+ * // Run integrity check (typically called automatically)
+ * checker()
+ *
+ * // The checker will create missing records and fix invalid references
+ * ```
+ */
 export function createIntegrityChecker(store: Store<TLRecord, TLStoreProps>): () => void {
 	const $pageIds = store.query.ids('page')
 	const $pageStates = store.query.records('instance_page_state')

package/src/assets/TLBaseAsset.ts

@@ -4,26 +4,109 @@ import { T } from '@tldraw/validate'
 import { idValidator } from '../misc/id-validator'
 import { TLAssetId } from '../records/TLAsset'
 
-/** @public */
+/**
+ * Base interface for all asset records in tldraw. Assets represent external resources
+ * like images, videos, or bookmarks that shapes can reference. This interface extends
+ * the base record system with asset-specific typing.
+ *
+ * @param Type - The specific asset type identifier (e.g., 'image', 'video', 'bookmark')
+ * @param Props - The properties object specific to this asset type
+ *
+ * @example
+ * ```ts
+ * // Define a custom asset type
+ * interface MyCustomAsset extends TLBaseAsset<'custom', { url: string; title: string }> {}
+ *
+ * const customAsset: MyCustomAsset = {
+ *   id: 'asset:custom123',
+ *   typeName: 'asset',
+ *   type: 'custom',
+ *   props: {
+ *     url: 'https://example.com',
+ *     title: 'My Custom Asset'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLBaseAsset<Type extends string, Props> extends BaseRecord<'asset', TLAssetId> {
+	/** The specific type of this asset (e.g., 'image', 'video', 'bookmark') */
 	type: Type
+	/** Type-specific properties for this asset */
 	props: Props
+	/** User-defined metadata that can be attached to this asset */
 	meta: JsonObject
 }
 
 /**
- * A validator for asset record type Ids.
+ * A validator for asset record type IDs. This validator ensures that asset IDs
+ * follow the correct format and type structure required by tldraw's asset system.
+ * Asset IDs are prefixed with 'asset:' followed by a unique identifier.
+ *
+ * @example
+ * ```ts
+ * import { assetIdValidator } from '@tldraw/tlschema'
+ *
+ * // Valid asset ID
+ * const validId = 'asset:abc123'
+ * console.log(assetIdValidator.isValid(validId)) // true
  *
- * @public */
+ * // Invalid asset ID
+ * const invalidId = 'shape:abc123'
+ * console.log(assetIdValidator.isValid(invalidId)) // false
+ * ```
+ *
+ * @public
+ */
 export const assetIdValidator = idValidator<TLAssetId>('asset')
 
 /**
- * Create a validator for an asset record type.
+ * Creates a validator for a specific asset record type. This factory function generates
+ * a complete validator that validates the entire asset record structure including the
+ * base properties (id, typeName, type, meta) and the type-specific props.
+ *
+ * @param type - The asset type identifier (e.g., 'image', 'video', 'bookmark')
+ * @param props - The validator for the asset's type-specific properties
+ * @returns A complete validator for the asset record type
+ *
+ * @example
+ * ```ts
+ * import { createAssetValidator, TLBaseAsset } from '@tldraw/tlschema'
+ * import { T } from '@tldraw/validate'
+ *
+ * // Define a custom asset type
+ * type TLCustomAsset = TLBaseAsset<'custom', {
+ *   url: string
+ *   title: string
+ *   description?: string
+ * }>
+ *
+ * // Create validator for the custom asset
+ * const customAssetValidator = createAssetValidator('custom', T.object({
+ *   url: T.string,
+ *   title: T.string,
+ *   description: T.string.optional()
+ * }))
+ *
+ * // Use the validator
+ * const assetData = {
+ *   id: 'asset:custom123',
+ *   typeName: 'asset' as const,
+ *   type: 'custom' as const,
+ *   props: {
+ *     url: 'https://example.com',
+ *     title: 'My Custom Asset'
+ *   },
+ *   meta: {}
+ * }
  *
- * @param type - The type of the asset
- * @param props - The validator for the asset's props
+ * const validatedAsset = customAssetValidator.validate(assetData)
+ * ```
  *
- * @public */
+ * @public
+ */
 export function createAssetValidator<Type extends string, Props extends JsonObject>(
 	type: Type,
 	props: T.Validator<Props>

package/src/assets/TLBookmarkAsset.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { bookmarkAssetVersions } from './TLBookmarkAsset'
+
+describe('TLBookmarkAsset', () => {
+	describe('MakeUrlsValid migration', () => {
+		const { up, down } = getTestMigration(bookmarkAssetVersions.MakeUrlsValid)
+
+		it('should clean invalid src URLs and preserve valid ones', () => {
+			const assetWithInvalidSrc = {
+				id: 'asset:bookmark1',
+				type: 'bookmark',
+				props: {
+					title: 'Test Bookmark',
+					description: 'Test Description',
+					image: 'https://example.com/image.jpg',
+					src: 'invalid-url-format',
+				},
+			}
+
+			const result = up(assetWithInvalidSrc)
+			expect(result.props.src).toBe('')
+
+			// Test valid URL is preserved
+			const assetWithValidSrc = {
+				...assetWithInvalidSrc,
+				props: { ...assetWithInvalidSrc.props, src: 'https://example.com' },
+			}
+			const validResult = up(assetWithValidSrc)
+			expect(validResult.props.src).toBe('https://example.com')
+		})
+
+		it('should be a no-op down migration', () => {
+			const asset = {
+				id: 'asset:bookmark1',
+				type: 'bookmark',
+				props: {
+					title: 'Test Bookmark',
+					description: 'Test Description',
+					image: 'https://example.com/image.jpg',
+					src: 'https://example.com',
+				},
+			}
+
+			const result = down(asset)
+			expect(result).toEqual(asset)
+		})
+	})
+
+	describe('AddFavicon migration', () => {
+		const { up, down } = getTestMigration(bookmarkAssetVersions.AddFavicon)
+
+		it('should add favicon property and clean invalid URLs', () => {
+			// Test adding favicon property to asset without one
+			const assetWithoutFavicon = {
+				id: 'asset:bookmark1',
+				type: 'bookmark',
+				props: {
+					title: 'Test Bookmark',
+					description: 'Test Description',
+					image: 'https://example.com/image.jpg',
+					src: 'https://example.com',
+				},
+			}
+
+			const result = up(assetWithoutFavicon)
+			expect(result.props.favicon).toBe('')
+
+			// Test cleaning invalid favicon URL
+			const assetWithInvalidFavicon = {
+				...assetWithoutFavicon,
+				props: { ...assetWithoutFavicon.props, favicon: 'invalid-url' },
+			}
+			const cleanResult = up(assetWithInvalidFavicon)
+			expect(cleanResult.props.favicon).toBe('')
+		})
+
+		it('should remove favicon property in down migration', () => {
+			const assetWithFavicon = {
+				id: 'asset:bookmark1',
+				type: 'bookmark',
+				props: {
+					title: 'Test Bookmark',
+					description: 'Test Description',
+					image: 'https://example.com/image.jpg',
+					src: 'https://example.com',
+					favicon: 'https://example.com/favicon.ico',
+				},
+			}
+
+			const result = down(assetWithFavicon)
+			expect(result.props).not.toHaveProperty('favicon')
+			expect(result.props.title).toBe('Test Bookmark')
+		})
+	})
+})

package/src/assets/TLBookmarkAsset.ts

@@ -18,7 +18,30 @@ export type TLBookmarkAsset = TLBaseAsset<
 	}
 >
 
-/** @public */
+/**
+ * Validator for TLBookmarkAsset records. Validates the structure and data types
+ * of bookmark asset properties including title, description, image, favicon, and source URL.
+ *
+ * @example
+ * ```ts
+ * const bookmarkData = {
+ *   id: 'asset:bookmark1',
+ *   typeName: 'asset',
+ *   type: 'bookmark',
+ *   props: {
+ *     title: 'Example Website',
+ *     description: 'A great example site',
+ *     image: 'https://example.com/preview.jpg',
+ *     favicon: 'https://example.com/favicon.ico',
+ *     src: 'https://example.com'
+ *   }
+ * }
+ *
+ * const isValid = bookmarkAssetValidator.isValid(bookmarkData)
+ * ```
+ *
+ * @public
+ */
 export const bookmarkAssetValidator: T.Validator<TLBookmarkAsset> = createAssetValidator(
 	'bookmark',
 	T.object({
@@ -35,9 +58,36 @@ const Versions = createMigrationIds('com.tldraw.asset.bookmark', {
 	AddFavicon: 2,
 } as const)
 
+/**
+ * Migration version identifiers for bookmark assets. These versions track
+ * the evolution of the bookmark asset schema over time.
+ *
+ * Available versions:
+ * - `MakeUrlsValid` (v1): Ensures src URLs are valid or empty
+ * - `AddFavicon` (v2): Adds favicon property to bookmark assets
+ *
+ * @example
+ * ```ts
+ * import { bookmarkAssetVersions } from '@tldraw/tlschema'
+ *
+ * // Check if a migration exists
+ * console.log(bookmarkAssetVersions.AddFavicon) // 2
+ * ```
+ *
+ * @public
+ */
 export { Versions as bookmarkAssetVersions }
 
-/** @public */
+/**
+ * Migration sequence for bookmark assets. Handles the evolution of bookmark asset
+ * data structure over time, ensuring backward and forward compatibility.
+ *
+ * The migration sequence includes:
+ * 1. **MakeUrlsValid** (v1): Validates and cleans up src URLs, setting invalid URLs to empty string
+ * 2. **AddFavicon** (v2): Adds the favicon property and validates it, setting invalid favicons to empty string
+ *
+ * @public
+ */
 export const bookmarkAssetMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.asset.bookmark',
 	recordType: 'asset',