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

package/dist-cjs/index.d.ts

@@ -27,28 +27,289 @@ export declare function assertIdType<R extends UnknownRecord>(id: string | undef
 export declare class AtomMap<K, V> implements Map<K, V> {
     private readonly name;
     private atoms;
+    /**
+     * Creates a new AtomMap instance.
+     *
+     * name - A unique name for this map, used for atom identification
+     * entries - Optional initial entries to populate the map with
+     * @example
+     * ```ts
+     * // Create an empty map
+     * const map = new AtomMap('userMap')
+     *
+     * // Create a map with initial data
+     * const initialData: [string, number][] = [['a', 1], ['b', 2]]
+     * const mapWithData = new AtomMap('numbersMap', initialData)
+     * ```
+     */
     constructor(name: string, entries?: Iterable<readonly [K, V]>);
     /* Excluded from this release type: getAtom */
+    /**
+     * Gets the value associated with a key. Returns undefined if the key doesn't exist.
+     * This method is reactive and will cause reactive contexts to update when the value changes.
+     *
+     * @param key - The key to retrieve the value for
+     * @returns The value associated with the key, or undefined if not found
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('name', 'Alice')
+     * console.log(map.get('name')) // 'Alice'
+     * console.log(map.get('missing')) // undefined
+     * ```
+     */
     get(key: K): undefined | V;
+    /**
+     * Gets the value associated with a key without creating reactive dependencies.
+     * This method will not cause reactive contexts to update when the value changes.
+     *
+     * @param key - The key to retrieve the value for
+     * @returns The value associated with the key, or undefined if not found
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('count', 42)
+     * const value = map.__unsafe__getWithoutCapture('count') // No reactive subscription
+     * ```
+     */
     __unsafe__getWithoutCapture(key: K): undefined | V;
+    /**
+     * Checks whether a key exists in the map.
+     * This method is reactive and will cause reactive contexts to update when keys are added or removed.
+     *
+     * @param key - The key to check for
+     * @returns True if the key exists in the map, false otherwise
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * console.log(map.has('name')) // false
+     * map.set('name', 'Alice')
+     * console.log(map.has('name')) // true
+     * ```
+     */
     has(key: K): boolean;
+    /**
+     * Checks whether a key exists in the map without creating reactive dependencies.
+     * This method will not cause reactive contexts to update when keys are added or removed.
+     *
+     * @param key - The key to check for
+     * @returns True if the key exists in the map, false otherwise
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('active', true)
+     * const exists = map.__unsafe__hasWithoutCapture('active') // No reactive subscription
+     * ```
+     */
     __unsafe__hasWithoutCapture(key: K): boolean;
+    /**
+     * Sets a value for the given key. If the key already exists, its value is updated.
+     * If the key doesn't exist, a new entry is created.
+     *
+     * @param key - The key to set the value for
+     * @param value - The value to associate with the key
+     * @returns This AtomMap instance for method chaining
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('name', 'Alice').set('age', 30)
+     * ```
+     */
     set(key: K, value: V): this;
+    /**
+     * Updates an existing value using an updater function.
+     *
+     * @param key - The key of the value to update
+     * @param updater - A function that receives the current value and returns the new value
+     * @throws Error if the key doesn't exist in the map
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('count', 5)
+     * map.update('count', count => count + 1) // count is now 6
+     * ```
+     */
     update(key: K, updater: (value: V) => V): void;
+    /**
+     * Removes a key-value pair from the map.
+     *
+     * @param key - The key to remove
+     * @returns True if the key existed and was removed, false if it didn't exist
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('temp', 'value')
+     * console.log(map.delete('temp')) // true
+     * console.log(map.delete('missing')) // false
+     * ```
+     */
     delete(key: K): boolean;
+    /**
+     * Removes multiple key-value pairs from the map in a single transaction.
+     *
+     * @param keys - An iterable of keys to remove
+     * @returns An array of [key, value] pairs that were actually deleted
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('a', 1).set('b', 2).set('c', 3)
+     * const deleted = map.deleteMany(['a', 'c', 'missing'])
+     * console.log(deleted) // [['a', 1], ['c', 3]]
+     * ```
+     */
     deleteMany(keys: Iterable<K>): [K, V][];
+    /**
+     * Removes all key-value pairs from the map.
+     *
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('a', 1).set('b', 2)
+     * map.clear()
+     * console.log(map.size) // 0
+     * ```
+     */
     clear(): void;
+    /**
+     * Returns an iterator that yields [key, value] pairs for each entry in the map.
+     * This method is reactive and will cause reactive contexts to update when entries change.
+     *
+     * @returns A generator that yields [key, value] tuples
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('a', 1).set('b', 2)
+     * for (const [key, value] of map.entries()) {
+     *   console.log(`${key}: ${value}`)
+     * }
+     * ```
+     */
     entries(): Generator<[K, V], undefined, unknown>;
+    /**
+     * Returns an iterator that yields all keys in the map.
+     * This method is reactive and will cause reactive contexts to update when keys change.
+     *
+     * @returns A generator that yields keys
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('name', 'Alice').set('age', 30)
+     * for (const key of map.keys()) {
+     *   console.log(key) // 'name', 'age'
+     * }
+     * ```
+     */
     keys(): Generator<K, undefined, unknown>;
+    /**
+     * Returns an iterator that yields all values in the map.
+     * This method is reactive and will cause reactive contexts to update when values change.
+     *
+     * @returns A generator that yields values
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('name', 'Alice').set('age', 30)
+     * for (const value of map.values()) {
+     *   console.log(value) // 'Alice', 30
+     * }
+     * ```
+     */
     values(): Generator<V, undefined, unknown>;
+    /**
+     * The number of key-value pairs in the map.
+     * This property is reactive and will cause reactive contexts to update when the size changes.
+     *
+     * @returns The number of entries in the map
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * console.log(map.size) // 0
+     * map.set('a', 1)
+     * console.log(map.size) // 1
+     * ```
+     */
     get size(): number;
+    /**
+     * Executes a provided function once for each key-value pair in the map.
+     * This method is reactive and will cause reactive contexts to update when entries change.
+     *
+     * @param callbackfn - Function to execute for each entry
+     *   - value - The value of the current entry
+     *   - key - The key of the current entry
+     *   - map - The AtomMap being traversed
+     * @param thisArg - Value to use as `this` when executing the callback
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('a', 1).set('b', 2)
+     * map.forEach((value, key) => {
+     *   console.log(`${key} = ${value}`)
+     * })
+     * ```
+     */
     forEach(callbackfn: (value: V, key: K, map: AtomMap<K, V>) => void, thisArg?: any): void;
+    /**
+     * Returns the default iterator for the map, which is the same as entries().
+     * This allows the map to be used in for...of loops and other iterable contexts.
+     *
+     * @returns The same iterator as entries()
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * map.set('a', 1).set('b', 2)
+     *
+     * // These are equivalent:
+     * for (const [key, value] of map) {
+     *   console.log(`${key}: ${value}`)
+     * }
+     *
+     * for (const [key, value] of map.entries()) {
+     *   console.log(`${key}: ${value}`)
+     * }
+     * ```
+     */
     [Symbol.iterator](): Generator<[K, V], undefined, unknown>;
+    /**
+     * The string tag used by Object.prototype.toString for this class.
+     *
+     * @example
+     * ```ts
+     * const map = new AtomMap('myMap')
+     * console.log(Object.prototype.toString.call(map)) // '[object AtomMap]'
+     * ```
+     */
     [Symbol.toStringTag]: string;
 }
 
 /**
- * The base record that all records must extend.
+ * The base record interface that all records in the store must extend.
+ * This interface provides the fundamental structure required for all records: a unique ID and a type name.
+ * The type parameters ensure type safety and prevent mixing of different record types.
+ *
+ * @example
+ * ```ts
+ * // Define a Book record that extends BaseRecord
+ * interface Book extends BaseRecord<'book', RecordId<Book>> {
+ *   title: string
+ *   author: string
+ *   publishedYear: number
+ * }
+ *
+ * // Define an Author record
+ * interface Author extends BaseRecord<'author', RecordId<Author>> {
+ *   name: string
+ *   birthYear: number
+ * }
+ *
+ * // Usage with RecordType
+ * const Book = createRecordType<Book>('book', { scope: 'document' })
+ * const book = Book.create({
+ *   title: '1984',
+ *   author: 'George Orwell',
+ *   publishedYear: 1949
+ * })
+ * // Results in: { id: 'book:abc123', typeName: 'book', title: '1984', ... }
+ * ```
  *
  * @public
  */
@@ -57,59 +318,135 @@ export declare interface BaseRecord<TypeName extends string, Id extends RecordId
     readonly typeName: TypeName;
 }
 
-/** @public */
+/**
+ * The source of a change to the store.
+ * - `'user'` - Changes originating from local user actions
+ * - `'remote'` - Changes originating from remote synchronization
+ *
+ * @public
+ */
 export declare type ChangeSource = 'remote' | 'user';
 
 /**
  * A diff describing the changes to a collection.
  *
+ * @example
+ * ```ts
+ * const diff: CollectionDiff<string> = {
+ *   added: new Set(['newItem']),
+ *   removed: new Set(['oldItem'])
+ * }
+ * ```
+ *
  * @public
  */
 export declare interface CollectionDiff<T> {
+    /** Items that were added to the collection */
     added?: Set<T>;
+    /** Items that were removed from the collection */
     removed?: Set<T>;
 }
 
 /**
- * A record store is a collection of records of different types.
+ * A computed cache that stores derived data for records.
+ * The cache automatically updates when underlying records change and cleans up when records are deleted.
+ *
+ * @example
+ * ```ts
+ * const expensiveCache = store.createComputedCache(
+ *   'expensive',
+ *   (book: Book) => performExpensiveCalculation(book)
+ * )
+ *
+ * const result = expensiveCache.get(bookId)
+ * ```
  *
  * @public
  */
 export declare interface ComputedCache<Data, R extends UnknownRecord> {
+    /**
+     * Get the cached data for a record by its ID.
+     *
+     * @param id - The ID of the record
+     * @returns The cached data or undefined if the record doesn't exist
+     */
     get(id: IdOf<R>): Data | undefined;
 }
 
 /**
- * Free version of {@link Store.createComputedCache}.
+ * Create a computed cache that works with any StoreObject (store or object containing a store).
+ * This is a standalone version of Store.createComputedCache that can work with multiple store instances.
  *
  * @example
  * ```ts
- * const myCache = createComputedCache('myCache', (editor: Editor, shape: TLShape) => {
- *     return editor.getSomethingExpensive(shape)
- * })
+ * const expensiveCache = createComputedCache(
+ *   'expensiveData',
+ *   (context: { store: Store<Book> }, book: Book) => {
+ *     return performExpensiveCalculation(book)
+ *   }
+ * )
  *
- * myCache.get(editor, shape.id)
+ * // Use with different store instances
+ * const result1 = expensiveCache.get(storeObject1, bookId)
+ * const result2 = expensiveCache.get(storeObject2, bookId)
  * ```
  *
+ * @param name - A unique name for the cache (used for debugging)
+ * @param derive - Function that derives a value from the context and record
+ * @param opts - Optional configuration for equality checks
+ * @returns A cache that can be used with multiple store instances
  * @public
  */
 export declare function createComputedCache<Context extends StoreObject<any>, Result, Record extends StoreObjectRecordType<Context> = StoreObjectRecordType<Context>>(name: string, derive: (context: Context, record: Record) => Result | undefined, opts?: CreateComputedCacheOpts<Result, Record>): {
     get(context: Context, id: IdOf<Record>): Result | undefined;
 };
 
-/** @public */
+/**
+ * Options for creating a computed cache.
+ *
+ * @example
+ * ```ts
+ * const options: CreateComputedCacheOpts<string[], Book> = {
+ *   areRecordsEqual: (a, b) => a.title === b.title,
+ *   areResultsEqual: (a, b) => JSON.stringify(a) === JSON.stringify(b)
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface CreateComputedCacheOpts<Data, R extends UnknownRecord> {
+    /** Custom equality function for comparing records */
     areRecordsEqual?(a: R, b: R): boolean;
+    /** Custom equality function for comparing results */
     areResultsEqual?(a: Data, b: Data): boolean;
 }
 
 /* Excluded from this release type: createEmptyRecordsDiff */
 
 /**
- * Creates a named set of migration ids given a named set of version numbers and a sequence id.
+ * Creates a named set of migration IDs from version numbers and a sequence ID.
+ *
+ * This utility function helps generate properly formatted migration IDs that follow
+ * the required `sequenceId/version` pattern. It takes a sequence ID and a record
+ * of named versions, returning migration IDs that can be used in migration definitions.
  *
  * See the [migration guide](https://tldraw.dev/docs/persistence#Migrations) for more info on how to use this API.
- * @public
+ * @param sequenceId - The sequence identifier (e.g., 'com.myapp.book')
+ * @param versions - Record mapping version names to numbers
+ * @returns Record mapping version names to properly formatted migration IDs
+ * @example
+ * ```ts
+ * const migrationIds = createMigrationIds('com.myapp.book', {
+ *   addGenre: 1,
+ *   addPublisher: 2,
+ *   removeOldField: 3
+ * })
+ * // Result: {
+ * //   addGenre: 'com.myapp.book/1',
+ * //   addPublisher: 'com.myapp.book/2',
+ * //   removeOldField: 'com.myapp.book/3'
+ * // }
+ * ```
  * @public
  */
 export declare function createMigrationIds<const ID extends string, const Versions extends Record<string, number>>(sequenceId: ID, versions: Versions): {
@@ -117,8 +454,32 @@ export declare function createMigrationIds<const ID extends string, const Versio
 };
 
 /**
- * Creates a migration sequence.
+ * Creates a migration sequence that defines how to transform data as your schema evolves.
+ *
+ * A migration sequence contains a series of migrations that are applied in order to transform
+ * data from older versions to newer versions. Each migration is identified by a unique ID
+ * and can operate at either the record level (transforming individual records) or store level
+ * (transforming the entire store structure).
+ *
  * See the [migration guide](https://tldraw.dev/docs/persistence#Migrations) for more info on how to use this API.
+ * @param options - Configuration for the migration sequence
+ *   - sequenceId - Unique identifier for this migration sequence (e.g., 'com.myapp.book')
+ *   - sequence - Array of migrations or dependency declarations to include in the sequence
+ *   - retroactive - Whether migrations should apply to snapshots created before this sequence was added (defaults to true)
+ * @returns A validated migration sequence that can be included in a store schema
+ * @example
+ * ```ts
+ * const bookMigrations = createMigrationSequence({
+ *   sequenceId: 'com.myapp.book',
+ *   sequence: [
+ *     {
+ *       id: 'com.myapp.book/1',
+ *       scope: 'record',
+ *       up: (record) => ({ ...record, newField: 'default' })
+ *     }
+ *   ]
+ * })
+ * ```
  * @public
  */
 export declare function createMigrationSequence({ sequence, sequenceId, retroactive, }: {
@@ -130,15 +491,29 @@ export declare function createMigrationSequence({ sequence, sequenceId, retroact
 /* Excluded from this release type: createRecordMigrationSequence */
 
 /**
- * Create a record type.
+ * Creates a new RecordType with the specified configuration.
  *
- * @example
+ * This factory function creates a RecordType that can be used to create, validate, and manage
+ * records of a specific type within a store. The resulting RecordType can be extended with
+ * default properties using the withDefaultProperties method.
  *
+ * @example
  * ```ts
- * const Book = createRecordType<Book>('book')
+ * interface BookRecord extends BaseRecord<'book', RecordId<BookRecord>> {
+ *   title: string
+ *   author: string
+ *   inStock: boolean
+ * }
+ *
+ * const Book = createRecordType<BookRecord>('book', {
+ *   scope: 'document',
+ *   validator: bookValidator
+ * })
  * ```
  *
- * @param typeName - The name of the type to create.
+ * @param typeName - The unique type name for this record type
+ * @param config - Configuration object containing validator, scope, and ephemeral keys
+ * @returns A new RecordType instance for creating and managing records
  * @public
  */
 export declare function createRecordType<R extends UnknownRecord>(typeName: R['typeName'], config: {
@@ -167,22 +542,85 @@ export declare function devFreeze<T>(object: T): T;
 
 /**
  * An entry containing changes that originated either by user actions or remote changes.
+ * History entries are used to track and replay changes to the store.
+ *
+ * @example
+ * ```ts
+ * const entry: HistoryEntry<Book> = {
+ *   changes: {
+ *     added: { 'book:123': bookRecord },
+ *     updated: {},
+ *     removed: {}
+ *   },
+ *   source: 'user'
+ * }
+ * ```
  *
  * @public
  */
 export declare interface HistoryEntry<R extends UnknownRecord = UnknownRecord> {
+    /** The changes that occurred in this history entry */
     changes: RecordsDiff<R>;
+    /** The source of these changes */
     source: ChangeSource;
 }
 
-/** @public */
+/**
+ * Utility type that extracts the ID type from a record type.
+ * This is useful when you need to work with record IDs without having the full record type.
+ *
+ * @example
+ * ```ts
+ * interface Book extends BaseRecord<'book', RecordId<Book>> {
+ *   title: string
+ *   author: string
+ * }
+ *
+ * // Extract the ID type from the Book record
+ * type BookId = IdOf<Book> // RecordId<Book>
+ *
+ * function findBook(id: IdOf<Book>): Book | undefined {
+ *   return store.get(id)
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type IdOf<R extends UnknownRecord> = R['id'];
 
 /* Excluded from this release type: IncrementalSetConstructor */
 
-/* Excluded from this release type: isRecordsDiffEmpty */
+/**
+ * Checks whether a RecordsDiff contains any changes. A diff is considered empty
+ * if it has no added, updated, or removed records.
+ *
+ * @param diff - The diff to check
+ * @returns True if the diff contains no changes, false otherwise
+ * @example
+ * ```ts
+ * const emptyDiff = createEmptyRecordsDiff<Book>()
+ * console.log(isRecordsDiffEmpty(emptyDiff)) // true
+ *
+ * const nonEmptyDiff: RecordsDiff<Book> = {
+ *   added: { 'book:1': someBook },
+ *   updated: {},
+ *   removed: {}
+ * }
+ * console.log(isRecordsDiffEmpty(nonEmptyDiff)) // false
+ * ```
+ *
+ * @public
+ */
+export declare function isRecordsDiffEmpty<T extends UnknownRecord>(diff: RecordsDiff<T>): boolean;
 
-/** @public */
+/**
+ * Base interface for legacy migration information.
+ *
+ * Contains the basic structure used by the legacy migration system, including version
+ * range information and the migration functions indexed by version number. This is
+ * maintained for backward compatibility with older migration definitions.
+ * @public
+ */
 export declare interface LegacyBaseMigrationsInfo {
     firstVersion: number;
     currentVersion: number;
@@ -191,19 +629,45 @@ export declare interface LegacyBaseMigrationsInfo {
     };
 }
 
-/** @public */
+/**
+ * Legacy migration interface for backward compatibility.
+ *
+ * This interface represents the old migration format that included both `up` and `down`
+ * transformation functions. While still supported, new code should use the `Migration`
+ * type which provides more flexibility and better integration with the current system.
+ * @public
+ */
 export declare interface LegacyMigration<Before = any, After = any> {
     up: (oldState: Before) => After;
     down: (newState: After) => Before;
 }
 
-/** @public */
+/**
+ * Legacy migration configuration with support for sub-type migrations.
+ *
+ * This interface extends the base legacy migration info to support migrations that
+ * vary based on a sub-type key within records. This allows different migration paths
+ * for different variants of the same record type, which was useful in older migration
+ * systems but is now handled more elegantly by the current Migration system.
+ * @public
+ */
 export declare interface LegacyMigrations extends LegacyBaseMigrationsInfo {
     subTypeKey?: string;
     subTypeMigrations?: Record<string, LegacyBaseMigrationsInfo>;
 }
 
-/** @public */
+/**
+ * Defines a single migration that transforms data from one schema version to another.
+ *
+ * A migration can operate at two different scopes:
+ * - `record`: Transforms individual records, with optional filtering to target specific records
+ * - `store`: Transforms the entire serialized store structure
+ *
+ * Each migration has a unique ID and can declare dependencies on other migrations that must
+ * be applied first. The `up` function performs the forward transformation, while the optional
+ * `down` function can reverse the migration if needed.
+ * @public
+ */
 export declare type Migration = {
     readonly dependsOn?: readonly MigrationId[] | undefined;
     readonly id: MigrationId;
@@ -218,7 +682,15 @@ export declare type Migration = {
     readonly up: (oldState: UnknownRecord) => UnknownRecord | void;
 });
 
-/** @public */
+/**
+ * Enumeration of possible reasons why a migration might fail.
+ *
+ * These reasons help identify what went wrong during migration processing,
+ * allowing applications to handle different failure scenarios appropriately.
+ * Common failures include incompatible data formats, unknown record types,
+ * and version mismatches between the data and available migrations.
+ * @public
+ */
 export declare enum MigrationFailureReason {
     IncompatibleSubtype = "incompatible-subtype",
     UnknownType = "unknown-type",
@@ -228,10 +700,24 @@ export declare enum MigrationFailureReason {
     UnrecognizedSubtype = "unrecognized-subtype"
 }
 
-/** @public */
+/**
+ * Unique identifier for a migration in the format `sequenceId/version`.
+ *
+ * Migration IDs follow a specific pattern where the sequence ID identifies the migration
+ * sequence and the version number indicates the order within that sequence. For example:
+ * 'com.myapp.book/1', 'com.myapp.book/2', etc.
+ * @public
+ */
 export declare type MigrationId = `${string}/${number}`;
 
-/** @public */
+/**
+ * Result type returned by migration operations.
+ *
+ * Migration operations can either succeed and return the transformed value,
+ * or fail with a specific reason. This discriminated union type allows for
+ * safe handling of both success and error cases when applying migrations.
+ * @public
+ */
 export declare type MigrationResult<T> = {
     reason: MigrationFailureReason;
     type: 'error';
@@ -240,7 +726,15 @@ export declare type MigrationResult<T> = {
     value: T;
 };
 
-/** @public */
+/**
+ * A complete sequence of migrations that can be applied to transform data.
+ *
+ * A migration sequence represents a series of ordered migrations that belong together,
+ * typically for a specific part of your schema. The sequence includes metadata about
+ * whether it should be applied retroactively to existing data and contains the actual
+ * migration definitions in execution order.
+ * @public
+ */
 export declare interface MigrationSequence {
     sequenceId: string;
     /**
@@ -258,12 +752,47 @@ export declare interface MigrationSequence {
 
 /* Excluded from this release type: parseMigrationId */
 
-/** @public */
+/**
+ * Query expression for filtering records by their property values. Maps record property names
+ * to matching criteria.
+ *
+ * @example
+ * ```ts
+ * // Query for books published after 2020 that are in stock
+ * const bookQuery: QueryExpression<Book> = {
+ *   publishedYear: { gt: 2020 },
+ *   inStock: { eq: true }
+ * }
+ *
+ * // Query for books not by a specific author
+ * const notByAuthor: QueryExpression<Book> = {
+ *   authorId: { neq: 'author:tolkien' }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type QueryExpression<R extends object> = {
     [k in keyof R & string]?: QueryValueMatcher<R[k]>;
 };
 
-/** @public */
+/**
+ * Defines matching criteria for query values. Supports equality, inequality, and greater-than comparisons.
+ *
+ * @example
+ * ```ts
+ * // Exact match
+ * const exactMatch: QueryValueMatcher<string> = { eq: 'Science Fiction' }
+ *
+ * // Not equal to
+ * const notMatch: QueryValueMatcher<string> = { neq: 'Romance' }
+ *
+ * // Greater than (numeric values only)
+ * const greaterThan: QueryValueMatcher<number> = { gt: 2020 }
+ * ```
+ *
+ * @public
+ */
 export declare type QueryValueMatcher<T> = {
     eq: T;
 } | {
@@ -272,10 +801,40 @@ export declare type QueryValueMatcher<T> = {
     neq: T;
 };
 
-/** @public */
+/**
+ * Extracts the record type from a record ID type.
+ *
+ * @example
+ * ```ts
+ * type BookId = RecordId<Book>
+ * type BookType = RecordFromId<BookId> // Book
+ * ```
+ *
+ * @public
+ */
 export declare type RecordFromId<K extends RecordId<UnknownRecord>> = K extends RecordId<infer R> ? R : never;
 
-/** @public */
+/**
+ * A branded string type that represents a unique identifier for a record.
+ * The brand ensures type safety by preventing mixing of IDs between different record types.
+ *
+ * @example
+ * ```ts
+ * // Define a Book record
+ * interface Book extends BaseRecord<'book', RecordId<Book>> {
+ *   title: string
+ *   author: string
+ * }
+ *
+ * const bookId: RecordId<Book> = 'book:abc123' as RecordId<Book>
+ * const authorId: RecordId<Author> = 'author:xyz789' as RecordId<Author>
+ *
+ * // TypeScript prevents mixing different record ID types
+ * // bookId = authorId // Type error!
+ * ```
+ *
+ * @public
+ */
 export declare type RecordId<R extends UnknownRecord> = string & {
     __type__: R;
 };
@@ -292,13 +851,36 @@ export declare type RecordId<R extends UnknownRecord> = string & {
 export declare type RecordScope = 'document' | 'presence' | 'session';
 
 /**
- * A diff describing the changes to a record.
+ * A diff describing the changes to records, containing collections of records that were added,
+ * updated, or removed. This is the fundamental data structure used throughout the store system
+ * to track and communicate changes.
+ *
+ * @example
+ * ```ts
+ * const diff: RecordsDiff<Book> = {
+ *   added: {
+ *     'book:1': { id: 'book:1', typeName: 'book', title: 'New Book' }
+ *   },
+ *   updated: {
+ *     'book:2': [
+ *       { id: 'book:2', typeName: 'book', title: 'Old Title' }, // from
+ *       { id: 'book:2', typeName: 'book', title: 'New Title' }  // to
+ *     ]
+ *   },
+ *   removed: {
+ *     'book:3': { id: 'book:3', typeName: 'book', title: 'Deleted Book' }
+ *   }
+ * }
+ * ```
  *
  * @public
  */
 export declare interface RecordsDiff<R extends UnknownRecord> {
+    /** Records that were created, keyed by their ID */
     added: Record<IdOf<R>, R>;
+    /** Records that were modified, keyed by their ID. Each entry contains [from, to] tuple */
     updated: Record<IdOf<R>, [from: R, to: R]>;
+    /** Records that were deleted, keyed by their ID */
     removed: Record<IdOf<R>, R>;
 }
 
@@ -316,13 +898,45 @@ export declare class RecordType<R extends UnknownRecord, RequiredProperties exte
      * @readonly
      */
     readonly typeName: R['typeName'];
+    /**
+     * Factory function that creates default properties for new records.
+     * @public
+     */
     readonly createDefaultProperties: () => Exclude<Omit<R, 'id' | 'typeName'>, RequiredProperties>;
+    /**
+     * Validator function used to validate records of this type.
+     * @public
+     */
     readonly validator: StoreValidator<R>;
+    /**
+     * Optional configuration specifying which record properties are ephemeral.
+     * Ephemeral properties are not included in snapshots or synchronization.
+     * @public
+     */
     readonly ephemeralKeys?: {
         readonly [K in Exclude<keyof R, 'id' | 'typeName'>]: boolean;
     };
+    /**
+     * Set of property names that are marked as ephemeral for efficient lookup.
+     * @public
+     */
     readonly ephemeralKeySet: ReadonlySet<string>;
+    /**
+     * The scope that determines how records of this type are persisted and synchronized.
+     * @public
+     */
     readonly scope: RecordScope;
+    /**
+     * Creates a new RecordType instance.
+     *
+     * typeName - The unique type name for records created by this RecordType
+     * config - Configuration object for the RecordType
+     *   - createDefaultProperties - Function that returns default properties for new records
+     *   - validator - Optional validator function for record validation
+     *   - scope - Optional scope determining persistence behavior (defaults to 'document')
+     *   - ephemeralKeys - Optional mapping of property names to ephemeral status
+     * @public
+     */
     constructor(
     /**
      * The unique type associated with this record.
@@ -339,17 +953,40 @@ export declare class RecordType<R extends UnknownRecord, RequiredProperties exte
         readonly validator?: StoreValidator<R>;
     });
     /**
-     * Create a new record of this type.
+     * Creates a new record of this type with the given properties.
+     *
+     * Properties are merged with default properties from the RecordType configuration.
+     * If no id is provided, a unique id will be generated automatically.
      *
-     * @param properties - The properties of the record.
-     * @returns The new record.
+     * @example
+     * ```ts
+     * const book = Book.create({
+     *   title: 'The Great Gatsby',
+     *   author: 'F. Scott Fitzgerald'
+     * })
+     * // Result: { id: 'book:abc123', typeName: 'book', title: 'The Great Gatsby', author: 'F. Scott Fitzgerald', inStock: true }
+     * ```
+     *
+     * @param properties - The properties for the new record, including both required and optional fields
+     * @returns The newly created record with generated id and typeName
+     * @public
      */
     create(properties: Expand<Pick<R, RequiredProperties> & Omit<Partial<R>, RequiredProperties>>): R;
     /**
-     * Clone a record of this type.
+     * Creates a deep copy of an existing record with a new unique id.
+     *
+     * This method performs a deep clone of all properties while generating a fresh id,
+     * making it useful for duplicating records without id conflicts.
+     *
+     * @example
+     * ```ts
+     * const originalBook = Book.create({ title: '1984', author: 'George Orwell' })
+     * const duplicatedBook = Book.clone(originalBook)
+     * // duplicatedBook has same properties but different id
+     * ```
      *
-     * @param record - The record to clone.
-     * @returns The cloned record.
+     * @param record - The record to clone
+     * @returns A new record with the same properties but a different id
      * @public
      */
     clone(record: R): R;
@@ -367,36 +1004,58 @@ export declare class RecordType<R extends UnknownRecord, RequiredProperties exte
      */
     createId(customUniquePart?: string): IdOf<R>;
     /**
-     * Takes an id like `user:123` and returns the part after the colon `123`
+     * Extracts the unique identifier part from a full record id.
      *
-     * @param id - The id
-     * @returns
+     * Record ids have the format `typeName:uniquePart`. This method returns just the unique part.
+     *
+     * @example
+     * ```ts
+     * const bookId = Book.createId() // 'book:abc123'
+     * const uniquePart = Book.parseId(bookId) // 'abc123'
+     * ```
+     *
+     * @param id - The full record id to parse
+     * @returns The unique identifier portion after the colon
+     * @throws Error if the id is not valid for this record type
+     * @public
      */
     parseId(id: IdOf<R>): string;
     /**
-     * Check whether a record is an instance of this record type.
+     * Type guard that checks whether a record belongs to this RecordType.
      *
-     * @example
+     * This method performs a runtime check by comparing the record's typeName
+     * against this RecordType's typeName.
      *
+     * @example
      * ```ts
-     * const result = recordType.isInstance(someRecord)
+     * if (Book.isInstance(someRecord)) {
+     *   // someRecord is now typed as a book record
+     *   console.log(someRecord.title)
+     * }
      * ```
      *
-     * @param record - The record to check.
-     * @returns Whether the record is an instance of this record type.
+     * @param record - The record to check, may be undefined
+     * @returns True if the record is an instance of this record type
+     * @public
      */
     isInstance(record?: UnknownRecord): record is R;
     /**
-     * Check whether an id is an id of this type.
+     * Type guard that checks whether an id string belongs to this RecordType.
      *
-     * @example
+     * Validates that the id starts with this RecordType's typeName followed by a colon.
+     * This is more efficient than parsing the full id when you only need to verify the type.
      *
+     * @example
      * ```ts
-     * const result = recordType.isIn('someId')
+     * if (Book.isId(someId)) {
+     *   // someId is now typed as IdOf<BookRecord>
+     *   const book = store.get(someId)
+     * }
      * ```
      *
-     * @param id - The id to check.
-     * @returns Whether the id is an id of this type.
+     * @param id - The id string to check, may be undefined
+     * @returns True if the id belongs to this record type
+     * @public
      */
     isId(id?: string): id is IdOf<R>;
     /**
@@ -415,28 +1074,156 @@ export declare class RecordType<R extends UnknownRecord, RequiredProperties exte
      */
     withDefaultProperties<DefaultProps extends Omit<Partial<R>, 'id' | 'typeName'>>(createDefaultProperties: () => DefaultProps): RecordType<R, Exclude<RequiredProperties, keyof DefaultProps>>;
     /**
-     * Check that the passed in record passes the validations for this type. Returns its input
-     * correctly typed if it does, but throws an error otherwise.
+     * Validates a record against this RecordType's validator and returns it with proper typing.
+     *
+     * This method runs the configured validator function and throws an error if validation fails.
+     * If a previous version of the record is provided, it may use optimized validation.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const validBook = Book.validate(untrustedData)
+     *   // validBook is now properly typed and validated
+     * } catch (error) {
+     *   console.log('Validation failed:', error.message)
+     * }
+     * ```
+     *
+     * @param record - The unknown record data to validate
+     * @param recordBefore - Optional previous version for optimized validation
+     * @returns The validated and properly typed record
+     * @throws Error if validation fails
+     * @public
      */
     validate(record: unknown, recordBefore?: R): R;
 }
 
-/** @public */
+/**
+ * Creates the inverse of a RecordsDiff, effectively reversing all changes.
+ * Added records become removed, removed records become added, and updated records
+ * have their from/to values swapped. This is useful for implementing undo operations.
+ *
+ * @param diff - The diff to reverse
+ * @returns A new RecordsDiff that represents the inverse of the input diff
+ * @example
+ * ```ts
+ * const originalDiff: RecordsDiff<Book> = {
+ *   added: { 'book:1': newBook },
+ *   updated: { 'book:2': [oldBook, updatedBook] },
+ *   removed: { 'book:3': deletedBook }
+ * }
+ *
+ * const reversedDiff = reverseRecordsDiff(originalDiff)
+ * // Result: {
+ * //   added: { 'book:3': deletedBook },
+ * //   updated: { 'book:2': [updatedBook, oldBook] },
+ * //   removed: { 'book:1': newBook }
+ * // }
+ * ```
+ *
+ * @public
+ */
 export declare function reverseRecordsDiff(diff: RecordsDiff<any>): RecordsDiff<any>;
 
-/** @public */
+/**
+ * A reactive computed index that provides efficient lookups of records by property values.
+ * Returns a computed value containing an RSIndexMap with diffs for change tracking.
+ *
+ * @example
+ * ```ts
+ * // Create an index on book authors
+ * const authorIndex: RSIndex<Book, 'authorId'> = store.query.index('book', 'authorId')
+ *
+ * // Get all books by a specific author
+ * const leguinBooks = authorIndex.get().get('author:leguin')
+ * ```
+ *
+ * @public
+ */
 export declare type RSIndex<R extends UnknownRecord, Property extends string & keyof R = string & keyof R> = Computed<RSIndexMap<R, Property>, RSIndexDiff<R, Property>>;
 
-/** @public */
+/**
+ * A type representing the diff of changes to a reactive store index.
+ * Maps property values to the collection differences for record IDs that have that property value.
+ *
+ * @example
+ * ```ts
+ * // For an index on book titles, the diff might look like:
+ * const titleIndexDiff: RSIndexDiff<Book, 'title'> = new Map([
+ *   ['The Lathe of Heaven', { added: new Set(['book:1']), removed: new Set() }],
+ *   ['Animal Farm', { added: new Set(), removed: new Set(['book:2']) }]
+ * ])
+ * ```
+ *
+ * @public
+ */
 export declare type RSIndexDiff<R extends UnknownRecord, Property extends string & keyof R = string & keyof R> = Map<R[Property], CollectionDiff<IdOf<R>>>;
 
-/** @public */
+/**
+ * A type representing a reactive store index as a map from property values to sets of record IDs.
+ * This is used to efficiently look up records by a specific property value.
+ *
+ * @example
+ * ```ts
+ * // Index mapping book titles to the IDs of books with that title
+ * const titleIndex: RSIndexMap<Book, 'title'> = new Map([
+ *   ['The Lathe of Heaven', new Set(['book:1'])],
+ *   ['Animal Farm', new Set(['book:2', 'book:3'])]
+ * ])
+ * ```
+ *
+ * @public
+ */
 export declare type RSIndexMap<R extends UnknownRecord, Property extends string & keyof R = string & keyof R> = Map<R[Property], Set<IdOf<R>>>;
 
-/** @public */
+/**
+ * Union type representing all supported serialized schema formats.
+ *
+ * This type allows the store to handle both legacy (V1) and current (V2)
+ * schema formats during deserialization and migration.
+ *
+ * @example
+ * ```ts
+ * function handleSchema(schema: SerializedSchema) {
+ *   if (schema.schemaVersion === 1) {
+ *     // Handle V1 format
+ *     console.log('Store version:', schema.storeVersion)
+ *   } else {
+ *     // Handle V2 format
+ *     console.log('Sequences:', schema.sequences)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type SerializedSchema = SerializedSchemaV1 | SerializedSchemaV2;
 
-/** @public */
+/**
+ * Version 1 format for serialized store schema information.
+ *
+ * This is the legacy format used before schema version 2. Version 1 schemas
+ * separate store-level versioning from record-level versioning, and support
+ * subtypes for complex record types like shapes.
+ *
+ * @example
+ * ```ts
+ * const schemaV1: SerializedSchemaV1 = {
+ *   schemaVersion: 1,
+ *   storeVersion: 2,
+ *   recordVersions: {
+ *     book: { version: 3 },
+ *     shape: {
+ *       version: 2,
+ *       subTypeVersions: { rectangle: 1, circle: 2 },
+ *       subTypeKey: 'type'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface SerializedSchemaV1 {
     /** Schema version is the version for this type you're looking at right now */
     schemaVersion: 1;
@@ -455,7 +1242,28 @@ export declare interface SerializedSchemaV1 {
     }>;
 }
 
-/** @public */
+/**
+ * Version 2 format for serialized store schema information.
+ *
+ * This is the current format that uses a unified sequence-based approach
+ * for tracking versions across all migration sequences. Each sequence ID
+ * maps to the latest version number for that sequence.
+ *
+ * @example
+ * ```ts
+ * const schemaV2: SerializedSchemaV2 = {
+ *   schemaVersion: 2,
+ *   sequences: {
+ *     'com.tldraw.store': 3,
+ *     'com.tldraw.book': 2,
+ *     'com.tldraw.shape': 4,
+ *     'com.tldraw.shape.rectangle': 1
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface SerializedSchemaV2 {
     schemaVersion: 2;
     sequences: {
@@ -465,17 +1273,53 @@ export declare interface SerializedSchemaV2 {
 
 /**
  * A serialized snapshot of the record store's values.
+ * This is a plain JavaScript object that can be saved to storage or transmitted over the network.
+ *
+ * @example
+ * ```ts
+ * const serialized: SerializedStore<Book> = {
+ *   'book:123': { id: 'book:123', typeName: 'book', title: 'The Lathe of Heaven' },
+ *   'book:456': { id: 'book:456', typeName: 'book', title: 'The Left Hand of Darkness' }
+ * }
+ * ```
  *
  * @public
  */
 export declare type SerializedStore<R extends UnknownRecord> = Record<IdOf<R>, R>;
 
 /**
- * Squash a collection of diffs into a single diff.
+ * Combines multiple RecordsDiff objects into a single consolidated diff.
+ * This function intelligently merges changes, handling cases where the same record
+ * is modified multiple times across different diffs. For example, if a record is
+ * added in one diff and then updated in another, the result will show it as added
+ * with the final state.
+ *
+ * @param diffs - An array of diffs to combine into a single diff
+ * @param options - Configuration options for the squashing operation
+ *   - mutateFirstDiff - If true, modifies the first diff in place instead of creating a new one
+ * @returns A single diff that represents the cumulative effect of all input diffs
+ * @example
+ * ```ts
+ * const diff1: RecordsDiff<Book> = {
+ *   added: { 'book:1': { id: 'book:1', title: 'New Book' } },
+ *   updated: {},
+ *   removed: {}
+ * }
+ *
+ * const diff2: RecordsDiff<Book> = {
+ *   added: {},
+ *   updated: { 'book:1': [{ id: 'book:1', title: 'New Book' }, { id: 'book:1', title: 'Updated Title' }] },
+ *   removed: {}
+ * }
+ *
+ * const squashed = squashRecordDiffs([diff1, diff2])
+ * // Result: {
+ * //   added: { 'book:1': { id: 'book:1', title: 'Updated Title' } },
+ * //   updated: {},
+ * //   removed: {}
+ * // }
+ * ```
  *
- * @param diffs - An array of diffs to squash.
- * @param options - An optional object with a `mutateFirstDiff` property. If `mutateFirstDiff` is true, the first diff in the array will be mutated in-place.
- * @returns A single diff that represents the squashed diffs.
  * @public
  */
 export declare function squashRecordDiffs<T extends UnknownRecord>(diffs: RecordsDiff<T>[], options?: {
@@ -484,19 +1328,59 @@ export declare function squashRecordDiffs<T extends UnknownRecord>(diffs: Record
 
 /* Excluded from this release type: squashRecordDiffsMutable */
 
-/** @public */
+/**
+ * Declares dependencies for migrations without being a migration itself.
+ *
+ * This interface allows you to specify that future migrations in a sequence depend on
+ * migrations from other sequences, without defining an actual migration transformation.
+ * It's used to establish cross-sequence dependencies in the migration graph.
+ * @public
+ */
 export declare interface StandaloneDependsOn {
     readonly dependsOn: readonly MigrationId[];
 }
 
 /**
- * A store of records.
+ * A reactive store that manages collections of typed records.
+ *
+ * The Store is the central container for your application's data, providing:
+ * - Reactive state management with automatic updates
+ * - Type-safe record operations
+ * - History tracking and change notifications
+ * - Schema validation and migrations
+ * - Side effects and business logic hooks
+ * - Efficient querying and indexing
+ *
+ * @example
+ * ```ts
+ * // Create a store with schema
+ * const schema = StoreSchema.create({
+ *   book: Book,
+ *   author: Author
+ * })
+ *
+ * const store = new Store({
+ *   schema,
+ *   props: {}
+ * })
+ *
+ * // Add records
+ * const book = Book.create({ title: 'The Lathe of Heaven', author: 'Le Guin' })
+ * store.put([book])
+ *
+ * // Listen to changes
+ * store.listen((entry) => {
+ *   console.log('Changes:', entry.changes)
+ * })
+ * ```
  *
  * @public
  */
 export declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
     /**
-     * The random id of the store.
+     * The unique identifier of the store instance.
+     *
+     * @public
      */
     readonly id: string;
     /* Excluded from this release type: records */
@@ -508,7 +1392,19 @@ export declare class Store<R extends UnknownRecord = UnknownRecord, Props = unkn
      */
     readonly history: Atom<number, RecordsDiff<R>>;
     /**
-     * A StoreQueries instance for this store.
+     * Reactive queries and indexes for efficiently accessing store data.
+     * Provides methods for filtering, indexing, and subscribing to subsets of records.
+     *
+     * @example
+     * ```ts
+     * // Create an index by a property
+     * const booksByAuthor = store.query.index('book', 'author')
+     *
+     * // Get records matching criteria
+     * const inStockBooks = store.query.records('book', () => ({
+     *   inStock: { eq: true }
+     * }))
+     * ```
      *
      * @public
      * @readonly
@@ -518,22 +1414,64 @@ export declare class Store<R extends UnknownRecord = UnknownRecord, Props = unkn
     /* Excluded from this release type: historyAccumulator */
     /* Excluded from this release type: historyReactor */
     /* Excluded from this release type: cancelHistoryReactor */
+    /**
+     * The schema that defines the structure and validation rules for records in this store.
+     *
+     * @public
+     */
     readonly schema: StoreSchema<R, Props>;
+    /**
+     * Custom properties associated with this store instance.
+     *
+     * @public
+     */
     readonly props: Props;
+    /**
+     * A mapping of record scopes to the set of record type names that belong to each scope.
+     * Used to filter records by their persistence and synchronization behavior.
+     *
+     * @public
+     */
     readonly scopedTypes: {
         readonly [K in RecordScope]: ReadonlySet<R['typeName']>;
     };
+    /**
+     * Side effects manager that handles lifecycle events for record operations.
+     * Allows registration of callbacks for create, update, delete, and validation events.
+     *
+     * @example
+     * ```ts
+     * store.sideEffects.registerAfterCreateHandler('book', (book) => {
+     *   console.log('Book created:', book.title)
+     * })
+     * ```
+     *
+     * @public
+     */
     readonly sideEffects: StoreSideEffects<R>;
+    /**
+     * Creates a new Store instance.
+     *
+     * @example
+     * ```ts
+     * const store = new Store({
+     *   schema: StoreSchema.create({ book: Book }),
+     *   props: { appName: 'MyLibrary' },
+     *   initialData: savedData
+     * })
+     * ```
+     *
+     * @param config - Configuration object for the store
+     */
     constructor(config: {
-        /**
-         * A map of validators for each record type. A record's validator will be called when the record
-         * is created or updated. It should throw an error if the record is invalid.
-         */
+        /** Custom properties for the store instance */
+        props: Props;
+        /** Optional unique identifier for the store */
+        id?: string;
+        /** The schema defining record types, validation, and migrations */
         schema: StoreSchema<R, Props>;
-        /** The store's initial data. */
+        /** The store's initial data to populate on creation */
         initialData?: SerializedStore<R>;
-        id?: string;
-        props: Props;
     });
     _flushHistory(): void;
     dispose(): void;
@@ -556,119 +1494,238 @@ export declare class Store<R extends UnknownRecord = UnknownRecord, Props = unkn
     private updateHistory;
     validate(phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord'): void;
     /**
-     * Add some records to the store. It's an error if they already exist.
+     * Add or update records in the store. If a record with the same ID already exists, it will be updated.
+     * Otherwise, a new record will be created.
+     *
+     * @example
+     * ```ts
+     * // Add new records
+     * const book = Book.create({ title: 'Lathe Of Heaven', author: 'Le Guin' })
+     * store.put([book])
      *
-     * @param records - The records to add.
-     * @param phaseOverride - The phase override.
+     * // Update existing record
+     * store.put([{ ...book, title: 'The Lathe of Heaven' }])
+     * ```
+     *
+     * @param records - The records to add or update
+     * @param phaseOverride - Override the validation phase (used internally)
      * @public
      */
     put(records: R[], phaseOverride?: 'initialize'): void;
     /**
-     * Remove some records from the store via their ids.
+     * Remove records from the store by their IDs.
+     *
+     * @example
+     * ```ts
+     * // Remove a single record
+     * store.remove([book.id])
+     *
+     * // Remove multiple records
+     * store.remove([book1.id, book2.id, book3.id])
+     * ```
      *
-     * @param ids - The ids of the records to remove.
+     * @param ids - The IDs of the records to remove
      * @public
      */
     remove(ids: IdOf<R>[]): void;
     /**
-     * Get the value of a store record by its id.
+     * Get a record by its ID. This creates a reactive subscription to the record.
+     *
+     * @example
+     * ```ts
+     * const book = store.get(bookId)
+     * if (book) {
+     *   console.log(book.title)
+     * }
+     * ```
      *
-     * @param id - The id of the record to get.
+     * @param id - The ID of the record to get
+     * @returns The record if it exists, undefined otherwise
      * @public
      */
     get<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined;
     /**
-     * Get the value of a store record by its id without updating its epoch.
+     * Get a record by its ID without creating a reactive subscription.
+     * Use this when you need to access a record but don't want reactive updates.
+     *
+     * @example
+     * ```ts
+     * // Won't trigger reactive updates when this record changes
+     * const book = store.unsafeGetWithoutCapture(bookId)
+     * ```
      *
-     * @param id - The id of the record to get.
+     * @param id - The ID of the record to get
+     * @returns The record if it exists, undefined otherwise
      * @public
      */
     unsafeGetWithoutCapture<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined;
     /**
-     * Creates a JSON payload from the record store.
+     * Serialize the store's records to a plain JavaScript object.
+     * Only includes records matching the specified scope.
+     *
+     * @example
+     * ```ts
+     * // Serialize only document records (default)
+     * const documentData = store.serialize('document')
+     *
+     * // Serialize all records
+     * const allData = store.serialize('all')
+     * ```
      *
-     * @param scope - The scope of records to serialize. Defaults to 'document'.
-     * @returns The record store snapshot as a JSON payload.
+     * @param scope - The scope of records to serialize. Defaults to 'document'
+     * @returns The serialized store data
+     * @public
      */
     serialize(scope?: 'all' | RecordScope): SerializedStore<R>;
     /**
      * Get a serialized snapshot of the store and its schema.
+     * This includes both the data and schema information needed for proper migration.
      *
+     * @example
      * ```ts
      * const snapshot = store.getStoreSnapshot()
-     * store.loadStoreSnapshot(snapshot)
-     * ```
+     * localStorage.setItem('myApp', JSON.stringify(snapshot))
      *
-     * @param scope - The scope of records to serialize. Defaults to 'document'.
+     * // Later...
+     * const saved = JSON.parse(localStorage.getItem('myApp'))
+     * store.loadStoreSnapshot(saved)
+     * ```
      *
+     * @param scope - The scope of records to serialize. Defaults to 'document'
+     * @returns A snapshot containing both store data and schema information
      * @public
      */
     getStoreSnapshot(scope?: 'all' | RecordScope): StoreSnapshot<R>;
     /**
-     * Migrate a serialized snapshot of the store and its schema.
+     * Migrate a serialized snapshot to the current schema version.
+     * This applies any necessary migrations to bring old data up to date.
      *
+     * @example
      * ```ts
-     * const snapshot = store.getStoreSnapshot()
-     * store.migrateSnapshot(snapshot)
+     * const oldSnapshot = JSON.parse(localStorage.getItem('myApp'))
+     * const migratedSnapshot = store.migrateSnapshot(oldSnapshot)
      * ```
      *
-     * @param snapshot - The snapshot to load.
+     * @param snapshot - The snapshot to migrate
+     * @returns The migrated snapshot with current schema version
+     * @throws Error if migration fails
      * @public
      */
     migrateSnapshot(snapshot: StoreSnapshot<R>): StoreSnapshot<R>;
     /**
-     * Load a serialized snapshot.
+     * Load a serialized snapshot into the store, replacing all current data.
+     * The snapshot will be automatically migrated to the current schema version if needed.
      *
+     * @example
      * ```ts
-     * const snapshot = store.getStoreSnapshot()
+     * const snapshot = JSON.parse(localStorage.getItem('myApp'))
      * store.loadStoreSnapshot(snapshot)
      * ```
      *
-     * @param snapshot - The snapshot to load.
+     * @param snapshot - The snapshot to load
+     * @throws Error if migration fails or snapshot is invalid
      * @public
      */
     loadStoreSnapshot(snapshot: StoreSnapshot<R>): void;
     /**
-     * Get an array of all values in the store.
+     * Get an array of all records in the store.
+     *
+     * @example
+     * ```ts
+     * const allRecords = store.allRecords()
+     * const books = allRecords.filter(r => r.typeName === 'book')
+     * ```
      *
-     * @returns An array of all values in the store.
+     * @returns An array containing all records in the store
      * @public
      */
     allRecords(): R[];
     /**
-     * Removes all records from the store.
+     * Remove all records from the store.
+     *
+     * @example
+     * ```ts
+     * store.clear()
+     * console.log(store.allRecords().length) // 0
+     * ```
      *
      * @public
      */
     clear(): void;
     /**
-     * Update a record. To update multiple records at once, use the `update` method of the
-     * `TypedStore` class.
+     * Update a single record using an updater function. To update multiple records at once,
+     * use the `update` method of the `TypedStore` class.
+     *
+     * @example
+     * ```ts
+     * store.update(book.id, (book) => ({
+     *   ...book,
+     *   title: 'Updated Title'
+     * }))
+     * ```
      *
-     * @param id - The id of the record to update.
-     * @param updater - A function that updates the record.
+     * @param id - The ID of the record to update
+     * @param updater - A function that receives the current record and returns the updated record
+     * @public
      */
     update<K extends IdOf<R>>(id: K, updater: (record: RecordFromId<K>) => RecordFromId<K>): void;
     /**
-     * Get whether the record store has a id.
+     * Check whether a record with the given ID exists in the store.
+     *
+     * @example
+     * ```ts
+     * if (store.has(bookId)) {
+     *   console.log('Book exists!')
+     * }
+     * ```
      *
-     * @param id - The id of the record to check.
+     * @param id - The ID of the record to check
+     * @returns True if the record exists, false otherwise
      * @public
      */
     has<K extends IdOf<R>>(id: K): boolean;
     /**
-     * Add a new listener to the store.
+     * Add a listener that will be called when the store changes.
+     * Returns a function to remove the listener.
+     *
+     * @example
+     * ```ts
+     * const removeListener = store.listen((entry) => {
+     *   console.log('Changes:', entry.changes)
+     *   console.log('Source:', entry.source)
+     * })
+     *
+     * // Listen only to user changes to document records
+     * const removeDocumentListener = store.listen(
+     *   (entry) => console.log('Document changed:', entry),
+     *   { source: 'user', scope: 'document' }
+     * )
+     *
+     * // Later, remove the listener
+     * removeListener()
+     * ```
      *
-     * @param onHistory - The listener to call when the store updates.
-     * @param filters - Filters to apply to the listener.
-     * @returns A function to remove the listener.
+     * @param onHistory - The listener function to call when changes occur
+     * @param filters - Optional filters to control when the listener is called
+     * @returns A function that removes the listener when called
+     * @public
      */
     listen(onHistory: StoreListener<R>, filters?: Partial<StoreListenerFilters>): () => void;
     private isMergingRemoteChanges;
     /**
-     * Merge changes from a remote source
+     * Merge changes from a remote source. Changes made within the provided function
+     * will be marked with source 'remote' instead of 'user'.
+     *
+     * @example
+     * ```ts
+     * // Changes from sync/collaboration
+     * store.mergeRemoteChanges(() => {
+     *   store.put(remoteRecords)
+     *   store.remove(deletedIds)
+     * })
+     * ```
      *
-     * @param fn - A function that merges the external changes.
+     * @param fn - A function that applies the remote changes
      * @public
      */
     mergeRemoteChanges(fn: () => void): void;
@@ -711,85 +1768,337 @@ export declare class Store<R extends UnknownRecord = UnknownRecord, Props = unkn
     /* Excluded from this release type: addHistoryInterceptor */
 }
 
-/** @public */
+/**
+ * Handler function called after a record has been successfully updated in the store.
+ * Use this for side effects that should happen after record changes, such as
+ * updating related records or maintaining consistency constraints.
+ *
+ * @param prev - The previous version of the record
+ * @param next - The new version of the record that was stored
+ * @param source - Whether the change originated from 'user' interaction or 'remote' synchronization
+ *
+ * @example
+ * ```ts
+ * const handler: StoreAfterChangeHandler<ShapeRecord> = (prev, next, source) => {
+ *   // Update connected arrows when a shape moves
+ *   if (prev.x !== next.x || prev.y !== next.y) {
+ *     updateConnectedArrows(next.id)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreAfterChangeHandler<R extends UnknownRecord> = (prev: R, next: R, source: 'remote' | 'user') => void;
 
-/** @public */
+/**
+ * Handler function called after a record has been successfully created in the store.
+ * Use this for side effects that should happen after record creation, such as updating
+ * related records or triggering notifications.
+ *
+ * @param record - The record that was created
+ * @param source - Whether the change originated from 'user' interaction or 'remote' synchronization
+ *
+ * @example
+ * ```ts
+ * const handler: StoreAfterCreateHandler<BookRecord> = (book, source) => {
+ *   if (source === 'user') {
+ *     console.log(`New book added: ${book.title}`)
+ *     updateAuthorBookCount(book.authorId)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreAfterCreateHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => void;
 
-/** @public */
+/**
+ * Handler function called after a record has been successfully deleted from the store.
+ * Use this for cleanup operations and maintaining referential integrity.
+ *
+ * @param record - The record that was deleted
+ * @param source - Whether the change originated from 'user' interaction or 'remote' synchronization
+ *
+ * @example
+ * ```ts
+ * const handler: StoreAfterDeleteHandler<ShapeRecord> = (shape, source) => {
+ *   // Clean up arrows that were connected to this shape
+ *   const connectedArrows = findArrowsConnectedTo(shape.id)
+ *   store.remove(connectedArrows.map(arrow => arrow.id))
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreAfterDeleteHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => void;
 
-/** @public */
+/**
+ * Handler function called before a record is updated in the store.
+ * The handler receives the current and new versions of the record and can return
+ * a modified version or the original to prevent the change.
+ *
+ * @param prev - The current version of the record in the store
+ * @param next - The proposed new version of the record
+ * @param source - Whether the change originated from 'user' interaction or 'remote' synchronization
+ * @returns The record version to actually store (may be modified or the original to block change)
+ *
+ * @example
+ * ```ts
+ * const handler: StoreBeforeChangeHandler<ShapeRecord> = (prev, next, source) => {
+ *   // Prevent shapes from being moved outside the canvas bounds
+ *   if (next.x < 0 || next.y < 0) {
+ *     return prev // Block the change
+ *   }
+ *   return next
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreBeforeChangeHandler<R extends UnknownRecord> = (prev: R, next: R, source: 'remote' | 'user') => R;
 
-/** @public */
+/**
+ * Handler function called before a record is created in the store.
+ * The handler receives the record to be created and can return a modified version.
+ * Use this to validate, transform, or modify records before they are added to the store.
+ *
+ * @param record - The record about to be created
+ * @param source - Whether the change originated from 'user' interaction or 'remote' synchronization
+ * @returns The record to actually create (may be modified)
+ *
+ * @example
+ * ```ts
+ * const handler: StoreBeforeCreateHandler<MyRecord> = (record, source) => {
+ *   // Ensure all user-created records have a timestamp
+ *   if (source === 'user' && !record.createdAt) {
+ *     return { ...record, createdAt: Date.now() }
+ *   }
+ *   return record
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreBeforeCreateHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => R;
 
-/** @public */
+/**
+ * Handler function called before a record is deleted from the store.
+ * The handler can return `false` to prevent the deletion from occurring.
+ *
+ * @param record - The record about to be deleted
+ * @param source - Whether the change originated from 'user' interaction or 'remote' synchronization
+ * @returns `false` to prevent deletion, `void` or any other value to allow it
+ *
+ * @example
+ * ```ts
+ * const handler: StoreBeforeDeleteHandler<BookRecord> = (book, source) => {
+ *   // Prevent deletion of books that are currently checked out
+ *   if (book.isCheckedOut) {
+ *     console.warn('Cannot delete checked out book')
+ *     return false
+ *   }
+ *   // Allow deletion for other books
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreBeforeDeleteHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => false | void;
 
-/** @public */
+/**
+ * Information about an error that occurred in the store.
+ *
+ * @example
+ * ```ts
+ * const error: StoreError = {
+ *   error: new Error('Validation failed'),
+ *   phase: 'updateRecord',
+ *   recordBefore: oldRecord,
+ *   recordAfter: newRecord,
+ *   isExistingValidationIssue: false
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface StoreError {
+    /** The error that occurred */
     error: Error;
+    /** The phase during which the error occurred */
     phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord';
+    /** The record state before the operation (if applicable) */
     recordBefore?: unknown;
+    /** The record state after the operation */
     recordAfter: unknown;
+    /** Whether this is an existing validation issue */
     isExistingValidationIssue: boolean;
 }
 
 /**
  * A function that will be called when the history changes.
  *
+ * @example
+ * ```ts
+ * const listener: StoreListener<Book> = (entry) => {
+ *   console.log('Changes:', entry.changes)
+ *   console.log('Source:', entry.source)
+ * }
+ *
+ * store.listen(listener)
+ * ```
+ *
+ * @param entry - The history entry containing the changes
+ *
  * @public
  */
 export declare type StoreListener<R extends UnknownRecord> = (entry: HistoryEntry<R>) => void;
 
-/** @public */
+/**
+ * Filters for store listeners to control which changes trigger the listener.
+ *
+ * @example
+ * ```ts
+ * const filters: StoreListenerFilters = {
+ *   source: 'user', // Only listen to user changes
+ *   scope: 'document' // Only listen to document-scoped records
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface StoreListenerFilters {
+    /** Filter by the source of changes */
     source: 'all' | ChangeSource;
+    /** Filter by the scope of records */
     scope: 'all' | RecordScope;
 }
 
-/** @public */
+/**
+ * A store or an object containing a store.
+ * This type is used for APIs that can accept either a store directly or an object with a store property.
+ *
+ * @example
+ * ```ts
+ * function useStore(storeOrObject: StoreObject<MyRecord>) {
+ *   const store = storeOrObject instanceof Store ? storeOrObject : storeOrObject.store
+ *   return store
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreObject<R extends UnknownRecord> = {
     store: Store<R>;
 } | Store<R>;
 
-/** @public */
+/**
+ * Extract the record type from a StoreObject.
+ *
+ * @example
+ * ```ts
+ * type MyStoreObject = { store: Store<Book | Author> }
+ * type Records = StoreObjectRecordType<MyStoreObject> // Book | Author
+ * ```
+ *
+ * @public
+ */
 export declare type StoreObjectRecordType<Context extends StoreObject<any>> = Context extends Store<infer R> ? R : Context extends {
     store: Store<infer R>;
 } ? R : never;
 
-/** @public */
+/**
+ * Handler function called when a store operation (atomic transaction) completes.
+ * This is useful for performing actions after a batch of changes has been applied,
+ * such as triggering saves or sending notifications.
+ *
+ * @param source - Whether the operation originated from 'user' interaction or 'remote' synchronization
+ *
+ * @example
+ * ```ts
+ * const handler: StoreOperationCompleteHandler = (source) => {
+ *   if (source === 'user') {
+ *     // Auto-save after user operations complete
+ *     saveStoreSnapshot()
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreOperationCompleteHandler = (source: 'remote' | 'user') => void;
 
 /**
- * A class that provides a 'namespace' for the various kinds of indexes one may wish to derive from
- * the record store.
+ * A class that provides reactive querying capabilities for a record store.
+ * Offers methods to create indexes, filter records, and perform efficient lookups with automatic cache management.
+ * All queries are reactive and will automatically update when the underlying store data changes.
+ *
+ * @example
+ * ```ts
+ * // Create a store with books
+ * const store = new Store({ schema: StoreSchema.create({ book: Book, author: Author }) })
+ *
+ * // Get reactive queries for books
+ * const booksByAuthor = store.query.index('book', 'authorId')
+ * const inStockBooks = store.query.records('book', () => ({ inStock: { eq: true } }))
+ * ```
+ *
  * @public
  */
 export declare class StoreQueries<R extends UnknownRecord> {
     private readonly recordMap;
     private readonly history;
-    constructor(recordMap: AtomMap<IdOf<R>, R>, history: Atom<number, RecordsDiff<R>>);
+    /* Excluded from this release type: __constructor */
     /* Excluded from this release type: indexCache */
     /* Excluded from this release type: historyCache */
     /**
-     * Create a derivation that contains the history for a given type
+     * Creates a reactive computed that tracks the change history for records of a specific type.
+     * The returned computed provides incremental diffs showing what records of the given type
+     * have been added, updated, or removed.
+     *
+     * @param typeName - The type name to filter the history by
+     * @returns A computed value containing the current epoch and diffs of changes for the specified type
+     *
+     * @example
+     * ```ts
+     * // Track changes to book records only
+     * const bookHistory = store.query.filterHistory('book')
+     *
+     * // React to book changes
+     * react('book-changes', () => {
+     *   const currentEpoch = bookHistory.get()
+     *   console.log('Books updated at epoch:', currentEpoch)
+     * })
+     * ```
      *
-     * @param typeName - The name of the type to filter by.
-     * @returns A derivation that returns the ids of all records of the given type.
      * @public
      */
     filterHistory<TypeName extends R['typeName']>(typeName: TypeName): Computed<number, RecordsDiff<Extract<R, {
         typeName: TypeName;
     }>>>;
     /**
-     * Create a derivation that returns an index on a property for the given type.
+     * Creates a reactive index that maps property values to sets of record IDs for efficient lookups.
+     * The index automatically updates when records are added, updated, or removed, and results are cached
+     * for performance.
+     *
+     * @param typeName - The type name of records to index
+     * @param property - The property name to index by
+     * @returns A reactive computed containing the index map with change diffs
+     *
+     * @example
+     * ```ts
+     * // Create an index of books by author ID
+     * const booksByAuthor = store.query.index('book', 'authorId')
+     *
+     * // Get all books by a specific author
+     * const authorBooks = booksByAuthor.get().get('author:leguin')
+     * console.log(authorBooks) // Set<RecordId<Book>>
+     *
+     * // Index by title for quick title lookups
+     * const booksByTitle = store.query.index('book', 'title')
+     * const booksLatheOfHeaven = booksByTitle.get().get('The Lathe of Heaven')
+     * ```
      *
-     * @param typeName - The name of the type.
-     * @param property - The name of the property.
      * @public
      */
     index<TypeName extends R['typeName'], Property extends string & keyof Extract<R, {
@@ -799,13 +2108,26 @@ export declare class StoreQueries<R extends UnknownRecord> {
     }>, Property>;
     /* Excluded from this release type: __uncached_createIndex */
     /**
-     * Create a derivation that will return a signle record matching the given query.
+     * Creates a reactive query that returns the first record matching the given query criteria.
+     * Returns undefined if no matching record is found. The query automatically updates
+     * when records change.
+     *
+     * @param typeName - The type name of records to query
+     * @param queryCreator - Function that returns the query expression object to match against
+     * @param name - Optional name for the query computation (used for debugging)
+     * @returns A computed value containing the first matching record or undefined
+     *
+     * @example
+     * ```ts
+     * // Find the first book with a specific title
+     * const bookLatheOfHeaven = store.query.record('book', () => ({ title: { eq: 'The Lathe of Heaven' } }))
+     * console.log(bookLatheOfHeaven.get()?.title) // 'The Lathe of Heaven' or undefined
      *
-     * It will return undefined if there is no matching record
+     * // Find any book in stock
+     * const anyInStockBook = store.query.record('book', () => ({ inStock: { eq: true } }))
+     * ```
      *
-     * @param typeName - The name of the type?
-     * @param queryCreator - A function that returns the query expression.
-     * @param name - (optional) The name of the query.
+     * @public
      */
     record<TypeName extends R['typeName']>(typeName: TypeName, queryCreator?: () => QueryExpression<Extract<R, {
         typeName: TypeName;
@@ -813,11 +2135,28 @@ export declare class StoreQueries<R extends UnknownRecord> {
         typeName: TypeName;
     }> | undefined>;
     /**
-     * Create a derivation that will return an array of records matching the given query
+     * Creates a reactive query that returns an array of all records matching the given query criteria.
+     * The array automatically updates when records are added, updated, or removed.
+     *
+     * @param typeName - The type name of records to query
+     * @param queryCreator - Function that returns the query expression object to match against
+     * @param name - Optional name for the query computation (used for debugging)
+     * @returns A computed value containing an array of all matching records
+     *
+     * @example
+     * ```ts
+     * // Get all books in stock
+     * const inStockBooks = store.query.records('book', () => ({ inStock: { eq: true } }))
+     * console.log(inStockBooks.get()) // Book[]
+     *
+     * // Get all books by a specific author
+     * const leguinBooks = store.query.records('book', () => ({ authorId: { eq: 'author:leguin' } }))
+     *
+     * // Get all books (no filter)
+     * const allBooks = store.query.records('book')
+     * ```
      *
-     * @param typeName - The name of the type?
-     * @param queryCreator - A function that returns the query expression.
-     * @param name - (optinal) The name of the query.
+     * @public
      */
     records<TypeName extends R['typeName']>(typeName: TypeName, queryCreator?: () => QueryExpression<Extract<R, {
         typeName: TypeName;
@@ -825,11 +2164,29 @@ export declare class StoreQueries<R extends UnknownRecord> {
         typeName: TypeName;
     }>>>;
     /**
-     * Create a derivation that will return the ids of all records of the given type.
+     * Creates a reactive query that returns a set of record IDs matching the given query criteria.
+     * This is more efficient than `records()` when you only need the IDs and not the full record objects.
+     * The set automatically updates with collection diffs when records change.
+     *
+     * @param typeName - The type name of records to query
+     * @param queryCreator - Function that returns the query expression object to match against
+     * @param name - Optional name for the query computation (used for debugging)
+     * @returns A computed value containing a set of matching record IDs with collection diffs
+     *
+     * @example
+     * ```ts
+     * // Get IDs of all books in stock
+     * const inStockBookIds = store.query.ids('book', () => ({ inStock: { eq: true } }))
+     * console.log(inStockBookIds.get()) // Set<RecordId<Book>>
+     *
+     * // Get all book IDs (no filter)
+     * const allBookIds = store.query.ids('book')
+     *
+     * // Use with other queries for efficient lookups
+     * const authorBookIds = store.query.ids('book', () => ({ authorId: { eq: 'author:leguin' } }))
+     * ```
      *
-     * @param typeName - The name of the type.
-     * @param queryCreator - A function that returns the query expression.
-     * @param name - (optinal) The name of the query.
+     * @public
      */
     ids<TypeName extends R['typeName']>(typeName: TypeName, queryCreator?: () => QueryExpression<Extract<R, {
         typeName: TypeName;
@@ -838,6 +2195,27 @@ export declare class StoreQueries<R extends UnknownRecord> {
     }>>>, CollectionDiff<IdOf<Extract<R, {
         typeName: TypeName;
     }>>>>;
+    /**
+     * Executes a one-time query against the current store state and returns matching records.
+     * This is a non-reactive query that returns results immediately without creating a computed value.
+     * Use this when you need a snapshot of data at a specific point in time.
+     *
+     * @param typeName - The type name of records to query
+     * @param query - The query expression object to match against
+     * @returns An array of records that match the query at the current moment
+     *
+     * @example
+     * ```ts
+     * // Get current in-stock books (non-reactive)
+     * const currentInStockBooks = store.query.exec('book', { inStock: { eq: true } })
+     * console.log(currentInStockBooks) // Book[]
+     *
+     * // Unlike records(), this won't update when the data changes
+     * const staticBookList = store.query.exec('book', { authorId: { eq: 'author:leguin' } })
+     * ```
+     *
+     * @public
+     */
     exec<TypeName extends R['typeName']>(typeName: TypeName, query: QueryExpression<Extract<R, {
         typeName: TypeName;
     }>>): Array<Extract<R, {
@@ -847,12 +2225,72 @@ export declare class StoreQueries<R extends UnknownRecord> {
 
 /* Excluded from this release type: StoreRecord */
 
-/** @public */
+/**
+ * Manages the schema definition, validation, and migration system for a Store.
+ *
+ * StoreSchema coordinates record types, handles data migrations between schema
+ * versions, validates records, and provides the foundational structure for
+ * reactive stores. It acts as the central authority for data consistency
+ * and evolution within the store system.
+ *
+ * @example
+ * ```ts
+ * // Define record types
+ * const Book = createRecordType<Book>('book', { scope: 'document' })
+ * const Author = createRecordType<Author>('author', { scope: 'document' })
+ *
+ * // Create schema with migrations
+ * const schema = StoreSchema.create(
+ *   { book: Book, author: Author },
+ *   {
+ *     migrations: [bookMigrations, authorMigrations],
+ *     onValidationFailure: (failure) => {
+ *       console.warn('Validation failed, using default:', failure.error)
+ *       return failure.record // or return a corrected version
+ *     }
+ *   }
+ * )
+ *
+ * // Use with store
+ * const store = new Store({ schema })
+ * ```
+ *
+ * @public
+ */
 export declare class StoreSchema<R extends UnknownRecord, P = unknown> {
     readonly types: {
         [Record in R as Record['typeName']]: RecordType<R, any>;
     };
     private readonly options;
+    /**
+     * Creates a new StoreSchema with the given record types and options.
+     *
+     * This static factory method is the recommended way to create a StoreSchema.
+     * It ensures type safety while providing a clean API for schema definition.
+     *
+     * @param types - Object mapping type names to their RecordType definitions
+     * @param options - Optional configuration for migrations, validation, and integrity checking
+     * @returns A new StoreSchema instance
+     *
+     * @example
+     * ```ts
+     * const Book = createRecordType<Book>('book', { scope: 'document' })
+     * const Author = createRecordType<Author>('author', { scope: 'document' })
+     *
+     * const schema = StoreSchema.create(
+     *   {
+     *     book: Book,
+     *     author: Author
+     *   },
+     *   {
+     *     migrations: [bookMigrations],
+     *     onValidationFailure: (failure) => failure.record
+     *   }
+     * )
+     * ```
+     *
+     * @public
+     */
     static create<R extends UnknownRecord, P = unknown>(types: {
         [TypeName in R['typeName']]: {
             createId: any;
@@ -862,19 +2300,186 @@ export declare class StoreSchema<R extends UnknownRecord, P = unknown> {
     readonly sortedMigrations: readonly Migration[];
     private readonly migrationCache;
     private constructor();
+    /**
+     * Validates a record using its corresponding RecordType validator.
+     *
+     * This method ensures that records conform to their type definitions before
+     * being stored. If validation fails and an onValidationFailure handler is
+     * provided, it will be called to potentially recover from the error.
+     *
+     * @param store - The store instance where validation is occurring
+     * @param record - The record to validate
+     * @param phase - The lifecycle phase where validation is happening
+     * @param recordBefore - The previous version of the record (for updates)
+     * @returns The validated record, potentially modified by validation failure handler
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const validatedBook = schema.validateRecord(
+     *     store,
+     *     { id: 'book:1', typeName: 'book', title: '', author: 'Jane Doe' },
+     *     'createRecord',
+     *     null
+     *   )
+     * } catch (error) {
+     *   console.error('Record validation failed:', error)
+     * }
+     * ```
+     *
+     * @public
+     */
     validateRecord(store: Store<R>, record: R, phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord', recordBefore: null | R): R;
+    /**
+     * Gets all migrations that need to be applied to upgrade from a persisted schema
+     * to the current schema version.
+     *
+     * This method compares the persisted schema with the current schema and determines
+     * which migrations need to be applied to bring the data up to date. It handles
+     * both regular migrations and retroactive migrations, and caches results for
+     * performance.
+     *
+     * @param persistedSchema - The schema version that was previously persisted
+     * @returns A Result containing the list of migrations to apply, or an error message
+     *
+     * @example
+     * ```ts
+     * const persistedSchema = {
+     *   schemaVersion: 2,
+     *   sequences: { 'com.tldraw.book': 1, 'com.tldraw.author': 0 }
+     * }
+     *
+     * const migrationsResult = schema.getMigrationsSince(persistedSchema)
+     * if (migrationsResult.ok) {
+     *   console.log('Migrations to apply:', migrationsResult.value.length)
+     *   // Apply each migration to bring data up to date
+     * }
+     * ```
+     *
+     * @public
+     */
     getMigrationsSince(persistedSchema: SerializedSchema): Result<Migration[], string>;
+    /**
+     * Migrates a single persisted record to match the current schema version.
+     *
+     * This method applies the necessary migrations to transform a record from an
+     * older (or newer) schema version to the current version. It supports both
+     * forward ('up') and backward ('down') migrations.
+     *
+     * @param record - The record to migrate
+     * @param persistedSchema - The schema version the record was persisted with
+     * @param direction - Direction to migrate ('up' for newer, 'down' for older)
+     * @returns A MigrationResult containing the migrated record or an error
+     *
+     * @example
+     * ```ts
+     * const oldRecord = { id: 'book:1', typeName: 'book', title: 'Old Title', publishDate: '2020-01-01' }
+     * const oldSchema = { schemaVersion: 2, sequences: { 'com.tldraw.book': 1 } }
+     *
+     * const result = schema.migratePersistedRecord(oldRecord, oldSchema, 'up')
+     * if (result.type === 'success') {
+     *   console.log('Migrated record:', result.value)
+     *   // Record now has publishedYear instead of publishDate
+     * } else {
+     *   console.error('Migration failed:', result.reason)
+     * }
+     * ```
+     *
+     * @public
+     */
     migratePersistedRecord(record: R, persistedSchema: SerializedSchema, direction?: 'down' | 'up'): MigrationResult<R>;
+    /**
+     * Migrates an entire store snapshot to match the current schema version.
+     *
+     * This method applies all necessary migrations to bring a persisted store
+     * snapshot up to the current schema version. It handles both record-level
+     * and store-level migrations, and can optionally mutate the input store
+     * for performance.
+     *
+     * @param snapshot - The store snapshot containing data and schema information
+     * @param opts - Options controlling migration behavior
+     *   - mutateInputStore - Whether to modify the input store directly (default: false)
+     * @returns A MigrationResult containing the migrated store or an error
+     *
+     * @example
+     * ```ts
+     * const snapshot = {
+     *   schema: { schemaVersion: 2, sequences: { 'com.tldraw.book': 1 } },
+     *   store: {
+     *     'book:1': { id: 'book:1', typeName: 'book', title: 'Old Book', publishDate: '2020-01-01' }
+     *   }
+     * }
+     *
+     * const result = schema.migrateStoreSnapshot(snapshot)
+     * if (result.type === 'success') {
+     *   console.log('Migrated store:', result.value)
+     *   // All records are now at current schema version
+     * }
+     * ```
+     *
+     * @public
+     */
     migrateStoreSnapshot(snapshot: StoreSnapshot<R>, opts?: {
         mutateInputStore?: boolean;
     }): MigrationResult<SerializedStore<R>>;
     /* Excluded from this release type: createIntegrityChecker */
+    /**
+     * Serializes the current schema to a SerializedSchemaV2 format.
+     *
+     * This method creates a serialized representation of the current schema,
+     * capturing the latest version number for each migration sequence.
+     * The result can be persisted and later used to determine what migrations
+     * need to be applied when loading data.
+     *
+     * @returns A SerializedSchemaV2 object representing the current schema state
+     *
+     * @example
+     * ```ts
+     * const serialized = schema.serialize()
+     * console.log(serialized)
+     * // {
+     * //   schemaVersion: 2,
+     * //   sequences: {
+     * //     'com.tldraw.book': 3,
+     * //     'com.tldraw.author': 2
+     * //   }
+     * // }
+     *
+     * // Store this with your data for future migrations
+     * localStorage.setItem('schema', JSON.stringify(serialized))
+     * ```
+     *
+     * @public
+     */
     serialize(): SerializedSchemaV2;
     /* Excluded from this release type: serializeEarliestVersion */
     /* Excluded from this release type: getType */
 }
 
-/** @public */
+/**
+ * Configuration options for creating a StoreSchema.
+ *
+ * These options control migration behavior, validation error handling,
+ * and integrity checking for the store schema.
+ *
+ * @example
+ * ```ts
+ * const options: StoreSchemaOptions<MyRecord, MyProps> = {
+ *   migrations: [bookMigrations, authorMigrations],
+ *   onValidationFailure: (failure) => {
+ *     // Log the error and return a corrected record
+ *     console.error('Validation failed:', failure.error)
+ *     return sanitizeRecord(failure.record)
+ *   },
+ *   createIntegrityChecker: (store) => {
+ *     // Set up integrity checking logic
+ *     return setupIntegrityChecks(store)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface StoreSchemaOptions<R extends UnknownRecord, P> {
     migrations?: MigrationSequence[];
     /** @public */
@@ -884,14 +2489,36 @@ export declare interface StoreSchemaOptions<R extends UnknownRecord, P> {
 
 /**
  * The side effect manager (aka a "correct state enforcer") is responsible
- * for making sure that the editor's state is always correct. This includes
+ * for making sure that the store's state is always correct and consistent. This includes
  * things like: deleting a shape if its parent is deleted; unbinding
- * arrows when their binding target is deleted; etc.
+ * arrows when their binding target is deleted; maintaining referential integrity; etc.
+ *
+ * Side effects are organized into lifecycle hooks that run before and after
+ * record operations (create, change, delete), allowing you to validate data,
+ * transform records, and maintain business rules.
+ *
+ * @example
+ * ```ts
+ * const sideEffects = new StoreSideEffects(store)
+ *
+ * // Ensure arrows are deleted when their target shape is deleted
+ * sideEffects.registerAfterDeleteHandler('shape', (shape) => {
+ *   const arrows = store.query.records('arrow', () => ({
+ *     toId: { eq: shape.id }
+ *   })).get()
+ *   store.remove(arrows.map(arrow => arrow.id))
+ * })
+ * ```
  *
  * @public
  */
 export declare class StoreSideEffects<R extends UnknownRecord> {
     private readonly store;
+    /**
+     * Creates a new side effects manager for the given store.
+     *
+     * store - The store instance to manage side effects for
+     */
     constructor(store: Store<R>);
     private _beforeCreateHandlers;
     private _afterCreateHandlers;
@@ -1103,13 +2730,52 @@ export declare class StoreSideEffects<R extends UnknownRecord> {
     registerOperationCompleteHandler(handler: StoreOperationCompleteHandler): () => void;
 }
 
-/** @public */
+/**
+ * A snapshot of the store including both data and schema information.
+ * This enables proper migration when loading data from different schema versions.
+ *
+ * @example
+ * ```ts
+ * const snapshot = store.getStoreSnapshot()
+ * // Later...
+ * store.loadStoreSnapshot(snapshot)
+ * ```
+ *
+ * @public
+ */
 export declare interface StoreSnapshot<R extends UnknownRecord> {
+    /** The serialized store data */
     store: SerializedStore<R>;
+    /** The serialized schema information */
     schema: SerializedSchema;
 }
 
-/** @public */
+/**
+ * Information about a record validation failure that occurred in the store.
+ *
+ * This interface provides context about validation errors, including the failed
+ * record, the store state, and the operation phase where the failure occurred.
+ * It's used by validation failure handlers to implement recovery strategies.
+ *
+ * @example
+ * ```ts
+ * const schema = StoreSchema.create(
+ *   { book: Book },
+ *   {
+ *     onValidationFailure: (failure: StoreValidationFailure<Book>) => {
+ *       console.error(`Validation failed during ${failure.phase}:`, failure.error)
+ *       console.log('Failed record:', failure.record)
+ *       console.log('Previous record:', failure.recordBefore)
+ *
+ *       // Return a corrected version of the record
+ *       return { ...failure.record, title: failure.record.title || 'Untitled' }
+ *     }
+ *   }
+ * )
+ * ```
+ *
+ * @public
+ */
 export declare interface StoreValidationFailure<R extends UnknownRecord> {
     error: unknown;
     store: Store<R>;
@@ -1118,20 +2784,85 @@ export declare interface StoreValidationFailure<R extends UnknownRecord> {
     recordBefore: null | R;
 }
 
-/** @public */
+/**
+ * A validator for store records that ensures data integrity.
+ * Validators are called when records are created or updated.
+ *
+ * @example
+ * ```ts
+ * const bookValidator: StoreValidator<Book> = {
+ *   validate(record: unknown): Book {
+ *     // Validate and return the record
+ *     if (typeof record !== 'object' || !record.title) {
+ *       throw new Error('Invalid book')
+ *     }
+ *     return record as Book
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface StoreValidator<R extends UnknownRecord> {
+    /**
+     * Validate a record.
+     *
+     * @param record - The record to validate
+     * @returns The validated record
+     * @throws When validation fails
+     */
     validate(record: unknown): R;
+    /**
+     * Validate a record using a known good version for reference.
+     *
+     * @param knownGoodVersion - A known valid version of the record
+     * @param record - The record to validate
+     * @returns The validated record
+     */
     validateUsingKnownGoodVersion?(knownGoodVersion: R, record: unknown): R;
 }
 
-/** @public */
+/**
+ * A map of validators for each record type in the store.
+ *
+ * @example
+ * ```ts
+ * const validators: StoreValidators<Book | Author> = {
+ *   book: bookValidator,
+ *   author: authorValidator
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type StoreValidators<R extends UnknownRecord> = {
     [K in R['typeName']]: StoreValidator<Extract<R, {
         typeName: K;
     }>>;
 };
 
-/** @public */
+/**
+ * A generic type representing any record that extends BaseRecord.
+ * This is useful for type constraints when you need to work with records of unknown types,
+ * but still want to ensure they follow the BaseRecord structure.
+ *
+ * @example
+ * ```ts
+ * // Function that works with any type of record
+ * function logRecord(record: UnknownRecord): void {
+ *   console.log(`Record ${record.id} of type ${record.typeName}`)
+ * }
+ *
+ * // Can be used with any record type
+ * const book: Book = { id: 'book:123' as RecordId<Book>, typeName: 'book', title: '1984' }
+ * const author: Author = { id: 'author:456' as RecordId<Author>, typeName: 'author', name: 'Orwell' }
+ *
+ * logRecord(book)   // "Record book:123 of type book"
+ * logRecord(author) // "Record author:456 of type author"
+ * ```
+ *
+ * @public
+ */
 export declare type UnknownRecord = BaseRecord<string, RecordId<UnknownRecord>>;
 
 export { }