@almadar/ui 5.42.0 → 5.44.0

package/dist/hooks/index.cjs

@@ -2504,6 +2504,73 @@ function useDropZone({ accepts, onDrop, disabled = false }) {
   );
   return { dropProps, isOver };
 }
+function useRenderInterpolation(options = {}) {
+  const tickIntervalMs = options.tickIntervalMs ?? 1e3 / 30;
+  const prevRef = react.useRef(null);
+  const currRef = react.useRef(null);
+  const rafRef = react.useRef(null);
+  const onSnapshot = react.useCallback((entities2) => {
+    prevRef.current = currRef.current;
+    currRef.current = { entities: entities2, arrivedAt: performance.now() };
+  }, []);
+  const getInterpolated = react.useCallback((now) => {
+    const out = /* @__PURE__ */ new Map();
+    const curr = currRef.current;
+    if (!curr) return out;
+    const prev = prevRef.current;
+    if (!prev) {
+      for (const e of curr.entities) out.set(e.id, { x: e.x, y: e.y });
+      return out;
+    }
+    const rawAlpha = (now - curr.arrivedAt) / tickIntervalMs;
+    const alpha = rawAlpha < 0 ? 0 : rawAlpha > 1 ? 1 : rawAlpha;
+    const prevMap = /* @__PURE__ */ new Map();
+    for (const e of prev.entities) prevMap.set(e.id, e);
+    for (const c of curr.entities) {
+      const p = prevMap.get(c.id);
+      if (!p) {
+        out.set(c.id, { x: c.x, y: c.y });
+      } else {
+        out.set(c.id, {
+          x: p.x + (c.x - p.x) * alpha,
+          y: p.y + (c.y - p.y) * alpha
+        });
+      }
+    }
+    return out;
+  }, [tickIntervalMs]);
+  const startLoop = react.useCallback(
+    (draw) => {
+      let active = true;
+      const loop = () => {
+        if (!active) return;
+        try {
+          draw(getInterpolated(performance.now()));
+        } catch {
+        }
+        rafRef.current = requestAnimationFrame(loop);
+      };
+      rafRef.current = requestAnimationFrame(loop);
+      return () => {
+        active = false;
+        if (rafRef.current !== null) {
+          cancelAnimationFrame(rafRef.current);
+          rafRef.current = null;
+        }
+      };
+    },
+    [getInterpolated]
+  );
+  react.useEffect(() => {
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    };
+  }, []);
+  return { onSnapshot, getInterpolated, startLoop };
+}
 var API_BASE = typeof process !== "undefined" && process.env?.VITE_API_URL ? process.env.VITE_API_URL : "http://localhost:3000";
 function getUserId() {
   return localStorage.getItem("userId") || "anonymous";
@@ -2626,6 +2693,7 @@ exports.usePlayer = usePlayer;
 exports.usePreview = usePreview;
 exports.usePullToRefresh = usePullToRefresh;
 exports.useQuerySingleton = useQuerySingleton;
+exports.useRenderInterpolation = useRenderInterpolation;
 exports.useSingletonEntity = useSingletonEntity;
 exports.useSwipeGesture = useSwipeGesture;
 exports.useTraitListens = useTraitListens;

package/dist/hooks/index.d.ts

@@ -26,4 +26,5 @@ export { usePullToRefresh, type PullToRefreshOptions, type PullToRefreshResult,
 export { usePinchZoom, type PinchZoomOptions, type PinchZoomResult, } from './usePinchZoom';
 export { useDraggable, ALMADAR_DND_MIME, type DraggablePayload, type UseDraggableOptions, type UseDraggableResult, } from './useDraggable';
 export { useDropZone, type UseDropZoneOptions, type UseDropZoneResult, } from './useDropZone';
+export { useRenderInterpolation, type Positioned, type RenderInterpolationOptions, type RenderInterpolationHandle, } from './useRenderInterpolation';
 export { useGitHubStatus, useConnectGitHub, useDisconnectGitHub, useGitHubRepos, useGitHubRepo, useGitHubBranches, type GitHubStatus, type GitHubRepo, } from './useGitHub';

package/dist/hooks/index.js

@@ -2502,6 +2502,73 @@ function useDropZone({ accepts, onDrop, disabled = false }) {
   );
   return { dropProps, isOver };
 }
+function useRenderInterpolation(options = {}) {
+  const tickIntervalMs = options.tickIntervalMs ?? 1e3 / 30;
+  const prevRef = useRef(null);
+  const currRef = useRef(null);
+  const rafRef = useRef(null);
+  const onSnapshot = useCallback((entities2) => {
+    prevRef.current = currRef.current;
+    currRef.current = { entities: entities2, arrivedAt: performance.now() };
+  }, []);
+  const getInterpolated = useCallback((now) => {
+    const out = /* @__PURE__ */ new Map();
+    const curr = currRef.current;
+    if (!curr) return out;
+    const prev = prevRef.current;
+    if (!prev) {
+      for (const e of curr.entities) out.set(e.id, { x: e.x, y: e.y });
+      return out;
+    }
+    const rawAlpha = (now - curr.arrivedAt) / tickIntervalMs;
+    const alpha = rawAlpha < 0 ? 0 : rawAlpha > 1 ? 1 : rawAlpha;
+    const prevMap = /* @__PURE__ */ new Map();
+    for (const e of prev.entities) prevMap.set(e.id, e);
+    for (const c of curr.entities) {
+      const p = prevMap.get(c.id);
+      if (!p) {
+        out.set(c.id, { x: c.x, y: c.y });
+      } else {
+        out.set(c.id, {
+          x: p.x + (c.x - p.x) * alpha,
+          y: p.y + (c.y - p.y) * alpha
+        });
+      }
+    }
+    return out;
+  }, [tickIntervalMs]);
+  const startLoop = useCallback(
+    (draw) => {
+      let active = true;
+      const loop = () => {
+        if (!active) return;
+        try {
+          draw(getInterpolated(performance.now()));
+        } catch {
+        }
+        rafRef.current = requestAnimationFrame(loop);
+      };
+      rafRef.current = requestAnimationFrame(loop);
+      return () => {
+        active = false;
+        if (rafRef.current !== null) {
+          cancelAnimationFrame(rafRef.current);
+          rafRef.current = null;
+        }
+      };
+    },
+    [getInterpolated]
+  );
+  useEffect(() => {
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    };
+  }, []);
+  return { onSnapshot, getInterpolated, startLoop };
+}
 var API_BASE = typeof process !== "undefined" && process.env?.VITE_API_URL ? process.env.VITE_API_URL : "http://localhost:3000";
 function getUserId() {
   return localStorage.getItem("userId") || "anonymous";
@@ -2578,4 +2645,4 @@ function useGitHubBranches(owner, repo, enabled = true) {
   });
 }
 
-export { ALMADAR_DND_MIME, DEFAULT_SLOTS, I18nProvider, clearEntities, createTranslate, getAllEntities, getByType, getEntity, getSingleton, parseQueryBinding, removeEntity, spawnEntity, updateEntity, updateSingleton, useAgentChat, useAuthContext, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEmitEvent, useEntities, useEntitiesByType, useEntity as useEntityById, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useInfiniteScroll, useInput, useLongPress, useOrbitalHistory, usePhysics, usePinchZoom, usePlayer, usePreview, usePullToRefresh, useQuerySingleton, useSingletonEntity, useSwipeGesture, useTraitListens, useTranslate, useUIEvents, useUISlotManager, useValidation };
+export { ALMADAR_DND_MIME, DEFAULT_SLOTS, I18nProvider, clearEntities, createTranslate, getAllEntities, getByType, getEntity, getSingleton, parseQueryBinding, removeEntity, spawnEntity, updateEntity, updateSingleton, useAgentChat, useAuthContext, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEmitEvent, useEntities, useEntitiesByType, useEntity as useEntityById, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useInfiniteScroll, useInput, useLongPress, useOrbitalHistory, usePhysics, usePinchZoom, usePlayer, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSingletonEntity, useSwipeGesture, useTraitListens, useTranslate, useUIEvents, useUISlotManager, useValidation };

package/dist/hooks/useRenderInterpolation.d.ts

@@ -0,0 +1,33 @@
+export interface Positioned {
+    id: string;
+    x: number;
+    y: number;
+}
+export interface RenderInterpolationOptions {
+    /** Expected tick interval in ms (default: 1000/30 ≈ 33.3ms) */
+    tickIntervalMs?: number;
+}
+export interface RenderInterpolationHandle<T extends Positioned> {
+    /** Call when a new authoritative snapshot arrives from the model */
+    onSnapshot: (entities: readonly T[]) => void;
+    /** Returns interpolated positions for the current rAF timestamp; falls back to authoritative values */
+    getInterpolated: (now: number) => Map<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Start the rAF loop; call the supplied draw fn on every frame */
+    startLoop: (draw: (positions: Map<string, {
+        x: number;
+        y: number;
+    }>) => void) => () => void;
+}
+/**
+ * Fixed-timestep render interpolation between the last two authoritative model snapshots.
+ *
+ * Buffers two snapshots. On each rAF frame computes
+ *   alpha = clamp((now - lastArrival) / tickIntervalMs, 0, 1)
+ * and lerps x/y between prev and curr, matched by entity id.
+ * New or removed entities fall back to their authoritative value directly.
+ * Never throws; never causes a React re-render per frame.
+ */
+export declare function useRenderInterpolation<T extends Positioned>(options?: RenderInterpolationOptions): RenderInterpolationHandle<T>;