MarkusNeusinger
diff --git a/‎app/src/pages/MapPage.test.tsx‎
Lines changed: 209 additions & 7 deletions b/‎app/src/pages/MapPage.test.tsx‎
Lines changed: 209 additions & 7 deletions
@@ -1,8 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { forwardRef, useImperativeHandle } from 'react';
+import { fireEvent } from '@testing-library/react';
 
 import { act, render, screen, waitFor } from '../test-utils';
-import { MapPage } from './MapPage';
+import { MapPage, outlierSquashForce, type SimNode } from './MapPage';
 
 
 vi.mock('react-helmet-async', () => ({
@@ -53,11 +54,20 @@ type FgInstance = {
   refresh: ReturnType<typeof vi.fn>;
   __forcesWired?: boolean;
 };
+// Captures the (forceName, forceFn) pairs registered via `fg.d3Force(...)`
+// during onRenderFramePre. Lets tests assert that the custom outlier-squash
+// force was wired up — without it the d3Force mock would just throw away
+// the function and we couldn't tell apart the four built-in forces from
+// the new one.
+const registeredForces: Map<string, unknown> = new Map();
 const fgInstance: FgInstance = {
   centerAt: vi.fn(),
   zoom: vi.fn().mockReturnValue(1),
   zoomToFit: vi.fn(),
-  d3Force: vi.fn().mockReturnValue({ strength: vi.fn().mockReturnThis(), distance: vi.fn().mockReturnThis() }),
+  d3Force: vi.fn().mockImplementation((name: string, fn?: unknown) => {
+    if (fn !== undefined) registeredForces.set(name, fn);
+    return { strength: vi.fn().mockReturnThis(), distance: vi.fn().mockReturnThis() };
+  }),
   d3ReheatSimulation: vi.fn(),
   refresh: vi.fn(),
 };
@@ -165,7 +175,11 @@ describe('MapPage', () => {
     fgInstance.centerAt.mockReset();
     fgInstance.zoom.mockReset().mockReturnValue(1);
     fgInstance.zoomToFit.mockReset();
-    fgInstance.d3Force.mockReset().mockReturnValue({ strength: vi.fn().mockReturnThis(), distance: vi.fn().mockReturnThis() });
+    registeredForces.clear();
+    fgInstance.d3Force.mockReset().mockImplementation((name: string, fn?: unknown) => {
+      if (fn !== undefined) registeredForces.set(name, fn);
+      return { strength: vi.fn().mockReturnThis(), distance: vi.fn().mockReturnThis() };
+    });
     fgInstance.d3ReheatSimulation.mockReset();
     fgInstance.refresh.mockReset();
     fgInstance.__forcesWired = undefined;
@@ -332,13 +346,16 @@ describe('MapPage', () => {
     render(<MapPage />);
     await waitFor(() => expect(screen.getByTestId('force-graph-2d')).toBeInTheDocument());
 
-    // Gate is visible while the engine is still cooling.
-    expect(screen.getByText(/arranging/i)).toBeInTheDocument();
+    // Gate is visible (role="status" is reachable) while the engine is still cooling.
+    expect(screen.getByRole('status')).toHaveTextContent(/map\.simulate\(\)/);
 
-    // Engine stops → settled flips → overlay disappears.
+    // Engine stops → settled flips → overlay sets aria-hidden=true and fades.
+    // We keep the node in the DOM for the fade transition, so query-by-role
+    // (which filters aria-hidden by default) is the right invariant: it
+    // becomes unreachable to assistive tech the moment the gate is settled.
     const onEngineStop = lastFgProps.current!.onEngineStop as () => void;
     act(() => onEngineStop());
-    await waitFor(() => expect(screen.queryByText(/arranging/i)).not.toBeInTheDocument());
+    await waitFor(() => expect(screen.queryByRole('status')).not.toBeInTheDocument());
   });
 
   it('frames the bbox via centerAt + zoom on engine stop', async () => {
@@ -381,4 +398,189 @@ describe('MapPage', () => {
     expect(mockNavigate).toHaveBeenCalledWith('/scatter-basic');
     expect(mockTrackEvent).toHaveBeenCalledWith('map_node_click', { spec: 'scatter-basic' });
   });
+
+  describe('outlierSquashForce', () => {
+    // Pure unit tests that exercise the force math directly. We bypass the
+    // d3-force harness because the force's contract is "modify vx/vy of
+    // outlier nodes in place"; the harness adds nothing beyond invoking
+    // force(alpha) and force.initialize(nodes).
+    type Sim = SimNode & { x: number; y: number; vx: number; vy: number };
+    const makeNode = (x: number, y: number): Sim => ({ x, y, vx: 0, vy: 0 });
+
+    it('is a no-op when there are no nodes', () => {
+      const force = outlierSquashForce(0.95, 200, 0.18);
+      // initialize with empty array; force(alpha) must not throw.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (force as unknown as { initialize: (n: SimNode[]) => void }).initialize([]);
+      expect(() => force(1)).not.toThrow();
+    });
+
+    it('is a no-op for graphs of fewer than 2 nodes', () => {
+      const force = outlierSquashForce(0.95, 200, 0.18);
+      const nodes: Sim[] = [makeNode(1000, 0)];
+      (force as unknown as { initialize: (n: SimNode[]) => void }).initialize(nodes);
+      force(1);
+      expect(nodes[0].vx).toBe(0);
+      expect(nodes[0].vy).toBe(0);
+    });
+
+    it('leaves nodes inside the threshold untouched (inner geometry preserved)', () => {
+      // 99 inner nodes co-located at the origin + 1 far outlier. All inner
+      // distances to the centroid are exactly equal, so the percentile
+      // cutoff R lands exactly at the inner radius and the early
+      // `r <= R → continue` short-circuit fires for every inner node.
+      // The outlier is the only node above R.
+      const force = outlierSquashForce(0.95, 200, 0.18);
+      const inner: Sim[] = Array.from({ length: 99 }, () => makeNode(0, 0));
+      const outlier = makeNode(5000, 0);
+      const nodes: Sim[] = [...inner, outlier];
+      (force as unknown as { initialize: (n: SimNode[]) => void }).initialize(nodes);
+      force(1);
+      for (const n of inner) {
+        expect(n.vx).toBe(0);
+        expect(n.vy).toBe(0);
+      }
+      // Outlier was pulled inward — vx is opposite-sign to its position.
+      expect(outlier.vx).toBeLessThan(0);
+      expect(outlier.vy).toBe(0);
+    });
+
+    it('still squashes outliers in small graphs (off-by-one regression guard)', () => {
+      // Naive `floor(length * p)` would pick index 19 (the max) on n = 20
+      // and never trigger the squash. The (n - 1) * p indexing must keep
+      // at least the most-outlying node above R.
+      const force = outlierSquashForce(0.95, 200, 0.18);
+      const nodes: Sim[] = Array.from({ length: 20 }, (_, i) => makeNode(i, 0));
+      // Push the last node much further so it's the unambiguous outlier.
+      nodes[19] = makeNode(10_000, 0);
+      (force as unknown as { initialize: (n: SimNode[]) => void }).initialize(nodes);
+      force(1);
+      // The outlier must have a non-zero inward correction.
+      expect(nodes[19].vx).not.toBe(0);
+      expect(nodes[19].vx).toBeLessThan(0);
+    });
+
+    it('keeps the velocity correction finite even for distant outliers', () => {
+      // The compression map r' = R + (r - R)/(1 + (r - R)/k) has an
+      // asymptote at R + k, so even a node at distance 1e6 produces a
+      // bounded velocity correction. This is the property that prevents
+      // a single rogue node from blowing up the simulation.
+      const force = outlierSquashForce(0.95, 200, 0.18);
+      const inner: Sim[] = Array.from({ length: 99 }, () => makeNode(0, 0));
+      const far = makeNode(1_000_000, 0);
+      const nodes: Sim[] = [...inner, far];
+      (force as unknown as { initialize: (n: SimNode[]) => void }).initialize(nodes);
+      force(1);
+      expect(far.vx).toBeLessThan(0);
+      expect(Number.isFinite(far.vx)).toBe(true);
+      // |vx| upper bound: |position - 0| * strength * alpha = 1e6 * 0.18.
+      // The actual value is much smaller because (targetR - r) / r is
+      // close to -1 once r >> R, so the correction approaches -position.
+      expect(Math.abs(far.vx)).toBeLessThan(1_000_000);
+    });
+
+    it('scales the velocity correction with alpha', () => {
+      const force = outlierSquashForce(0.95, 200, 0.18);
+      const inner: Sim[] = Array.from({ length: 99 }, () => makeNode(0, 0));
+      const hot = makeNode(5_000, 0);
+      const cool = makeNode(5_000, 0);
+      // First simulation — alpha = 1 (hot).
+      (force as unknown as { initialize: (n: SimNode[]) => void }).initialize([...inner, hot]);
+      force(1);
+      // Second simulation — alpha = 0.1 (cooling).
+      const force2 = outlierSquashForce(0.95, 200, 0.18);
+      const inner2: Sim[] = Array.from({ length: 99 }, () => makeNode(0, 0));
+      (force2 as unknown as { initialize: (n: SimNode[]) => void }).initialize([...inner2, cool]);
+      force2(0.1);
+      // Cooler alpha → ~10× smaller velocity correction.
+      expect(Math.abs(hot.vx)).toBeGreaterThan(Math.abs(cool.vx) * 5);
+    });
+  });
+
+  it('registers an outlier-squash force on the simulation via onRenderFramePre', async () => {
+    mockFetchSuccess();
+    render(<MapPage />);
+    await waitFor(() => expect(lastFgProps.current).not.toBeNull());
+
+    // Trigger the lazy force-wiring side effect — onRenderFramePre is
+    // idempotent, so we can call it directly.
+    const onRenderFramePre = lastFgProps.current!.onRenderFramePre as () => void;
+    act(() => onRenderFramePre());
+
+    // The custom force key must have been registered alongside the
+    // built-in charge / link / collide / center forces.
+    expect(registeredForces.has('outlier-squash')).toBe(true);
+    expect(typeof registeredForces.get('outlier-squash')).toBe('function');
+  });
+
+  it('advances the progress bar as onEngineTick fires', async () => {
+    mockFetchSuccess();
+    render(<MapPage />);
+    // Wait for the canvas mount; once it's there, `ready` is true and the
+    // overlay's progressbar is in the DOM. (Same pattern as the existing
+    // settling-overlay test.)
+    await waitFor(() => expect(screen.getByTestId('force-graph-2d')).toBeInTheDocument());
+
+    // Two elements have role="progressbar" — MUI's CircularProgress (the
+    // spinner) and our hand-rolled determinate bar. Disambiguate via the
+    // bar's unique aria-label.
+    const bar = screen.getByRole('progressbar', { name: 'Layout computation progress' });
+    expect(bar).toHaveAttribute('aria-valuenow', '0');
+
+    // Tick progress is throttled to a flush every 6 ticks; fire enough
+    // ticks to cross the throttle boundary at least once.
+    const onEngineTick = lastFgProps.current!.onEngineTick as () => void;
+    act(() => {
+      for (let i = 0; i < 18; i++) onEngineTick();
+    });
+
+    const after = Number(bar.getAttribute('aria-valuenow'));
+    expect(after).toBeGreaterThan(0);
+    expect(after).toBeLessThanOrEqual(100);
+  });
+
+  it('re-arms the settling overlay when graphData re-derives (weight change)', async () => {
+    // Regression guard for the gate re-arm path. When the user moves a
+    // weights slider, `weights` state changes → graphData useMemo
+    // re-derives with a new identity → the prevGraphData ≠ graphData
+    // branch in render must reset settled/tickProgress so the user sees
+    // the loading indicator return for the new cooling phase. Without
+    // this test, that path is exercised only via manual UI interaction.
+    mockFetchSuccess();
+    render(<MapPage />);
+    await waitFor(() => expect(screen.getByTestId('force-graph-2d')).toBeInTheDocument());
+
+    // 1. Initial state: gate is visible, progressbar reachable.
+    expect(
+      screen.getByRole('progressbar', { name: 'Layout computation progress' }),
+    ).toHaveAttribute('aria-valuenow', '0');
+
+    // 2. Cool the simulation. settled flips true → gate gets
+    //    aria-hidden=true → queryByRole filters it out.
+    const onEngineStop = lastFgProps.current!.onEngineStop as () => void;
+    act(() => onEngineStop());
+    await waitFor(() =>
+      expect(
+        screen.queryByRole('progressbar', { name: 'Layout computation progress' }),
+      ).not.toBeInTheDocument(),
+    );
+
+    // 3. Open the weights panel and bump a slider. The first slider in
+    //    the panel is for the `plot_type` category — changing it
+    //    triggers setWeights, weights changes, graphData re-derives.
+    fireEvent.click(screen.getByText(/^weights/));
+    const sliders = await screen.findAllByRole('slider');
+    expect(sliders.length).toBeGreaterThan(0);
+    // MUI Slider's hidden <input type="range"> responds to change events.
+    act(() => {
+      fireEvent.change(sliders[0], { target: { value: '4' } });
+    });
+
+    // 4. Gate re-armed: progressbar reachable again, aria-valuenow back
+    //    to 0 (tickCountRef was reset alongside settled).
+    await waitFor(() => {
+      const bar = screen.getByRole('progressbar', { name: 'Layout computation progress' });
+      expect(bar).toHaveAttribute('aria-valuenow', '0');
+    });
+  });
 });