@semio/utils 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -1,13 +1,12 @@
 import * as react from 'react';
+import { Context, ComponentType, ReactNode } from 'react';
 import * as zustand from 'zustand';
+import { OrthographicCamera, PerspectiveCamera } from 'three';
 
 /**
  * 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;
 
@@ -56,38 +55,56 @@ declare function getId(lookup: string): string;
  * Time representation in milliseconds.
  */
 type RawTime = number;
+declare enum PlayerDirection {
+    Reverse = "reverse",
+    Forward = "forward"
+}
 /**
  * A timer implementation for managing animation playback.
  *
- * The timer operates on a normalized time range of [0, 1], where:
+ * The timer operates in milliseconds, where:
  * - 0 represents the start of the animation
- * - 1 represents the end of the animation
+ * - duration (in ms) represents the end of the animation
+ *
+ * Fields prefixed with `_` (e.g. `_previousTime`, `_currentDirection`,
+ * `_bounced`, `_enteredBounds`) are internal bookkeeping for the
+ * `updated()` tick function and should not be read by external
+ * consumers. They're on the public type because immutable spread-and-
+ * return pattern means every `withX` helper must roundtrip them.
  *
  * @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
+ * @property _previousTime - INTERNAL. Last update time in ms.
+ * @property _currentTime - INTERNAL. Current update time in ms.
+ * @property stamp - Current time position in milliseconds
+ * @property speed - Playback speed multiplier (always positive)
+ * @property direction - Initial playback direction (PlayerDirection.Forward or PlayerDirection.Reverse)
+ * @property _currentDirection - INTERNAL. Actual movement direction during bouncing.
+ * @property _bounced - INTERNAL. Whether the player has already bounced this run.
+ * @property _enteredBounds - INTERNAL. Whether the player has crossed into bounds at least once.
+ * @property bounds - Constrains playback to a [start, end] range in milliseconds
+ * @property bounce - Whether to reverse direction when reaching bounds
+ * @property looping - Whether to continue playing after reaching bounds
+ * @property duration - Total animation duration in milliseconds (used for playback stepping)
  */
 interface Player {
     running: boolean;
     _previousTime: RawTime;
     _currentTime: RawTime;
     stamp: number;
-    timescale: number;
+    speed: number;
+    direction: PlayerDirection;
+    _currentDirection: PlayerDirection;
+    _bounced: boolean;
+    _enteredBounds: boolean;
     bounds: [number, number];
-    playback: "loop" | "bounce" | "once";
-    viewport: [number, number];
+    bounce: boolean;
+    looping: boolean;
     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]
+ * @param stamp - the new timestamp in milliseconds
  * @returns the updated timer
  */
 declare function reset(player: Player, stamp?: number): Player;
@@ -102,38 +119,34 @@ declare function now(): RawTime;
  * @param timer - the timer to be updated
  * @returns the updated timer
  */
-declare function update(player: Player, coldStart: boolean): Player;
+declare function updated(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]
+ * @param bounds - the new bounds in milliseconds [start, end]
  * @returns the updated player
  */
-declare function setBounds(player: Player, bounds: [number, number]): Player;
+declare function withBounds(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.
+ * Creates a copy of the provided timer, but updated with speed and direction.
  * @param timer - the timer to be updated
- * @param speed - the speed of playback desired (defaults to 1)
+ * @param speed - the speed of playback desired (defaults to current speed)
+ * @param direction - the direction of playback desired (defaults to current direction)
  * @returns the updated timer
  */
-declare function play(player: Player, speed?: number): Player;
+declare function play(player: Player, speed?: number, direction?: PlayerDirection.Forward | PlayerDirection.Reverse): Player;
 /**
- * Creates a copy of the provided timer, but updated with a timescale of 0 (paused)
+ * Creates a copy of the provided timer, but 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.
+ * Returns the provided player, reset to the given stamp.
+ * Pure stamp-set; viewport-follow is handled separately by the
+ * viewport-follow subscription.
  * @param player - the player to be updated
- * @param stamp - the new stamp to center the viewport around
+ * @param stamp - the new stamp
  * @returns the updated player
  */
 declare function seek(player: Player, stamp: number): Player;
@@ -143,21 +156,55 @@ declare function seek(player: Player, stamp: number): Player;
  * @param duration - the new duration
  * @returns the updated player
  */
-declare function setDuration(player: Player, duration: number): Player;
+declare function withDuration(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
+ * - Zero stamp position (0ms)
+ * - Normal speed (1x)
+ * - Forward direction
+ * - Default bounds [0, 5000] ms
+ * - Looping enabled, bounce disabled
+ * - 5000ms duration
  */
 declare function newPlayer(): Player;
+/**
+ * Sets the playback speed without affecting direction.
+ * @param player - the player to be updated
+ * @param speed - the new speed (must be positive)
+ * @returns the updated player
+ */
+declare function withSpeed(player: Player, speed: number): Player;
+/**
+ * Sets the playback direction without affecting speed.
+ * @param player - the player to be updated
+ * @param direction - the new direction
+ * @returns the updated player
+ */
+declare function withDirection(player: Player, direction: PlayerDirection.Forward | PlayerDirection.Reverse): Player;
+/**
+ * Reverses the current playback direction.
+ * @param player - the player to be updated
+ * @returns the updated player
+ */
+declare function reversed(player: Player): Player;
+/**
+ * Sets the bounce behavior for the player.
+ * @param player - the player to be updated
+ * @param bounce - whether to bounce at boundaries
+ * @returns the updated player
+ */
+declare function withBounce(player: Player, bounce: boolean): Player;
+/**
+ * Sets the looping behavior for the player.
+ * @param player - the player to be updated
+ * @param looping - whether to loop at boundaries
+ * @returns the updated player
+ */
+declare function withLooping(player: Player, looping: boolean): Player;
 
 /**
  * Core data structure for player state
@@ -172,12 +219,16 @@ interface PlayerData {
 interface PlayerActions {
     /** Updates the total duration of the animation */
     updateDuration: (duration: number) => void;
-    /** Updates the playback speed multiplier */
-    updateTimescale: (speed: number) => void;
+    /** Updates the playback speed */
+    updateSpeed: (speed: number) => void;
+    /** Updates the playback direction */
+    updateDirection: (direction: PlayerDirection) => void;
+    /** Reverses the current playback direction */
+    reverseDirection: () => void;
     /** Resets the player to initial state or specified time */
     resetPlayer: (time?: number) => void;
     /** Plays the animation */
-    playPlayer: (speed?: number) => void;
+    playPlayer: (speed?: number, direction?: PlayerDirection) => void;
     /** Pauses the animation */
     pausePlayer: () => void;
     /** Updates the timer */
@@ -186,28 +237,27 @@ interface PlayerActions {
     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;
+    /** Update the player bounce setting */
+    updateBounce: (bounce: boolean) => void;
+    /** Update the player looping setting */
+    updateLooping: (looping: boolean) => void;
 }
-type PlayerStoreSetter = (partial: (PlayerData & PlayerActions) | Partial<PlayerData & PlayerActions> | ((state: PlayerData & PlayerActions) => (PlayerData & PlayerActions) | Partial<PlayerData & PlayerActions>), replace?: false | undefined) => void;
+type PlayerStoreSetter = (partial: (PlayerData & PlayerActions) | Partial<PlayerData & PlayerActions> | ((state: PlayerData & PlayerActions) => (PlayerData & PlayerActions) | Partial<PlayerData & PlayerActions>), replace?: false) => void;
 type PlayerStoreGetter = () => PlayerData & PlayerActions;
 declare const PlayerSlice: (set: PlayerStoreSetter) => {
     player: Player;
     updateDuration: (duration: number) => void;
-    updateTimescale: (speed: number) => void;
+    updateSpeed: (speed: number) => void;
+    updateDirection: (direction: PlayerDirection) => void;
+    reverseDirection: () => void;
     resetPlayer: (time?: number) => void;
-    playPlayer: (speed?: number) => void;
+    playPlayer: (speed?: number, direction?: PlayerDirection) => 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;
+    updateBounce: (bounce: boolean) => void;
+    updateLooping: (looping: boolean) => void;
 };
 declare const usePlayerStore: zustand.UseBoundStore<Omit<zustand.StoreApi<PlayerData & PlayerActions>, "subscribe"> & {
     subscribe: {
@@ -242,9 +292,9 @@ interface RawVector2 {
     y: number;
 }
 interface RawEuler {
-    x: number;
+    r: number;
+    p: number;
     y: number;
-    z: number;
 }
 interface RawRGB {
     r: number;
@@ -264,7 +314,33 @@ interface AnimatablePubInfo {
     output: string;
     color?: string;
 }
-type AnimatableValue = AnimatableBoolean | AnimatableNumber | AnimatableString | AnimatableVector3 | AnimatableVector2 | AnimatableEuler | AnimatableColor;
+declare enum AnimatableGroupType {
+    Vector2 = "vector2",
+    Vector3 = "vector3",
+    Euler = "euler",
+    RGB = "rgb",
+    HSL = "hsl",
+    Group = "group",
+    /** Entity-level group (spans all instances for one entity/namespace). */
+    Entity = "entity",
+    /** Instance-level group (one animation instance within an entity). */
+    Instance = "instance"
+}
+interface AnimatableGroupInfo {
+    /** Stable group UUID used to associate related simple animatables. */
+    id: string;
+    /** Composite group type for editor grouping semantics. */
+    type: AnimatableGroupType;
+    /** Optional axis label (x/y/z or r/p/y) for disambiguation. */
+    axis?: string;
+    /** Optional ordering hint within the group. */
+    order?: number;
+}
+type AnimatableValue = AnimatableBoolean | AnimatableNumber | AnimatableString;
+/**
+ * @deprecated Complex animatables should be flattened into scalar values.
+ */
+type DeprecatedComplexAnimatableValue = AnimatableVector3 | AnimatableVector2 | AnimatableEuler | AnimatableColor;
 /**
  * A specification for an animated numerical value
  *
@@ -284,6 +360,7 @@ interface AnimatableBoolean {
         frequency?: number;
     };
     pub?: AnimatablePubInfo;
+    group?: AnimatableGroupInfo;
 }
 /**
  * A specification for an animated numerical value
@@ -307,6 +384,7 @@ interface AnimatableNumber {
         velocity?: number;
     };
     pub?: AnimatablePubInfo;
+    group?: AnimatableGroupInfo;
 }
 /**
  * A specification for an animated string value
@@ -327,6 +405,7 @@ interface AnimatableString {
         length?: number;
     };
     pub?: AnimatablePubInfo;
+    group?: AnimatableGroupInfo;
 }
 /**
  * A specification for an animated 3-vector value
@@ -425,6 +504,15 @@ 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;
+/**
+ * Logs a console warning when a feature callback receives a value of an unexpected type.
+ * Use this in `useFeatures` callbacks to surface data-flow issues early.
+ *
+ * @param feature  - The feature key (e.g. "translation.x", "jointValue").
+ * @param expected - Human-readable description of the expected type(s) (e.g. "number", "number | string").
+ * @param value    - The actual value received.
+ */
+declare function warnUnexpectedFeatureValue(feature: string, expected: string, value: unknown): void;
 declare function isRawObject(value: any): boolean;
 
 /**
@@ -506,14 +594,13 @@ declare function getHexagonPath(x: number, y: number, size: number, height: numb
 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.
+ * Snaps a timestamp in milliseconds to the nearest frame boundary.
  *
- * @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.
+ * @param stampMs - The timestamp in milliseconds.
+ * @param framerate - The framerate (frames per second).
+ * @returns The timestamp snapped to the nearest frame boundary in milliseconds.
  */
-declare function closestFrame(completion: number, count: number): number;
+declare function closestFrame(stampMs: number, framerate: number): number;
 
 /**
  * Converts an angle from radians to degrees.
@@ -604,6 +691,44 @@ 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;
+declare function randomHexString(constrainLuminosity?: number, constrainSaturation?: number): string;
+/**
+ * Compute normalized chroma (0..1) from an RGB tuple.
+ *  - 0 means perfectly gray
+ *  - 1 means maximum colorfulness
+ */
+declare function rgbChroma([r, g, b]: [number, number, number]): number;
+/**
+ * Compute lightness (0..1) from an RGB tuple using (max+min)/2.
+ *  - 0 is black
+ *  - 1 is white
+ */
+declare function rgbLightness([r, g, b]: [number, number, number]): number;
+/**
+ * Compute chroma from any CSS color string.
+ */
+declare function colorChroma(color: string): number;
+/**
+ * Compute lightness from any CSS color string.
+ */
+declare function colorLightness(color: string): number;
+interface BlendHeuristicOptions {
+    chromaCutoff?: number;
+    minLightness?: number;
+    maxLightness?: number;
+}
+/**
+ * Decide whether mix-blend-difference is likely to improve contrast for a given color.
+ * Disables blending for near-neutral, mid-lightness colors (e.g., #737373),
+ * where difference blending tends to reduce contrast.
+ *
+ * Returns false for undefined/unparseable colors as a safe default.
+ */
+declare function shouldUseBlendForLabelColor(color?: string | null, opts?: BlendHeuristicOptions): boolean;
+/**
+ * Convenience helper to detect a near-neutral, mid-lightness color.
+ */
+declare function isNearNeutralMid(color: string, opts?: BlendHeuristicOptions): boolean;
 
 /**
  * Creates a memoized selector function that only updates when the selected value
@@ -780,6 +905,71 @@ declare function rotationMatrixToAngle(R: number[][]): number;
  * ```
  */
 declare function angularDistance(euler1: [number, number, number], euler2: [number, number, number]): number;
+/**
+ * Converts Euler angles (ZYX order) to a quaternion.
+ *
+ * @param euler - Array of three numbers representing rotation angles in radians [z, y, x]
+ * @returns A quaternion as [w, x, y, z]
+ */
+declare function eulerToQuaternion(euler: [number, number, number]): [number, number, number, number];
+/**
+ * Converts a quaternion to Euler angles (ZYX order).
+ *
+ * @param q - A quaternion as [w, x, y, z]
+ * @returns Euler angles as [z, y, x] in radians
+ */
+declare function quaternionToEuler(q: [number, number, number, number]): [number, number, number];
+/**
+ * Multiplies two quaternions.
+ *
+ * @param q1 - First quaternion as [w, x, y, z]
+ * @param q2 - Second quaternion as [w, x, y, z]
+ * @returns The product quaternion as [w, x, y, z]
+ */
+declare function quaternionMultiply(q1: [number, number, number, number], q2: [number, number, number, number]): [number, number, number, number];
+/**
+ * Calculates the conjugate of a quaternion (inverse for unit quaternions).
+ *
+ * @param q - A quaternion as [w, x, y, z]
+ * @returns The conjugate quaternion as [w, -x, -y, -z]
+ */
+declare function quaternionConjugate(q: [number, number, number, number]): [number, number, number, number];
+/**
+ * Performs spherical linear interpolation between two quaternions.
+ *
+ * @param q1 - First quaternion as [w, x, y, z]
+ * @param q2 - Second quaternion as [w, x, y, z]
+ * @param t - Interpolation factor. Values between 0-1 interpolate, outside this range extrapolate.
+ *           t=0 returns q1, t=1 returns q2, t<0 extrapolates backwards, t>1 extrapolates forwards.
+ * @returns The interpolated/extrapolated quaternion as [w, x, y, z]
+ */
+declare function quaternionSlerp(q1: [number, number, number, number], q2: [number, number, number, number], t: number): [number, number, number, number];
+/**
+ * Performs spherical linear interpolation between two Euler angles.
+ *
+ * @param euler1 - First Euler angle [z, y, x] in radians
+ * @param euler2 - Second Euler angle [z, y, x] in radians
+ * @param t - Interpolation factor. Values between 0-1 interpolate, outside this range extrapolate.
+ *           t=0 returns euler1, t=1 returns euler2, t<0 extrapolates backwards, t>1 extrapolates forwards.
+ * @returns The interpolated/extrapolated Euler angle [z, y, x] in radians
+ *
+ * @example
+ * ```typescript
+ * const from = [0, 0, 0];
+ * const to = [Math.PI, Math.PI/2, 0];
+ * const halfway = eulerSlerp(from, to, 0.5);        // 50% interpolation
+ * const extrapolated = eulerSlerp(from, to, 1.5);   // 150% - extrapolates beyond 'to'
+ * const backwards = eulerSlerp(from, to, -0.5);     // Extrapolates backwards from 'from'
+ * ```
+ */
+declare function eulerSlerp(euler1: [number, number, number], euler2: [number, number, number], t: number): [number, number, number];
+/**
+ * Calculates the euler angle that represents the rotation matrix from one euler angle to another.
+ * @param euler1 - The first euler angle [z, y, x] in radians (source orientation)
+ * @param euler2 - The second euler angle [z, y, x] in radians (destination orientation)
+ * @return The euler angle representing the rotation from euler1 to euler2 [z, y, x] in radians
+ */
+declare function eulerRotationBetween(euler1: [number, number, number], euler2: [number, number, number]): [number, number, number];
 
 /**
  * Merges overlapping segments in an array of intervals.
@@ -1001,20 +1191,243 @@ declare function composeProgressiveResult<T extends {
  */
 declare const EMAIL: RegExp;
 
+/**
+ * Filter function type for map comparison
+ */
+type MapFilterFn<K, V> = (key: K, value: V) => boolean;
+/**
+ * Options for map deep equality comparison
+ */
+interface MapDeepEqualOptions<K, V> {
+    /** Filter function to determine which entries to compare */
+    filter?: MapFilterFn<K, V>;
+}
 /**
  * Compares two maps for deep equality by checking all key/value pairs.
+ * Optionally filters which entries to consider in the comparison.
  *
  * @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.
+ * @param options - Optional configuration for the comparison
+ * @returns True if both maps have the same entries (after filtering); false otherwise.
  *
  * @example
  * ```typescript
- * const mapA = new Map([["key1", { a: 1 }]]);
- * const mapB = new Map([["key1", { a: 1 }]]);
+ * const mapA = new Map([["key1", { a: 1 }], ["key2", { b: 2 }]]);
+ * const mapB = new Map([["key1", { a: 1 }], ["key2", { b: 2 }]]);
  * console.log(isMapDeepEqual(mapA, mapB)); // true
+ *
+ * // With filter - only compare entries where key starts with "key1"
+ * const mapC = new Map([["key1", { a: 1 }], ["key2", { b: 3 }]]);
+ * const mapD = new Map([["key1", { a: 1 }], ["key2", { b: 2 }]]);
+ * console.log(isMapDeepEqual(mapC, mapD, {
+ *   filter: (key) => key.toString().startsWith("key1")
+ * })); // true (only key1 is compared)
+ *
+ * // Filter by value properties
+ * const mapE = new Map([["a", { priority: 1, data: "x" }], ["b", { priority: 2, data: "y" }]]);
+ * const mapF = new Map([["a", { priority: 1, data: "z" }], ["b", { priority: 2, data: "y" }]]);
+ * console.log(isMapDeepEqual(mapE, mapF, {
+ *   filter: (key, value) => value.priority === 2
+ * })); // true (only compares entries with priority: 2)
  * ```
  */
-declare function isMapDeepEqual<K, V>(map1: Map<K, V>, map2: Map<K, V>): boolean;
+declare function isMapDeepEqual<K, V>(map1: Map<K, V>, map2: Map<K, V>, options?: MapDeepEqualOptions<K, V>): boolean;
+
+declare function storedEulerXYZtoRPY(robotData: any): any;
+
+/**
+ * Configuration for a context provider
+ */
+interface ContextConfig<T> {
+    /** The React context */
+    context: Context<T | null>;
+    /** Default store/value to provide when context is missing */
+    defaultValue: T;
+    /** Name for error messages */
+    name: string;
+}
+/**
+ * Props for components that can optionally provide their own context
+ */
+interface OptionalContextProps {
+    /** Whether to skip providing context (assume parent provides it) */
+    skipContext?: boolean;
+}
+/**
+ * Creates a hook that requires context to be present
+ */
+declare function createContextHook<T>(context: Context<T | null>, name: string): () => T;
+/**
+ * Creates a component that provides context if not already present
+ */
+declare function withOptionalContext<P extends object>(CoreComponent: ComponentType<P>, contextConfig: ContextConfig<any>): ComponentType<P & OptionalContextProps>;
+/**
+ * Composes multiple context providers into a single component
+ */
+declare function composeContexts(contexts: {
+    Provider: ComponentType<{
+        children: ReactNode;
+    }>;
+    condition?: () => boolean;
+}[]): ComponentType<{
+    children: ReactNode;
+}>;
+/**
+ * Creates a provider component for a context
+ */
+declare function createContextProvider<T>(context: Context<T | null>, defaultValue: T): ComponentType<{
+    children: ReactNode;
+    value?: T;
+}>;
+/**
+ * Utility type for extracting context value type
+ */
+type ContextValue<T> = T extends Context<infer U> ? U : never;
+/**
+ * Configuration for creating a complete context solution
+ */
+interface ContextSolutionConfig<T> {
+    /** The React context */
+    context: Context<T | null>;
+    /** Default store/value */
+    defaultValue: T;
+    /** Name for debugging and errors */
+    name: string;
+}
+/**
+ * Creates a complete context solution with consistent patterns
+ */
+declare function createContextSolution<T>(config: ContextSolutionConfig<T>): {
+    useContext: () => T;
+    Provider: ComponentType<{
+        children: ReactNode;
+        value?: T | undefined;
+    }>;
+    withOptional: <P extends object>(Component: ComponentType<P>) => ComponentType<P & OptionalContextProps>;
+    context: Context<T | null>;
+};
+/**
+ * Standard interface for components that might need tooltip context
+ */
+interface WithTooltipContextProps {
+    /** Skip providing tooltip context (assume parent provides) */
+    skipTooltipContext?: boolean;
+}
+/**
+ * Utility for checking if context exists without throwing
+ */
+declare function useOptionalContext<T>(context: Context<T | null>): T | null;
+/**
+ * Creates a context checker function
+ */
+declare function createContextChecker<T>(context: Context<T | null>): () => boolean;
+
+interface ValuesData {
+    values: Map<string, RawValue | undefined>;
+    velocities: Map<string, RawValue | undefined>;
+}
+interface ValuesActions {
+    updateValues: (values: Map<string, RawValue | undefined>) => void;
+    updateVelocities: (velocities: Map<string, RawValue | undefined>) => void;
+    setTrackValue: (trackKey: string, value: RawValue) => void;
+    /** Replace both maps at once (used by derived orchestrator). */
+    replaceAll: (values: Map<string, RawValue | undefined>, velocities: Map<string, RawValue | undefined>) => void;
+}
+type ValuesStore = ValuesData & ValuesActions;
+/**
+ * Merge `updates` into `base`, returning a new Map.
+ * Keys mapped to `undefined` in `updates` are deleted from the result.
+ */
+declare function mergeValueMaps(base: Map<string, RawValue | undefined>, updates: Map<string, RawValue | undefined>): Map<string, RawValue | undefined>;
+/**
+ * Standalone Zustand store for high-frequency transient values and velocities.
+ *
+ * **Single source of truth for runtime animatable values.** Scene rendering,
+ * animation editor controls, and device commanders all read from this store.
+ * The studio/animation/scene stores own *structure* (animatables, tracks,
+ * world, namespaces); this store owns *current numeric state*.
+ *
+ * ## Why a separate store
+ * During playback the derived orchestrator writes new interpolated values at
+ * ~40 Hz. A dedicated store with `subscribeWithSelector` means only the
+ * consumers that need per-tick updates re-evaluate; subscribers of the other
+ * stores aren't woken on every tick. `mergeValueMaps` additionally returns
+ * the same Map reference when no values changed, so redundant writes don't
+ * fan out to subscribers.
+ *
+ * ## Key formats
+ * Two key formats coexist in the maps:
+ * - **trackKey** (`namespaceId/instanceId/trackId`) — written by the derived
+ *   orchestrator during playback. Only meaningful to the animation system.
+ * - **dotKey** (`namespaceId.animatableId`) — used by scene rendering hooks
+ *   and device command subscriptions.
+ *
+ * The values-bridge subscription (in `apps/studio`) converts trackKey entries
+ * into dotKey entries during playback so downstream consumers don't need to
+ * know about the animation layer.
+ *
+ * ## Readers
+ * - `useFeatures`, `useAnimatableSubscription` (`@semio/scene`, `@semio/vizij`)
+ *   — scene rendering hooks subscribe to dotKey entries.
+ * - `AnimatableControl`, `AnimatableEditor` (`@semio/animation`) — animation
+ *   editor controls subscribe to trackKey or dotKey entries.
+ * - `device-subscriptions.ts` (studio) — outbound device commands and
+ *   trajectories read dotKey entries.
+ *
+ * ## Writers
+ * - `setValueDirectAction` (studio) — direct user edits.
+ * - `device-subscriptions.ts` `onData` handler (studio) — incoming device
+ *   feedback writes feedback-namespace dotKeys.
+ * - `namespace-subscription.ts` (studio) — writes root-transform dotKeys for
+ *   target/feedback/sim instances when entity config changes.
+ * - `init-derived-orchestrator.ts` (`@semio/animation`) — writes trackKey
+ *   values during playback.
+ * - `values-bridge-subscription.ts` (studio) — writes converted trackKey →
+ *   dotKey entries.
+ *
+ * ## Gizmo writes (override seam)
+ * Scene primitives that write values back (e.g. joint gizmos) go through
+ * `SceneValueWriterContext` from `@semio/scene` — they call
+ * `useSceneValueWriter().setValue(id, namespace, value)` rather than touching
+ * this store directly. The default writer hits `updateValues` here. Studio
+ * overrides the writer to route through its animation-aware `setValueAction`,
+ * which produces a keypoint update or a direct write depending on the entity's
+ * controlMode and selected animation instance. See `packages/scene/README.md`.
+ *
+ * ## Lifecycle
+ * On project load, studio's `loadFromFullContext` calls `replaceAll(new Map(),
+ * new Map())` before applying the new project, so post-load subscribers
+ * (`namespace-subscription`, derived orchestrator) repopulate from a clean
+ * slate. Outside of load the store accumulates dotKey entries as namespaces
+ * and animatables are added; entries for removed animatables can become stale
+ * until cleared.
+ */
+declare const useValuesStore: zustand.UseBoundStore<Omit<zustand.StoreApi<ValuesStore>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: ValuesStore, previousSelectedState: ValuesStore) => void): () => void;
+        <U>(selector: (state: ValuesStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}>;
+
+/**
+ * Type guard for Three.js OrthographicCamera.
+ *
+ * Accepts a broad parameter type to work with both Three.js Camera and
+ * R3F's Camera union (which may resolve from a different @types/three
+ * declaration in monorepo setups).
+ */
+declare function isOrthographicCamera(camera: object): camera is OrthographicCamera;
+/**
+ * Type guard for Three.js PerspectiveCamera.
+ *
+ * Accepts a broad parameter type to work with both Three.js Camera and
+ * R3F's Camera union (which may resolve from a different @types/three
+ * declaration in monorepo setups).
+ */
+declare function isPerspectiveCamera(camera: object): camera is PerspectiveCamera;
 
-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 };
+export { type AnimatableBoolean, type AnimatableColor, type AnimatableEuler, type AnimatableGroupInfo, AnimatableGroupType, type AnimatableNumber, type AnimatablePubInfo, type AnimatableString, type AnimatableValue, type AnimatableVector2, type AnimatableVector3, type BlendHeuristicOptions, type ContextConfig, type ContextSolutionConfig, type ContextValue, type DeprecatedComplexAnimatableValue, EMAIL, type MapDeepEqualOptions, type MapFilterFn, type OptionalContextProps, type Player, type PlayerActions, PlayerContext, type PlayerData, PlayerDirection, 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 ValuesActions, type ValuesData, type ValuesStore, type WithTooltipContextProps, type Write, alpha, altColor, angularDistance, closestFrame, colorChroma, colorLightness, composeContexts, composeProgress, composeProgressiveResult, createContextChecker, createContextHook, createContextProvider, createContextSolution, downloadBlob, downloadJSONFile, eulerRotationBetween, eulerSlerp, eulerToQuaternion, eulerToRotationMatrix, getDegenerateHexagonPath, getHexagonPath, getId, getLookup, getNamespace, hexToRgbArray, hexToRgba, hslToRgba, incrementProgress, instanceOfRawBoolean, instanceOfRawColor, instanceOfRawEuler, instanceOfRawHSL, instanceOfRawNumber, instanceOfRawRGB, instanceOfRawString, instanceOfRawVector2, instanceOfRawVector3, isMapDeepEqual, isNearNeutralMid, isOrthographicCamera, isPerspectiveCamera, isRawObject, log, mergeValueMaps, newPlayer, now, numberToDurationString, overlappingSegments, pairwise, parseJSONFileEvent, parseToMapped, pause, play, pointsToPath, quaternionConjugate, quaternionMultiply, quaternionSlerp, quaternionToEuler, randomHexString, rawHSLToHex, rawRGBToHex, reset, reversed, rgbChroma, rgbLightness, rgbToRgba, rotationMatrixToAngle, seek, shouldUseBlendForLabelColor, storedEulerXYZtoRPY, stringifyMapped, toDegrees, toRadians, updated, useDeep, useDeepSelector, useLazy, useMediaQuery, useOptionalContext, usePlayerStore, useValuesStore, warnUnexpectedFeatureValue, withBounce, withBounds, withDirection, withDuration, withLooping, withOptionalContext, withSpeed };