@tldraw/utils 4.0.3 → 4.1.0-canary.0259516ffb8c

package/dist-cjs/index.d.ts

@@ -14,16 +14,54 @@ import { default as uniq } from 'lodash.uniq';
 /* Excluded from this release type: assertExists */
 
 /**
- * `@bind` is a decorator that binds the method to the instance of the class (legacy stage-2
- * typescript decorators).
+ * Decorator that binds a method to its class instance (legacy stage-2 TypeScript decorators).
+ * When applied to a class method, ensures `this` always refers to the class instance,
+ * even when the method is called as a callback or event handler.
  *
+ * @param target - The prototype of the class being decorated
+ * @param propertyKey - The name of the method being decorated
+ * @param descriptor - The property descriptor for the method being decorated
+ * @returns The modified property descriptor with bound method access
+ * @example
+ * ```typescript
+ * class MyClass {
+ *   name = 'example';
+ *
+ *   @bind
+ *   getName() {
+ *     return this.name;
+ *   }
+ * }
+ *
+ * const instance = new MyClass();
+ * const callback = instance.getName;
+ * console.log(callback()); // 'example' (this is properly bound)
+ * ```
  * @public
  */
 export declare function bind<T extends (...args: any[]) => any>(target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T>;
 
 /**
- * `@bind` is a decorator that binds the method to the instance of the class (TC39 decorators).
+ * Decorator that binds a method to its class instance (TC39 decorators standard).
+ * When applied to a class method, ensures `this` always refers to the class instance,
+ * even when the method is called as a callback or event handler.
  *
+ * @param originalMethod - The original method being decorated
+ * @param context - The decorator context containing metadata about the method
+ * @example
+ * ```typescript
+ * class EventHandler {
+ *   message = 'Hello World';
+ *
+ *   @bind
+ *   handleClick() {
+ *     console.log(this.message);
+ *   }
+ * }
+ *
+ * const handler = new EventHandler();
+ * document.addEventListener('click', handler.handleClick); // 'this' is properly bound
+ * ```
  * @public
  */
 export declare function bind<This extends object, T extends (...args: any[]) => any>(originalMethod: T, context: ClassMethodDecoratorContext<This, T>): void;
@@ -35,12 +73,37 @@ export declare function bind<This extends object, T extends (...args: any[]) =>
 /* Excluded from this release type: compact */
 
 /**
- * Debounce a function.
+ * Create a debounced version of a function that delays execution until after a specified wait time.
  *
- * @example
+ * Debouncing ensures that a function is only executed once after a specified delay,
+ * even if called multiple times in rapid succession. Each new call resets the timer. The debounced
+ * function returns a Promise that resolves with the result of the original function. Includes a
+ * cancel method to prevent execution if needed.
+ *
+ * @param callback - The function to debounce (can be sync or async)
+ * @param wait - The delay in milliseconds before executing the function
+ * @returns A debounced function that returns a Promise and includes a cancel method
  *
+ * @example
  * ```ts
- * const A = debounce(myFunction, 1000)
+ * // Debounce a search function
+ * const searchAPI = (query: string) => fetch(`/search?q=${query}`)
+ * const debouncedSearch = debounce(searchAPI, 300)
+ *
+ * // Multiple rapid calls will only execute the last one after 300ms
+ * debouncedSearch('react').then(result => console.log(result))
+ * debouncedSearch('react hooks') // This cancels the previous call
+ * debouncedSearch('react typescript') // Only this will execute
+ *
+ * // Cancel pending execution
+ * debouncedSearch.cancel()
+ *
+ * // With async/await
+ * const saveData = debounce(async (data: any) => {
+ *   return await api.save(data)
+ * }, 1000)
+ *
+ * const result = await saveData({name: 'John'})
  * ```
  *
  * @public
@@ -52,22 +115,88 @@ export declare function debounce<T extends unknown[], U>(callback: (...args: T)
 };
 
 /**
- * Deduplicate the items in an array
+ * Remove duplicate items from an array.
+ *
+ * Creates a new array with duplicate items removed. Uses strict equality by default,
+ * or a custom equality function if provided. Order of first occurrence is preserved.
  *
+ * @param input - The array to deduplicate
+ * @param equals - Optional custom equality function to compare items (defaults to strict equality)
+ * @returns A new array with duplicate items removed
+ *
+ * @example
+ * ```ts
+ * dedupe([1, 2, 2, 3, 1]) // [1, 2, 3]
+ * dedupe(['a', 'b', 'a', 'c']) // ['a', 'b', 'c']
+ *
+ * // With custom equality function
+ * const objects = [{id: 1}, {id: 2}, {id: 1}]
+ * dedupe(objects, (a, b) => a.id === b.id) // [{id: 1}, {id: 2}]
+ * ```
  * @public
  */
 export declare function dedupe<T>(input: T[], equals?: (a: any, b: any) => boolean): T[];
 
-/** @public */
+/**
+ * Array of supported video MIME types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORT_VIDEO_TYPES } from '@tldraw/utils'
+ *
+ * const isVideo = DEFAULT_SUPPORT_VIDEO_TYPES.includes('video/mp4')
+ * console.log(isVideo) // true
+ * ```
+ * @public
+ */
 export declare const DEFAULT_SUPPORT_VIDEO_TYPES: readonly ("video/mp4" | "video/quicktime" | "video/webm")[];
 
-/** @public */
+/**
+ * Array of all supported image MIME types, combining static, vector, and animated types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_IMAGE_TYPES } from '@tldraw/utils'
+ *
+ * const isSupported = DEFAULT_SUPPORTED_IMAGE_TYPES.includes('image/png')
+ * console.log(isSupported) // true
+ * ```
+ * @public
+ */
 export declare const DEFAULT_SUPPORTED_IMAGE_TYPES: readonly ("image/apng" | "image/avif" | "image/gif" | "image/jpeg" | "image/png" | "image/svg+xml" | "image/webp")[];
 
-/** @public */
+/**
+ * Comma-separated string of all supported media MIME types, useful for HTML file input accept attributes.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_MEDIA_TYPE_LIST } from '@tldraw/utils'
+ *
+ * // Use in HTML file input for media uploads
+ * const input = document.createElement('input')
+ * input.type = 'file'
+ * input.accept = DEFAULT_SUPPORTED_MEDIA_TYPE_LIST
+ * input.addEventListener('change', (e) => {
+ *   const files = (e.target as HTMLInputElement).files
+ *   if (files) console.log(`Selected ${files.length} file(s)`)
+ * })
+ * ```
+ * @public
+ */
 export declare const DEFAULT_SUPPORTED_MEDIA_TYPE_LIST: string;
 
-/** @public */
+/**
+ * Array of all supported media MIME types, combining images and videos.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_MEDIA_TYPES } from '@tldraw/utils'
+ *
+ * const isMediaFile = DEFAULT_SUPPORTED_MEDIA_TYPES.includes('video/mp4')
+ * console.log(isMediaFile) // true
+ * ```
+ * @public
+ */
 export declare const DEFAULT_SUPPORTED_MEDIA_TYPES: readonly ("image/apng" | "image/avif" | "image/gif" | "image/jpeg" | "image/png" | "image/svg+xml" | "image/webp" | "video/mp4" | "video/quicktime" | "video/webm")[];
 
 /* Excluded from this release type: deleteFromLocalStorage */
@@ -80,7 +209,21 @@ export declare interface ErrorAnnotations {
     extras: Record<string, unknown>;
 }
 
-/** @public */
+/**
+ * Represents a failed result containing an error.
+ *
+ * Interface for the error case of a Result type, containing the error information.
+ * Used in conjunction with OkResult to create a discriminated union for error handling.
+ *
+ * @example
+ * ```ts
+ * const failure: ErrorResult<string> = { ok: false, error: 'Something went wrong' }
+ * if (!failure.ok) {
+ *   console.error(failure.error) // 'Something went wrong'
+ * }
+ * ```
+ * @public
+ */
 export declare interface ErrorResult<E> {
     readonly ok: false;
     readonly error: E;
@@ -90,7 +233,27 @@ export declare interface ErrorResult<E> {
 
 /* Excluded from this release type: exhaustiveSwitchError */
 
-/** @public */
+/**
+ * Expands a type definition to show its full structure in IDE tooltips and error messages.
+ * This utility type forces TypeScript to resolve and display the complete type structure
+ * instead of showing complex conditional types or intersections as-is.
+ *
+ * @example
+ * ```ts
+ * type User = { name: string }
+ * type WithId = { id: string }
+ * type UserWithId = User & WithId
+ *
+ * // Without Expand, IDE shows: User & WithId
+ * // With Expand, IDE shows: { name: string; id: string }
+ * type ExpandedUserWithId = Expand<UserWithId>
+ *
+ * // Useful for complex intersections
+ * type ComplexType = Expand<BaseType & Mixin1 & Mixin2>
+ * ```
+ *
+ * @public
+ */
 export declare type Expand<T> = T extends infer O ? {
     [K in keyof O]: O[K];
 } : never;
@@ -98,41 +261,146 @@ export declare type Expand<T> = T extends infer O ? {
 /* Excluded from this release type: fetch_2 */
 
 /**
- * Helpers for files
+ * Utility class providing helper methods for file and blob operations.
+ *
+ * FileHelpers contains static methods for common file operations including
+ * URL fetching, format conversion, and MIME type manipulation. All methods work with
+ * web APIs like fetch, FileReader, and Blob/File objects.
+ *
+ * @example
+ * ```ts
+ * // Fetch and convert a remote image to data URL
+ * const dataUrl = await FileHelpers.urlToDataUrl('https://example.com/image.png')
+ *
+ * // Convert user-selected file to text
+ * const text = await FileHelpers.blobToText(userFile)
+ *
+ * // Change file MIME type
+ * const newFile = FileHelpers.rewriteMimeType(originalFile, 'application/json')
+ * ```
  *
  * @public
  */
 export declare class FileHelpers {
     /**
-     * @param url - The url of the file.
+     * Converts a URL to an ArrayBuffer by fetching the resource.
+     *
+     * Fetches the resource at the given URL and returns its content as an ArrayBuffer.
+     * This is useful for loading binary data like images, videos, or other file types.
+     *
+     * @param url - The URL of the file to fetch
+     * @returns Promise that resolves to the file content as an ArrayBuffer
+     * @example
+     * ```ts
+     * const buffer = await FileHelpers.urlToArrayBuffer('https://example.com/image.png')
+     * console.log(buffer.byteLength) // Size of the file in bytes
+     * ```
+     * @public
      */
     static urlToArrayBuffer(url: string): Promise<ArrayBuffer>;
-    static urlToBlob(url: string): Promise<Blob>;
-    static urlToDataUrl(url: string): Promise<string>;
     /**
-     * Convert a file to a base64 encoded data url.
+     * Converts a URL to a Blob by fetching the resource.
      *
+     * Fetches the resource at the given URL and returns its content as a Blob object.
+     * Blobs are useful for handling file data in web applications.
+     *
+     * @param url - The URL of the file to fetch
+     * @returns Promise that resolves to the file content as a Blob
      * @example
+     * ```ts
+     * const blob = await FileHelpers.urlToBlob('https://example.com/document.pdf')
+     * console.log(blob.type) // 'application/pdf'
+     * console.log(blob.size) // Size in bytes
+     * ```
+     * @public
+     */
+    static urlToBlob(url: string): Promise<Blob>;
+    /**
+     * Converts a URL to a data URL by fetching the resource.
+     *
+     * Fetches the resource at the given URL and converts it to a base64-encoded data URL.
+     * If the URL is already a data URL, it returns the URL unchanged. This is useful for embedding
+     * resources directly in HTML or CSS.
      *
+     * @param url - The URL of the file to convert, or an existing data URL
+     * @returns Promise that resolves to a data URL string
+     * @example
      * ```ts
-     * const A = FileHelpers.toDataUrl(myImageFile)
+     * const dataUrl = await FileHelpers.urlToDataUrl('https://example.com/image.jpg')
+     * // Returns: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...'
+     *
+     * const existing = await FileHelpers.urlToDataUrl('data:text/plain;base64,SGVsbG8=')
+     * // Returns the same data URL unchanged
      * ```
+     * @public
+     */
+    static urlToDataUrl(url: string): Promise<string>;
+    /**
+     * Convert a Blob to a base64 encoded data URL.
+     *
+     * Converts a Blob object to a base64-encoded data URL using the FileReader API.
+     * This is useful for displaying images or embedding file content directly in HTML.
+     *
+     * @param file - The Blob object to convert
+     * @returns Promise that resolves to a base64-encoded data URL string
+     * @example
+     * ```ts
+     * const blob = new Blob(['Hello World'], { type: 'text/plain' })
+     * const dataUrl = await FileHelpers.blobToDataUrl(blob)
+     * // Returns: 'data:text/plain;base64,SGVsbG8gV29ybGQ='
      *
-     * @param file - The file as a blob.
+     * // With an image file
+     * const imageDataUrl = await FileHelpers.blobToDataUrl(myImageFile)
+     * // Can be used directly in img src attribute
+     * ```
+     * @public
      */
     static blobToDataUrl(file: Blob): Promise<string>;
     /**
-     * Convert a file to a unicode text string.
+     * Convert a Blob to a unicode text string.
      *
-     * @example
+     * Reads the content of a Blob object as a UTF-8 text string using the FileReader API.
+     * This is useful for reading text files or extracting text content from blobs.
      *
+     * @param file - The Blob object to convert to text
+     * @returns Promise that resolves to the text content as a string
+     * @example
      * ```ts
-     * const A = FileHelpers.fileToDataUrl(myTextFile)
-     * ```
+     * const textBlob = new Blob(['Hello World'], { type: 'text/plain' })
+     * const text = await FileHelpers.blobToText(textBlob)
+     * console.log(text) // 'Hello World'
      *
-     * @param file - The file as a blob.
+     * // With a text file from user input
+     * const content = await FileHelpers.blobToText(myTextFile)
+     * console.log(content) // File content as string
+     * ```
+     * @public
      */
     static blobToText(file: Blob): Promise<string>;
+    /**
+     * Creates a new Blob or File with a different MIME type.
+     *
+     * Creates a copy of the given Blob or File with a new MIME type while preserving
+     * all other properties. If the current MIME type already matches the new one, returns the
+     * original object unchanged. For File objects, preserves the filename.
+     *
+     * @param blob - The Blob or File object to modify
+     * @param newMimeType - The new MIME type to assign
+     * @returns A new Blob or File with the updated MIME type
+     * @example
+     * ```ts
+     * // Change a generic blob to a specific image type
+     * const blob = new Blob([imageData])
+     * const imageBlob = FileHelpers.rewriteMimeType(blob, 'image/png')
+     *
+     * // Change a file's MIME type while preserving filename
+     * const file = new File([data], 'document.txt', { type: 'text/plain' })
+     * const jsonFile = FileHelpers.rewriteMimeType(file, 'application/json')
+     * console.log(jsonFile.name) // 'document.txt' (preserved)
+     * console.log(jsonFile.type) // 'application/json' (updated)
+     * ```
+     * @public
+     */
     static rewriteMimeType(blob: Blob, newMimeType: string): Blob;
     static rewriteMimeType(blob: File, newMimeType: string): File;
 }
@@ -148,19 +416,18 @@ export declare class FileHelpers {
 /**
  * Get the first item from an iterable Set or Map.
  *
+ * @param value - The iterable Set or Map to get the first item from
+ * @returns The first value from the Set or Map
  * @example
- *
  * ```ts
- * const A = getFirstItem(new Set([1, 2, 3])) // 1
- * const B = getFirstItem(
+ * const A = getFirstFromIterable(new Set([1, 2, 3])) // 1
+ * const B = getFirstFromIterable(
  * 	new Map([
  * 		['a', 1],
  * 		['b', 2],
  * 	])
  * ) // 1
  * ```
- *
- * @param value - The iterable Set or Map.
  * @public
  */
 export declare function getFirstFromIterable<T = unknown>(set: Map<any, T> | Set<T>): T;
@@ -172,13 +439,47 @@ export declare function getFirstFromIterable<T = unknown>(set: Map<any, T> | Set
 /**
  * Hash an ArrayBuffer using the FNV-1a algorithm.
  *
+ * Generates a deterministic hash value for binary data stored in an ArrayBuffer.
+ * Processes the buffer byte by byte using the same hashing algorithm as getHashForString.
+ * Useful for creating consistent identifiers for binary data like images or files.
+ *
+ * @param buffer - The ArrayBuffer containing binary data to hash
+ * @returns A string representation of the 32-bit hash value
+ * @example
+ * ```ts
+ * // Hash some binary data
+ * const data = new Uint8Array([1, 2, 3, 4, 5])
+ * const hash = getHashForBuffer(data.buffer)
+ * console.log(hash) // '123456789'
+ *
+ * // Hash image file data
+ * const fileBuffer = await file.arrayBuffer()
+ * const fileHash = getHashForBuffer(fileBuffer)
+ * console.log(fileHash) // Unique hash for the file
+ * ```
  * @public
  */
 export declare function getHashForBuffer(buffer: ArrayBuffer): string;
 
 /**
- * Hash a string using the FNV-1a algorithm.
+ * Hash an object by converting it to JSON and then hashing the resulting string.
+ *
+ * Converts the object to a JSON string using JSON.stringify and then applies the same
+ * hashing algorithm as getHashForString. Useful for creating consistent hash values
+ * for objects, though the hash depends on JSON serialization order.
+ *
+ * @param obj - The object to hash (any JSON-serializable value)
+ * @returns A string representation of the 32-bit hash value
+ * @example
+ * ```ts
+ * const hash1 = getHashForObject({ name: 'John', age: 30 })
+ * const hash2 = getHashForObject({ name: 'John', age: 30 })
+ * console.log(hash1 === hash2) // true
  *
+ * // Arrays work too
+ * const arrayHash = getHashForObject([1, 2, 3, 'hello'])
+ * console.log(arrayHash) // '-123456789'
+ * ```
  * @public
  */
 export declare function getHashForObject(obj: any): string;
@@ -186,6 +487,20 @@ export declare function getHashForObject(obj: any): string;
 /**
  * Hash a string using the FNV-1a algorithm.
  *
+ * Generates a deterministic hash value for a given string using a variant of the FNV-1a
+ * (Fowler-Noll-Vo) algorithm. The hash is returned as a string representation of a 32-bit integer.
+ *
+ * @param string - The input string to hash
+ * @returns A string representation of the 32-bit hash value
+ * @example
+ * ```ts
+ * const hash = getHashForString('hello world')
+ * console.log(hash) // '-862545276'
+ *
+ * // Same input always produces same hash
+ * const hash2 = getHashForString('hello world')
+ * console.log(hash === hash2) // true
+ * ```
  * @public
  */
 export declare function getHashForString(string: string): string;
@@ -193,6 +508,12 @@ export declare function getHashForString(string: string): string;
 /**
  * Get the index above a given index.
  * @param below - The index below.
+ * @returns An IndexKey value above the given index.
+ * @example
+ * ```ts
+ * const index = getIndexAbove('a0' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
  * @public
  */
 export declare function getIndexAbove(below?: IndexKey | null | undefined): IndexKey;
@@ -200,7 +521,13 @@ export declare function getIndexAbove(below?: IndexKey | null | undefined): Inde
 /**
  * Get the index below a given index.
  * @param above - The index above.
- *  @public
+ * @returns An IndexKey value below the given index.
+ * @example
+ * ```ts
+ * const index = getIndexBelow('a2' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
+ * @public
  */
 export declare function getIndexBelow(above?: IndexKey | null | undefined): IndexKey;
 
@@ -208,6 +535,12 @@ export declare function getIndexBelow(above?: IndexKey | null | undefined): Inde
  * Get the index between two indices.
  * @param below - The index below.
  * @param above - The index above.
+ * @returns A single IndexKey value between below and above.
+ * @example
+ * ```ts
+ * const index = getIndexBetween('a0' as IndexKey, 'a2' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
  * @public
  */
 export declare function getIndexBetween(below: IndexKey | null | undefined, above: IndexKey | null | undefined): IndexKey;
@@ -215,7 +548,13 @@ export declare function getIndexBetween(below: IndexKey | null | undefined, abov
 /**
  * Get n number of indices, starting at an index.
  * @param n - The number of indices to get.
- * @param start -  The index to start at.
+ * @param start - The index to start at.
+ * @returns An array containing the start index plus n additional IndexKey values.
+ * @example
+ * ```ts
+ * const indices = getIndices(3, 'a1' as IndexKey)
+ * console.log(indices) // ['a1', 'a2', 'a3', 'a4']
+ * ```
  * @public
  */
 export declare function getIndices(n: number, start?: IndexKey): IndexKey[];
@@ -224,6 +563,12 @@ export declare function getIndices(n: number, start?: IndexKey): IndexKey[];
  * Get a number of indices above an index.
  * @param below - The index below.
  * @param n - The number of indices to get.
+ * @returns An array of n IndexKey values above the given index.
+ * @example
+ * ```ts
+ * const indices = getIndicesAbove('a0' as IndexKey, 3)
+ * console.log(indices) // ['a1', 'a2', 'a3']
+ * ```
  * @public
  */
 export declare function getIndicesAbove(below: IndexKey | null | undefined, n: number): IndexKey[];
@@ -232,6 +577,12 @@ export declare function getIndicesAbove(below: IndexKey | null | undefined, n: n
  * Get a number of indices below an index.
  * @param above - The index above.
  * @param n - The number of indices to get.
+ * @returns An array of n IndexKey values below the given index.
+ * @example
+ * ```ts
+ * const indices = getIndicesBelow('a2' as IndexKey, 2)
+ * console.log(indices) // ['a1', 'a0V']
+ * ```
  * @public
  */
 export declare function getIndicesBelow(above: IndexKey | null | undefined, n: number): IndexKey[];
@@ -241,6 +592,12 @@ export declare function getIndicesBelow(above: IndexKey | null | undefined, n: n
  * @param below - The index below.
  * @param above - The index above.
  * @param n - The number of indices to get.
+ * @returns An array of n IndexKey values between below and above.
+ * @example
+ * ```ts
+ * const indices = getIndicesBetween('a0' as IndexKey, 'a2' as IndexKey, 2)
+ * console.log(indices) // ['a0V', 'a1']
+ * ```
  * @public
  */
 export declare function getIndicesBetween(below: IndexKey | null | undefined, above: IndexKey | null | undefined, n: number): IndexKey[];
@@ -265,9 +622,18 @@ export declare type IndexKey = string & {
 };
 
 /**
- * Inverse lerp between two values. Given a value `n` in the range [a, b], returns a number between
+ * Inverse lerp between two values. Given a value `t` in the range [a, b], returns a number between
  * 0 and 1.
  *
+ * @param a - The start value of the range
+ * @param b - The end value of the range
+ * @param t - The value within the range [a, b]
+ * @returns The normalized position (0-1) of t within the range [a, b]
+ * @example
+ * ```ts
+ * const position = invLerp(0, 100, 25) // 0.25
+ * const normalized = invLerp(10, 20, 15) // 0.5
+ * ```
  * @public
  */
 export declare function invLerp(a: number, b: number, t: number): number;
@@ -276,6 +642,20 @@ export declare function invLerp(a: number, b: number, t: number): number;
  * Get whether a value is not undefined.
  *
  * @param value - The value to check.
+ * @returns True if the value is not undefined, with proper type narrowing.
+ * @example
+ * ```ts
+ * const maybeString: string | undefined = getValue()
+ *
+ * if (isDefined(maybeString)) {
+ *   // TypeScript knows maybeString is string, not undefined
+ *   console.log(maybeString.toUpperCase())
+ * }
+ *
+ * // Filter undefined values from arrays
+ * const values = [1, undefined, 2, undefined, 3]
+ * const definedValues = values.filter(isDefined) // [1, 2, 3]
+ * ```
  * @public
  */
 export declare function isDefined<T>(value: T): value is typeof value extends undefined ? never : T;
@@ -288,33 +668,125 @@ export { isEqualWith }
 /* Excluded from this release type: isNativeStructuredClone */
 
 /**
- * Get whether a value is null
+ * Get whether a value is not null.
  *
  * @param value - The value to check.
+ * @returns True if the value is not null, with proper type narrowing.
+ * @example
+ * ```ts
+ * const maybeString: string | null = getValue()
+ *
+ * if (isNonNull(maybeString)) {
+ *   // TypeScript knows maybeString is string, not null
+ *   console.log(maybeString.length)
+ * }
+ *
+ * // Filter null values from arrays
+ * const values = ["a", null, "b", null, "c"]
+ * const nonNullValues = values.filter(isNonNull) // ["a", "b", "c"]
+ * ```
  * @public
  */
 export declare function isNonNull<T>(value: T): value is typeof value extends null ? never : T;
 
 /**
- * Get whether a value is nullish (null, undefined).
+ * Get whether a value is not nullish (not null and not undefined).
  *
  * @param value - The value to check.
+ * @returns True if the value is neither null nor undefined, with proper type narrowing.
+ * @example
+ * ```ts
+ * const maybeString: string | null | undefined = getValue()
+ *
+ * if (isNonNullish(maybeString)) {
+ *   // TypeScript knows maybeString is string, not null or undefined
+ *   console.log(maybeString.charAt(0))
+ * }
+ *
+ * // Filter nullish values from arrays
+ * const values = ["hello", null, "world", undefined, "!"]
+ * const cleanValues = values.filter(isNonNullish) // ["hello", "world", "!"]
+ * ```
  * @public
  */
 export declare function isNonNullish<T>(value: T): value is typeof value extends undefined ? never : typeof value extends null ? never : T;
 
-/** @public */
+/**
+ * A type representing a JSON array containing any valid JSON values.
+ * Arrays can contain mixed types of JSON values including nested arrays and objects.
+ *
+ * @example
+ * ```ts
+ * const jsonArray: JsonArray = [
+ *   "text",
+ *   123,
+ *   true,
+ *   { nested: "object" },
+ *   [1, 2, 3]
+ * ]
+ * ```
+ *
+ * @public
+ */
 export declare type JsonArray = JsonValue[];
 
-/** @public */
+/**
+ * A type representing a JSON object with string keys and JSON values.
+ * Object values can be undefined to handle optional properties safely.
+ *
+ * @example
+ * ```ts
+ * const jsonObject: JsonObject = {
+ *   required: "value",
+ *   optional: undefined,
+ *   nested: {
+ *     deep: "property"
+ *   },
+ *   array: [1, 2, 3]
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare interface JsonObject {
     [key: string]: JsonValue | undefined;
 }
 
-/** @public */
+/**
+ * A type representing JSON primitive values: boolean, null, string, or number.
+ * These are the atomic values that can appear in JSON data.
+ *
+ * @example
+ * ```ts
+ * const primitives: JsonPrimitive[] = [
+ *   true,
+ *   null,
+ *   "hello",
+ *   42
+ * ]
+ * ```
+ *
+ * @public
+ */
 export declare type JsonPrimitive = boolean | null | number | string;
 
-/** @public */
+/**
+ * A type that represents any valid JSON value. This includes primitives (boolean, null, string, number),
+ * arrays of JSON values, and objects with string keys and JSON values.
+ *
+ * @example
+ * ```ts
+ * const jsonData: JsonValue = {
+ *   name: "Alice",
+ *   age: 30,
+ *   active: true,
+ *   tags: ["user", "premium"],
+ *   metadata: null
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type JsonValue = JsonArray | JsonObject | JsonPrimitive;
 
 /* Excluded from this release type: last */
@@ -322,20 +794,72 @@ export declare type JsonValue = JsonArray | JsonObject | JsonPrimitive;
 /**
  * Linear interpolate between two values.
  *
+ * @param a - The start value
+ * @param b - The end value
+ * @param t - The interpolation factor (0-1)
+ * @returns The interpolated value
  * @example
- *
  * ```ts
- * const A = lerp(0, 1, 0.5)
+ * const halfway = lerp(0, 100, 0.5) // 50
+ * const quarter = lerp(10, 20, 0.25) // 12.5
  * ```
- *
  * @public
  */
 export declare function lerp(a: number, b: number, t: number): number;
 
-/** @public */
+/**
+ * Applies a string transformation algorithm that rearranges and modifies characters.
+ *
+ * Performs a series of character manipulations on the input string including
+ * character repositioning through splicing operations and numeric character transformations.
+ * This appears to be a custom encoding/obfuscation function.
+ *
+ * @param str - The input string to transform
+ * @returns The transformed string after applying all manipulations
+ * @example
+ * ```ts
+ * const result = lns('hello123')
+ * console.log(result) // Transformed string (exact output depends on algorithm)
+ *
+ * // Can be used for simple string obfuscation
+ * const obfuscated = lns('sensitive-data')
+ * console.log(obfuscated) // Obfuscated version
+ * ```
+ * @public
+ */
 export declare function lns(str: string): string;
 
-/** @public */
+/**
+ * Automatically makes properties optional if their type includes `undefined`.
+ * This transforms properties like `prop: string | undefined` to `prop?: string | undefined`,
+ * making the API more ergonomic by not requiring explicit undefined assignments.
+ *
+ * @example
+ * ```ts
+ * interface RawConfig {
+ *   name: string
+ *   theme: string | undefined
+ *   debug: boolean | undefined
+ *   version: number
+ * }
+ *
+ * type Config = MakeUndefinedOptional<RawConfig>
+ * // Result: {
+ * //   name: string
+ * //   theme?: string | undefined    // now optional
+ * //   debug?: boolean | undefined   // now optional
+ * //   version: number
+ * // }
+ *
+ * const config: Config = {
+ *   name: 'MyApp',
+ *   version: 1
+ *   // theme and debug can be omitted instead of explicitly set to undefined
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type MakeUndefinedOptional<T extends object> = Expand<{
     [P in {
         [K in keyof T]: undefined extends T[K] ? never : K;
@@ -363,24 +887,65 @@ export declare type MakeUndefinedOptional<T extends object> = Expand<{
  */
 export declare class MediaHelpers {
     /**
-     * Load a video from a url.
+     * Load a video element from a URL with cross-origin support.
+     *
+     * @param src - The URL of the video to load
+     * @returns Promise that resolves to the loaded HTMLVideoElement
+     * @example
+     * ```ts
+     * const video = await MediaHelpers.loadVideo('https://example.com/video.mp4')
+     * console.log(`Video dimensions: ${video.videoWidth}x${video.videoHeight}`)
+     * ```
      * @public
      */
     static loadVideo(src: string): Promise<HTMLVideoElement>;
-    static getVideoFrameAsDataUrl(video: HTMLVideoElement, time?: number): Promise<string>;
     /**
-     * Load an image from a url.
+     * Extract a frame from a video element as a data URL.
+     *
+     * @param video - The HTMLVideoElement to extract frame from
+     * @param time - The time in seconds to extract the frame from (default: 0)
+     * @returns Promise that resolves to a data URL of the video frame
+     * @example
+     * ```ts
+     * const video = await MediaHelpers.loadVideo('https://example.com/video.mp4')
+     * const frameDataUrl = await MediaHelpers.getVideoFrameAsDataUrl(video, 5.0)
+     * // Use frameDataUrl as image thumbnail
+     * const img = document.createElement('img')
+     * img.src = frameDataUrl
+     * ```
      * @public
      */
-    static getImageAndDimensions(src: string): Promise<{
-        h: number;
-        image: HTMLImageElement;
-        w: number;
+    static getVideoFrameAsDataUrl(video: HTMLVideoElement, time?: number): Promise<string>;
+    /**
+     * Load an image from a URL and get its dimensions along with the image element.
+     *
+     * @param src - The URL of the image to load
+     * @returns Promise that resolves to an object with width, height, and the image element
+     * @example
+     * ```ts
+     * const { w, h, image } = await MediaHelpers.getImageAndDimensions('https://example.com/image.png')
+     * console.log(`Image size: ${w}x${h}`)
+     * // Image is ready to use
+     * document.body.appendChild(image)
+     * ```
+     * @public
+     */
+    static getImageAndDimensions(src: string): Promise<{
+        h: number;
+        image: HTMLImageElement;
+        w: number;
     }>;
     /**
      * Get the size of a video blob
      *
-     * @param blob - A SharedBlob containing the video
+     * @param blob - A Blob containing the video
+     * @returns Promise that resolves to an object with width and height properties
+     * @example
+     * ```ts
+     * const file = new File([...], 'video.mp4', { type: 'video/mp4' })
+     * const { w, h } = await MediaHelpers.getVideoSize(file)
+     * console.log(`Video dimensions: ${w}x${h}`)
+     * ```
      * @public
      */
     static getVideoSize(blob: Blob): Promise<{
@@ -390,18 +955,103 @@ export declare class MediaHelpers {
     /**
      * Get the size of an image blob
      *
-     * @param blob - A Blob containing the image.
+     * @param blob - A Blob containing the image
+     * @returns Promise that resolves to an object with width and height properties
+     * @example
+     * ```ts
+     * const file = new File([...], 'image.png', { type: 'image/png' })
+     * const { w, h } = await MediaHelpers.getImageSize(file)
+     * console.log(`Image dimensions: ${w}x${h}`)
+     * ```
      * @public
      */
     static getImageSize(blob: Blob): Promise<{
         h: number;
         w: number;
     }>;
+    /**
+     * Check if a media file blob contains animation data.
+     *
+     * @param file - The Blob to check for animation
+     * @returns Promise that resolves to true if the file is animated, false otherwise
+     * @example
+     * ```ts
+     * const file = new File([...], 'animation.gif', { type: 'image/gif' })
+     * const animated = await MediaHelpers.isAnimated(file)
+     * console.log(animated ? 'Animated' : 'Static')
+     * ```
+     * @public
+     */
     static isAnimated(file: Blob): Promise<boolean>;
+    /**
+     * Check if a MIME type represents an animated image format.
+     *
+     * @param mimeType - The MIME type to check
+     * @returns True if the MIME type is an animated image format, false otherwise
+     * @example
+     * ```ts
+     * const isAnimated = MediaHelpers.isAnimatedImageType('image/gif')
+     * console.log(isAnimated) // true
+     * ```
+     * @public
+     */
     static isAnimatedImageType(mimeType: null | string): boolean;
+    /**
+     * Check if a MIME type represents a static (non-animated) image format.
+     *
+     * @param mimeType - The MIME type to check
+     * @returns True if the MIME type is a static image format, false otherwise
+     * @example
+     * ```ts
+     * const isStatic = MediaHelpers.isStaticImageType('image/jpeg')
+     * console.log(isStatic) // true
+     * ```
+     * @public
+     */
     static isStaticImageType(mimeType: null | string): boolean;
+    /**
+     * Check if a MIME type represents a vector image format.
+     *
+     * @param mimeType - The MIME type to check
+     * @returns True if the MIME type is a vector image format, false otherwise
+     * @example
+     * ```ts
+     * const isVector = MediaHelpers.isVectorImageType('image/svg+xml')
+     * console.log(isVector) // true
+     * ```
+     * @public
+     */
     static isVectorImageType(mimeType: null | string): boolean;
+    /**
+     * Check if a MIME type represents any supported image format (static, animated, or vector).
+     *
+     * @param mimeType - The MIME type to check
+     * @returns True if the MIME type is a supported image format, false otherwise
+     * @example
+     * ```ts
+     * const isImage = MediaHelpers.isImageType('image/png')
+     * console.log(isImage) // true
+     * ```
+     * @public
+     */
     static isImageType(mimeType: string): boolean;
+    /**
+     * Utility function to create an object URL from a blob, execute a function with it, and automatically clean it up.
+     *
+     * @param blob - The Blob to create an object URL for
+     * @param fn - Function to execute with the object URL
+     * @returns Promise that resolves to the result of the function
+     * @example
+     * ```ts
+     * const result = await MediaHelpers.usingObjectURL(imageBlob, async (url) => {
+     *   const { w, h } = await MediaHelpers.getImageAndDimensions(url)
+     *   return { width: w, height: h }
+     * })
+     * // Object URL is automatically revoked after function completes
+     * console.log(`Image dimensions: ${result.width}x${result.height}`)
+     * ```
+     * @public
+     */
     static usingObjectURL<T>(blob: Blob, fn: (url: string) => Promise<T>): Promise<T>;
 }
 
@@ -440,7 +1090,21 @@ export declare function modulate(value: number, rangeA: number[], rangeB: number
 
 /* Excluded from this release type: objectMapValues */
 
-/** @public */
+/**
+ * Represents a successful result containing a value.
+ *
+ * Interface for the success case of a Result type, containing the computed value.
+ * Used in conjunction with ErrorResult to create a discriminated union for error handling.
+ *
+ * @example
+ * ```ts
+ * const success: OkResult<string> = { ok: true, value: 'Hello World' }
+ * if (success.ok) {
+ *   console.log(success.value) // 'Hello World'
+ * }
+ * ```
+ * @public
+ */
 export declare interface OkResult<T> {
     readonly ok: true;
     readonly value: T;
@@ -452,44 +1116,307 @@ export declare interface OkResult<T> {
 
 /* Excluded from this release type: partition */
 
-/** @public */
+/**
+ * A utility class for measuring and tracking frame rate performance during operations.
+ * Provides visual feedback in the browser console with color-coded FPS indicators.
+ *
+ * @example
+ * ```ts
+ * const tracker = new PerformanceTracker()
+ *
+ * tracker.start('render')
+ * renderShapes()
+ * tracker.stop() // Logs performance info to console
+ *
+ * // Check if tracking is active
+ * if (tracker.isStarted()) {
+ *   console.log('Still tracking performance')
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare class PerformanceTracker {
     private startTime;
     private name;
     private frames;
     private started;
     private frame;
+    /**
+     * Records animation frames to calculate frame rate.
+     * Called automatically during performance tracking.
+     */
     recordFrame: () => void;
+    /**
+     * Starts performance tracking for a named operation.
+     *
+     * @param name - A descriptive name for the operation being tracked
+     *
+     * @example
+     * ```ts
+     * tracker.start('canvas-render')
+     * // ... perform rendering operations
+     * tracker.stop()
+     * ```
+     */
     start(name: string): void;
+    /**
+     * Stops performance tracking and logs results to the console.
+     *
+     * Displays the operation name, frame rate, and uses color coding:
+     * - Green background: \> 55 FPS (good performance)
+     * - Yellow background: 30-55 FPS (moderate performance)
+     * - Red background: \< 30 FPS (poor performance)
+     *
+     * @example
+     * ```ts
+     * tracker.start('interaction')
+     * handleUserInteraction()
+     * tracker.stop() // Logs: "Perf Interaction 60 fps"
+     * ```
+     */
     stop(): void;
+    /**
+     * Checks whether performance tracking is currently active.
+     *
+     * @returns True if tracking is in progress, false otherwise
+     *
+     * @example
+     * ```ts
+     * if (!tracker.isStarted()) {
+     *   tracker.start('new-operation')
+     * }
+     * ```
+     */
     isStarted(): boolean;
 }
 
-/** @public */
+/**
+ * Utility class for reading and manipulating PNG image files.
+ * Provides methods for parsing PNG chunks, validating PNG format, and modifying PNG metadata.
+ *
+ * @example
+ * ```ts
+ * // Validate PNG file from blob
+ * const blob = new Blob([pngData], { type: 'image/png' })
+ * const view = new DataView(await blob.arrayBuffer())
+ * const isPng = PngHelpers.isPng(view, 0)
+ *
+ * // Parse PNG metadata for image processing
+ * const chunks = PngHelpers.readChunks(view)
+ * const physChunk = PngHelpers.findChunk(view, 'pHYs')
+ *
+ * // Create high-DPI PNG for export
+ * const highDpiBlob = PngHelpers.setPhysChunk(view, 2, { type: 'image/png' })
+ * ```
+ *
+ * @public
+ */
 export declare class PngHelpers {
+    /**
+     * Checks if binary data at the specified offset contains a valid PNG file signature.
+     * Validates the 8-byte PNG signature: 89 50 4E 47 0D 0A 1A 0A.
+     *
+     * @param view - DataView containing the binary data to check
+     * @param offset - Byte offset where the PNG signature should start
+     * @returns True if the data contains a valid PNG signature, false otherwise
+     *
+     * @example
+     * ```ts
+     * // Validate PNG from file upload
+     * const file = event.target.files[0]
+     * const buffer = await file.arrayBuffer()
+     * const view = new DataView(buffer)
+     *
+     * if (PngHelpers.isPng(view, 0)) {
+     *   console.log('Valid PNG file detected')
+     *   // Process PNG file...
+     * } else {
+     *   console.error('Not a valid PNG file')
+     * }
+     * ```
+     */
     static isPng(view: DataView, offset: number): boolean;
+    /**
+     * Reads the 4-character chunk type identifier from a PNG chunk header.
+     *
+     * @param view - DataView containing the PNG data
+     * @param offset - Byte offset of the chunk type field (after length field)
+     * @returns 4-character string representing the chunk type (e.g., 'IHDR', 'IDAT', 'IEND')
+     *
+     * @example
+     * ```ts
+     * // Read chunk type from PNG header (after 8-byte signature)
+     * const chunkType = PngHelpers.getChunkType(dataView, 8)
+     * console.log(chunkType) // 'IHDR' (Image Header)
+     *
+     * // Read chunk type at a specific position during parsing
+     * let offset = 8 // Skip PNG signature
+     * const chunkLength = dataView.getUint32(offset)
+     * const type = PngHelpers.getChunkType(dataView, offset + 4)
+     * ```
+     */
     static getChunkType(view: DataView, offset: number): string;
+    /**
+     * Parses all chunks in a PNG file and returns their metadata.
+     * Skips duplicate IDAT chunks but includes all other chunk types.
+     *
+     * @param view - DataView containing the complete PNG file data
+     * @param offset - Starting byte offset (defaults to 0)
+     * @returns Record mapping chunk types to their metadata (start position, data offset, and size)
+     * @throws Error if the data is not a valid PNG file
+     *
+     * @example
+     * ```ts
+     * // Parse PNG structure for metadata extraction
+     * const view = new DataView(await blob.arrayBuffer())
+     * const chunks = PngHelpers.readChunks(view)
+     *
+     * // Check for specific chunks
+     * const ihdrChunk = chunks['IHDR']
+     * const physChunk = chunks['pHYs']
+     *
+     * if (physChunk) {
+     *   console.log(`Found pixel density info at byte ${physChunk.start}`)
+     * } else {
+     *   console.log('No pixel density information found')
+     * }
+     * ```
+     */
     static readChunks(view: DataView, offset?: number): Record<string, {
         dataOffset: number;
         size: number;
         start: number;
     }>;
+    /**
+     * Parses the pHYs (physical pixel dimensions) chunk data.
+     * Reads pixels per unit for X and Y axes, and the unit specifier.
+     *
+     * @param view - DataView containing the PNG data
+     * @param offset - Byte offset of the pHYs chunk data
+     * @returns Object with ppux (pixels per unit X), ppuy (pixels per unit Y), and unit specifier
+     *
+     * @example
+     * ```ts
+     * // Extract pixel density information for DPI calculation
+     * const physChunk = PngHelpers.findChunk(dataView, 'pHYs')
+     * if (physChunk) {
+     *   const physData = PngHelpers.parsePhys(dataView, physChunk.dataOffset)
+     *
+     *   if (physData.unit === 1) { // meters
+     *     const dpiX = Math.round(physData.ppux * 0.0254)
+     *     const dpiY = Math.round(physData.ppuy * 0.0254)
+     *     console.log(`DPI: ${dpiX} x ${dpiY}`)
+     *   }
+     * }
+     * ```
+     */
     static parsePhys(view: DataView, offset: number): {
         ppux: number;
         ppuy: number;
         unit: number;
     };
+    /**
+     * Finds a specific chunk type in the PNG file and returns its metadata.
+     *
+     * @param view - DataView containing the PNG file data
+     * @param type - 4-character chunk type to search for (e.g., 'pHYs', 'IDAT')
+     * @returns Chunk metadata object if found, undefined otherwise
+     *
+     * @example
+     * ```ts
+     * // Look for pixel density information in PNG
+     * const physChunk = PngHelpers.findChunk(dataView, 'pHYs')
+     * if (physChunk) {
+     *   const physData = PngHelpers.parsePhys(dataView, physChunk.dataOffset)
+     *   console.log(`Found pHYs chunk with ${physData.ppux} x ${physData.ppuy} pixels per unit`)
+     * }
+     *
+     * // Check for text metadata
+     * const textChunk = PngHelpers.findChunk(dataView, 'tEXt')
+     * if (textChunk) {
+     *   console.log(`Found text metadata at byte ${textChunk.start}`)
+     * }
+     * ```
+     */
     static findChunk(view: DataView, type: string): {
         dataOffset: number;
         size: number;
         start: number;
     };
+    /**
+     * Adds or replaces a pHYs chunk in a PNG file to set pixel density for high-DPI displays.
+     * The method determines insertion point by prioritizing IDAT chunk position over existing pHYs,
+     * creates a properly formatted pHYs chunk with CRC validation, and returns a new Blob.
+     *
+     * @param view - DataView containing the original PNG file data
+     * @param dpr - Device pixel ratio multiplier (defaults to 1)
+     * @param options - Optional Blob constructor options for MIME type and other properties
+     * @returns New Blob containing the PNG with updated pixel density information
+     *
+     * @example
+     * ```ts
+     * // Export PNG with proper pixel density for high-DPI displays
+     * const canvas = document.createElement('canvas')
+     * const ctx = canvas.getContext('2d')
+     * // ... draw content to canvas ...
+     *
+     * canvas.toBlob(async (blob) => {
+     *   if (blob) {
+     *     const view = new DataView(await blob.arrayBuffer())
+     *     // Create 2x DPI version for Retina displays
+     *     const highDpiBlob = PngHelpers.setPhysChunk(view, 2, { type: 'image/png' })
+     *     // Download or use the blob...
+     *   }
+     * }, 'image/png')
+     * ```
+     */
     static setPhysChunk(view: DataView, dpr?: number, options?: BlobPropertyBag): Blob;
 }
 
 /* Excluded from this release type: promiseWithResolve */
 
-/** @public */
+/**
+ * Makes all properties in a type and all nested properties optional recursively.
+ * This is useful for creating partial update objects where you only want to specify
+ * some deeply nested properties while leaving others unchanged.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   name: string
+ *   settings: {
+ *     theme: string
+ *     notifications: {
+ *       email: boolean
+ *       push: boolean
+ *     }
+ *   }
+ * }
+ *
+ * type PartialUser = RecursivePartial<User>
+ * // Result: {
+ * //   name?: string
+ * //   settings?: {
+ * //     theme?: string
+ * //     notifications?: {
+ * //       email?: boolean
+ * //       push?: boolean
+ * //     }
+ * //   }
+ * // }
+ *
+ * const update: PartialUser = {
+ *   settings: {
+ *     notifications: {
+ *       email: false
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare type RecursivePartial<T> = {
     [P in keyof T]?: RecursivePartial<T[P]>;
 };
@@ -500,12 +1427,65 @@ export declare type RecursivePartial<T> = {
 
 /* Excluded from this release type: restoreUniqueId */
 
-/** @public */
+/**
+ * A discriminated union type for handling success and error cases.
+ *
+ * Represents either a successful result with a value or a failed result with an error.
+ * This pattern provides type-safe error handling without throwing exceptions. The 'ok' property
+ * serves as the discriminant for type narrowing.
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) {
+ *     return Result.err('Division by zero')
+ *   }
+ *   return Result.ok(a / b)
+ * }
+ *
+ * const result = divide(10, 2)
+ * if (result.ok) {
+ *   console.log(`Result: ${result.value}`) // Result: 5
+ * } else {
+ *   console.error(`Error: ${result.error}`)
+ * }
+ * ```
+ * @public
+ */
 export declare type Result<T, E> = ErrorResult<E> | OkResult<T>;
 
-/** @public */
+/**
+ * Utility object for creating Result instances.
+ *
+ * Provides factory methods for creating OkResult and ErrorResult instances.
+ * This is the preferred way to construct Result values for consistent structure.
+ *
+ * @example
+ * ```ts
+ * // Create success result
+ * const success = Result.ok(42)
+ * // success: OkResult<number> = { ok: true, value: 42 }
+ *
+ * // Create error result
+ * const failure = Result.err('Invalid input')
+ * // failure: ErrorResult<string> = { ok: false, error: 'Invalid input' }
+ * ```
+ * @public
+ */
 export declare const Result: {
+    /**
+     * Create a failed result containing an error.
+     *
+     * @param error - The error value to wrap
+     * @returns An ErrorResult containing the error
+     */
     err<E>(error: E): ErrorResult<E>;
+    /**
+     * Create a successful result containing a value.
+     *
+     * @param value - The success value to wrap
+     * @returns An OkResult containing the value
+     */
     ok<T>(value: T): OkResult<T>;
 };
 
@@ -513,22 +1493,87 @@ export declare const Result: {
 
 /**
  * Seeded random number generator, using [xorshift](https://en.wikipedia.org/wiki/Xorshift). The
- * result will always be betweeen -1 and 1.
+ * result will always be between -1 and 1.
  *
  * Adapted from [seedrandom](https://github.com/davidbau/seedrandom).
  *
+ * @param seed - The seed string for deterministic random generation (defaults to empty string)
+ * @returns A function that will return a random number between -1 and 1 each time it is called
+ * @example
+ * ```ts
+ * const random = rng('my-seed')
+ * const num1 = random() // Always the same for this seed
+ * const num2 = random() // Next number in sequence
+ *
+ * // Different seed produces different sequence
+ * const otherRandom = rng('other-seed')
+ * const different = otherRandom() // Different value
+ * ```
  * @public
  */
 export declare function rng(seed?: string): () => number;
 
 /**
- * Rotate the contents of an array.
+ * Rotate the contents of an array by a specified offset.
+ *
+ * Creates a new array with elements shifted to the left by the specified number of positions.
+ * Both positive and negative offsets result in left shifts (elements move left, with elements
+ * from the front wrapping to the back).
+ *
+ * @param arr - The array to rotate
+ * @param offset - The number of positions to shift left (both positive and negative values shift left)
+ * @returns A new array with elements shifted left by the specified offset
  *
+ * @example
+ * ```ts
+ * rotateArray([1, 2, 3, 4], 1) // [2, 3, 4, 1]
+ * rotateArray([1, 2, 3, 4], -1) // [2, 3, 4, 1]
+ * rotateArray(['a', 'b', 'c'], 2) // ['c', 'a', 'b']
+ * ```
  * @public
  */
 export declare function rotateArray<T>(arr: T[], offset: number): T[];
 
-/** @public */
+/**
+ * Safely parses a URL string without throwing exceptions on invalid input.
+ * Returns a URL object for valid URLs or undefined for invalid ones.
+ *
+ * @param url - The URL string to parse
+ * @param baseUrl - Optional base URL to resolve relative URLs against
+ * @returns A URL object if parsing succeeds, undefined if it fails
+ *
+ * @example
+ * ```ts
+ * // Valid absolute URL
+ * const url1 = safeParseUrl('https://example.com')
+ * if (url1) {
+ *   console.log(`Valid URL: ${url1.href}`) // "Valid URL: https://example.com/"
+ * }
+ *
+ * // Invalid URL
+ * const url2 = safeParseUrl('not-a-url')
+ * console.log(url2) // undefined
+ *
+ * // Relative URL with base
+ * const url3 = safeParseUrl('/path', 'https://example.com')
+ * if (url3) {
+ *   console.log(url3.href) // "https://example.com/path"
+ * }
+ *
+ * // Error handling
+ * function handleUserUrl(input: string) {
+ *   const url = safeParseUrl(input)
+ *   if (url) {
+ *     return url
+ *   } else {
+ *     console.log('Invalid URL provided')
+ *     return null
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare const safeParseUrl: (url: string, baseUrl?: string | URL) => undefined | URL;
 
 /* Excluded from this release type: setInLocalStorage */
@@ -537,7 +1582,28 @@ export declare const safeParseUrl: (url: string, baseUrl?: string | URL) => unde
 
 /* Excluded from this release type: sleep */
 
-/** @public */
+/**
+ * Compares two objects by their id property for use with Array.sort().
+ * Sorts objects in ascending order based on their id values.
+ *
+ * @param a - First object to compare
+ * @param b - Second object to compare
+ * @returns 1 if a.id \> b.id, -1 if a.id \<= b.id
+ *
+ * @example
+ * ```ts
+ * const items = [
+ *   { id: 'c', name: 'Charlie' },
+ *   { id: 'a', name: 'Alice' },
+ *   { id: 'b', name: 'Bob' },
+ * ]
+ *
+ * const sorted = items.sort(sortById)
+ * // [{ id: 'a', name: 'Alice' }, { id: 'b', name: 'Bob' }, { id: 'c', name: 'Charlie' }]
+ * ```
+ *
+ * @public
+ */
 export declare function sortById<T extends {
     id: any;
 }>(a: T, b: T): -1 | 1;
@@ -546,7 +1612,18 @@ export declare function sortById<T extends {
  * Sort by index.
  * @param a - An object with an index property.
  * @param b - An object with an index property.
- * @public */
+ * @returns A number indicating sort order (-1, 0, or 1).
+ * @example
+ * ```ts
+ * const shapes = [
+ *   { id: 'b', index: 'a2' as IndexKey },
+ *   { id: 'a', index: 'a1' as IndexKey }
+ * ]
+ * const sorted = shapes.sort(sortByIndex)
+ * console.log(sorted) // [{ id: 'a', index: 'a1' }, { id: 'b', index: 'a2' }]
+ * ```
+ * @public
+ */
 export declare function sortByIndex<T extends {
     index: IndexKey;
 }>(a: T, b: T): -1 | 0 | 1;
@@ -559,7 +1636,26 @@ export declare function sortByIndex<T extends {
  * Create a deep copy of a value. Uses the structuredClone API if available, otherwise uses JSON.parse(JSON.stringify()).
  *
  * @param i - The value to clone.
- * @public */
+ * @returns A deep copy of the input value.
+ * @example
+ * ```ts
+ * const original = { a: 1, b: { c: 2 } }
+ * const copy = structuredClone(original)
+ *
+ * copy.b.c = 3
+ * console.log(original.b.c) // 2 (unchanged)
+ * console.log(copy.b.c) // 3
+ *
+ * // Works with complex objects
+ * const complexObject = {
+ *   date: new Date(),
+ *   array: [1, 2, 3],
+ *   nested: { deep: { value: "test" } }
+ * }
+ * const cloned = structuredClone(complexObject)
+ * ```
+ * @public
+ */
 declare const structuredClone_2: <T>(i: T) => T;
 export { structuredClone_2 as structuredClone }
 
@@ -567,21 +1663,140 @@ export { throttle }
 
 /* Excluded from this release type: throttleToNextFrame */
 
-/** @public */
+/**
+ * A utility class for managing timeouts, intervals, and animation frames with context-based organization and automatic cleanup.
+ * Helps prevent memory leaks by organizing timers into named contexts that can be cleared together.
+ * @example
+ * ```ts
+ * const timers = new Timers()
+ *
+ * // Set timers with context organization
+ * timers.setTimeout('ui', () => console.log('Auto save'), 5000)
+ * timers.setInterval('ui', () => console.log('Refresh'), 1000)
+ * timers.requestAnimationFrame('ui', () => console.log('Render'))
+ *
+ * // Clear all timers for a context
+ * timers.dispose('ui')
+ *
+ * // Or get context-bound functions
+ * const uiTimers = timers.forContext('ui')
+ * uiTimers.setTimeout(() => console.log('Contextual timeout'), 1000)
+ * ```
+ * @public
+ */
 export declare class Timers {
     private timeouts;
     private intervals;
     private rafs;
+    /**
+     * Creates a new Timers instance with bound methods for safe callback usage.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * // Methods are pre-bound, safe to use as callbacks
+     * element.addEventListener('click', timers.dispose)
+     * ```
+     */
     constructor();
-    /** @public */
+    /**
+     * Creates a timeout that will be tracked under the specified context.
+     * @param contextId - The context identifier to group this timer under.
+     * @param handler - The function to execute when the timeout expires.
+     * @param timeout - The delay in milliseconds (default: 0).
+     * @param args - Additional arguments to pass to the handler.
+     * @returns The timer ID that can be used with clearTimeout.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const id = timers.setTimeout('autosave', () => save(), 5000)
+     * // Timer will be automatically cleared when 'autosave' context is disposed
+     * ```
+     * @public
+     */
     setTimeout(contextId: string, handler: TimerHandler, timeout?: number, ...args: any[]): number;
-    /** @public */
+    /**
+     * Creates an interval that will be tracked under the specified context.
+     * @param contextId - The context identifier to group this timer under.
+     * @param handler - The function to execute repeatedly.
+     * @param timeout - The delay in milliseconds between executions (default: 0).
+     * @param args - Additional arguments to pass to the handler.
+     * @returns The interval ID that can be used with clearInterval.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const id = timers.setInterval('refresh', () => updateData(), 1000)
+     * // Interval will be automatically cleared when 'refresh' context is disposed
+     * ```
+     * @public
+     */
     setInterval(contextId: string, handler: TimerHandler, timeout?: number, ...args: any[]): number;
-    /** @public */
+    /**
+     * Requests an animation frame that will be tracked under the specified context.
+     * @param contextId - The context identifier to group this animation frame under.
+     * @param callback - The function to execute on the next animation frame.
+     * @returns The request ID that can be used with cancelAnimationFrame.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const id = timers.requestAnimationFrame('render', () => draw())
+     * // Animation frame will be automatically cancelled when 'render' context is disposed
+     * ```
+     * @public
+     */
     requestAnimationFrame(contextId: string, callback: FrameRequestCallback): number;
-    /** @public */
+    /**
+     * Disposes of all timers associated with the specified context.
+     * Clears all timeouts, intervals, and animation frames for the given context ID.
+     * @param contextId - The context identifier whose timers should be cleared.
+     * @returns void
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * timers.setTimeout('ui', () => console.log('timeout'), 1000)
+     * timers.setInterval('ui', () => console.log('interval'), 500)
+     *
+     * // Clear all 'ui' context timers
+     * timers.dispose('ui')
+     * ```
+     * @public
+     */
     dispose(contextId: string): void;
+    /**
+     * Disposes of all timers across all contexts.
+     * Clears every timeout, interval, and animation frame managed by this instance.
+     * @returns void
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * timers.setTimeout('ui', () => console.log('ui'), 1000)
+     * timers.setTimeout('background', () => console.log('bg'), 2000)
+     *
+     * // Clear everything
+     * timers.disposeAll()
+     * ```
+     * @public
+     */
     disposeAll(): void;
+    /**
+     * Returns an object with timer methods bound to a specific context.
+     * Convenient for getting context-specific timer functions without repeatedly passing the contextId.
+     * @param contextId - The context identifier to bind the returned methods to.
+     * @returns An object with setTimeout, setInterval, requestAnimationFrame, and dispose methods bound to the context.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const uiTimers = timers.forContext('ui')
+     *
+     * // These are equivalent to calling timers.setTimeout('ui', ...)
+     * uiTimers.setTimeout(() => console.log('timeout'), 1000)
+     * uiTimers.setInterval(() => console.log('interval'), 500)
+     * uiTimers.requestAnimationFrame(() => console.log('frame'))
+     *
+     * // Dispose only this context
+     * uiTimers.dispose()
+     * ```
+     * @public
+     */
     forContext(contextId: string): {
         dispose: () => void;
         requestAnimationFrame: (callback: FrameRequestCallback) => number;
@@ -593,14 +1808,28 @@ export declare class Timers {
 export { uniq }
 
 /**
- * Generate a unique id.
+ * Generate a unique ID using a modified nanoid algorithm.
  *
- * @example
+ * Generates a cryptographically secure random string ID using URL-safe characters.
+ * The default size is 21 characters, which provides a good balance of uniqueness
+ * and brevity. Uses the global crypto API for secure random number generation.
  *
+ * @param size - Optional length of the generated ID (defaults to 21 characters)
+ * @returns A unique string identifier
+ * @example
  * ```ts
+ * // Generate default 21-character ID
  * const id = uniqueId()
- * ```
+ * console.log(id) // 'V1StGXR8_Z5jdHi6B-myT'
  *
+ * // Generate shorter ID
+ * const shortId = uniqueId(10)
+ * console.log(shortId) // 'V1StGXR8_Z'
+ *
+ * // Generate longer ID
+ * const longId = uniqueId(32)
+ * console.log(longId) // 'V1StGXR8_Z5jdHi6B-myTVKahvjdx...'
+ * ```
  * @public
  */
 export declare function uniqueId(size?: number): string;
@@ -612,18 +1841,59 @@ export declare function uniqueId(size?: number): string;
 /* Excluded from this release type: warnOnce */
 
 /**
- * A micro cache used when storing records in memory (using a WeakMap).
+ * A lightweight cache implementation using WeakMap for storing key-value pairs.
+ *
+ * A micro cache that stores computed values associated with object keys.
+ * Uses WeakMap internally, which means keys can be garbage collected when no other
+ * references exist, and only object keys are supported. Provides lazy computation
+ * with memoization.
+ *
+ * @example
+ * ```ts
+ * const cache = new WeakCache<User, string>()
+ * const user = { id: 1, name: 'Alice' }
+ *
+ * // Get cached value, computing it if not present
+ * const displayName = cache.get(user, (u) => `${u.name} (#${u.id})`)
+ * // Returns 'Alice (#1)'
+ *
+ * // Subsequent calls return cached value
+ * const sameName = cache.get(user, (u) => `${u.name} (#${u.id})`)
+ * // Returns 'Alice (#1)' without recomputing
+ * ```
  * @public
  */
 export declare class WeakCache<K extends object, V> {
-    /** The map of items to their cached values. */
+    /**
+     * The internal WeakMap storage for cached key-value pairs.
+     *
+     * @public
+     */
     items: WeakMap<K, V>;
     /**
-     * Get the cached value for a given record. If the record is not present in the map, the callback
-     * will be used to create the value (with the result being stored in the cache for next time).
+     * Get the cached value for a given key, computing it if not already cached.
+     *
+     * Retrieves the cached value associated with the given key. If no cached
+     * value exists, calls the provided callback function to compute the value, stores it
+     * in the cache, and returns it. Subsequent calls with the same key will return the
+     * cached value without recomputation.
+     *
+     * @param item - The object key to retrieve the cached value for
+     * @param cb - Callback function that computes the value when not already cached
+     * @returns The cached value if it exists, otherwise the newly computed value from the callback
      *
-     * @param item - The item to get.
-     * @param cb - The callback to use to create the value when a cached value is not found.
+     * @example
+     * ```ts
+     * const cache = new WeakCache<HTMLElement, DOMRect>()
+     * const element = document.getElementById('my-element')!
+     *
+     * // First call computes and caches the bounding rect
+     * const rect1 = cache.get(element, (el) => el.getBoundingClientRect())
+     *
+     * // Second call returns cached value
+     * const rect2 = cache.get(element, (el) => el.getBoundingClientRect())
+     * // rect1 and rect2 are the same object
+     * ```
      */
     get<P extends K>(item: P, cb: (item: P) => V): NonNullable<V>;
 }