@semio/utils 0.0.0

package/dist/index.d.mts

@@ -0,0 +1,1020 @@
+import * as react from 'react';
+import * as zustand from 'zustand';
+
+/**
+ * Logs a message to the console.
+ *
+ * @param value - The message to be logged
+ *
+ * @remarks
+ * This function temporarily disables ESLint console warnings for testing purposes.
+ */
+declare function log(value: string): void;
+
+/**
+ * Generates a namespaced lookup key.
+ *
+ * @param namespace - The namespace identifier ("default" is treated specially)
+ * @param id - The identifier to namespace
+ * @returns A dot-separated namespaced key (e.g., "namespace.id")
+ *
+ * @example
+ * ```typescript
+ * getLookup("users", "123") // Returns: "users.123"
+ * getLookup("default", "123") // Returns: "default.123"
+ * ```
+ */
+declare function getLookup(namespace: string, id: string): string;
+/**
+ * Extracts the namespace from a lookup key.
+ *
+ * @param lookup - The namespaced lookup key
+ * @returns The namespace portion, or "default" if no namespace is present
+ *
+ * @example
+ * ```typescript
+ * getNamespace("users.123") // Returns: "users"
+ * getNamespace("123") // Returns: "default"
+ * ```
+ */
+declare function getNamespace(lookup: string): string;
+/**
+ * Extracts the identifier from a lookup key.
+ *
+ * @param lookup - The namespaced lookup key
+ * @returns The identifier portion, or the entire key if no namespace is present
+ *
+ * @example
+ * ```typescript
+ * getId("users.123") // Returns: "123"
+ * getId("123") // Returns: "123"
+ * ```
+ */
+declare function getId(lookup: string): string;
+
+/**
+ * Time representation in milliseconds.
+ */
+type RawTime = number;
+/**
+ * A timer implementation for managing animation playback.
+ *
+ * The timer operates on a normalized time range of [0, 1], where:
+ * - 0 represents the start of the animation
+ * - 1 represents the end of the animation
+ *
+ * @property running - Whether the timer is actively running
+ * @property _previousTime - The last update time in milliseconds
+ * @property _currentTime - The current time in milliseconds
+ * @property stamp - Current normalized time position [0, 1]
+ * @property timescale - Playback speed multiplier (negative for reverse)
+ * @property bounds - Constrains playback to a [start, end] range within [0, 1]
+ * @property playback - Animation behavior at bounds ("loop"|"bounce"|"once")
+ * @property viewport - Visible time range as [start, end] within [0, 1]
+ * @property duration - Total animation duration in milliseconds
+ */
+interface Player {
+    running: boolean;
+    _previousTime: RawTime;
+    _currentTime: RawTime;
+    stamp: number;
+    timescale: number;
+    bounds: [number, number];
+    playback: "loop" | "bounce" | "once";
+    viewport: [number, number];
+    duration: number;
+}
+/**
+ * Creates a copy of the provided timer, but updated with the new timestamp.
+ * @param timer - the timer to be updated
+ * @param stamp - the new timestamp in the range [0, 1]
+ * @returns the updated timer
+ */
+declare function reset(player: Player, stamp?: number): Player;
+/**
+ * Returns the current time in milliseconds.
+ * @returns the current time in milliseconds
+ */
+declare function now(): RawTime;
+/**
+ * Creates a copy of the provided timer, but updated with a new timestamp as determined by
+ * the timestamp since it was last called and the duration of the animation itself.
+ * @param timer - the timer to be updated
+ * @returns the updated timer
+ */
+declare function update(player: Player, coldStart: boolean): Player;
+/**
+ * Sets the bounds for the player.
+ * @param player - the player to be updated
+ * @param bounds - the new bounds in the range [0, 1]
+ * @returns the updated player
+ */
+declare function setBounds(player: Player, bounds: [number, number]): Player;
+/**
+ * Sets the viewport for the player
+ * @param player - the player to be updated
+ * @param viewport - the new viewport in the range [0, 1]
+ * @returns the updated player
+ */
+declare function setViewport(player: Player, viewport: [number, number]): Player;
+/**
+ * Creates a copy of the provided timer, but updated with a timescale based on the speed provided.
+ * @param timer - the timer to be updated
+ * @param speed - the speed of playback desired (defaults to 1)
+ * @returns the updated timer
+ */
+declare function play(player: Player, speed?: number): Player;
+/**
+ * Creates a copy of the provided timer, but updated with a timescale of 0 (paused)
+ * @param timer - the timer to be updated
+ * @returns the updated timer
+ */
+declare function pause(player: Player): Player;
+/**
+ * Returns the provided player, with the viewport centered around the provided stamp as much as possible.
+ * @param player - the player to be updated
+ * @param stamp - the new stamp to center the viewport around
+ * @returns the updated player
+ */
+declare function seek(player: Player, stamp: number): Player;
+/**
+ * Returns the provided player, with the duration set to the provided value.
+ * @param player - the player to be updated
+ * @param duration - the new duration
+ * @returns the updated player
+ */
+declare function setDuration(player: Player, duration: number): Player;
+/**
+ * Creates a new Player instance with default values.
+ *
+ * @returns A new Player instance initialized with:
+ * - Not running
+ * - Current timestamp
+ * - Zero stamp position
+ * - No timescale
+ * - Full bounds [0, 1]
+ * - Loop playback
+ * - Full viewport [0, 1]
+ * - 1000ms duration
+ */
+declare function newPlayer(): Player;
+
+/**
+ * Core data structure for player state
+ */
+interface PlayerData {
+    /** The player instance containing current state */
+    player: Player;
+}
+/**
+ * Actions available for controlling the player
+ */
+interface PlayerActions {
+    /** Updates the total duration of the animation */
+    updateDuration: (duration: number) => void;
+    /** Updates the playback speed multiplier */
+    updateTimescale: (speed: number) => void;
+    /** Resets the player to initial state or specified time */
+    resetPlayer: (time?: number) => void;
+    /** Plays the animation */
+    playPlayer: (speed?: number) => void;
+    /** Pauses the animation */
+    pausePlayer: () => void;
+    /** Updates the timer */
+    updatePlayer: (coldStart?: boolean) => void;
+    /** Sets the player bounds */
+    updatePlayerBounds: (start: number, end: number) => void;
+    /** Updates one bound of the player */
+    updatePlayerBound: (bound: "start" | "end", time?: number) => void;
+    /** Sets the player viewport */
+    updatePlayerViewport: (start: number, end: number) => void;
+    /** Seeks the viewport to center the player at a time */
+    updatePlayerViewportCenter: (time?: number) => void;
+    /** Updates one bound of the player viewport */
+    updatePlayerViewportBound: (bound: "start" | "end", time: number) => void;
+}
+type PlayerStoreSetter = (partial: (PlayerData & PlayerActions) | Partial<PlayerData & PlayerActions> | ((state: PlayerData & PlayerActions) => (PlayerData & PlayerActions) | Partial<PlayerData & PlayerActions>), replace?: false | undefined) => void;
+type PlayerStoreGetter = () => PlayerData & PlayerActions;
+declare const PlayerSlice: (set: PlayerStoreSetter) => {
+    player: Player;
+    updateDuration: (duration: number) => void;
+    updateTimescale: (speed: number) => void;
+    resetPlayer: (time?: number) => void;
+    playPlayer: (speed?: number) => void;
+    pausePlayer: () => void;
+    updatePlayer: (coldStart?: boolean) => void;
+    updatePlayerBounds: (start: number, end: number) => void;
+    updatePlayerBound: (bound: "start" | "end", time?: number) => void;
+    updatePlayerViewport: (start: number, end: number) => void;
+    updatePlayerViewportCenter: (time?: number) => void;
+    updatePlayerViewportBound: (bound: "start" | "end", time: number) => void;
+};
+declare const usePlayerStore: zustand.UseBoundStore<Omit<zustand.StoreApi<PlayerData & PlayerActions>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: PlayerData & PlayerActions, previousSelectedState: PlayerData & PlayerActions) => void): () => void;
+        <U>(selector: (state: PlayerData & PlayerActions) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}>;
+type PlayerStore = typeof usePlayerStore;
+declare const PlayerContext: react.Context<zustand.UseBoundStore<Omit<zustand.StoreApi<PlayerData & PlayerActions>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: PlayerData & PlayerActions, previousSelectedState: PlayerData & PlayerActions) => void): () => void;
+        <U>(selector: (state: PlayerData & PlayerActions) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}> | null>;
+
+type RawBoolean = boolean;
+type RawNumber = number;
+type RawString = string;
+interface RawVector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface RawVector2 {
+    x: number;
+    y: number;
+}
+interface RawEuler {
+    x: number;
+    y: number;
+    z: number;
+}
+interface RawRGB {
+    r: number;
+    g: number;
+    b: number;
+}
+interface RawHSL {
+    h: number;
+    s: number;
+    l: number;
+}
+type RawColor = RawRGB | RawHSL;
+type RawValue = RawBoolean | RawNumber | RawString | RawVector3 | RawVector2 | RawEuler | RawColor;
+interface AnimatablePubInfo {
+    public: boolean;
+    units?: string;
+    output: string;
+    color?: string;
+}
+type AnimatableValue = AnimatableBoolean | AnimatableNumber | AnimatableString | AnimatableVector3 | AnimatableVector2 | AnimatableEuler | AnimatableColor;
+/**
+ * A specification for an animated numerical value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "boolean" for this type).
+ * @param default - the default value of the boolean.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableBoolean {
+    id: string;
+    name?: string;
+    type: "boolean";
+    default: RawBoolean;
+    constraints: {
+        frequency?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+/**
+ * A specification for an animated numerical value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "number" for this type).
+ * @param default - the default value of the number.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param angle - a boolean indicating whether the value represents an angle.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableNumber {
+    id: string;
+    name?: string;
+    type: "number";
+    default: RawNumber;
+    constraints: {
+        min?: number;
+        max?: number;
+        velocity?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+/**
+ * A specification for an animated string value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "string" for this type).
+ * @param default - the default value of the string.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableString {
+    id: string;
+    name?: string;
+    type: "string";
+    default: RawString;
+    constraints: {
+        length?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+/**
+ * A specification for an animated 3-vector value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "vector3" for this type).
+ * @param default - the default value of the vector3.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableVector3 {
+    id: string;
+    name?: string;
+    type: "vector3";
+    default: RawVector3;
+    constraints: {
+        min?: [number | null, number | null, number | null];
+        max?: [number | null, number | null, number | null];
+        velocity?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+/**
+ * A specification for an animated 2-vector value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "vector2" for this type).
+ * @param default - the default value of the vector2.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableVector2 {
+    id: string;
+    name?: string;
+    type: "vector2";
+    default: RawVector2;
+    constraints: {
+        min?: [number | null, number | null];
+        max?: [number | null, number | null];
+        velocity?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+/**
+ * A specification for an animated Euler value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "euler" for this type).
+ * @param default - the default value of the euler.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableEuler {
+    id: string;
+    name?: string;
+    type: "euler";
+    default: RawEuler;
+    constraints: {
+        min?: [number | null, number | null, number | null];
+        max?: [number | null, number | null, number | null];
+        velocity?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+/**
+ * A specification for an animated encoded color value
+ *
+ * @param id - a unique identifier for the value.
+ * @param name - the name of the value, defined by the user.
+ * @param type - the type of the value (always "rgb" or "hsl" for this type).
+ * @param default - the default value of the color.
+ * @param constraints - a collection of constraints that the value must adhere to.
+ * @param pub - a collection of properties that determine whether the value is public and what its output should be.
+ */
+interface AnimatableColor {
+    id: string;
+    name?: string;
+    type: "rgb" | "hsl";
+    default: RawColor;
+    constraints: {
+        min?: [number | null, number | null, number | null];
+        max?: [number | null, number | null, number | null];
+        velocity?: number;
+    };
+    pub?: AnimatablePubInfo;
+}
+declare function instanceOfRawBoolean(object: any): object is RawBoolean;
+declare function instanceOfRawNumber(object: any): object is RawNumber;
+declare function instanceOfRawString(object: any): object is RawString;
+declare function instanceOfRawVector3(object: any): object is RawVector3;
+declare function instanceOfRawVector2(object: any): object is RawVector2;
+declare function instanceOfRawEuler(object: any): object is RawEuler;
+declare function instanceOfRawColor(object: any): object is RawColor;
+declare function instanceOfRawRGB(object: any): object is RawRGB;
+declare function instanceOfRawHSL(object: any): object is RawHSL;
+declare function isRawObject(value: any): boolean;
+
+/**
+ * Converts a duration in milliseconds to a formatted time string.
+ *
+ * @param duration - The duration in milliseconds to convert
+ * @returns A string in the format "mm:ss:ms" where:
+ *          - mm: minutes (zero-padded to 2 digits)
+ *          - ss: seconds (zero-padded to 2 digits)
+ *          - ms: milliseconds (zero-padded to 2 digits)
+ *
+ * @example
+ * ```typescript
+ * numberToDurationString(63450) // Returns "01:03:45"
+ * numberToDurationString(5000)  // Returns "00:05:00"
+ * ```
+ */
+declare const numberToDurationString: (duration: number) => string;
+
+/**
+ * Creates pairs of adjacent elements from an array.
+ *
+ * @template T - The type of elements in the array
+ * @param arr - The source array to create pairs from
+ * @returns An array of tuples, where each tuple contains consecutive elements
+ *
+ * @example
+ * ```typescript
+ * pairwise([1, 2, 3, 4]) // Returns: [[1,2], [2,3], [3,4]]
+ * ```
+ */
+declare function pairwise<T>(arr: T[]): [T, T][];
+
+/**
+ * A hook that delays the nullification of a boolean state value.
+ *
+ * Useful for maintaining hover states or other temporary UI states
+ * for a specified duration after the triggering condition becomes false.
+ *
+ * @param value - The current boolean state value
+ * @param timeout - The delay duration in milliseconds
+ * @returns The delayed boolean state value
+ *
+ * @example
+ * ```typescript
+ * const isHoveredWithDelay = useLazy(isHovered, 500);
+ * ```
+ */
+declare function useLazy(value: boolean, timeout: number): boolean;
+
+/**
+ * Generates an SVG path string for a hexagon with flanges.
+ *
+ * @param x - Center X coordinate of the hexagon
+ * @param y - Center Y coordinate of the hexagon
+ * @param size - Width/height of the hexagon's body
+ * @param height - Total height including top and bottom flanges
+ * @returns SVG path string for the hexagon
+ *
+ * @example
+ * ```typescript
+ * const path = getHexagonPath(100, 100, 50, 80);
+ * // Use in SVG: <path d={path} />
+ * ```
+ */
+declare function getHexagonPath(x: number, y: number, size: number, height: number): string;
+/**
+ * Generates an SVG path string for a degenerate (collapsed) hexagon.
+ *
+ * Creates a vertical line with the same number of vertices as a regular hexagon,
+ * allowing smooth interpolation between the two shapes.
+ *
+ * @param x - Center X coordinate of the line
+ * @param y - Center Y coordinate of the line
+ * @param size - Reference size (affects vertical spacing of points)
+ * @param height - Total height of the line including endpoints
+ * @returns SVG path string for the degenerate hexagon
+ */
+declare function getDegenerateHexagonPath(x: number, y: number, size: number, height: number): string;
+
+/**
+ * Takes in the completion percentage and the total number of frames in an animation,
+ * and returns the closest frame as a percentage of the whole animation's duration.
+ *
+ * @param completion - The completion of the animation from 0 to 1.
+ * @param count - The number of frames in the animation.
+ * @returns The closest frame number to the completion as a percentage of the total frames.
+ */
+declare function closestFrame(completion: number, count: number): number;
+
+/**
+ * Converts an angle from radians to degrees.
+ *
+ * @param radians - The angle in radians
+ * @returns The angle in degrees
+ *
+ * @example
+ * ```typescript
+ * toDegrees(Math.PI) // Returns: 180
+ * ```
+ */
+declare const toDegrees: (radians: number) => number;
+/**
+ * Converts an angle from degrees to radians.
+ *
+ * @param degrees - The angle in degrees
+ * @returns The angle in radians
+ *
+ * @example
+ * ```typescript
+ * toRadians(180) // Returns: 3.141592653589793
+ * ```
+ */
+declare const toRadians: (degrees: number) => number;
+
+/**
+ * Converts a hexadecimal color value to an RGBA color string.
+ *
+ * @param hex - The hex color string (with or without #)
+ * @param alpha - The opacity value between 0 and 1
+ * @returns An RGBA color string
+ * @throws {Error} If the hex color format is invalid
+ *
+ * @example
+ * ```typescript
+ * const color = hexToRgba('#ff0000', 0.5); // "rgba(255, 0, 0, 0.5)"
+ * ```
+ */
+declare const hexToRgba: (hex: string, alpha: number) => string;
+/**
+ * Converts an RGB color value to an RGBA color string.
+ *
+ * @param rgb - The RGB color string in format "r, g, b"
+ * @param alpha - The opacity value between 0 and 1
+ * @returns An RGBA color string
+ * @throws {Error} If the RGB color format is invalid
+ */
+declare const rgbToRgba: (rgb: string, alpha: number) => string;
+/**
+ * Converts an HSL color value to an RGBA color string.
+ *
+ * @param hsl - The HSL color string in format "h, s, l"
+ * @param alpha - The opacity value between 0 and 1
+ * @returns An RGBA color string
+ * @throws {Error} If the HSL color format is invalid
+ */
+declare const hslToRgba: (hsl: string, alpha: number) => string;
+/**
+ * Adds transparency to a color string of any supported format (hex, rgb, hsl).
+ *
+ * @param color - The color string in hex, RGB, or HSL format
+ * @param opacity - The desired opacity value between 0 and 1
+ * @returns An RGBA color string
+ * @throws {Error} If the color format is not supported
+ *
+ * @example
+ * ```typescript
+ * const transparentRed = alpha('#ff0000', 0.5); // "rgba(255, 0, 0, 0.5)"
+ * const transparentBlue = alpha('rgb(0, 0, 255)', 0.7); // "rgba(0, 0, 255, 0.7)"
+ * ```
+ */
+declare const alpha: (color: string, opacity: number) => string;
+/**
+ * Lightens or darkens a color by a given factor.
+ *
+ * @param color - The color string to modify
+ * @param factor - Positive values lighten the color, negative values darken it
+ * @returns A hex color string
+ *
+ * @example
+ * ```typescript
+ * const lighterBlue = altColor('#0000ff', 0.2); // Lightens blue by 20%
+ * const darkerRed = altColor('#ff0000', -0.3); // Darkens red by 30%
+ * ```
+ */
+declare function altColor(color: string, factor: number): string;
+declare function hexToRgbArray(color: string): [number, number, number];
+declare function rawRGBToHex({ r, g, b }: RawRGB): string;
+declare function rawHSLToHex({ h, s, l }: RawHSL): string;
+
+/**
+ * Creates a memoized selector function that only updates when the selected value
+ * deeply changes.
+ *
+ * @param selector - A function that selects a value from the state
+ * @returns A memoized selector function that returns the same reference if the
+ *          selected value hasn't deeply changed
+ *
+ * @example
+ * ```typescript
+ * const selectUserData = useDeepSelector((state) => state.user.data);
+ * const userData = selectUserData(state);
+ * ```
+ */
+declare function useDeepSelector<S, U>(selector: (state: S) => U): (state: S) => U;
+/**
+ * Similar to useMemo, but performs a deep comparison of dependencies instead of
+ * reference equality.
+ *
+ * @param initializer - Function that returns the value to be memoized
+ * @param dependencies - Array of dependencies that trigger recalculation when deeply changed
+ * @returns The memoized value
+ *
+ * @example
+ * ```typescript
+ * const memoizedValue = useDeep(
+ *   () => expensiveCalculation(obj),
+ *   [obj]
+ * );
+ * ```
+ */
+declare function useDeep<V, D>(initializer: () => V, dependencies: D[]): V;
+
+/**
+ * Custom hook to handle responsive media queries in React components.
+ *
+ * @param query - A valid CSS media query string (e.g., '(min-width: 768px)')
+ * @returns A boolean indicating whether the media query matches
+ *
+ * @example
+ * ```typescript
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ *
+ * return (
+ *   <div>
+ *     {isMobile ? <MobileView /> : <DesktopView />}
+ *   </div>
+ * );
+ * ```
+ */
+declare const useMediaQuery: (query: string) => boolean;
+
+/**
+ * A utility type that overwrites properties in T with properties from U.
+ * @template T - The original type
+ * @template U - The type containing properties to overwrite with
+ */
+type Write<T, U> = Omit<T, keyof U> & U;
+/**
+ * Interface for a store that supports subscribing to state changes with selector support.
+ * @template T - The type of the store's state
+ */
+interface StoreSubscribeWithSelector<T> {
+    subscribe: {
+        /**
+         * Subscribe to all state changes
+         * @param listener - Callback called with the new and previous state values
+         * @returns Unsubscribe function
+         */
+        (listener: (selectedState: T, previousSelectedState: T) => void): () => void;
+        /**
+         * Subscribe to changes in a selected portion of the state
+         * @template U - The type of the selected state portion
+         * @param selector - Function to select a portion of the state
+         * @param listener - Callback called with the new and previous selected values
+         * @param options - Configuration options for the subscription
+         * @returns Unsubscribe function
+         */
+        <U>(selector: (state: T) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: (a: U, b: U) => boolean;
+            fireImmediately?: boolean;
+        }): () => void;
+    };
+}
+
+/**
+ * Converts a value to a JSON string, handling Maps appropriately.
+ *
+ * @param value - The value to stringify.
+ * @returns The JSON string representation of the value.
+ */
+declare function stringifyMapped(value: unknown): string;
+/**
+ * Parses a JSON string, reviving Maps appropriately.
+ *
+ * @param json - The JSON string to parse.
+ * @returns The parsed value.
+ */
+declare function parseToMapped(json: string): unknown;
+/**
+ * Parses the files in the given event and calls the provided function on each array item.
+ *
+ * @param event - The event containing the files to parse.
+ * @param fn - The function to call on each array item.
+ */
+declare function parseJSONFileEvent(event: React.ChangeEvent<HTMLInputElement>, fn: (item: unknown) => void): void;
+
+/**
+ * Downloads a JSON object as a file.
+ *
+ * @param data - The data to be converted to JSON and downloaded.
+ * @param filename - The name of the file to be downloaded.
+ */
+declare function downloadJSONFile(data: unknown, filename: string): void;
+/**
+ * Downloads a Blob as a file.
+ *
+ * @param blob - The Blob to be downloaded.
+ * @param filename - The name of the file to be downloaded.
+ */
+declare function downloadBlob(blob: Blob, filename: string): void;
+
+/**
+ * Converts an array of 2D points to an SVG path string.
+ *
+ * @param points - Array of [x, y] coordinate pairs
+ * @param close - If true, closes the path by adding a 'Z' command
+ * @returns An SVG path string using absolute move ('M') and line ('L') commands
+ *
+ * @example
+ * ```typescript
+ * pointsToPath([[0, 0], [1, 1], [2, 0]])     // Returns "M 0 0 L 1 1 L 2 0"
+ * pointsToPath([[0, 0], [1, 1]], true)        // Returns "M 0 0 L 1 1 Z"
+ * ```
+ *
+ * @remarks
+ * The path starts with a move command to the first point, followed by line commands
+ * to each subsequent point. If close is true, a final 'Z' command is added to
+ * create a closed shape.
+ */
+declare function pointsToPath(points: [number, number][], close?: boolean): string;
+
+/**
+ * Converts Euler angles to a 3x3 rotation matrix.
+ * Uses ZYX order (intrinsic rotations).
+ *
+ * @param euler - Array of three numbers representing rotation angles in radians [z, y, x]
+ * @returns A 3x3 rotation matrix as a nested array
+ *
+ * @example
+ * ```typescript
+ * const matrix = eulerToRotationMatrix([0, Math.PI/2, 0]);
+ * ```
+ */
+declare function eulerToRotationMatrix(euler: [number, number, number]): number[][];
+/**
+ * Calculates the angle of rotation from a rotation matrix.
+ *
+ * @param R - A 3x3 rotation matrix as a nested array
+ * @returns The angle of rotation in radians
+ */
+declare function rotationMatrixToAngle(R: number[][]): number;
+/**
+ * Calculates the angular distance between two orientations specified by Euler angles.
+ *
+ * @param euler1 - First orientation in Euler angles [z, y, x] in radians
+ * @param euler2 - Second orientation in Euler angles [z, y, x] in radians
+ * @returns The angular distance in radians
+ *
+ * @example
+ * ```typescript
+ * const distance = angularDistance([0, 0, 0], [0, Math.PI/2, 0]);
+ * ```
+ */
+declare function angularDistance(euler1: [number, number, number], euler2: [number, number, number]): number;
+
+/**
+ * Merges overlapping segments in an array of intervals.
+ *
+ * This function takes an array of intervals represented as tuples of two numbers,
+ * sorts them, and merges any overlapping intervals. The result is an array of
+ * non-overlapping intervals that cover the same ranges as the input.
+ *
+ * @param original - An array of intervals represented as tuples of two numbers.
+ *                   Each tuple contains a start and end value.
+ * @returns An array of merged, non-overlapping intervals.
+ *
+ * @example
+ * ```typescript
+ * const intervals = [[1, 3], [2, 4], [5, 7]];
+ * const result = overlappingSegments(intervals);
+ * console.log(result); // Output: [[1, 4], [5, 7]]
+ * ```
+ */
+declare function overlappingSegments(original: [number, number][]): [number, number][];
+
+/**
+ * A class representing a Result type that can either contain a success value of type T
+ * or an error value of type E. This implementation is inspired by Rust's Result type.
+ *
+ * @typeParam T - The type of the success value
+ * @typeParam E - The type of the error value, defaults to Error
+ *
+ * @example
+ * ```typescript
+ * // Creating a success result
+ * const okResult = Result.Ok<number, string>(42);
+ *
+ * // Creating an error result
+ * const errResult = Result.Err<number, string>("something went wrong");
+ *
+ * // Using map to transform the success value
+ * const doubled = okResult.map(x => x * 2);
+ *
+ * // Using match to handle both cases
+ * const output = result.match(
+ *   value => `Success: ${value}`,
+ *   error => `Error: ${error}`
+ * );
+ * ```
+ *
+ * @remarks
+ * This class provides a way to handle operations that might fail, making error handling more explicit
+ * and type-safe. It includes methods for transforming, combining, and extracting values in a safe manner.
+ *
+ * The Result type is immutable - all transformation methods return a new Result instance.
+ */
+declare class Result<T, E = Error> {
+    readonly value?: T | undefined;
+    readonly error?: E | undefined;
+    private constructor();
+    /**
+     * Creates a new Result instance with a success value
+     * @template T The type of the success value
+     * @template E The type of the error value
+     * @param value The success value
+     * @returns A new Result instance containing the success value
+     */
+    static Ok<T, E>(value: T): Result<T, E>;
+    /**
+     * Creates a new Result instance with an error value
+     * @template T The type of the success value
+     * @template E The type of the error value
+     * @param error The error value
+     * @returns A new Result instance containing the error value
+     */
+    static Err<T, E>(error: E): Result<T, E>;
+    /**
+     * Creates a new Result instance with an Error created from a string message
+     * @template T The type of the success value
+     * @param errorMessage The error message string
+     * @returns A new Result instance containing an Error with the given message
+     */
+    static ErrFromStr<T>(errorMessage: string): Result<T>;
+    /**
+     * Maps the success value to a new value using the provided function
+     * @template U The type of the new success value
+     * @param fn The mapping function
+     * @returns A new Result with the mapped success value or the original error
+     */
+    map<U>(fn: (value: T) => U): Result<U, E>;
+    /**
+     * Maps the error value to a new error using the provided function
+     * @template F The type of the new error value
+     * @param fn The mapping function
+     * @returns A new Result with the mapped error value or the original success value
+     */
+    mapErr<F>(fn: (error: E) => F): Result<T, F>;
+    /**
+     * Chains a computation that returns a Result
+     * @template U The type of the new success value
+     * @param fn The function to chain
+     * @returns The result of the chained function or the original error
+     */
+    andThen<U>(fn: (value: T) => Result<U, E>): Result<U, E>;
+    /**
+     * Applies one of two functions depending on whether the Result is Ok or Err
+     * @template U The type of the return value
+     * @param ok The function to apply to the success value
+     * @param err The function to apply to the error value
+     * @returns The result of applying the appropriate function
+     */
+    match<U>(ok: (value: T) => U, err: (error: E) => U): U;
+    /**
+     * Checks if the Result contains a success value
+     * @returns true if the Result contains a success value, false otherwise
+     */
+    isOk(): boolean;
+    /**
+     * Checks if the Result contains an error value
+     * @returns true if the Result contains an error value, false otherwise
+     */
+    isErr(): boolean;
+    /**
+     * Extracts the success value from the Result
+     * @throws Error if the Result contains an error value
+     * @returns The success value
+     */
+    unwrap(): T;
+    /**
+     * Returns the success value or a default value if the Result contains an error
+     * @param defaultValue The value to return if the Result contains an error
+     * @returns The success value or the default value
+     */
+    unwrapOr(defaultValue: T): T;
+    /**
+     * Extracts the error value from the Result
+     * @throws Error if the Result contains a success value
+     * @returns The error value
+     */
+    unwrapErr(): E;
+    /**
+     * Converts the Result to a string representation
+     * @returns A string representation of the Result
+     */
+    toString(): string;
+}
+
+/**
+ * Represents progress towards a goal with optional status message.
+ *
+ * @remarks
+ * Used to track progress of operations without depending on DOM ProgressEvent.
+ * Progress is indeterminate when total is 0.
+ */
+interface Progress {
+    /** Current progress value */
+    current: number;
+    /** Total value representing 100% completion. 0 indicates indeterminate progress */
+    total: number;
+    /** Optional status message describing current progress state */
+    message?: string;
+}
+/**
+ * Creates and updated progress object by adding the given increment, and updating the message.
+ * @param progress - The progress object to update.
+ * @param increment - The amount to increment the progress by. Default is 1.
+ * @param message - The message to set on the progress object. Default is undefined.
+ * @returns The new progress object.
+ */
+declare function incrementProgress(progress: Progress, message?: string, increment?: number): Progress;
+/**
+ * Sums the given progresses into a single progress object.
+ * @param progresses - A collection of progresses.
+ * @returns A new progress which is the sum of all the given progresses.
+ */
+declare function composeProgress(progresses: Progress[]): Progress;
+/**
+ * Represents a result that can either be a success or a failure, with an associated progress.
+ * Until result is defined, the operation is still pending.
+ */
+interface ProgressiveResult<T, E = Error> {
+    result?: Result<T, E>;
+    progress: Progress;
+}
+/**
+ * Composes multiple progressive results into a single progressive result containing an array of results.
+ *
+ * @remarks
+ * This function handles both array and single item progressive results, combining them into a unified result
+ * while maintaining progress information. It can optionally filter and order results based on expected IDs.
+ *
+ * @typeparam T - Type of the result items, must contain an 'id' string property
+ *
+ * @param progressiveResults - Array of progressive results to compose
+ * @param expectedIds - Optional array of IDs to filter and order the results
+ *
+ * @returns A ProgressiveResult containing an array of results (or undefined values)
+ * where:
+ * - If any input result is an error, returns an error result
+ * - If expectedIds is provided, returns results ordered by the expected IDs
+ * - If expectedIds is provided and not all IDs are found when progress is complete, returns an error
+ * - Otherwise returns all results combined into an array
+ */
+declare function composeProgressiveResult<T extends {
+    id: string;
+}>(progressiveResults: ProgressiveResult<T[] | T | undefined | null>[], expectedIds?: string[]): ProgressiveResult<(T | undefined | null)[]>;
+
+/**
+ * Regular expression for validating email addresses.
+ *
+ * @remarks
+ * This regex validates email addresses following RFC 5322 standards.
+ * It checks for:
+ * - Local part (before @) allowing letters, numbers, and special characters
+ * - Domain part (after @) requiring at least one dot and valid characters
+ * - Case-insensitive matching
+ *
+ * @example
+ * ```typescript
+ * EMAIL.test('user@example.com')  // Returns true
+ * EMAIL.test('invalid.email')     // Returns false
+ * ```
+ */
+declare const EMAIL: RegExp;
+
+/**
+ * Compares two maps for deep equality by checking all key/value pairs.
+ *
+ * @param map1 - The first map to compare.
+ * @param map2 - The second map to compare.
+ * @returns True if both maps have the same entries; false otherwise.
+ *
+ * @example
+ * ```typescript
+ * const mapA = new Map([["key1", { a: 1 }]]);
+ * const mapB = new Map([["key1", { a: 1 }]]);
+ * console.log(isMapDeepEqual(mapA, mapB)); // true
+ * ```
+ */
+declare function isMapDeepEqual<K, V>(map1: Map<K, V>, map2: Map<K, V>): boolean;
+
+export { type AnimatableBoolean, type AnimatableColor, type AnimatableEuler, type AnimatableNumber, type AnimatablePubInfo, type AnimatableString, type AnimatableValue, type AnimatableVector2, type AnimatableVector3, EMAIL, type Player, type PlayerActions, PlayerContext, type PlayerData, PlayerSlice, type PlayerStore, type PlayerStoreGetter, type PlayerStoreSetter, type Progress, type ProgressiveResult, type RawBoolean, type RawColor, type RawEuler, type RawHSL, type RawNumber, type RawRGB, type RawString, type RawTime, type RawValue, type RawVector2, type RawVector3, Result, type StoreSubscribeWithSelector, type Write, alpha, altColor, angularDistance, closestFrame, composeProgress, composeProgressiveResult, downloadBlob, downloadJSONFile, eulerToRotationMatrix, getDegenerateHexagonPath, getHexagonPath, getId, getLookup, getNamespace, hexToRgbArray, hexToRgba, hslToRgba, incrementProgress, instanceOfRawBoolean, instanceOfRawColor, instanceOfRawEuler, instanceOfRawHSL, instanceOfRawNumber, instanceOfRawRGB, instanceOfRawString, instanceOfRawVector2, instanceOfRawVector3, isMapDeepEqual, isRawObject, log, newPlayer, now, numberToDurationString, overlappingSegments, pairwise, parseJSONFileEvent, parseToMapped, pause, play, pointsToPath, rawHSLToHex, rawRGBToHex, reset, rgbToRgba, rotationMatrixToAngle, seek, setBounds, setDuration, setViewport, stringifyMapped, toDegrees, toRadians, update, useDeep, useDeepSelector, useLazy, useMediaQuery, usePlayerStore };