perf(navigation): attach the puck once and sleep the settled camera loop

The follow-camera animation loop called `Marker.addTo(map)` every frame.
MapLibre implements `addTo` as `remove()` followed by a full re-append and
listener rebind, so the puck was torn down and reattached at display rate for
the whole trip. The loop also scheduled its next frame before checking whether
there was any work to do, so it ran at full rate with no fix, no route, or a
pose that had long since converged.

Attachment, pose integration and publication to MapLibre are now three separate
jobs. The marker is attached once per map and only re-attached when the map
itself changes; setters and `jumpTo` run only for poses that moved far enough
to see; and a frame that publishes nothing twice in a row stops asking for
frames until an input wakes it. Every input that can change the visible pose --
a fix, route, camera mode, north-up toggle, style reload, gesture end, recenter
or visibility change -- wakes it explicitly.

Moving cadence is unchanged: no frame cap is introduced, and a 600-frame 60 Hz
and 1200-frame 120 Hz replay reproduce the previous puck and camera poses
bit-for-bit, including which frame issued each command.

`MapCanvas` now returns from its `moveend` listener before reading the camera,
so the guarded programmatic path no longer allocates a center it discards.

Measured on a Pixel 6 Pro against the previous build, 60 s per arm:

  moving      2530 puck detach/reattach cycles -> 0
  stationary  3497 cycles -> 0, and 14148 animation-frame requests -> 1152

Author: Medformatik

apps/web/src/components/map/MapCanvas.test.tsx

@@ -80,6 +80,8 @@ vi.mock("maplibre-gl", () => {
   let onCallCount = 0;
   class FakeMap {
     jumpTo = vi.fn();
+    /** Counts camera reads so a test can prove a guarded path never took one. */
+    cameraReads = 0;
 
     constructor(mapOptions: { center: [number, number]; container: HTMLElement; zoom: number }) {
       instances.push(this);
@@ -88,6 +90,13 @@ vi.mock("maplibre-gl", () => {
       mapOptions.container.append(document.createElement("canvas"));
     }
 
+    getCenter = () => {
+      this.cameraReads += 1;
+      return { lng: 1.5, lat: 2.5 };
+    };
+    getZoom = () => 12;
+    getBearing = () => 33;
+    getPitch = () => 44;
     isStyleLoaded = () => true;
     off = vi.fn();
     on = vi.fn(() => {
@@ -128,7 +137,7 @@ vi.mock("maplibre-gl", () => {
   };
 });
 
-import { useMapStore } from "@openmapx/core";
+import { useMapStore, useNavigationStore } from "@openmapx/core";
 import * as maplibre from "maplibre-gl";
 import * as mapContext from "@/lib/MapContext";
 import * as mapStyle from "@/lib/map";
@@ -138,7 +147,9 @@ const maplibreTest = (
   maplibre as unknown as {
     __test: {
       instances: Array<{
+        cameraReads: number;
         jumpTo: ReturnType<typeof vi.fn>;
+        on: ReturnType<typeof vi.fn>;
         remove: ReturnType<typeof vi.fn>;
       }>;
       options: Array<{ center: [number, number]; zoom: number }>;
@@ -166,8 +177,26 @@ afterEach(() => {
   console.error = originalConsoleError;
   vi.unstubAllGlobals();
   vi.clearAllMocks();
+  useNavigationStore.getState().stopNavigation();
 });
 
+/** Render a map and hand back its registered `moveend` listener. */
+async function renderWithMoveEnd() {
+  maplibreTest.reset();
+  mapStyleTest.reset();
+  useMapStore.setState({ bearing: 0, center: [0, 20], pitch: 0, userLocation: null, zoom: 2 });
+  vi.stubGlobal("navigator", { ...navigator, geolocation: undefined, permissions: undefined });
+
+  render(<MapCanvas />);
+  await waitFor(() => expect(maplibreTest.instances).toHaveLength(1));
+  const map = maplibreTest.instances[0];
+  const moveEnd = map.on.mock.calls.find(([event]: unknown[]) => event === "moveend")?.[1] as (
+    e?: unknown,
+  ) => void;
+  expect(moveEnd).toBeTypeOf("function");
+  return { map, moveEnd };
+}
+
 describe("MapCanvas", () => {
   it("renders the base map without waiting for a granted geolocation callback", async () => {
     maplibreTest.reset();
@@ -252,4 +281,52 @@ describe("MapCanvas", () => {
     expect(mapContextTest.mapRef.current).toBeNull();
     expect(mapContextTest.notifyMapReady).not.toHaveBeenCalled();
   });
+
+  it("persists the viewport for a user-originated move", async () => {
+    const { map, moveEnd } = await renderWithMoveEnd();
+    const readsBefore = map.cameraReads;
+
+    act(() => moveEnd({}));
+
+    expect(map.cameraReads).toBe(readsBefore + 1);
+    expect(useMapStore.getState()).toMatchObject({
+      bearing: 33,
+      center: [1.5, 2.5],
+      pitch: 44,
+      zoom: 12,
+    });
+  });
+
+  it("persists the viewport for a programmatic move outside navigation", async () => {
+    const { moveEnd } = await renderWithMoveEnd();
+
+    act(() => moveEnd({ programmatic: true }));
+
+    expect(useMapStore.getState().center).toEqual([1.5, 2.5]);
+  });
+
+  it("reads no camera state for its own programmatic move while navigating", async () => {
+    const { map, moveEnd } = await renderWithMoveEnd();
+    useNavigationStore.setState({ status: "navigating" });
+    const readsBefore = map.cameraReads;
+
+    act(() => moveEnd({ programmatic: true }));
+
+    expect(map.cameraReads).toBe(readsBefore);
+    expect(useMapStore.getState()).toMatchObject({
+      bearing: 0,
+      center: [0, 20],
+      pitch: 0,
+      zoom: 2,
+    });
+  });
+
+  it("still persists a user gesture while navigating", async () => {
+    const { moveEnd } = await renderWithMoveEnd();
+    useNavigationStore.setState({ status: "navigating" });
+
+    act(() => moveEnd({}));
+
+    expect(useMapStore.getState().center).toEqual([1.5, 2.5]);
+  });
 });

apps/web/src/components/map/MapCanvas.tsx

@@ -133,18 +133,20 @@ export function MapCanvas() {
         };
 
         map.on("moveend", (e) => {
-          const c = map.getCenter();
-          const center: LngLat = [c.lng, c.lat];
           // The navigation follow camera drives the map with a programmatic
           // jumpTo every animation frame; skip those so we don't write to the
-          // store 60×/s while navigating. User gestures and other programmatic
-          // moves (flyTo, deep links) still persist as before.
+          // store 60×/s while navigating. Bail before reading the camera at all:
+          // getCenter() allocates, and this is the hottest listener on the map
+          // during a trip. User gestures and other programmatic moves (flyTo,
+          // deep links) still persist as before.
           if (
             (e as { programmatic?: boolean })?.programmatic &&
             useNavigationStore.getState().status !== "idle"
           ) {
             return;
           }
+          const c = map.getCenter();
+          const center: LngLat = [c.lng, c.lat];
           setCenter(center);
           setZoom(map.getZoom());
           setBearing(map.getBearing());

apps/web/src/lib/navigation/navCameraScheduler.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import {
+  CAMERA_BEARING_EPSILON,
+  CAMERA_LNGLAT_EPSILON,
+  CAMERA_ZOOM_EPSILON,
+  cameraPoseChanged,
+  PUCK_BEARING_EPSILON,
+  PUCK_LNGLAT_EPSILON,
+  puckPoseChanged,
+  SETTLED_FRAMES_BEFORE_SLEEP,
+  shouldKeepAnimating,
+} from "./navCameraScheduler";
+
+const pose = (lng: number, lat: number, bearing: number) => ({ lng, lat, bearing });
+const cam = (lng: number, lat: number, bearing: number, zoom: number) => ({
+  lng,
+  lat,
+  bearing,
+  zoom,
+});
+
+describe("puckPoseChanged", () => {
+  it("treats a never-published pose as changed", () => {
+    expect(puckPoseChanged(null, pose(0, 0, 0))).toBe(true);
+  });
+
+  it("ignores drift below the puck threshold", () => {
+    const last = pose(13.4, 52.5, 90);
+    expect(puckPoseChanged(last, pose(13.4 + PUCK_LNGLAT_EPSILON / 2, 52.5, 90))).toBe(false);
+    expect(puckPoseChanged(last, pose(13.4, 52.5 + PUCK_LNGLAT_EPSILON / 2, 90))).toBe(false);
+    expect(puckPoseChanged(last, pose(13.4, 52.5, 90 + PUCK_BEARING_EPSILON / 2))).toBe(false);
+  });
+
+  it("reports movement past the threshold on any axis", () => {
+    const last = pose(13.4, 52.5, 90);
+    expect(puckPoseChanged(last, pose(13.4 + 1e-8, 52.5, 90))).toBe(true);
+    expect(puckPoseChanged(last, pose(13.4, 52.5 - 1e-8, 90))).toBe(true);
+    expect(puckPoseChanged(last, pose(13.4, 52.5, 90.001))).toBe(true);
+  });
+
+  it("publishes the metre-scale movement one frame of walking produces", () => {
+    // ~1.4 m/s over a 16 ms frame is ~0.02 m, an order below the camera's own
+    // threshold — the puck still has to track it frame by frame.
+    const last = pose(13.4, 52.5, 90);
+    expect(puckPoseChanged(last, pose(13.4 + 2e-7, 52.5, 90))).toBe(true);
+    expect(
+      cameraPoseChanged({ ...last, zoom: 16 }, { ...pose(13.4 + 2e-7, 52.5, 90), zoom: 16 }, true),
+    ).toBe(false);
+  });
+
+  it("measures rotation along the shortest arc across north", () => {
+    expect(puckPoseChanged(pose(0, 0, 359.99999), pose(0, 0, 0.0))).toBe(false);
+    expect(puckPoseChanged(pose(0, 0, 359.5), pose(0, 0, 0.5))).toBe(true);
+  });
+});
+
+describe("cameraPoseChanged", () => {
+  it("ignores sub-pixel centre and bearing drift", () => {
+    const last = cam(13.4, 52.5, 90, 16);
+    expect(cameraPoseChanged(last, cam(13.4 + CAMERA_LNGLAT_EPSILON / 2, 52.5, 90, 16), true)).toBe(
+      false,
+    );
+    expect(
+      cameraPoseChanged(last, cam(13.4, 52.5, 90 + CAMERA_BEARING_EPSILON / 2, 16), true),
+    ).toBe(false);
+    expect(cameraPoseChanged(last, cam(13.4 + 2e-6, 52.5, 90, 16), true)).toBe(true);
+  });
+
+  it("ignores a sub-threshold zoom drift while commanding zoom", () => {
+    const last = cam(0, 0, 0, 16);
+    expect(cameraPoseChanged(last, cam(0, 0, 0, 16 + CAMERA_ZOOM_EPSILON / 2), true)).toBe(false);
+    expect(cameraPoseChanged(last, cam(0, 0, 0, 16.05), true)).toBe(true);
+  });
+
+  it("never moves the camera for zoom alone once the user owns zoom", () => {
+    const last = cam(0, 0, 0, 16);
+    expect(cameraPoseChanged(last, cam(0, 0, 0, 18), false)).toBe(false);
+    expect(cameraPoseChanged(last, cam(1e-5, 0, 0, 18), false)).toBe(true);
+  });
+});
+
+describe("shouldKeepAnimating", () => {
+  const frame = (over: Partial<Parameters<typeof shouldKeepAnimating>[0]> = {}) =>
+    shouldKeepAnimating({
+      publishedThisFrame: false,
+      settledFrames: SETTLED_FRAMES_BEFORE_SLEEP,
+      holdUntilMs: 0,
+      nowMs: 1000,
+      ...over,
+    });
+
+  it("keeps running while anything was published", () => {
+    expect(frame({ publishedThisFrame: true })).toBe(true);
+  });
+
+  it("keeps running inside a hold window even with nothing to publish", () => {
+    expect(frame({ holdUntilMs: 1001 })).toBe(true);
+    expect(frame({ holdUntilMs: 1000 })).toBe(false);
+  });
+
+  it("needs two settled frames before it sleeps", () => {
+    expect(frame({ settledFrames: 1 })).toBe(true);
+    expect(frame({ settledFrames: 2 })).toBe(false);
+  });
+});

apps/web/src/lib/navigation/navCameraScheduler.ts

@@ -0,0 +1,109 @@
+/**
+ * Visibility predicates for the navigation camera loop, kept pure and free of
+ * MapLibre so the wake/sleep rule can be exercised without a map, a marker or a
+ * frame clock.
+ *
+ * The loop has two jobs that are easy to conflate: integrating a pose every
+ * frame, and publishing that pose to MapLibre. Publication is the expensive
+ * half, so it happens only once a pose has moved far enough to be visible —
+ * and when nothing has been published for a couple of frames there is, by
+ * definition, nothing left to animate and the loop can stop asking for frames.
+ */
+
+/**
+ * Puck thresholds. Repositioning a DOM marker is cheap, so these sit far below
+ * anything renderable (~0.1 mm, ~0.0001°) and exist only to recognise a pose
+ * that has genuinely stopped converging. Anything a traveller can do — down to
+ * a walking pace — clears them on every frame, so the puck's moving cadence is
+ * exactly the frame cadence.
+ */
+export const PUCK_LNGLAT_EPSILON = 1e-9;
+export const PUCK_BEARING_EPSILON = 1e-4;
+/**
+ * Camera thresholds. A `jumpTo` transforms and repaints the whole map, so it is
+ * worth suppressing for a move nobody can see: ~0.1 m of centre drift, a
+ * twentieth of a degree of rotation, and four thousandths of a zoom level.
+ */
+export const CAMERA_LNGLAT_EPSILON = 1e-6;
+export const CAMERA_BEARING_EPSILON = 0.05;
+export const CAMERA_ZOOM_EPSILON = 0.004;
+/**
+ * Consecutive frames that must publish nothing before the loop sleeps. Two,
+ * because the first frame after a wake runs with dt = 0 — the filters cannot
+ * move on it, so a single settled frame is not evidence that the pose has
+ * converged.
+ */
+export const SETTLED_FRAMES_BEFORE_SLEEP = 2;
+
+export interface PuckPose {
+  lng: number;
+  lat: number;
+  bearing: number;
+}
+
+export interface CameraPose extends PuckPose {
+  zoom: number;
+}
+
+/** Shortest angular distance between two bearings, degrees, always positive. */
+function bearingDistance(a: number, b: number): number {
+  return Math.abs(((a - b + 540) % 360) - 180);
+}
+
+function poseChanged(
+  last: PuckPose | null,
+  next: PuckPose,
+  lngLatEpsilon: number,
+  bearingEpsilon: number,
+): boolean {
+  return (
+    !last ||
+    Math.abs(next.lng - last.lng) > lngLatEpsilon ||
+    Math.abs(next.lat - last.lat) > lngLatEpsilon ||
+    bearingDistance(next.bearing, last.bearing) > bearingEpsilon
+  );
+}
+
+/**
+ * Whether a puck pose has moved far enough since the last published one to be
+ * worth another `setLngLat`/`setRotation`. A missing previous pose counts as
+ * changed: the puck has never been placed, or a route/map swap invalidated it.
+ */
+export function puckPoseChanged(last: PuckPose | null, next: PuckPose): boolean {
+  return poseChanged(last, next, PUCK_LNGLAT_EPSILON, PUCK_BEARING_EPSILON);
+}
+
+/**
+ * Whether a camera pose warrants another `jumpTo`. Zoom only participates while
+ * the loop still commands zoom — once the user has taken zoom control the loop
+ * leaves it alone, so a zoom delta must not by itself force a camera transform.
+ */
+export function cameraPoseChanged(
+  last: CameraPose | null,
+  next: CameraPose,
+  commandsZoom: boolean,
+): boolean {
+  if (poseChanged(last, next, CAMERA_LNGLAT_EPSILON, CAMERA_BEARING_EPSILON)) return true;
+  return commandsZoom && !!last && Math.abs(next.zoom - last.zoom) > CAMERA_ZOOM_EPSILON;
+}
+
+export interface FrameSettlement {
+  /** Whether this frame moved the puck or the camera. */
+  publishedThisFrame: boolean;
+  /** Consecutive frames that published nothing, counting this one. */
+  settledFrames: number;
+  /**
+   * `performance.now()` value until which the loop must keep running whatever
+   * the pose does — the enter-follow ease and the post-gesture grace window
+   * both end with a camera hand-back that nothing else would wake.
+   */
+  holdUntilMs: number;
+  nowMs: number;
+}
+
+/** Whether the loop should request another frame after the one just run. */
+export function shouldKeepAnimating(frame: FrameSettlement): boolean {
+  if (frame.nowMs < frame.holdUntilMs) return true;
+  if (frame.publishedThisFrame) return true;
+  return frame.settledFrames < SETTLED_FRAMES_BEFORE_SLEEP;
+}