@semio/utils 0.0.0 → 0.1.0

package/dist/index.js

@@ -30,18 +30,30 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AnimatableGroupType: () => AnimatableGroupType,
   EMAIL: () => EMAIL,
   PlayerContext: () => PlayerContext,
+  PlayerDirection: () => PlayerDirection,
   PlayerSlice: () => PlayerSlice,
   Result: () => Result,
   alpha: () => alpha,
   altColor: () => altColor,
   angularDistance: () => angularDistance,
   closestFrame: () => closestFrame,
+  colorChroma: () => colorChroma,
+  colorLightness: () => colorLightness,
+  composeContexts: () => composeContexts,
   composeProgress: () => composeProgress,
   composeProgressiveResult: () => composeProgressiveResult,
+  createContextChecker: () => createContextChecker,
+  createContextHook: () => createContextHook,
+  createContextProvider: () => createContextProvider,
+  createContextSolution: () => createContextSolution,
   downloadBlob: () => downloadBlob,
   downloadJSONFile: () => downloadJSONFile,
+  eulerRotationBetween: () => eulerRotationBetween,
+  eulerSlerp: () => eulerSlerp,
+  eulerToQuaternion: () => eulerToQuaternion,
   eulerToRotationMatrix: () => eulerToRotationMatrix,
   getDegenerateHexagonPath: () => getDegenerateHexagonPath,
   getHexagonPath: () => getHexagonPath,
@@ -62,8 +74,12 @@ __export(index_exports, {
   instanceOfRawVector2: () => instanceOfRawVector2,
   instanceOfRawVector3: () => instanceOfRawVector3,
   isMapDeepEqual: () => isMapDeepEqual,
+  isNearNeutralMid: () => isNearNeutralMid,
+  isOrthographicCamera: () => isOrthographicCamera,
+  isPerspectiveCamera: () => isPerspectiveCamera,
   isRawObject: () => isRawObject,
   log: () => log,
+  mergeValueMaps: () => mergeValueMaps,
   newPlayer: () => newPlayer,
   now: () => now,
   numberToDurationString: () => numberToDurationString,
@@ -74,24 +90,41 @@ __export(index_exports, {
   pause: () => pause,
   play: () => play,
   pointsToPath: () => pointsToPath,
+  quaternionConjugate: () => quaternionConjugate,
+  quaternionMultiply: () => quaternionMultiply,
+  quaternionSlerp: () => quaternionSlerp,
+  quaternionToEuler: () => quaternionToEuler,
+  randomHexString: () => randomHexString,
   rawHSLToHex: () => rawHSLToHex,
   rawRGBToHex: () => rawRGBToHex,
   reset: () => reset,
+  reversed: () => reversed,
+  rgbChroma: () => rgbChroma,
+  rgbLightness: () => rgbLightness,
   rgbToRgba: () => rgbToRgba,
   rotationMatrixToAngle: () => rotationMatrixToAngle,
   seek: () => seek,
-  setBounds: () => setBounds,
-  setDuration: () => setDuration,
-  setViewport: () => setViewport,
+  shouldUseBlendForLabelColor: () => shouldUseBlendForLabelColor,
+  storedEulerXYZtoRPY: () => storedEulerXYZtoRPY,
   stringifyMapped: () => stringifyMapped,
   toDegrees: () => toDegrees,
   toRadians: () => toRadians,
-  update: () => update,
+  updated: () => updated,
   useDeep: () => useDeep,
   useDeepSelector: () => useDeepSelector,
   useLazy: () => useLazy,
   useMediaQuery: () => useMediaQuery,
-  usePlayerStore: () => usePlayerStore
+  useOptionalContext: () => useOptionalContext,
+  usePlayerStore: () => usePlayerStore,
+  useValuesStore: () => useValuesStore,
+  warnUnexpectedFeatureValue: () => warnUnexpectedFeatureValue,
+  withBounce: () => withBounce,
+  withBounds: () => withBounds,
+  withDirection: () => withDirection,
+  withDuration: () => withDuration,
+  withLooping: () => withLooping,
+  withOptionalContext: () => withOptionalContext,
+  withSpeed: () => withSpeed
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -116,103 +149,114 @@ function getId(lookup) {
 }
 
 // src/player.ts
+var PlayerDirection = /* @__PURE__ */ ((PlayerDirection3) => {
+  PlayerDirection3["Reverse"] = "reverse";
+  PlayerDirection3["Forward"] = "forward";
+  return PlayerDirection3;
+})(PlayerDirection || {});
 function reset(player, stamp) {
   const p = { ...player };
   const nowVal = now();
   p._currentTime = nowVal;
   p._previousTime = nowVal;
   p.stamp = stamp ? stamp : 0;
+  p._currentDirection = p.direction;
+  p._bounced = false;
+  p._enteredBounds = false;
   return p;
 }
 function now() {
   return (typeof performance === "undefined" ? Date : performance).now();
 }
-function update(player, coldStart) {
+function updated(player, coldStart) {
   const p = { ...player };
   const duration = p.duration;
   const t = now();
   p._previousTime = coldStart ? t : p._currentTime;
   p._currentTime = t;
   const currentInBounds = p.stamp >= p.bounds[0] && p.stamp <= p.bounds[1];
-  const currentViewportCenter = (p.viewport[1] + p.viewport[0]) / 2;
-  const nearViewportCenterCurrent = Math.abs(p.stamp - currentViewportCenter) < 0.01;
-  const delta = (p._currentTime - p._previousTime) * p.timescale / duration;
+  if (currentInBounds && !p._enteredBounds) {
+    p._enteredBounds = true;
+  }
+  const effectiveTimescale = p.speed * (p._currentDirection === "forward" /* Forward */ ? 1 : -1);
+  const delta = (p._currentTime - p._previousTime) * effectiveTimescale;
   const updatedStamp = p.stamp + delta;
-  const [start, end] = currentInBounds ? p.bounds : [0, 1];
-  let attachOverride = false;
+  const [start, end] = !p._enteredBounds && !currentInBounds ? [0, duration] : p.bounds;
+  const movingTowardBounds = p.stamp < start && p._currentDirection === "forward" /* Forward */ || p.stamp > end && p._currentDirection === "reverse" /* Reverse */;
   if (updatedStamp > end) {
-    if (p.playback === "loop") {
-      p.stamp = start;
-    } else if (p.playback === "bounce") {
-      p.stamp = end;
-      p.timescale *= -1;
+    if (movingTowardBounds) {
+      p.stamp = updatedStamp;
     } else {
-      p.stamp = start;
-      p.running = false;
-    }
-    attachOverride = true;
-  } else if (currentInBounds && updatedStamp < start) {
-    if (p.playback === "loop") {
-      p.stamp = start;
-      if (p.timescale < 0) {
+      if (p.bounce && (p.looping || !p._bounced)) {
+        p.stamp = end;
+        p._currentDirection = p._currentDirection === "forward" /* Forward */ ? "reverse" /* Reverse */ : "forward" /* Forward */;
+        p._bounced = true;
+      } else if (p.looping) {
+        p.stamp = start;
+      } else {
+        p.stamp = end;
         p.running = false;
       }
-    } else if (p.playback === "bounce") {
-      p.stamp = start;
-      p.timescale *= -1;
+    }
+  } else if (updatedStamp < start) {
+    if (movingTowardBounds) {
+      p.stamp = updatedStamp;
     } else {
-      p.stamp = start;
-      p.running = false;
+      if (p.bounce && (p.looping || !p._bounced)) {
+        p.stamp = start;
+        p._currentDirection = p._currentDirection === "forward" /* Forward */ ? "reverse" /* Reverse */ : "forward" /* Forward */;
+        p._bounced = true;
+      } else if (p.looping) {
+        p.stamp = end;
+      } else {
+        p.stamp = start;
+        p.running = false;
+      }
     }
-    attachOverride = true;
   } else {
     p.stamp = updatedStamp;
   }
-  const newNearViewportCenter = Math.abs(p.stamp - currentViewportCenter) < 0.01;
-  const boundsInsideViewport = p.viewport[0] <= p.bounds[0] || p.viewport[1] >= p.bounds[1];
-  if (p.running && !boundsInsideViewport && (nearViewportCenterCurrent || newNearViewportCenter || attachOverride)) {
-    p.viewport = getFittedViewport(p.stamp, p.viewport);
-  } else if (p.running && !boundsInsideViewport && !newNearViewportCenter) {
-    const oomphOffset = currentViewportCenter < p.stamp ? delta : 0;
-    const idealViewport = getFittedViewport(p.stamp + oomphOffset, p.viewport);
-    p.viewport = [
-      p.viewport[0] * 0.6 + idealViewport[0] * 0.4,
-      p.viewport[1] * 0.6 + idealViewport[1] * 0.4
-    ];
-  }
   return p;
 }
-function setBounds(player, bounds) {
+function withBounds(player, bounds) {
   const p = { ...player };
   p.bounds = bounds;
   return p;
 }
-function setViewport(player, viewport) {
-  const p = { ...player };
-  p.viewport = viewport;
-  return p;
-}
-function play(player, speed) {
+function play(player, speed, direction) {
   const p = { ...player };
   p.running = true;
-  p.timescale = speed ?? 1;
-  if (p.playback === "once" && p.stamp === p.bounds[1]) {
+  if (speed !== void 0) p.speed = Math.abs(speed);
+  if (direction !== void 0) {
+    p.direction = direction;
+  }
+  p._currentDirection = p.direction;
+  p._bounced = false;
+  p._enteredBounds = false;
+  if (!p.looping && !p.bounce) {
+    if (p.direction === "forward" /* Forward */ && p.stamp === p.bounds[1]) {
+      p.stamp = p.bounds[0];
+    } else if (p.direction === "reverse" /* Reverse */ && p.stamp === p.bounds[0]) {
+      p.stamp = p.bounds[1];
+    }
+  }
+  const tolerance = 1;
+  if (p._currentDirection === "forward" /* Forward */ && Math.abs(p.stamp - p.bounds[1]) <= tolerance) {
     p.stamp = p.bounds[0];
+  } else if (p._currentDirection === "reverse" /* Reverse */ && Math.abs(p.stamp - p.bounds[0]) <= tolerance) {
+    p.stamp = p.bounds[1];
   }
   return p;
 }
 function pause(player) {
   const p = { ...player };
   p.running = false;
-  p.timescale = 0;
   return p;
 }
 function seek(player, stamp) {
-  const p = reset(player, stamp);
-  p.viewport = getFittedViewport(stamp, p.viewport);
-  return p;
+  return reset(player, stamp);
 }
-function setDuration(player, duration) {
+function withDuration(player, duration) {
   const p = { ...player };
   p.duration = duration;
   return p;
@@ -223,25 +267,52 @@ function newPlayer() {
     _previousTime: now(),
     _currentTime: now(),
     stamp: 0,
-    timescale: 0,
-    bounds: [0, 1],
-    playback: "loop",
-    viewport: [0, 1],
-    duration: 1e3
+    speed: 1,
+    direction: "forward" /* Forward */,
+    _currentDirection: "forward" /* Forward */,
+    _bounced: false,
+    _enteredBounds: false,
+    bounds: [0, 5e3],
+    bounce: false,
+    looping: true,
+    duration: 5e3
   };
 }
-var getFittedViewport = (playhead, proposedViewport) => {
-  const viewportWidth = proposedViewport[1] - proposedViewport[0];
-  const proposedLeft = playhead - viewportWidth / 2;
-  const proposedRight = playhead + viewportWidth / 2;
-  if (proposedLeft >= 0 && proposedRight <= 1) {
-    return [playhead - viewportWidth / 2, playhead + viewportWidth / 2];
-  } else if (proposedLeft < 0) {
-    return [0, viewportWidth];
-  } else {
-    return [1 - viewportWidth, 1];
+function withSpeed(player, speed) {
+  const p = { ...player };
+  if (speed < 0) {
+    throw new Error("Speed must be a positive number.");
   }
-};
+  p.speed = speed;
+  return p;
+}
+function withDirection(player, direction) {
+  const p = { ...player };
+  p.direction = direction;
+  p._currentDirection = direction;
+  p._bounced = false;
+  p._enteredBounds = false;
+  return p;
+}
+function reversed(player) {
+  const p = { ...player };
+  const newDirection = p.direction === "forward" /* Forward */ ? "reverse" /* Reverse */ : "forward" /* Forward */;
+  p.direction = newDirection;
+  p._currentDirection = newDirection;
+  p._bounced = false;
+  p._enteredBounds = false;
+  return p;
+}
+function withBounce(player, bounce) {
+  const p = { ...player };
+  p.bounce = bounce;
+  return p;
+}
+function withLooping(player, looping) {
+  const p = { ...player };
+  p.looping = looping;
+  return p;
+}
 
 // src/player-store.ts
 var import_react = require("react");
@@ -253,29 +324,50 @@ THREE.Object3D.DEFAULT_UP.set(0, 0, 1);
 (0, import_immer.enableMapSet)();
 var PlayerSlice = (set) => ({
   player: newPlayer(),
-  // Set the duration of the player
+  // Set the duration of the player. Also rescales bounds if they were at
+  // the old default. Uses `produce` (rather than the spread+`withX` pattern
+  // the other actions use) because the bounds rescaling is a multi-field
+  // atomic conditional write. Viewport rescaling is handled separately by
+  // the viewport-follow subscription.
   updateDuration: (duration) => {
     set(
       (0, import_immer.produce)((state) => {
+        const oldDuration = state.player.duration;
         state.player.duration = duration;
+        if (oldDuration > 0 && duration > 0) {
+          const b = state.player.bounds;
+          if (Math.abs(b[1] - oldDuration) < 1) {
+            state.player.bounds = [b[0], duration];
+          }
+        }
       })
     );
   },
-  // Set the timescale of the animation playback
-  updateTimescale: (speed) => {
-    set(
-      (0, import_immer.produce)((state) => {
-        state.player.timescale = speed;
-      })
-    );
+  // Set the speed of the animation playback
+  updateSpeed: (speed) => {
+    set((state) => ({
+      player: withSpeed(state.player, speed)
+    }));
+  },
+  // Set the direction of the animation playback
+  updateDirection: (direction) => {
+    set((state) => ({
+      player: withDirection(state.player, direction)
+    }));
+  },
+  // Reverse the current direction of the animation playback
+  reverseDirection: () => {
+    set((state) => ({
+      player: reversed(state.player)
+    }));
   },
   // Set the time of the animation
   resetPlayer: (time) => {
     set((state) => ({ player: reset(state.player, time) }));
   },
   // Play the animation
-  playPlayer: (speed) => {
-    set((state) => ({ player: play(state.player, speed) }));
+  playPlayer: (speed, direction) => {
+    set((state) => ({ player: play(state.player, speed, direction) }));
   },
   // Pause the animation
   pausePlayer: () => {
@@ -284,13 +376,13 @@ var PlayerSlice = (set) => ({
   // Update the timer
   updatePlayer: (coldStart) => {
     set((state) => ({
-      player: update(state.player, coldStart ?? false)
+      player: updated(state.player, coldStart ?? false)
     }));
   },
   // Set the player bounds
   updatePlayerBounds: (start, end) => {
     set((state) => ({
-      player: setBounds(state.player, [start, end])
+      player: withBounds(state.player, [start, end])
     }));
   },
   updatePlayerBound: (bound, time) => {
@@ -298,54 +390,32 @@ var PlayerSlice = (set) => ({
       const t = time ?? state.player.stamp;
       if (bound === "start" && state.player.bounds[1] <= t) {
         return {
-          player: setBounds(state.player, [state.player.bounds[1], t])
+          player: withBounds(state.player, [state.player.bounds[1], t])
         };
       } else if (bound === "end" && state.player.bounds[0] >= t) {
         return {
-          player: setBounds(state.player, [t, state.player.bounds[0]])
+          player: withBounds(state.player, [t, state.player.bounds[0]])
         };
       } else if (bound === "start") {
         return {
-          player: setBounds(state.player, [t, state.player.bounds[1]])
+          player: withBounds(state.player, [t, state.player.bounds[1]])
         };
       } else {
         return {
-          player: setBounds(state.player, [state.player.bounds[0], t])
+          player: withBounds(state.player, [state.player.bounds[0], t])
         };
       }
     });
   },
-  // Set the player viewport
-  updatePlayerViewport: (start, end) => {
+  updateBounce: (bounce) => {
     set((state) => ({
-      player: setViewport(state.player, [start, end])
+      player: withBounce(state.player, bounce)
     }));
   },
-  updatePlayerViewportCenter: (time) => {
+  updateLooping: (looping) => {
     set((state) => ({
-      player: seek(state.player, time ?? state.player.stamp)
+      player: withLooping(state.player, looping)
     }));
-  },
-  updatePlayerViewportBound: (bound, time) => {
-    set((state) => {
-      if (bound === "start" && state.player.viewport[1] <= time) {
-        return {
-          player: setViewport(state.player, [state.player.viewport[1], time])
-        };
-      } else if (bound === "end" && state.player.viewport[0] >= time) {
-        return {
-          player: setViewport(state.player, [time, state.player.viewport[0]])
-        };
-      } else if (bound === "start") {
-        return {
-          player: setViewport(state.player, [time, state.player.viewport[1]])
-        };
-      } else {
-        return {
-          player: setViewport(state.player, [state.player.viewport[0], time])
-        };
-      }
-    });
   }
 });
 var usePlayerStore = (0, import_zustand.create)()(
@@ -354,6 +424,17 @@ var usePlayerStore = (0, import_zustand.create)()(
 var PlayerContext = (0, import_react.createContext)(null);
 
 // src/animated-values.ts
+var AnimatableGroupType = /* @__PURE__ */ ((AnimatableGroupType2) => {
+  AnimatableGroupType2["Vector2"] = "vector2";
+  AnimatableGroupType2["Vector3"] = "vector3";
+  AnimatableGroupType2["Euler"] = "euler";
+  AnimatableGroupType2["RGB"] = "rgb";
+  AnimatableGroupType2["HSL"] = "hsl";
+  AnimatableGroupType2["Group"] = "group";
+  AnimatableGroupType2["Entity"] = "entity";
+  AnimatableGroupType2["Instance"] = "instance";
+  return AnimatableGroupType2;
+})(AnimatableGroupType || {});
 function instanceOfRawBoolean(object) {
   return typeof object === "boolean";
 }
@@ -367,10 +448,10 @@ function instanceOfRawVector3(object) {
   return object.x !== void 0 && object.y !== void 0 && object.z !== void 0;
 }
 function instanceOfRawVector2(object) {
-  return object.x !== void 0 && object.y !== void 0;
+  return object.x !== void 0 && object.y !== void 0 && object.z === void 0;
 }
 function instanceOfRawEuler(object) {
-  return object.x !== void 0 && object.y !== void 0 && object.z !== void 0;
+  return object.r !== void 0 && object.p !== void 0 && object.y !== void 0;
 }
 function instanceOfRawColor(object) {
   return object.r !== void 0 && object.g !== void 0 && object.b !== void 0 || object.h !== void 0 && object.s !== void 0 && object.l !== void 0;
@@ -381,6 +462,12 @@ function instanceOfRawRGB(object) {
 function instanceOfRawHSL(object) {
   return object.h !== void 0 && object.s !== void 0 && object.l !== void 0;
 }
+function warnUnexpectedFeatureValue(feature, expected, value) {
+  console.warn(
+    `Feature "${feature}" expected ${expected}, received ${typeof value}:`,
+    value
+  );
+}
 function isRawObject(value) {
   if (instanceOfRawVector3(value) || instanceOfRawVector2(value) || instanceOfRawEuler(value) || instanceOfRawColor(value) || instanceOfRawRGB(value) || instanceOfRawHSL(value))
     return true;
@@ -462,9 +549,11 @@ function getDegenerateHexagonPath(x, y, size, height) {
 }
 
 // src/closest-frame.ts
-function closestFrame(completion, count) {
-  const frameIdx = Math.round(completion * count);
-  return frameIdx / count;
+function closestFrame(stampMs, framerate) {
+  if (framerate <= 0) return stampMs;
+  const frameDurationMs = 1e3 / framerate;
+  const frameIdx = Math.round(stampMs / frameDurationMs);
+  return frameIdx * frameDurationMs;
 }
 
 // src/angles.ts
@@ -559,19 +648,62 @@ function rawRGBToHex({ r, g, b }) {
 function rawHSLToHex({ h, s, l }) {
   return (0, import_color.default)({ h, s, l }).hex();
 }
+function randomHexString(constrainLuminosity, constrainSaturation) {
+  const h = Math.floor(Math.random() * 255);
+  const s = Math.floor(constrainSaturation ? constrainSaturation * 100 : Math.random() * 100);
+  const l = Math.floor(constrainLuminosity ? constrainLuminosity * 100 : Math.random() * 100);
+  return (0, import_color.default)({ h, s, l }).hex();
+}
+function rgbChroma([r, g, b]) {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  return (max - min) / 255;
+}
+function rgbLightness([r, g, b]) {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  return (max + min) / (2 * 255);
+}
+function colorChroma(color) {
+  return rgbChroma(hexToRgbArray(color));
+}
+function colorLightness(color) {
+  return rgbLightness(hexToRgbArray(color));
+}
+function shouldUseBlendForLabelColor(color, opts) {
+  if (!color) return false;
+  let rgb;
+  try {
+    rgb = hexToRgbArray(color);
+  } catch {
+    return false;
+  }
+  const chroma = rgbChroma(rgb);
+  const lightness = rgbLightness(rgb);
+  const { chromaCutoff = 0.08, minLightness = 0.28, maxLightness = 0.75 } = opts ?? {};
+  const isNearGray = chroma < chromaCutoff;
+  const isMidLightness = lightness > minLightness && lightness < maxLightness;
+  return !(isNearGray && isMidLightness);
+}
+function isNearNeutralMid(color, opts) {
+  const { chromaCutoff = 0.08, minLightness = 0.28, maxLightness = 0.75 } = opts ?? {};
+  const c = colorChroma(color);
+  const l = colorLightness(color);
+  return c < chromaCutoff && l > minLightness && l < maxLightness;
+}
 
 // src/use-deep.ts
 var import_react3 = require("react");
 var import_deep_equal = __toESM(require("deep-equal"));
 function useDeepSelector(selector) {
-  const prev = (0, import_react3.useRef)();
+  const prev = (0, import_react3.useRef)(void 0);
   return (state) => {
     const next = selector(state);
     return (0, import_deep_equal.default)(prev.current, next) ? prev.current : prev.current = next;
   };
 }
 function useDeep(initializer, dependencies) {
-  const prevValue = (0, import_react3.useRef)();
+  const prevValue = (0, import_react3.useRef)(void 0);
   const prevDependencies = (0, import_react3.useRef)([]);
   return (0, import_deep_equal.default)(prevDependencies.current, dependencies) ? prevValue.current : prevValue.current = initializer();
 }
@@ -709,6 +841,98 @@ function angularDistance(euler1, euler2) {
   ];
   return rotationMatrixToAngle(R12);
 }
+function eulerToQuaternion(euler) {
+  const [z, y, x] = euler;
+  const cx = Math.cos(x * 0.5);
+  const sx = Math.sin(x * 0.5);
+  const cy = Math.cos(y * 0.5);
+  const sy = Math.sin(y * 0.5);
+  const cz = Math.cos(z * 0.5);
+  const sz = Math.sin(z * 0.5);
+  const w = cx * cy * cz + sx * sy * sz;
+  const qx = sx * cy * cz - cx * sy * sz;
+  const qy = cx * sy * cz + sx * cy * sz;
+  const qz = cx * cy * sz - sx * sy * cz;
+  return [w, qx, qy, qz];
+}
+function quaternionToEuler(q) {
+  const [w, x, y, z] = q;
+  const sinrCosp = 2 * (w * x + y * z);
+  const cosrCosp = 1 - 2 * (x * x + y * y);
+  const roll = Math.atan2(sinrCosp, cosrCosp);
+  const sinp = 2 * (w * y - z * x);
+  let pitch;
+  if (Math.abs(sinp) >= 1) {
+    pitch = Math.sign(sinp) * Math.PI / 2;
+  } else {
+    pitch = Math.asin(sinp);
+  }
+  const sinyCosp = 2 * (w * z + x * y);
+  const cosyCosp = 1 - 2 * (y * y + z * z);
+  const yaw = Math.atan2(sinyCosp, cosyCosp);
+  return [yaw, pitch, roll];
+}
+function quaternionMultiply(q1, q2) {
+  const [w1, x1, y1, z1] = q1;
+  const [w2, x2, y2, z2] = q2;
+  const w = w1 * w2 - x1 * x2 - y1 * y2 - z1 * z2;
+  const x = w1 * x2 + x1 * w2 + y1 * z2 - z1 * y2;
+  const y = w1 * y2 - x1 * z2 + y1 * w2 + z1 * x2;
+  const z = w1 * z2 + x1 * y2 - y1 * x2 + z1 * w2;
+  return [w, x, y, z];
+}
+function quaternionConjugate(q) {
+  const [w, x, y, z] = q;
+  return [w, -x, -y, -z];
+}
+function quaternionSlerp(q1, q2, t) {
+  const [w1, x1, y1, z1] = q1;
+  const [w2, x2, y2, z2] = q2;
+  let dot = w1 * w2 + x1 * x2 + y1 * y2 + z1 * z2;
+  let q2Adjusted = [w2, x2, y2, z2];
+  if (dot < 0) {
+    q2Adjusted = [-w2, -x2, -y2, -z2];
+    dot = -dot;
+  }
+  const DOT_THRESHOLD = 0.9995;
+  if (dot > DOT_THRESHOLD) {
+    const result = [
+      w1 + t * (q2Adjusted[0] - w1),
+      x1 + t * (q2Adjusted[1] - x1),
+      y1 + t * (q2Adjusted[2] - y1),
+      z1 + t * (q2Adjusted[3] - z1)
+    ];
+    const length = Math.sqrt(
+      result[0] * result[0] + result[1] * result[1] + result[2] * result[2] + result[3] * result[3]
+    );
+    return [result[0] / length, result[1] / length, result[2] / length, result[3] / length];
+  }
+  const theta0 = Math.acos(Math.abs(dot));
+  const sinTheta0 = Math.sin(theta0);
+  const theta = theta0 * t;
+  const sinTheta = Math.sin(theta);
+  const s0 = Math.cos(theta) - dot * sinTheta / sinTheta0;
+  const s1 = sinTheta / sinTheta0;
+  return [
+    s0 * w1 + s1 * q2Adjusted[0],
+    s0 * x1 + s1 * q2Adjusted[1],
+    s0 * y1 + s1 * q2Adjusted[2],
+    s0 * z1 + s1 * q2Adjusted[3]
+  ];
+}
+function eulerSlerp(euler1, euler2, t) {
+  const q1 = eulerToQuaternion(euler1);
+  const q2 = eulerToQuaternion(euler2);
+  const qResult = quaternionSlerp(q1, q2, t);
+  return quaternionToEuler(qResult);
+}
+function eulerRotationBetween(euler1, euler2) {
+  const q1 = eulerToQuaternion(euler1);
+  const q2 = eulerToQuaternion(euler2);
+  const q1Conjugate = quaternionConjugate(q1);
+  const qDiff = quaternionMultiply(q2, q1Conjugate);
+  return quaternionToEuler(qDiff);
+}
 
 // src/overlapping-segments.ts
 function overlappingSegments(original) {
@@ -903,31 +1127,228 @@ var EMAIL = /^(([^<>()[\].,;:\s@"]+(\.[^<>()[\].,;:\s@"]+)*)|(".+"))@(([^<>()[\]
 
 // src/map-deep-equal.ts
 var import_fast_deep_equal = __toESM(require("fast-deep-equal"));
-function isMapDeepEqual(map1, map2) {
-  if (map1.size !== map2.size) return false;
+function isMapDeepEqual(map1, map2, options = {}) {
+  if (map1 === map2) return true;
+  const { filter } = options || {};
+  if (!filter) {
+    if (map1.size !== map2.size) return false;
+    for (const [key, value] of map1.entries()) {
+      if (!map2.has(key)) return false;
+      const otherValue = map2.get(key);
+      if (value !== otherValue && !(0, import_fast_deep_equal.default)(value, otherValue)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  const filteredEntries1 = [];
+  const filteredEntries2 = [];
   for (const [key, value] of map1.entries()) {
-    if (!map2.has(key)) return false;
-    const otherValue = map2.get(key);
-    if (!(0, import_fast_deep_equal.default)(value, otherValue)) {
+    if (filter(key, value)) {
+      filteredEntries1.push([key, value]);
+    }
+  }
+  for (const [key, value] of map2.entries()) {
+    if (filter(key, value)) {
+      filteredEntries2.push([key, value]);
+    }
+  }
+  if (filteredEntries1.length !== filteredEntries2.length) {
+    return false;
+  }
+  const filteredMap2 = new Map(filteredEntries2);
+  for (const [key, value] of filteredEntries1) {
+    if (!filteredMap2.has(key)) return false;
+    const otherValue = filteredMap2.get(key);
+    if (value !== otherValue && !(0, import_fast_deep_equal.default)(value, otherValue)) {
       return false;
     }
   }
   return true;
 }
+
+// src/migrate-euler.ts
+function storedEulerXYZtoRPY(robotData) {
+  if ("rotation" in robotData.features) {
+    if (!robotData.features.rotation.animated) {
+      const rotationValue = robotData.features.rotation.value;
+      if (!instanceOfRawEuler(rotationValue)) {
+        const oldRot = rotationValue;
+        const newRot = { r: oldRot.x, p: oldRot.y, y: oldRot.z };
+        robotData.features.rotation.value = newRot;
+      }
+    } else {
+      const rotationValue = robotData.features.rotation.value;
+      if (!instanceOfRawEuler(rotationValue.default)) {
+        const oldRot = rotationValue.default;
+        const newRot = { r: oldRot.x, p: oldRot.y, y: oldRot.z };
+        robotData.features.rotation.value.default = newRot;
+      }
+    }
+  }
+  if ("origin" in robotData) {
+    const rotationValue = robotData.origin.rotation;
+    if (!instanceOfRawEuler(rotationValue)) {
+      const oldRot = rotationValue;
+      const newRot = { r: oldRot.x, p: oldRot.y, y: oldRot.z };
+      robotData.origin.rotation = newRot;
+    }
+  }
+  return robotData;
+}
+
+// src/react/context-providers.tsx
+var import_react5 = require("react");
+function createContextHook(context, name) {
+  return function useRequiredContext() {
+    const value = (0, import_react5.useContext)(context);
+    if (!value) {
+      throw new Error(
+        `${name} context is required. Make sure you're using the component within a ${name}Provider.`
+      );
+    }
+    return value;
+  };
+}
+function withOptionalContext(CoreComponent, contextConfig) {
+  const { context, defaultValue } = contextConfig;
+  return function ComponentWithContext(props) {
+    const { skipContext = false, ...coreProps } = props;
+    const existingContext = (0, import_react5.useContext)(context);
+    if (skipContext || existingContext) {
+      return (0, import_react5.createElement)(CoreComponent, coreProps);
+    }
+    return (0, import_react5.createElement)(
+      context.Provider,
+      { value: defaultValue },
+      (0, import_react5.createElement)(CoreComponent, coreProps)
+    );
+  };
+}
+function composeContexts(contexts) {
+  return function ComposedContexts({ children }) {
+    return contexts.reduceRight((acc, { Provider, condition }) => {
+      if (condition && !condition()) {
+        return acc;
+      }
+      return (0, import_react5.createElement)(Provider, {}, acc);
+    }, children);
+  };
+}
+function createContextProvider(context, defaultValue) {
+  return function ContextProvider({
+    children,
+    value = defaultValue
+  }) {
+    return (0, import_react5.createElement)(context.Provider, { value }, children);
+  };
+}
+function createContextSolution(config) {
+  const { context, defaultValue, name } = config;
+  const useRequiredContext = createContextHook(context, name);
+  const Provider = createContextProvider(context, defaultValue);
+  const withOptional = (Component) => withOptionalContext(Component, config);
+  return {
+    useContext: useRequiredContext,
+    Provider,
+    withOptional,
+    context: config.context
+  };
+}
+function useOptionalContext(context) {
+  return (0, import_react5.useContext)(context);
+}
+function createContextChecker(context) {
+  return function useHasContext() {
+    return (0, import_react5.useContext)(context) !== null;
+  };
+}
+
+// src/values-store.ts
+var import_zustand2 = require("zustand");
+var import_middleware2 = require("zustand/middleware");
+function mergeValueMaps(base, updates) {
+  if (updates.size === 0) return base;
+  let hasChange = false;
+  updates.forEach((value, key) => {
+    if (hasChange) return;
+    if (value === void 0) {
+      if (base.has(key)) hasChange = true;
+    } else if (base.get(key) !== value) {
+      hasChange = true;
+    }
+  });
+  if (!hasChange) return base;
+  const merged = new Map(base);
+  updates.forEach((value, key) => {
+    if (value === void 0) {
+      merged.delete(key);
+    } else {
+      merged.set(key, value);
+    }
+  });
+  return merged;
+}
+var useValuesStore = (0, import_zustand2.create)()(
+  (0, import_middleware2.subscribeWithSelector)((set) => ({
+    values: /* @__PURE__ */ new Map(),
+    velocities: /* @__PURE__ */ new Map(),
+    updateValues: (updates) => {
+      set((state) => ({
+        values: mergeValueMaps(state.values, updates)
+      }));
+    },
+    updateVelocities: (updates) => {
+      set((state) => ({
+        velocities: mergeValueMaps(state.velocities, updates)
+      }));
+    },
+    setTrackValue: (trackKey, value) => {
+      set((state) => {
+        const next = new Map(state.values);
+        next.set(trackKey, value);
+        return { values: next };
+      });
+    },
+    replaceAll: (values, velocities) => {
+      set({ values, velocities });
+    }
+  }))
+);
+
+// src/three-guards.ts
+function isOrthographicCamera(camera) {
+  return "isOrthographicCamera" in camera;
+}
+function isPerspectiveCamera(camera) {
+  return "isPerspectiveCamera" in camera;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AnimatableGroupType,
   EMAIL,
   PlayerContext,
+  PlayerDirection,
   PlayerSlice,
   Result,
   alpha,
   altColor,
   angularDistance,
   closestFrame,
+  colorChroma,
+  colorLightness,
+  composeContexts,
   composeProgress,
   composeProgressiveResult,
+  createContextChecker,
+  createContextHook,
+  createContextProvider,
+  createContextSolution,
   downloadBlob,
   downloadJSONFile,
+  eulerRotationBetween,
+  eulerSlerp,
+  eulerToQuaternion,
   eulerToRotationMatrix,
   getDegenerateHexagonPath,
   getHexagonPath,
@@ -948,8 +1369,12 @@ function isMapDeepEqual(map1, map2) {
   instanceOfRawVector2,
   instanceOfRawVector3,
   isMapDeepEqual,
+  isNearNeutralMid,
+  isOrthographicCamera,
+  isPerspectiveCamera,
   isRawObject,
   log,
+  mergeValueMaps,
   newPlayer,
   now,
   numberToDurationString,
@@ -960,22 +1385,39 @@ function isMapDeepEqual(map1, map2) {
   pause,
   play,
   pointsToPath,
+  quaternionConjugate,
+  quaternionMultiply,
+  quaternionSlerp,
+  quaternionToEuler,
+  randomHexString,
   rawHSLToHex,
   rawRGBToHex,
   reset,
+  reversed,
+  rgbChroma,
+  rgbLightness,
   rgbToRgba,
   rotationMatrixToAngle,
   seek,
-  setBounds,
-  setDuration,
-  setViewport,
+  shouldUseBlendForLabelColor,
+  storedEulerXYZtoRPY,
   stringifyMapped,
   toDegrees,
   toRadians,
-  update,
+  updated,
   useDeep,
   useDeepSelector,
   useLazy,
   useMediaQuery,
-  usePlayerStore
+  useOptionalContext,
+  usePlayerStore,
+  useValuesStore,
+  warnUnexpectedFeatureValue,
+  withBounce,
+  withBounds,
+  withDirection,
+  withDuration,
+  withLooping,
+  withOptionalContext,
+  withSpeed
 });