@ibodr/utils 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,3098 @@
+export { default as isEqual } from 'lodash.isequal';
+export { default as isEqualWith } from 'lodash.isequalwith';
+export { default as throttle } from 'lodash.throttle';
+export { default as uniq } from 'lodash.uniq';
+
+/**
+ * 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
+ */
+declare function rotateArray<T>(arr: T[], offset: number): T[];
+/**
+ * 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
+ */
+declare function dedupe<T>(input: T[], equals?: (a: any, b: any) => boolean): T[];
+/**
+ * Remove null and undefined values from an array.
+ *
+ * Creates a new array with all null and undefined values filtered out.
+ * The resulting array has a refined type that excludes null and undefined.
+ *
+ * @param arr - The array to compact
+ * @returns A new array with null and undefined values removed
+ *
+ * @example
+ * ```ts
+ * compact([1, null, 2, undefined, 3]) // [1, 2, 3]
+ * compact(['a', null, 'b', undefined]) // ['a', 'b']
+ * ```
+ * @internal
+ */
+declare function compact<T>(arr: T[]): NonNullable<T>[];
+/**
+ * Get the last element of an array.
+ *
+ * Returns the last element of an array, or undefined if the array is empty.
+ * Works with readonly arrays and preserves the element type.
+ *
+ * @param arr - The array to get the last element from
+ * @returns The last element of the array, or undefined if the array is empty
+ *
+ * @example
+ * ```ts
+ * last([1, 2, 3]) // 3
+ * last(['a', 'b', 'c']) // 'c'
+ * last([]) // undefined
+ * ```
+ * @internal
+ */
+declare function last<T>(arr: readonly T[]): T | undefined;
+/**
+ * Find the item in an array with the minimum value according to a function.
+ *
+ * Finds the array item that produces the smallest value when passed through
+ * the provided function. Returns undefined for empty arrays.
+ *
+ * @param arr - The array to search
+ * @param fn - Function to compute the comparison value for each item
+ * @returns The item with the minimum value, or undefined if the array is empty
+ *
+ * @example
+ * ```ts
+ * const people = [{name: 'Alice', age: 30}, {name: 'Bob', age: 25}]
+ * minBy(people, p => p.age) // {name: 'Bob', age: 25}
+ *
+ * minBy([3, 1, 4, 1, 5], x => x) // 1
+ * minBy([], x => x) // undefined
+ * ```
+ * @internal
+ */
+declare function minBy<T>(arr: readonly T[], fn: (item: T) => number): T | undefined;
+/**
+ * Find the item in an array with the maximum value according to a function.
+ *
+ * Finds the array item that produces the largest value when passed through
+ * the provided function. Returns undefined for empty arrays.
+ *
+ * @param arr - The array to search
+ * @param fn - Function to compute the comparison value for each item
+ * @returns The item with the maximum value, or undefined if the array is empty
+ *
+ * @example
+ * ```ts
+ * const people = [{name: 'Alice', age: 30}, {name: 'Bob', age: 25}]
+ * maxBy(people, p => p.age) // {name: 'Alice', age: 30}
+ *
+ * maxBy([3, 1, 4, 1, 5], x => x) // 5
+ * maxBy([], x => x) // undefined
+ * ```
+ * @internal
+ */
+declare function maxBy<T>(arr: readonly T[], fn: (item: T) => number): T | undefined;
+/**
+ * Split an array into two arrays based on a predicate function.
+ *
+ * Partitions an array into two arrays: one containing items that satisfy
+ * the predicate, and another containing items that do not. The original array order is preserved.
+ *
+ * @param arr - The array to partition
+ * @param predicate - The predicate function to test each item
+ * @returns A tuple of two arrays: [satisfying items, non-satisfying items]
+ *
+ * @example
+ * ```ts
+ * const [evens, odds] = partition([1, 2, 3, 4, 5], x => x % 2 === 0)
+ * // evens: [2, 4], odds: [1, 3, 5]
+ *
+ * const [adults, minors] = partition(
+ *   [{name: 'Alice', age: 30}, {name: 'Bob', age: 17}],
+ *   person => person.age >= 18
+ * )
+ * // adults: [{name: 'Alice', age: 30}], minors: [{name: 'Bob', age: 17}]
+ * ```
+ * @internal
+ */
+declare function partition<T>(arr: T[], predicate: (item: T) => boolean): [T[], T[]];
+/**
+ * Check if two arrays are shallow equal.
+ *
+ * Compares two arrays for shallow equality by checking if they have the same length
+ * and the same elements at each index using Object.is comparison. Returns true if arrays are
+ * the same reference, have different lengths, or any elements differ.
+ *
+ * @param arr1 - First array to compare
+ * @param arr2 - Second array to compare
+ * @returns True if arrays are shallow equal, false otherwise
+ *
+ * @example
+ * ```ts
+ * areArraysShallowEqual([1, 2, 3], [1, 2, 3]) // true
+ * areArraysShallowEqual([1, 2, 3], [1, 2, 4]) // false
+ * areArraysShallowEqual(['a', 'b'], ['a', 'b']) // true
+ * areArraysShallowEqual([1, 2], [1, 2, 3]) // false
+ *
+ * const obj = {x: 1}
+ * areArraysShallowEqual([obj], [obj]) // true (same reference)
+ * areArraysShallowEqual([{x: 1}], [{x: 1}]) // false (different objects)
+ * ```
+ * @internal
+ */
+declare function areArraysShallowEqual<T>(arr1: readonly T[], arr2: readonly T[]): boolean;
+/**
+ * Merge custom entries with defaults, replacing defaults that have matching keys.
+ *
+ * Combines two arrays by keeping all custom entries and only the default entries
+ * that don't have a matching key in the custom entries. Custom entries always override defaults.
+ * The result contains remaining defaults first, followed by all custom entries.
+ *
+ * @param key - The property name to use as the unique identifier
+ * @param customEntries - Array of custom entries that will override defaults
+ * @param defaults - Array of default entries
+ * @returns A new array with defaults filtered out where custom entries exist, plus all custom entries
+ *
+ * @example
+ * ```ts
+ * const defaults = [{type: 'text', value: 'default'}, {type: 'number', value: 0}]
+ * const custom = [{type: 'text', value: 'custom'}]
+ *
+ * mergeArraysAndReplaceDefaults('type', custom, defaults)
+ * // Result: [{type: 'number', value: 0}, {type: 'text', value: 'custom'}]
+ *
+ * const tools = [{id: 'select', name: 'Select'}, {id: 'draw', name: 'Draw'}]
+ * const customTools = [{id: 'select', name: 'Custom Select'}]
+ *
+ * mergeArraysAndReplaceDefaults('id', customTools, tools)
+ * // Result: [{id: 'draw', name: 'Draw'}, {id: 'select', name: 'Custom Select'}]
+ * ```
+ * @internal
+ */
+declare function mergeArraysAndReplaceDefaults<const Key extends string, T extends {
+    [K in Key]: string;
+}>(key: Key, customEntries: readonly T[], defaults: readonly T[]): T[];
+
+/*!
+ * MIT License: https://github.com/NoHomey/bind-decorator/blob/master/License
+ * Copyright (c) 2016 Ivo Stratev
+ */
+/**
+ * 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
+ */
+declare function bind<T extends (...args: any[]) => any>(target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T>;
+/**
+ * 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
+ */
+declare function bind<This extends object, T extends (...args: any[]) => any>(originalMethod: T, context: ClassMethodDecoratorContext<This, T>): void;
+
+/**
+ * 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
+ */
+declare class WeakCache<K extends object, V> {
+    /**
+     * The internal WeakMap storage for cached key-value pairs.
+     *
+     * @public
+     */
+    items: WeakMap<K, V>;
+    /**
+     * 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
+     *
+     * @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>;
+}
+
+/**
+ * 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
+ */
+interface OkResult<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/**
+ * 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
+ */
+interface ErrorResult<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+/**
+ * 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
+ */
+type Result<T, E> = OkResult<T> | ErrorResult<E>;
+/**
+ * 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
+ */
+declare const Result: {
+    /**
+     * 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>;
+    /**
+     * 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 an array of values.
+     *
+     * If any of the results are errors, the returned result will be an error containing the first error.
+     *
+     * @param results - The array of results to wrap
+     * @returns An OkResult containing the array of values
+     */
+    all<T>(results: Result<T, any>[]): Result<T[], any>;
+};
+/**
+ * Throws an error for unhandled switch cases in exhaustive switch statements.
+ *
+ * Utility function to ensure exhaustive handling of discriminated unions in switch
+ * statements. When called, it indicates a programming error where a case was not handled.
+ * The TypeScript 'never' type ensures this function is only reachable if all cases aren't covered.
+ *
+ * @param value - The unhandled value (typed as 'never' for exhaustiveness checking)
+ * @param property - Optional property name to extract from the value for better error messages
+ * @returns Never returns (always throws)
+ *
+ * @example
+ * ```ts
+ * type Shape = 'circle' | 'square' | 'triangle'
+ *
+ * function getArea(shape: Shape): number {
+ *   switch (shape) {
+ *     case 'circle': return Math.PI * 5 * 5
+ *     case 'square': return 10 * 10
+ *     case 'triangle': return 0.5 * 10 * 8
+ *     default: return exhaustiveSwitchError(shape)
+ *   }
+ * }
+ * ```
+ * @internal
+ */
+declare function exhaustiveSwitchError(value: never, property?: string): never;
+/**
+ * Assert that a value is truthy, throwing an error if it's not.
+ *
+ * TypeScript assertion function that throws an error if the provided value is falsy.
+ * After this function executes successfully, TypeScript narrows the type to exclude falsy values.
+ * Stack trace is omitted from the error for cleaner debugging.
+ *
+ * @param value - The value to assert as truthy
+ * @param message - Optional custom error message
+ *
+ * @example
+ * ```ts
+ * const user = getUser() // User | null
+ * assert(user, 'User must be logged in')
+ * // TypeScript now knows user is non-null
+ * console.log(user.name) // Safe to access properties
+ * ```
+ * @internal
+ */
+declare const assert: (value: unknown, message?: string) => asserts value;
+/**
+ * Assert that a value is not null or undefined.
+ *
+ * Throws an error if the value is null or undefined, otherwise returns the value
+ * with a refined type that excludes null and undefined. Stack trace is omitted for cleaner debugging.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @returns The value with null and undefined excluded from the type
+ *
+ * @example
+ * ```ts
+ * const element = document.getElementById('my-id') // HTMLElement | null
+ * const safeElement = assertExists(element, 'Element not found')
+ * // TypeScript now knows safeElement is HTMLElement (not null)
+ * safeElement.addEventListener('click', handler) // Safe to call methods
+ * ```
+ * @internal
+ */
+declare const assertExists: <T>(value: T, message?: string | undefined) => NonNullable<T>;
+/**
+ * Create a Promise with externally accessible resolve and reject functions.
+ *
+ * Creates a Promise along with its resolve and reject functions exposed as
+ * properties on the returned object. This allows external code to control when the
+ * Promise resolves or rejects, useful for coordination between async operations.
+ *
+ * @returns A Promise object with additional resolve and reject methods
+ *
+ * @example
+ * ```ts
+ * const deferred = promiseWithResolve<string>()
+ *
+ * // Set up the promise consumer
+ * deferred.then(value => console.log(`Resolved: ${value}`))
+ * deferred.catch(error => console.error(`Rejected: ${error}`))
+ *
+ * // Later, resolve from external code
+ * setTimeout(() => {
+ *   deferred.resolve('Hello World')
+ * }, 1000)
+ * ```
+ * @internal
+ */
+declare function promiseWithResolve<T>(): Promise<T> & {
+    resolve(value: T): void;
+    reject(reason?: any): void;
+};
+/**
+ * Create a Promise that resolves after a specified delay.
+ *
+ * Utility function for introducing delays in async code. Returns a Promise
+ * that resolves with undefined after the specified number of milliseconds. Useful for
+ * implementing timeouts, rate limiting, or adding delays in testing scenarios.
+ *
+ * @param ms - The delay in milliseconds
+ * @returns A Promise that resolves after the specified delay
+ *
+ * @example
+ * ```ts
+ * async function delayedOperation() {
+ *   console.log('Starting...')
+ *   await sleep(1000) // Wait 1 second
+ *   console.log('Done!')
+ * }
+ *
+ * // Can also be used with .then()
+ * sleep(500).then(() => {
+ *   console.log('Half second has passed')
+ * })
+ * ```
+ * @internal
+ */
+declare function sleep(ms: number): Promise<void>;
+
+/**
+ * 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
+ */
+type RecursivePartial<T> = {
+    [P in keyof T]?: RecursivePartial<T[P]>;
+};
+/**
+ * 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
+ */
+type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+/**
+ * A value that may be returned synchronously or as a `Promise` / `PromiseLike`.
+ * Use with `await` or `Promise.resolve(...)` to normalize to a single `Promise`.
+ *
+ * @public
+ */
+type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * Makes specified keys in a type required while keeping all other properties as-is.
+ * This is useful when you need to ensure certain optional properties are provided
+ * in specific contexts without affecting the entire type structure.
+ *
+ * @example
+ * ```ts
+ * interface Shape {
+ *   id: string
+ *   x?: number
+ *   y?: number
+ *   visible?: boolean
+ * }
+ *
+ * // Make position properties required
+ * type PositionedShape = Required<Shape, 'x' | 'y'>
+ * // Result: {
+ * //   id: string
+ * //   x: number      // now required
+ * //   y: number      // now required
+ * //   visible?: boolean
+ * // }
+ *
+ * const shape: PositionedShape = {
+ *   id: 'rect1',
+ *   x: 10,    // must provide
+ *   y: 20,    // must provide
+ *   // visible is still optional
+ * }
+ * ```
+ *
+ * @internal
+ */
+type Required<T, K extends keyof T> = Expand<Omit<T, K> & {
+    [P in K]-?: T[P];
+}>;
+/**
+ * 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
+ */
+type MakeUndefinedOptional<T extends object> = Expand<{
+    [P in {
+        [K in keyof T]: undefined extends T[K] ? never : K;
+    }[keyof T]]: T[P];
+} & {
+    [P in {
+        [K in keyof T]: undefined extends T[K] ? K : never;
+    }[keyof T]]?: T[P];
+}>;
+
+/**
+ * Create a debounced version of a function that delays execution until after a specified wait time.
+ *
+ * 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
+ * // 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
+ * @see source - https://gist.github.com/ca0v/73a31f57b397606c9813472f7493a940
+ */
+declare function debounce<T extends unknown[], U>(callback: (...args: T) => Awaitable<U>, wait: number): {
+    (...args: T): Promise<U>;
+    cancel(): void;
+};
+
+/** @public */
+interface ErrorAnnotations {
+    tags: Record<string, number | string | boolean | bigint | symbol | null | undefined>;
+    extras: Record<string, unknown>;
+}
+/**
+ * Annotate an error with tags and additional data. Annotations won't overwrite existing ones.
+ * Retrieve them with `getErrorAnnotations`.
+ *
+ * @param error - The error object to annotate
+ * @param annotations - Partial annotations to add (tags and/or extras)
+ * @returns void
+ * @example
+ * ```ts
+ * const error = new Error('Something went wrong')
+ * annotateError(error, {
+ *   tags: { userId: '123', operation: 'save' },
+ *   extras: { timestamp: Date.now() }
+ * })
+ * ```
+ *
+ * @internal
+ */
+declare function annotateError(error: unknown, annotations: Partial<ErrorAnnotations>): void;
+/**
+ * Retrieve annotations that have been added to an error object.
+ *
+ * @param error - The error object to get annotations from
+ * @returns The error annotations (tags and extras) or empty objects if none exist
+ * @example
+ * ```ts
+ * const error = new Error('Something went wrong')
+ * annotateError(error, { tags: { userId: '123' } })
+ * const annotations = getErrorAnnotations(error)
+ * console.log(annotations.tags.userId) // '123'
+ * ```
+ *
+ * @internal
+ */
+declare function getErrorAnnotations(error: Error): ErrorAnnotations;
+
+/**
+ * A queue that executes tasks sequentially with optional delay between tasks.
+ *
+ * ExecutionQueue ensures that tasks are executed one at a time in the order they were added,
+ * with an optional timeout delay between each task execution. This is useful for rate limiting,
+ * preventing race conditions, or controlling the flow of asynchronous operations.
+ *
+ * @example
+ * ```ts
+ * // Create a queue with 100ms delay between tasks
+ * const queue = new ExecutionQueue(100)
+ *
+ * // Add tasks to the queue
+ * const result1 = await queue.push(() => fetch('/api/data'))
+ * const result2 = await queue.push(async () => {
+ *   const data = await processData()
+ *   return data
+ * })
+ *
+ * // Check if queue is empty
+ * if (queue.isEmpty()) {
+ *   console.log('All tasks completed')
+ * }
+ *
+ * // Clean up
+ * queue.close()
+ * ```
+ *
+ * @internal
+ */
+declare class ExecutionQueue {
+    private readonly timeout?;
+    private queue;
+    private running;
+    /**
+     * Creates a new ExecutionQueue.
+     *
+     * Creates a new execution queue that will process tasks sequentially.
+     * If a timeout is provided, there will be a delay between each task execution,
+     * which is useful for rate limiting or controlling execution flow.
+     *
+     * timeout - Optional delay in milliseconds between task executions
+     * @example
+     * ```ts
+     * // Create queue without delay
+     * const fastQueue = new ExecutionQueue()
+     *
+     * // Create queue with 500ms delay between tasks
+     * const slowQueue = new ExecutionQueue(500)
+     * ```
+     */
+    constructor(timeout?: number | undefined);
+    /**
+     * Checks if the queue is empty and not currently running a task.
+     *
+     * Determines whether the execution queue has completed all tasks and is idle.
+     * Returns true only when there are no pending tasks in the queue AND no task is currently being executed.
+     *
+     * @returns True if the queue has no pending tasks and is not currently executing
+     * @example
+     * ```ts
+     * const queue = new ExecutionQueue()
+     *
+     * console.log(queue.isEmpty()) // true - queue is empty
+     *
+     * queue.push(() => console.log('task'))
+     * console.log(queue.isEmpty()) // false - task is running/pending
+     * ```
+     */
+    isEmpty(): boolean;
+    private run;
+    /**
+     * Adds a task to the queue and returns a promise that resolves with the task's result.
+     *
+     * Enqueues a task for sequential execution. The task will be executed after all
+     * previously queued tasks have completed. If a timeout was specified in the constructor,
+     * there will be a delay between this task and the next one.
+     *
+     * @param task - The function to execute (can be sync or async)
+     * @returns Promise that resolves with the task's return value
+     * @example
+     * ```ts
+     * const queue = new ExecutionQueue(100)
+     *
+     * // Add async task
+     * const result = await queue.push(async () => {
+     *   const response = await fetch('/api/data')
+     *   return response.json()
+     * })
+     *
+     * // Add sync task
+     * const number = await queue.push(() => 42)
+     * ```
+     */
+    push<T>(task: () => T): Promise<Awaited<T>>;
+    /**
+     * Clears all pending tasks from the queue.
+     *
+     * Immediately removes all pending tasks from the queue. Any currently
+     * running task will complete normally, but no additional tasks will be executed.
+     * This method does not wait for the current task to finish.
+     *
+     * @returns void
+     * @example
+     * ```ts
+     * const queue = new ExecutionQueue()
+     *
+     * // Add several tasks
+     * queue.push(() => console.log('task 1'))
+     * queue.push(() => console.log('task 2'))
+     * queue.push(() => console.log('task 3'))
+     *
+     * // Clear all pending tasks
+     * queue.close()
+     * // Only 'task 1' will execute if it was already running
+     * ```
+     */
+    close(): void;
+}
+
+/**
+ * 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
+ */
+declare class FileHelpers {
+    /**
+     * 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>;
+    /**
+     * 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 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='
+     *
+     * // 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 Blob to a unicode text string.
+     *
+     * 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 textBlob = new Blob(['Hello World'], { type: 'text/plain' })
+     * const text = await FileHelpers.blobToText(textBlob)
+     * console.log(text) // 'Hello World'
+     *
+     * // 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;
+}
+
+/**
+ * When a function is wrapped in `omitFromStackTrace`, if it throws an error the stack trace won't
+ * include the function itself or any stack frames above it. Useful for assertion-style function
+ * where the error will ideally originate from the call-site rather than within the implementation
+ * of the assert fn.
+ *
+ * Only works in platforms that support `Error.captureStackTrace` (ie v8).
+ *
+ * @param fn - The function to wrap and exclude from stack traces
+ * @returns A wrapped version of the function that omits itself from error stack traces
+ * @example
+ * ```ts
+ * const assertPositive = omitFromStackTrace((value: number) => {
+ *   if (value <= 0) throw new Error('Value must be positive')
+ *   return value
+ * })
+ *
+ * assertPositive(-1) // Error stack trace will point to this line, not inside assertPositive
+ * ```
+ * @internal
+ */
+declare function omitFromStackTrace<Args extends Array<unknown>, Return>(fn: (...args: Args) => Return): (...args: Args) => Return;
+/**
+ * Does nothing, but it's really really good at it.
+ * @internal
+ */
+declare const noop: () => void;
+
+/**
+ * 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
+ */
+declare function getHashForString(string: string): string;
+/**
+ * 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
+ */
+declare function getHashForObject(obj: any): string;
+/**
+ * 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
+ */
+declare function getHashForBuffer(buffer: ArrayBuffer): string;
+/**
+ * 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
+ */
+declare function lns(str: string): string;
+
+/*!
+ * MIT License: https://github.com/ai/nanoid/blob/main/LICENSE
+ * Modified code originally from <https://github.com/ai/nanoid>
+ * Copyright 2017 Andrey Sitnik <andrey@sitnik.ru>
+ *
+ * `nanoid` is currently only distributed as an ES module. Some tools (jest, playwright) don't
+ * properly support ESM-only code yet, and tldraw itself is distributed as both an ES module and a
+ * CommonJS module. By including nanoid here, we can make sure it works well in every environment
+ * where tldraw is used. We can also remove some unused features like custom alphabets.
+ */
+/**
+ * Mock the unique ID generator with a custom implementation for testing.
+ *
+ * Replaces the internal ID generation function with a custom one. This is useful
+ * for testing scenarios where you need predictable or deterministic IDs.
+ *
+ * @param fn - The mock function that should return a string ID. Takes optional size parameter.
+ * @example
+ * ```ts
+ * // Mock with predictable IDs for testing
+ * mockUniqueId((size = 21) => 'test-id-' + size)
+ * console.log(uniqueId()) // 'test-id-21'
+ * console.log(uniqueId(10)) // 'test-id-10'
+ *
+ * // Restore original implementation when done
+ * restoreUniqueId()
+ * ```
+ * @internal
+ */
+declare function mockUniqueId(fn: (size?: number) => string): void;
+/**
+ * Restore the original unique ID generator after mocking.
+ *
+ * Resets the ID generation function back to the original nanoid implementation.
+ * This should be called after testing to restore normal ID generation behavior.
+ *
+ * @example
+ * ```ts
+ * // After mocking for tests
+ * mockUniqueId(() => 'mock-id')
+ *
+ * // Restore original behavior
+ * restoreUniqueId()
+ * console.log(uniqueId()) // Now generates real random IDs again
+ * ```
+ * @internal
+ */
+declare function restoreUniqueId(): void;
+/**
+ * Generate a unique ID using a modified nanoid algorithm.
+ *
+ * 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
+ */
+declare function uniqueId(size?: number): string;
+
+/**
+ * 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 = getFirstFromIterable(new Set([1, 2, 3])) // 1
+ * const B = getFirstFromIterable(
+ * 	new Map([
+ * 		['a', 1],
+ * 		['b', 2],
+ * 	])
+ * ) // 1
+ * ```
+ * @public
+ */
+declare function getFirstFromIterable<T = unknown>(set: Set<T> | Map<any, T>): T;
+
+/** Simple LRU cache backed by a Map's insertion-order iteration. @public */
+declare class LruCache<K, V> {
+    private maxSize;
+    private map;
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    get size(): number;
+}
+
+/**
+ * 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
+ */
+type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/**
+ * 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
+ */
+type JsonPrimitive = boolean | null | string | number;
+/**
+ * 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
+ */
+type JsonArray = JsonValue[];
+/**
+ * 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
+ */
+interface JsonObject {
+    [key: string]: JsonValue | undefined;
+}
+
+/**
+ * Array of all supported image MIME types, combining static, vector, and animated types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_IMAGE_TYPES } from '@ibodr/utils'
+ *
+ * const isSupported = DEFAULT_SUPPORTED_IMAGE_TYPES.includes('image/png')
+ * console.log(isSupported) // true
+ * ```
+ * @public
+ */
+declare const DEFAULT_SUPPORTED_IMAGE_TYPES: readonly ("image/svg+xml" | "image/jpeg" | "image/png" | "image/webp" | "image/gif" | "image/apng" | "image/avif")[];
+/**
+ * Array of supported video MIME types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORT_VIDEO_TYPES } from '@ibodr/utils'
+ *
+ * const isVideo = DEFAULT_SUPPORT_VIDEO_TYPES.includes('video/mp4')
+ * console.log(isVideo) // true
+ * ```
+ * @public
+ */
+declare const DEFAULT_SUPPORT_VIDEO_TYPES: readonly ("video/mp4" | "video/webm" | "video/quicktime")[];
+/**
+ * Array of all supported media MIME types, combining images and videos.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_MEDIA_TYPES } from '@ibodr/utils'
+ *
+ * const isMediaFile = DEFAULT_SUPPORTED_MEDIA_TYPES.includes('video/mp4')
+ * console.log(isMediaFile) // true
+ * ```
+ * @public
+ */
+declare const DEFAULT_SUPPORTED_MEDIA_TYPES: readonly ("image/svg+xml" | "image/jpeg" | "image/png" | "image/webp" | "image/gif" | "image/apng" | "image/avif" | "video/mp4" | "video/webm" | "video/quicktime")[];
+/**
+ * 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 '@ibodr/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
+ */
+declare const DEFAULT_SUPPORTED_MEDIA_TYPE_LIST: string;
+/**
+ * Helpers for media
+ *
+ * @public
+ */
+declare class MediaHelpers {
+    /**
+     * Load a video element from a URL with cross-origin support.
+     *
+     * @param src - The URL of the video to load
+     * @param doc - Optional document to create the video element in
+     * @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, doc?: Document): Promise<HTMLVideoElement>;
+    /**
+     * 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 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
+     * @param doc - Optional document to use for DOM operations (e.g. measuring SVG dimensions)
+     * @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, doc?: Document): Promise<{
+        w: number;
+        h: number;
+        image: HTMLImageElement;
+    }>;
+    /**
+     * Get the size of a video blob
+     *
+     * @param blob - A Blob containing the video
+     * @param doc - Optional document to create elements in
+     * @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, doc?: Document): Promise<{
+        w: number;
+        h: number;
+    }>;
+    /**
+     * Get the size of an image blob
+     *
+     * @param blob - A Blob containing the image
+     * @param doc - Optional document to use for DOM operations
+     * @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, doc?: Document): Promise<{
+        w: number;
+        h: number;
+        pixelRatio: 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: string | null): 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: string | null): 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: string | null): 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>;
+}
+
+/*!
+ * MIT License: https://github.com/alexgorbatchev/crc/blob/master/LICENSE
+ * Copyright: 2014 Alex Gorbatchev
+ * Code: crc32, https://github.com/alexgorbatchev/crc/blob/master/src/calculators/crc32.ts
+ */
+/**
+ * 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
+ */
+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;
+}
+
+/**
+ * Just a wrapper around `window.fetch` that sets the `referrerPolicy` to `strict-origin-when-cross-origin`.
+ *
+ * @param input - A Request object or string containing the URL to fetch
+ * @param init - Optional request initialization options
+ * @returns Promise that resolves to the Response object
+ * @internal
+ */
+declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Just a wrapper around `new Image`, and yeah, it's a bit strange that it's in the network.ts file
+ * but the main concern here is the referrerPolicy and setting it correctly.
+ *
+ * @param width - Optional width for the image element
+ * @param height - Optional height for the image element
+ * @returns HTMLImageElement with referrerPolicy set to 'strict-origin-when-cross-origin'
+ * @internal
+ */
+declare const Image: (width?: number, height?: number) => HTMLImageElement;
+
+/**
+ * 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 halfway = lerp(0, 100, 0.5) // 50
+ * const quarter = lerp(10, 20, 0.25) // 12.5
+ * ```
+ * @public
+ */
+declare function lerp(a: number, b: number, t: number): number;
+/**
+ * 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
+ */
+declare function invLerp(a: number, b: number, t: number): number;
+/**
+ * Seeded random number generator, using [xorshift](https://en.wikipedia.org/wiki/Xorshift). The
+ * 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
+ */
+declare function rng(seed?: string): () => number;
+/**
+ * Modulate a value between two ranges.
+ *
+ * @example
+ *
+ * ```ts
+ * const A = modulate(0, [0, 1], [0, 100]) // 0
+ * const B = modulate(0.5, [0, 1], [0, 100]) // 50
+ * const C = modulate(1, [0, 1], [0, 100]) // 100
+ * ```
+ *
+ * @param value - The interpolation value.
+ * @param rangeA - From [low, high]
+ * @param rangeB - To [low, high]
+ * @param clamp - Whether to clamp the the result to [low, high]
+ * @public
+ */
+declare function modulate(value: number, rangeA: number[], rangeB: number[], clamp?: boolean): number;
+
+/**
+ * Safely checks if an object has a specific property as its own property (not inherited).
+ * Uses Object.prototype.hasOwnProperty.call to avoid issues with objects that have null prototype
+ * or have overridden the hasOwnProperty method.
+ *
+ * @param obj - The object to check
+ * @param key - The property key to check for
+ * @returns True if the object has the property as its own property, false otherwise
+ * @example
+ * ```ts
+ * const obj = { name: 'Alice', age: 30 }
+ * hasOwnProperty(obj, 'name') // true
+ * hasOwnProperty(obj, 'toString') // false (inherited)
+ * hasOwnProperty(obj, 'unknown') // false
+ * ```
+ * @internal
+ */
+declare function hasOwnProperty(obj: object, key: string): boolean;
+/**
+ * Safely gets an object's own property value (not inherited). Returns undefined if the property
+ * doesn't exist as an own property. Provides type-safe access with proper TypeScript inference.
+ *
+ * @param obj - The object to get the property from
+ * @param key - The property key to retrieve
+ * @returns The property value if it exists as an own property, undefined otherwise
+ * @example
+ * ```ts
+ * const user = { name: 'Alice', age: 30 }
+ * const name = getOwnProperty(user, 'name') // 'Alice'
+ * const missing = getOwnProperty(user, 'unknown') // undefined
+ * const inherited = getOwnProperty(user, 'toString') // undefined (inherited)
+ * ```
+ * @internal
+ */
+declare function getOwnProperty<K extends string, V>(obj: Partial<Record<K, V>>, key: K): V | undefined;
+/** @internal */
+declare function getOwnProperty<O extends object>(obj: O, key: string): O[keyof O] | undefined;
+/** @internal */
+declare function getOwnProperty(obj: object, key: string): unknown;
+/**
+ * An alias for `Object.keys` that treats the object as a map and so preserves the type of the keys.
+ * Unlike standard Object.keys which returns string[], this maintains the specific string literal types.
+ *
+ * @param object - The object to get keys from
+ * @returns Array of keys with preserved string literal types
+ * @example
+ * ```ts
+ * const config = { theme: 'dark', lang: 'en' } as const
+ * const keys = objectMapKeys(config)
+ * // keys is Array<'theme' | 'lang'> instead of string[]
+ * ```
+ * @internal
+ */
+declare function objectMapKeys<Key extends string>(object: {
+    readonly [K in Key]: unknown;
+}): Array<Key>;
+/**
+ * An alias for `Object.values` that treats the object as a map and so preserves the type of the
+ * values. Unlike standard Object.values which returns unknown[], this maintains the specific value types.
+ *
+ * @param object - The object to get values from
+ * @returns Array of values with preserved types
+ * @example
+ * ```ts
+ * const scores = { alice: 85, bob: 92, charlie: 78 }
+ * const values = objectMapValues(scores)
+ * // values is Array<number> instead of unknown[]
+ * ```
+ * @internal
+ */
+declare function objectMapValues<Key extends string, Value>(object: {
+    [K in Key]: Value;
+}): Array<Value>;
+/**
+ * An alias for `Object.entries` that treats the object as a map and so preserves the type of the
+ * keys and values. Unlike standard Object.entries which returns `Array<[string, unknown]>`, this maintains specific types.
+ *
+ * @param object - The object to get entries from
+ * @returns Array of key-value pairs with preserved types
+ * @example
+ * ```ts
+ * const user = { name: 'Alice', age: 30 }
+ * const entries = objectMapEntries(user)
+ * // entries is Array<['name' | 'age', string | number]>
+ * ```
+ * @internal
+ */
+declare function objectMapEntries<Obj extends object>(object: Obj): Array<[keyof Obj, Obj[keyof Obj]]>;
+/**
+ * Returns the entries of an object as an iterable iterator.
+ * Useful when working with large collections, to avoid allocating an array.
+ * Only yields own properties (not inherited ones).
+ *
+ * @param object - The object to iterate over
+ * @returns Iterator yielding key-value pairs with preserved types
+ * @example
+ * ```ts
+ * const largeMap = { a: 1, b: 2, c: 3 } // Imagine thousands of entries
+ * for (const [key, value] of objectMapEntriesIterable(largeMap)) {
+ *   // Process entries one at a time without creating a large array
+ *   console.log(key, value)
+ * }
+ * ```
+ * @internal
+ */
+declare function objectMapEntriesIterable<Key extends string, Value>(object: {
+    [K in Key]: Value;
+}): IterableIterator<[Key, Value]>;
+/**
+ * An alias for `Object.fromEntries` that treats the object as a map and so preserves the type of the
+ * keys and values. Creates an object from key-value pairs with proper TypeScript typing.
+ *
+ * @param entries - Array of key-value pairs to convert to an object
+ * @returns Object with preserved key and value types
+ * @example
+ * ```ts
+ * const pairs: Array<['name' | 'age', string | number]> = [['name', 'Alice'], ['age', 30]]
+ * const obj = objectMapFromEntries(pairs)
+ * // obj is { name: string | number, age: string | number }
+ * ```
+ * @internal
+ */
+declare function objectMapFromEntries<Key extends string, Value>(entries: ReadonlyArray<readonly [Key, Value]>): {
+    [K in Key]: Value;
+};
+/**
+ * Filters an object using a predicate function, returning a new object with only the entries
+ * that pass the predicate. Optimized to return the original object if no changes are needed.
+ *
+ * @param object - The object to filter
+ * @param predicate - Function that tests each key-value pair
+ * @returns A new object with only the entries that pass the predicate, or the original object if unchanged
+ * @example
+ * ```ts
+ * const scores = { alice: 85, bob: 92, charlie: 78 }
+ * const passing = filterEntries(scores, (name, score) => score >= 80)
+ * // { alice: 85, bob: 92 }
+ * ```
+ * @internal
+ */
+declare function filterEntries<Key extends string, Value>(object: {
+    [K in Key]: Value;
+}, predicate: (key: Key, value: Value) => boolean): {
+    [K in Key]: Value;
+};
+/**
+ * Maps the values of an object to new values using a mapper function, preserving keys.
+ * The mapper function receives both the key and value for each entry.
+ *
+ * @param object - The object whose values to transform
+ * @param mapper - Function that transforms each value (receives key and value)
+ * @returns A new object with the same keys but transformed values
+ * @example
+ * ```ts
+ * const prices = { apple: 1.50, banana: 0.75, orange: 2.00 }
+ * const withTax = mapObjectMapValues(prices, (fruit, price) => price * 1.08)
+ * // { apple: 1.62, banana: 0.81, orange: 2.16 }
+ * ```
+ * @internal
+ */
+declare function mapObjectMapValues<Key extends string, ValueBefore, ValueAfter>(object: {
+    readonly [K in Key]: ValueBefore;
+}, mapper: (key: Key, value: ValueBefore) => ValueAfter): {
+    [K in Key]: ValueAfter;
+};
+/**
+ * Performs a shallow equality check between two objects. Compares all enumerable own properties
+ * using Object.is for value comparison. Returns true if both objects have the same keys and values.
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @returns True if objects are shallow equal, false otherwise
+ * @example
+ * ```ts
+ * const a = { x: 1, y: 2 }
+ * const b = { x: 1, y: 2 }
+ * const c = { x: 1, y: 3 }
+ * areObjectsShallowEqual(a, b) // true
+ * areObjectsShallowEqual(a, c) // false
+ * areObjectsShallowEqual(a, a) // true (same reference)
+ * ```
+ * @internal
+ */
+declare function areObjectsShallowEqual<T extends object>(obj1: T, obj2: T): boolean;
+/**
+ * Groups an array of values into a record by a key extracted from each value.
+ * The key selector function is called for each element to determine the grouping key.
+ *
+ * @param array - The array to group
+ * @param keySelector - Function that extracts the grouping key from each value
+ * @returns A record where keys are the extracted keys and values are arrays of grouped items
+ * @example
+ * ```ts
+ * const people = [
+ *   { name: 'Alice', age: 25 },
+ *   { name: 'Bob', age: 30 },
+ *   { name: 'Charlie', age: 25 }
+ * ]
+ * const byAge = groupBy(people, person => `age-${person.age}`)
+ * // { 'age-25': [Alice, Charlie], 'age-30': [Bob] }
+ * ```
+ * @internal
+ */
+declare function groupBy<K extends string, V>(array: ReadonlyArray<V>, keySelector: (value: V) => K): Record<K, V[]>;
+/**
+ * Creates a new object with specified keys omitted from the original object.
+ * Uses shallow copying and then deletes the unwanted keys.
+ *
+ * @param obj - The source object
+ * @param keys - Array of key names to omit from the result
+ * @returns A new object without the specified keys
+ * @example
+ * ```ts
+ * const user = { id: '123', name: 'Alice', password: 'secret', email: 'alice@example.com' }
+ * const publicUser = omit(user, ['password'])
+ * // { id: '123', name: 'Alice', email: 'alice@example.com' }
+ * ```
+ * @internal
+ */
+declare function omit(obj: Record<string, unknown>, keys: ReadonlyArray<string>): Record<string, unknown>;
+/**
+ * Compares two objects and returns an array of keys where the values differ.
+ * Uses Object.is for comparison, which handles NaN and -0/+0 correctly.
+ * Only checks keys present in the first object.
+ *
+ * @param obj1 - The first object (keys to check come from this object)
+ * @param obj2 - The second object to compare against
+ * @returns Array of keys where values differ between the objects
+ * @example
+ * ```ts
+ * const before = { name: 'Alice', age: 25, city: 'NYC' }
+ * const after = { name: 'Alice', age: 26, city: 'NYC' }
+ * const changed = getChangedKeys(before, after)
+ * // ['age']
+ * ```
+ * @internal
+ */
+declare function getChangedKeys<T extends object>(obj1: T, obj2: T): (keyof T)[];
+/**
+ * Deep equality comparison that allows for floating-point precision errors.
+ * Numbers are considered equal if they differ by less than the threshold.
+ * Uses lodash.isequalwith internally for the deep comparison logic.
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @param threshold - Maximum difference allowed between numbers (default: 0.000001)
+ * @returns True if objects are deeply equal with floating-point tolerance
+ * @example
+ * ```ts
+ * const a = { x: 0.1 + 0.2 } // 0.30000000000000004
+ * const b = { x: 0.3 }
+ * isEqualAllowingForFloatingPointErrors(a, b) // true
+ *
+ * const c = { coords: [1.0000001, 2.0000001] }
+ * const d = { coords: [1.0000002, 2.0000002] }
+ * isEqualAllowingForFloatingPointErrors(c, d) // true
+ * ```
+ * @internal
+ */
+declare function isEqualAllowingForFloatingPointErrors(obj1: object, obj2: object, threshold?: number): boolean;
+
+/**
+ * Measures and logs the execution time of a callback function.
+ * Executes the provided callback and logs the duration to the console with styled output.
+ *
+ * @param name - Descriptive name for the operation being measured
+ * @param cb - Callback function to execute and measure
+ * @returns The return value of the callback function
+ *
+ * @example
+ * ```ts
+ * const result = measureCbDuration('data processing', () => {
+ *   return processLargeDataSet(data)
+ * })
+ * // Console output: "Perf data processing took 42.5ms"
+ * ```
+ *
+ * @internal
+ */
+declare function measureCbDuration(name: string, cb: () => any): any;
+/**
+ * Decorator that measures and logs the execution time of class methods.
+ * Wraps the decorated method to automatically log its execution duration.
+ *
+ * @param _target - The class prototype (unused)
+ * @param propertyKey - Name of the method being decorated
+ * @param descriptor - Property descriptor of the method
+ * @returns Modified property descriptor with timing measurement
+ *
+ * @example
+ * ```ts
+ * class DataProcessor {
+ *   @measureDuration
+ *   processData(data: unknown[]) {
+ *     return data.map(item => transform(item))
+ *   }
+ * }
+ * // When processData is called, logs: "Perf processData took: 15.2ms"
+ * ```
+ *
+ * @internal
+ */
+declare function measureDuration(_target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+/**
+ * Decorator that measures method execution time and tracks running averages.
+ * Wraps the decorated method to log both current execution time and running average.
+ * Maintains a running total and count for each decorated method to calculate averages.
+ *
+ * @param _target - The class prototype (unused)
+ * @param propertyKey - Name of the method being decorated
+ * @param descriptor - Property descriptor of the method
+ * @returns Modified property descriptor with timing measurement and averaging
+ *
+ * @example
+ * ```ts
+ * class RenderEngine {
+ *   @measureAverageDuration
+ *   renderFrame() {
+ *     // Rendering logic here
+ *   }
+ * }
+ * // After multiple calls, logs: "Perf renderFrame took 16.67ms | average 15.83ms"
+ * ```
+ *
+ * @internal
+ */
+declare function measureAverageDuration(_target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+
+/**
+ * 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
+ */
+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;
+}
+
+/**
+ * A string made up of an integer part followed by a fraction part. The fraction point consists of
+ * zero or more digits with no trailing zeros. Based on
+ * {@link https://observablehq.com/@dgreensp/implementing-fractional-indexing}.
+ *
+ * @public
+ */
+type IndexKey = string & {
+    __brand: 'indexKey';
+};
+/**
+ * The index key for the first index - 'a0'.
+ * @public
+ */
+declare const ZERO_INDEX_KEY: IndexKey;
+/**
+ * Validates that a string is a valid IndexKey.
+ * @param index - The string to validate.
+ * @throws Error if the index is invalid.
+ * @internal
+ */
+declare function validateIndexKey(index: string): asserts index is IndexKey;
+/**
+ * Get a number of indices between two indices.
+ * @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
+ */
+declare function getIndicesBetween(below: IndexKey | null | undefined, above: IndexKey | null | undefined, n: number): 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
+ */
+declare function getIndicesAbove(below: IndexKey | null | undefined, n: number): IndexKey[];
+/**
+ * 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
+ */
+declare function getIndicesBelow(above: IndexKey | null | undefined, n: number): IndexKey[];
+/**
+ * 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
+ */
+declare function getIndexBetween(below: IndexKey | null | undefined, above: IndexKey | null | undefined): IndexKey;
+/**
+ * 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
+ */
+declare function getIndexAbove(below?: IndexKey | null | undefined): IndexKey;
+/**
+ * Get the index below a given index.
+ * @param above - The index above.
+ * @returns An IndexKey value below the given index.
+ * @example
+ * ```ts
+ * const index = getIndexBelow('a2' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
+ * @public
+ */
+declare function getIndexBelow(above?: IndexKey | null | undefined): IndexKey;
+/**
+ * Get n number of indices, starting at an index.
+ * @param n - The number of indices to get.
+ * @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
+ */
+declare function getIndices(n: number, start?: IndexKey): IndexKey[];
+/**
+ * Sort by index.
+ * @param a - An object with an index property.
+ * @param b - An object with an index property.
+ * @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
+ */
+declare function sortByIndex<T extends {
+    index: IndexKey;
+}>(a: T, b: T): 1 | -1 | 0;
+/**
+ * Sort by index, or null.
+ * @param a - An object with an index property.
+ * @param b - An object with an index property.
+ * @public
+ */
+declare function sortByMaybeIndex<T extends {
+    index?: IndexKey | null;
+}>(a: T, b: T): 1 | -1 | 0;
+
+/**
+ * Retries an async operation with configurable attempt count, wait duration, and error filtering.
+ * Executes the provided async function repeatedly until it succeeds or the maximum number of attempts is reached.
+ * Includes support for abort signals and custom error matching to determine which errors should trigger retries.
+ *
+ * @param fn - The async function to retry on failure
+ * @param options - Configuration options for retry behavior:
+ *   - `attempts`: Maximum number of retry attempts (default: 3)
+ *   - `waitDuration`: Milliseconds to wait between retry attempts (default: 1000)
+ *   - `abortSignal`: Optional AbortSignal to cancel the retry operation
+ *   - `matchError`: Optional function to determine if an error should trigger a retry
+ * @returns Promise that resolves with the function's return value on success
+ *
+ * @example
+ * ```ts
+ * // Basic retry with default settings (3 attempts, 1 second wait)
+ * const data = await retry(async () => {
+ *   const response = await fetch('/api/data')
+ *   if (!response.ok) throw new Error('Network error')
+ *   return response.json()
+ * })
+ *
+ * // Custom retry configuration
+ * const result = await retry(
+ *   async () => unreliableApiCall(),
+ *   {
+ *     attempts: 5,
+ *     waitDuration: 2000,
+ *     matchError: (error) => error instanceof NetworkError
+ *   }
+ * )
+ *
+ * // With abort signal for cancellation
+ * const controller = new AbortController()
+ * setTimeout(() => controller.abort(), 10000) // Cancel after 10 seconds
+ *
+ * const data = await retry(
+ *   async () => fetchData(),
+ *   {
+ *     attempts: 10,
+ *     abortSignal: controller.signal
+ *   }
+ * )
+ * ```
+ *
+ * @internal
+ */
+declare function retry<T>(fn: (args: {
+    attempt: number;
+    remaining: number;
+    total: number;
+}) => Promise<T>, { attempts, waitDuration, abortSignal, matchError, }?: {
+    attempts?: number;
+    waitDuration?: number;
+    abortSignal?: AbortSignal;
+    matchError?(error: unknown): boolean;
+}): Promise<T>;
+
+/**
+ * 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
+ */
+declare function sortById<T extends {
+    id: any;
+}>(a: T, b: T): 1 | -1;
+
+/**
+ * Get a value from local storage.
+ *
+ * @param key - The key to get.
+ * @returns The stored value as a string, or null if not found or storage is unavailable.
+ * @example
+ * ```ts
+ * const userTheme = getFromLocalStorage('user-theme')
+ * if (userTheme) {
+ *   console.log('Stored theme:', userTheme)
+ * }
+ * ```
+ * @internal
+ */
+declare function getFromLocalStorage(key: string): string | null;
+/**
+ * Set a value in local storage. Will not throw an error if localStorage is not available.
+ *
+ * @param key - The key to set.
+ * @param value - The value to set.
+ * @returns void
+ * @example
+ * ```ts
+ * const preferences = { theme: 'dark', language: 'en' }
+ * setInLocalStorage('user-preferences', JSON.stringify(preferences))
+ * ```
+ * @internal
+ */
+declare function setInLocalStorage(key: string, value: string): void;
+/**
+ * Remove a value from local storage. Will not throw an error if localStorage is not available.
+ *
+ * @param key - The key to remove.
+ * @returns void
+ * @example
+ * ```ts
+ * deleteFromLocalStorage('user-preferences')
+ * // Value is now removed from localStorage
+ * ```
+ * @internal
+ */
+declare function deleteFromLocalStorage(key: string): void;
+/**
+ * Clear all values from local storage. Will not throw an error if localStorage is not available.
+ *
+ * @returns void
+ * @example
+ * ```ts
+ * clearLocalStorage()
+ * // All localStorage data is now cleared
+ * ```
+ * @internal
+ */
+declare function clearLocalStorage(): void;
+/**
+ * Get a value from session storage.
+ *
+ * @param key - The key to get.
+ * @returns The stored value as a string, or null if not found or storage is unavailable.
+ * @example
+ * ```ts
+ * const currentTool = getFromSessionStorage('current-tool')
+ * if (currentTool) {
+ *   console.log('Active tool:', currentTool)
+ * }
+ * ```
+ * @internal
+ */
+declare function getFromSessionStorage(key: string): string | null;
+/**
+ * Set a value in session storage. Will not throw an error if sessionStorage is not available.
+ *
+ * @param key - The key to set.
+ * @param value - The value to set.
+ * @returns void
+ * @example
+ * ```ts
+ * setInSessionStorage('current-tool', 'select')
+ * setInSessionStorage('temp-data', JSON.stringify({ x: 100, y: 200 }))
+ * ```
+ * @internal
+ */
+declare function setInSessionStorage(key: string, value: string): void;
+/**
+ * Remove a value from session storage. Will not throw an error if sessionStorage is not available.
+ *
+ * @param key - The key to remove.
+ * @returns void
+ * @example
+ * ```ts
+ * deleteFromSessionStorage('temp-data')
+ * // Value is now removed from sessionStorage
+ * ```
+ * @internal
+ */
+declare function deleteFromSessionStorage(key: string): void;
+/**
+ * Clear all values from session storage. Will not throw an error if sessionStorage is not available.
+ *
+ * @returns void
+ * @example
+ * ```ts
+ * clearSessionStorage()
+ * // All sessionStorage data is now cleared
+ * ```
+ * @internal
+ */
+declare function clearSessionStorage(): void;
+
+/**
+ * Creates an enum-like object from string values where each key maps to itself.
+ * Useful for creating string constant objects with type safety and autocompletion.
+ * @param values - The string values to create the enum from.
+ * @returns An object where each provided string is both the key and value.
+ * @example
+ * ```ts
+ * const Colors = stringEnum('red', 'green', 'blue')
+ * // Results in: { red: 'red', green: 'green', blue: 'blue' }
+ *
+ * // Type-safe usage
+ * function setColor(color: keyof typeof Colors) {
+ *   console.log(`Setting color to ${Colors[color]}`)
+ * }
+ *
+ * setColor('red') // ✓ Valid
+ * setColor('yellow') // ✗ TypeScript error
+ * ```
+ * @internal
+ */
+declare function stringEnum<T extends string>(...values: T[]): {
+    [K in T]: K;
+};
+
+/**
+ * A scheduler class that manages a queue of functions to be executed at a target frame rate.
+ * Each instance maintains its own queue and state, allowing for separate throttling contexts
+ * (e.g., UI operations vs network sync operations).
+ *
+ * @public
+ */
+declare class FpsScheduler {
+    private targetFps;
+    private targetTimePerFrame;
+    private fpsQueue;
+    private frameRaf;
+    private flushRaf;
+    private lastFlushTime;
+    constructor(targetFps?: number);
+    updateTargetFps(targetFps: number): void;
+    private flush;
+    private tick;
+    /**
+     * Creates a throttled version of a function that executes at most once per frame.
+     * The default target frame rate is set by the FpsScheduler instance.
+     * Subsequent calls within the same frame are ignored, ensuring smooth performance
+     * for high-frequency events like mouse movements or scroll events.
+     *
+     * @param fn - The function to throttle, optionally with a cancel method
+     * @returns A throttled function with an optional cancel method to remove pending calls
+     *
+     * @public
+     */
+    fpsThrottle(fn: {
+        (): void;
+        cancel?(): void;
+    }): {
+        (): void;
+        cancel?(): void;
+    };
+    /**
+     * Schedules a function to execute on the next animation frame.
+     * If the same function is passed multiple times before the frame executes,
+     * it will only be called once, effectively batching multiple calls.
+     *
+     * @param fn - The function to execute on the next frame
+     * @returns A cancel function that can prevent execution if called before the next frame
+     *
+     * @public
+     */
+    throttleToNextFrame(fn: () => void): () => void;
+}
+/**
+ * Creates a throttled version of a function that executes at most once per frame.
+ * The default target frame rate is 120fps, but can be customized per function.
+ * Subsequent calls within the same frame are ignored, ensuring smooth performance
+ * for high-frequency events like mouse movements or scroll events.
+ *
+ * Uses the default throttle instance for UI operations. If you need a separate
+ * throttling queue (e.g., for network operations), create your own Throttle instance.
+ *
+ * @param fn - The function to throttle, optionally with a cancel method
+ * @returns A throttled function with an optional cancel method to remove pending calls
+ *
+ * @example
+ * ```ts
+ * // Default 120fps throttling
+ * const updateCanvas = fpsThrottle(() => {
+ *   // This will run at most once per frame (~8.33ms)
+ *   redrawCanvas()
+ * })
+ *
+ * // Call as often as you want - automatically throttled to 120fps
+ * document.addEventListener('mousemove', updateCanvas)
+ *
+ * // Cancel pending calls if needed
+ * updateCanvas.cancel?.()
+ * ```
+ *
+ * @internal
+ */
+declare function fpsThrottle(fn: {
+    (): void;
+    cancel?(): void;
+}): {
+    (): void;
+    cancel?(): void;
+};
+/**
+ * Schedules a function to execute on the next animation frame, targeting 120fps.
+ * If the same function is passed multiple times before the frame executes,
+ * it will only be called once, effectively batching multiple calls.
+ *
+ * Uses the default throttle instance for UI operations.
+ *
+ * @param fn - The function to execute on the next frame
+ * @returns A cancel function that can prevent execution if called before the next frame
+ *
+ * @example
+ * ```ts
+ * const updateUI = throttleToNextFrame(() => {
+ *   // Batches multiple calls into the next animation frame
+ *   updateStatusBar()
+ *   refreshToolbar()
+ * })
+ *
+ * // Multiple calls within the same frame are batched
+ * updateUI() // Will execute
+ * updateUI() // Ignored (same function already queued)
+ * updateUI() // Ignored (same function already queued)
+ *
+ * // Get cancel function to prevent execution
+ * const cancel = updateUI()
+ * cancel() // Prevents execution if called before next frame
+ * ```
+ *
+ * @internal
+ */
+declare function throttleToNextFrame(fn: () => void): () => void;
+
+/**
+ * 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
+ */
+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();
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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): {
+        setTimeout: (handler: TimerHandler, timeout?: number, ...args: any[]) => number;
+        setInterval: (handler: TimerHandler, timeout?: number, ...args: any[]) => number;
+        requestAnimationFrame: (callback: FrameRequestCallback) => number;
+        dispose: () => void;
+    };
+}
+
+/**
+ * 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
+ */
+declare const safeParseUrl: (url: string, baseUrl?: string | URL) => URL | undefined;
+
+/**
+ * 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
+ */
+declare function isDefined<T>(value: T): value is typeof value extends undefined ? never : T;
+/**
+ * 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
+ */
+declare function isNonNull<T>(value: T): value is typeof value extends null ? never : T;
+/**
+ * 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
+ */
+declare function isNonNullish<T>(value: T): value is typeof value extends undefined ? never : typeof value extends null ? never : T;
+/**
+ * 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.
+ * @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: <T>(i: T) => T;
+/**
+ * Whether the current environment has native structuredClone support.
+ * @returns True if using native structuredClone, false if using JSON fallback.
+ * @internal
+ */
+declare const isNativeStructuredClone: boolean;
+/**
+ * The prototype object used by structuredClone for cloned objects.
+ * When we patch structuredClone in jsdom for testing (see https://github.com/jsdom/jsdom/issues/3363),
+ * the Object that is used as a prototype for the cloned object is not the same as the Object in
+ * the code under test (that comes from jsdom's fake global context). This constant is used in
+ * our code to work around this case.
+ *
+ * This is also the case for Array prototype, but that problem can be worked around with an
+ * Array.isArray() check.
+ * @internal
+ */
+declare const STRUCTURED_CLONE_OBJECT_PROTOTYPE: any;
+
+/**
+ * Registers a tldraw library version for conflict detection.
+ * This function tracks different tldraw library versions to warn about potential conflicts
+ * when multiple versions are loaded simultaneously.
+ * @param name - The name of the tldraw library package (e.g., '\@ibodr/editor').
+ * @param version - The semantic version string (e.g., '2.0.0').
+ * @param modules - The module system being used ('esm' or 'cjs').
+ * @returns void
+ * @example
+ * ```ts
+ * // Register a library version during package initialization
+ * registerDrawLibraryVersion('@ibodr/editor', '2.0.0', 'esm')
+ * registerDrawLibraryVersion('@ibodr/tldraw', '2.0.0', 'esm')
+ *
+ * // If conflicting versions are detected, warnings will be logged:
+ * registerDrawLibraryVersion('@ibodr/editor', '1.9.0', 'cjs')
+ * // Console warning about version mismatch will appear
+ * ```
+ * @internal
+ */
+declare function registerDrawLibraryVersion(name?: string, version?: string, modules?: string): void;
+
+/**
+ * Issues a deprecation warning for deprecated getter properties, advising users to use
+ * the equivalent getter method instead. The warning is shown only once per property name.
+ *
+ * @param name - The name of the deprecated property (e.g., 'viewport')
+ *
+ * @example
+ * ```ts
+ * // Inside a class with deprecated property access
+ * get viewport() {
+ *   warnDeprecatedGetter('viewport')
+ *   return this.getViewport()
+ * }
+ *
+ * // Usage will show: "[tldraw] Using 'viewport' is deprecated and will be removed..."
+ * // But only the first time it's accessed
+ * ```
+ *
+ * @internal
+ */
+declare function warnDeprecatedGetter(name: string): void;
+/**
+ * Issues a warning message to the console, but only once per unique message.
+ * Subsequent calls with the same message are ignored, preventing console spam.
+ * All messages are prefixed with "[tldraw]".
+ *
+ * @param message - The warning message to display
+ *
+ * @example
+ * ```ts
+ * // Warn about deprecated usage
+ * function oldFunction() {
+ *   warnOnce('oldFunction is deprecated, use newFunction instead')
+ *   // Continue with implementation...
+ * }
+ *
+ * // First call logs: "[tldraw] oldFunction is deprecated, use newFunction instead"
+ * oldFunction() // Shows warning
+ * oldFunction() // No warning (already shown)
+ * oldFunction() // No warning (already shown)
+ * ```
+ *
+ * @internal
+ */
+declare function warnOnce(message: string): void;
+
+export { type Awaitable, DEFAULT_SUPPORTED_IMAGE_TYPES, DEFAULT_SUPPORTED_MEDIA_TYPES, DEFAULT_SUPPORTED_MEDIA_TYPE_LIST, DEFAULT_SUPPORT_VIDEO_TYPES, type ErrorAnnotations, type ErrorResult, ExecutionQueue, type Expand, FileHelpers, FpsScheduler, Image, type IndexKey, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, LruCache, type MakeUndefinedOptional, MediaHelpers, type OkResult, PerformanceTracker, PngHelpers, type RecursivePartial, type Required, Result, STRUCTURED_CLONE_OBJECT_PROTOTYPE, Timers, WeakCache, ZERO_INDEX_KEY, annotateError, areArraysShallowEqual, areObjectsShallowEqual, assert, assertExists, bind, clearLocalStorage, clearSessionStorage, compact, debounce, dedupe, deleteFromLocalStorage, deleteFromSessionStorage, exhaustiveSwitchError, fetch, filterEntries, fpsThrottle, getChangedKeys, getErrorAnnotations, getFirstFromIterable, getFromLocalStorage, getFromSessionStorage, getHashForBuffer, getHashForObject, getHashForString, getIndexAbove, getIndexBelow, getIndexBetween, getIndices, getIndicesAbove, getIndicesBelow, getIndicesBetween, getOwnProperty, groupBy, hasOwnProperty, invLerp, isDefined, isEqualAllowingForFloatingPointErrors, isNativeStructuredClone, isNonNull, isNonNullish, last, lerp, lns, mapObjectMapValues, maxBy, measureAverageDuration, measureCbDuration, measureDuration, mergeArraysAndReplaceDefaults, minBy, mockUniqueId, modulate, noop, objectMapEntries, objectMapEntriesIterable, objectMapFromEntries, objectMapKeys, objectMapValues, omit, omitFromStackTrace, partition, promiseWithResolve, registerDrawLibraryVersion, restoreUniqueId, retry, rng, rotateArray, safeParseUrl, setInLocalStorage, setInSessionStorage, sleep, sortById, sortByIndex, sortByMaybeIndex, stringEnum, structuredClone, throttleToNextFrame, uniqueId, validateIndexKey, warnDeprecatedGetter, warnOnce };