rescale synthetic prices to cents and throttle editorial cells to 4 Hz (#26)

Two related polish changes from observing the live demo at
https://meridian-orderbook.pages.dev.

First, the synthetic generator was emitting prices as integer dollars
in a narrow [95, 105] band, so the minimum spread was always $1 and
the "Spread 2.00" cell read as "200.0 bp wide" on the dashboard.
That is technically a $2 spread on a $100 stock, which is enormous
for a liquid name and looked broken. Rescale the price model: anchor
at 10000 cents ($100.00), reference walks +/-2 cents per event with
bounded mean reversion to anchor, limit orders cluster within 5
cents of the reference, per-order quantity range [5, 40]. Spreads
now land at 1 to 5 bp ("tight"), the dashboard reads like a real
instrument. Local verification at seed 42 over 20s steady state:
top size median 761 in [451, 1700], spread median 2 cents in [1, 5].

formatPrice and formatSpread in the frontend divide by 100 before
rendering so the cells display "$100.01" instead of "10001".

Second, the editorial cells (Hero Last, Spread, Top size; Ladder L1
row; DepthChart geometry; PerfPanel book-state cells) were updating
on every WebSocket delta at 30 Hz. Real-time financial dashboards
(Bloomberg, Refinitiv, Eikon) refresh headline numerics at 2 to 5 Hz
because faster reads as flicker rather than as throughput. Add a
displayedTop slice to the Zustand store that mirrors top at a
throttled cadence; a new useDisplayThrottle hook runs the mirror at
4 Hz (250 ms). Selectors reading displayedTop only re-render when
the reference changes, so the components that need live data (the
PerfPanel wire counters, the perf histogram) continue to read top
directly. A fresh snapshot eagerly populates displayedTop so the
dashboard leaves the connecting skeleton immediately.

Tests:

* `tests/unit/test_ws_origin.cpp` and the rest of the C++ suite stay
  at 182/182.
* Three new Vitest cases cover the throttle: snapshot eagerly
  populates displayedTop, deltas update top but leave displayedTop
  alone until flushDisplayed is called, flushDisplayed is a no-op
  when top has not advanced. Total Vitest count: 18/18.

Author: MustafaNazeer

apps/server/main.cpp

@@ -204,29 +204,31 @@ int main(int argc, char** argv) {
 
     // Engine thread: synthetic limit / market / cancel mix.
     //
-    // The price model tracks a slowly drifting reference mid: every event
-    // nudges it by at most one tick with a strong pull toward the anchor
-    // (kAnchor = 100), so the displayed top of book moves like a real
-    // instrument rather than skipping uniformly across a wide range. New
-    // limit orders cluster near the current reference (one to four ticks
-    // off depending on side), so a tight visible spread builds and
-    // moves a tick at a time. The event mix favors limit orders so the
-    // book accumulates depth between cancels and market sweeps.
+    // The price model tracks a slowly drifting reference mid in cents
+    // (kAnchor = 10000 = $100.00), so the displayed top of book moves
+    // like a real instrument with realistic 1-to-3-cent spreads. New
+    // limit orders cluster near the current reference within 30 cents
+    // on either side, so a tight visible spread builds and moves at
+    // cent granularity. The event mix favors limit and cancel orders
+    // so the book reaches a steady state in the low hundreds of
+    // resting quantity rather than accumulating indefinitely.
     std::thread engine_thr([&]() {
         std::mt19937_64 rng(cfg.seed);
-        constexpr int kAnchor = 100;
-        constexpr int kPriceFloor = 92;
-        constexpr int kPriceCeiling = 108;
+        constexpr int kAnchor = 10000;       // $100.00 expressed in cents
+        constexpr int kPriceFloor = 9000;    // $90.00
+        constexpr int kPriceCeiling = 11000; // $110.00
         int reference = kAnchor;
 
-        std::uniform_int_distribution<int> offset_dist(0, 3);   // ticks off the mid
-        std::uniform_int_distribution<int> drift_dist(-1, 1);   // small random walk
-        // Small order sizes keep the per-level resting depth in a
-        // visually legible range (top size lands around 100 to 300
-        // qty in steady state, not 1000+). The bench binary still
-        // exercises the engine at much higher per-event quantities;
-        // the live demo runs in a range a viewer can read.
-        std::uniform_int_distribution<int> qty_dist(1, 6);
+        // Orders cluster within a 5-cent band of the reference so the
+        // visible top of book carries real depth rather than scattering
+        // thin across many levels.
+        std::uniform_int_distribution<int> offset_dist(0, 5);   // cents off the mid
+        std::uniform_int_distribution<int> drift_dist(-2, 2);   // cents per event
+        // Per-order quantities are in the 5 to 40 range so each event
+        // measurably shifts the visible numerals but the per-level
+        // size stays in the readable hundreds-to-low-thousands range
+        // at steady state.
+        std::uniform_int_distribution<int> qty_dist(5, 40);
         std::uniform_int_distribution<int> bucket(0, 99);
         std::bernoulli_distribution side_dist(0.5);
 
@@ -246,21 +248,21 @@ int main(int argc, char** argv) {
             ev.ts = ++ts;
             ev.side = side_dist(rng) ? meridian::Side::Buy : meridian::Side::Sell;
 
-            // Mean-reverting random walk: each event nudges the
-            // reference at most one tick. At the anchor the step is a
-            // free uniform draw over {-1, 0, +1}; away from the anchor
-            // the away-direction step is suppressed so the reference
-            // drifts back toward the anchor over time. This keeps the
-            // displayed top of book within a few ticks of kAnchor.
+            // Mean-reverting random walk in cents. At the anchor the
+            // step is a free uniform draw over the drift_dist range;
+            // away from the anchor the away-from-anchor step is
+            // suppressed so the reference drifts back over time.
+            // Toward-anchor steps of any magnitude are allowed (so the
+            // walk can correct quickly if it has drifted multiple
+            // cents off the anchor).
             const int raw_step = drift_dist(rng);
             const int pull = reference > kAnchor ? -1 : (reference < kAnchor ? 1 : 0);
             int step;
-            if (pull == 0) {
-                step = raw_step;
-            } else if (raw_step == 0 || raw_step == pull) {
+            if (pull == 0 || raw_step == 0) {
                 step = raw_step;
             } else {
-                step = 0;
+                const bool toward_anchor = (raw_step * pull) > 0;
+                step = toward_anchor ? raw_step : 0;
             }
             reference += step;
             if (reference < kPriceFloor) reference = kPriceFloor;

frontend/src/App.tsx

@@ -6,11 +6,13 @@ import { Hero } from './components/Hero';
 import { Ladder } from './components/Ladder';
 import { PerfPanel } from './components/PerfPanel';
 import { Tape } from './components/Tape';
+import { useDisplayThrottle } from './hooks/useDisplayThrottle';
 import { useMeridianStream } from './hooks/useMeridianStream';
 import { useDashboard } from './store/dashboard';
 
 function App() {
   useMeridianStream();
+  useDisplayThrottle();
   const state = useDashboard((s) => s.connectionState);
   const fadedNumerics = state === 'stalled' || state === 'disconnected';
   return (

frontend/src/components/DepthChart.tsx

@@ -7,7 +7,7 @@ import { SectionHead } from './SectionHead';
 // section aux makes it clear this is the v1 view until the extended
 // snapshot payload lands.
 export function DepthChart() {
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const state = useDashboard((s) => s.connectionState);
   const ready = state !== 'connecting' && top !== null;
 

frontend/src/components/Hero.tsx

@@ -13,7 +13,7 @@ function Skeleton({ w = 80, h = 32 }: { w?: number; h?: number }) {
 }
 
 function StatLast() {
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const color = useDashboard((s) => s.lastTickColor);
   const ready = useDashboard((s) => s.connectionState !== 'connecting');
   const bidPx = top?.bidPx ?? null;
@@ -55,7 +55,7 @@ function StatLast() {
 }
 
 function StatSpread() {
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const ready = useDashboard((s) => s.connectionState !== 'connecting');
   const s = formatSpread(top?.bidPx ?? null, top?.askPx ?? null);
   return (
@@ -85,7 +85,7 @@ function StatSpread() {
 }
 
 function StatBookSize() {
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const ticks = useDashboard((s) => s.ticksSinceConnect);
   const ready = useDashboard((s) => s.connectionState !== 'connecting');
   const totalQty = (top?.bidQty ?? 0) + (top?.askQty ?? 0);
@@ -123,7 +123,7 @@ function HeroIdentity() {
   const state = useDashboard((s) => s.connectionState);
   const symbol = useDashboard((s) => s.selectedSymbol);
   const ticks = useDashboard((s) => s.ticksSinceConnect);
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const meta = symbolMeta(symbol);
 
   if (state === 'connecting') {

frontend/src/components/Ladder.tsx

@@ -87,7 +87,7 @@ function SpreadRow({ bidPx, askPx }: { bidPx: number | null; askPx: number | nul
 }
 
 export function Ladder() {
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const state = useDashboard((s) => s.connectionState);
   const ready = state !== 'connecting';
 

frontend/src/components/PerfPanel.tsx

@@ -87,7 +87,7 @@ function PerfLatency() {
 }
 
 function PerfBookState() {
-  const top = useDashboard((s) => s.top);
+  const top = useDashboard((s) => s.displayedTop);
   const ticks = useDashboard((s) => s.ticksSinceConnect);
   return (
     <div data-element="PerfBookState" className="mb-8">

frontend/src/hooks/useDisplayThrottle.ts

@@ -0,0 +1,23 @@
+import { useEffect } from 'react';
+import { useDashboard } from '../store/dashboard';
+
+// Default throttle interval. 250 ms (4 Hz) is roughly the slowest the
+// eye can absorb numeric updates without feeling broken; faster reads
+// as flicker, slower reads as stale. The Bloomberg / Refinitiv
+// terminal cadence is in the 2 to 5 Hz range and this lands in the
+// middle of that band.
+const DEFAULT_INTERVAL_MS = 250;
+
+// Throttle the rendered editorial cells (Hero stats, Ladder, Tape) to
+// a human-legible cadence while the underlying WebSocket stream keeps
+// running at 30 Hz for the perf panel and depth chart inputs. The
+// throttle works by mirroring `top` into `displayedTop` on a fixed
+// interval; selectors reading `displayedTop` only re-render when the
+// store entry changes reference.
+export function useDisplayThrottle(intervalMs: number = DEFAULT_INTERVAL_MS): void {
+  const flush = useDashboard((s) => s.flushDisplayed);
+  useEffect(() => {
+    const id = window.setInterval(flush, intervalMs);
+    return () => window.clearInterval(id);
+  }, [flush, intervalMs]);
+}

frontend/src/lib/format.ts

@@ -1,13 +1,13 @@
 // Display formatting helpers. Numbers from the wire arrive as integer
-// engine ticks; the synthetic event generator in apps/server emits
-// prices in the small 95..105 range, so the dashboard renders raw
-// ticks as-is rather than pretending they are dollars. When the
-// extended snapshot payload (real ITCH prices, currency-scaled) lands,
-// this module is the single place to widen the conversion.
+// engine ticks where one tick equals one cent (so $100.00 corresponds
+// to 10000 ticks). The helpers below divide by 100 to display as
+// currency with two decimal places.
+
+const CENTS_PER_DOLLAR = 100;
 
 export function formatPrice(px: number | null): string {
   if (px === null) return '—';
-  return px.toFixed(2);
+  return (px / CENTS_PER_DOLLAR).toFixed(2);
 }
 
 export function formatQty(qty: number): string {
@@ -22,12 +22,12 @@ export function formatSpread(bidPx: number | null, askPx: number | null): {
   if (bidPx === null || askPx === null) {
     return { abs: '—', bps: '—', band: 'normal' };
   }
-  const spread = askPx - bidPx;
+  const spreadCents = askPx - bidPx;
   const mid = (askPx + bidPx) / 2;
-  const bps = mid > 0 ? (spread / mid) * 10_000 : 0;
+  const bps = mid > 0 ? (spreadCents / mid) * 10_000 : 0;
   const band = bps < 4 ? 'tight' : bps > 12 ? 'wide' : 'normal';
   return {
-    abs: spread.toFixed(2),
+    abs: (spreadCents / CENTS_PER_DOLLAR).toFixed(2),
     bps: bps.toFixed(1),
     band,
   };

frontend/src/store/dashboard.test.ts

@@ -87,4 +87,34 @@ describe('useDashboard', () => {
     expect(s.reconnectAttempt).toBe(3);
     expect(s.reconnectInMs).toBe(2_000);
   });
+
+  it('a snapshot eagerly populates displayedTop so the dashboard leaves the connecting skeleton immediately', () => {
+    useDashboard.getState().applySnapshot(tob(10000, 10001, 1), 0);
+    const s = useDashboard.getState();
+    expect(s.displayedTop).not.toBeNull();
+    expect(s.displayedTop?.bidPx).toBe(10000);
+    expect(s.displayedTop?.askPx).toBe(10001);
+  });
+
+  it('deltas update top but leave displayedTop alone until flushDisplayed is called', () => {
+    useDashboard.getState().applySnapshot(tob(10000, 10001, 1), 0);
+    const initial = useDashboard.getState().displayedTop;
+    useDashboard.getState().applyDelta(tob(10001, 10002, 2), 0);
+    useDashboard.getState().applyDelta(tob(10002, 10003, 3), 0);
+    const afterDeltas = useDashboard.getState();
+    expect(afterDeltas.top?.ts).toBe(3);
+    // displayedTop still references the snapshot, not the latest delta:
+    expect(afterDeltas.displayedTop).toBe(initial);
+
+    useDashboard.getState().flushDisplayed();
+    const afterFlush = useDashboard.getState();
+    expect(afterFlush.displayedTop?.ts).toBe(3);
+  });
+
+  it('flushDisplayed is a no-op when top has not changed since the last flush', () => {
+    useDashboard.getState().applySnapshot(tob(10000, 10001, 1), 0);
+    const ref = useDashboard.getState().displayedTop;
+    useDashboard.getState().flushDisplayed();
+    expect(useDashboard.getState().displayedTop).toBe(ref);
+  });
 });

frontend/src/store/dashboard.ts

@@ -30,6 +30,12 @@ export type DashboardState = {
   connectionState: ConnectionState;
   selectedSymbol: Symbol;
   top: TopOfBook | null;
+  // `displayedTop` mirrors `top` at a throttled cadence (see
+  // hooks/useDisplayThrottle). The editorial cells (Hero stats, Ladder,
+  // Tape) read this so their numerals refresh at a human-legible rate;
+  // the wire counters and depth-chart inputs continue to read `top` so
+  // the perf panel and chart stay accurate.
+  displayedTop: TopOfBook | null;
   prevLast: LastTick | null;
   lastTickColor: 'up' | 'down' | 'flat';
   ticksSinceConnect: number;
@@ -45,6 +51,7 @@ export type DashboardState = {
   applyDelta: (t: TopOfBook, bytes: number) => void;
   notePerfTick: (perSec: { deltas: number; bytes: number }) => void;
   setReconnect: (attempt: number, inMs: number) => void;
+  flushDisplayed: () => void;
   reset: () => void;
 };
 
@@ -61,6 +68,7 @@ export const useDashboard = create<DashboardState>((set) => ({
   connectionState: 'connecting',
   selectedSymbol: 'AAPL',
   top: null,
+  displayedTop: null,
   prevLast: null,
   lastTickColor: 'flat',
   ticksSinceConnect: 0,
@@ -75,6 +83,7 @@ export const useDashboard = create<DashboardState>((set) => ({
     set({
       selectedSymbol: s,
       top: null,
+      displayedTop: null,
       prevLast: null,
       lastTickColor: 'flat',
       ticksSinceConnect: 0,
@@ -88,6 +97,10 @@ export const useDashboard = create<DashboardState>((set) => ({
       const history = lastMid !== null ? [{ px: lastMid, ts: t.ts }] : [];
       return {
         top: t,
+        // A snapshot is the start of a stream: mirror immediately to
+        // displayedTop so the editorial cells leave the connecting
+        // skeleton without waiting for the next throttle tick.
+        displayedTop: t,
         // A snapshot is the start of a stream; reset prior-tick state.
         prevLast: null,
         lastTickColor: 'flat',
@@ -155,10 +168,18 @@ export const useDashboard = create<DashboardState>((set) => ({
       connectionState: 'disconnected',
     }),
 
+  // Mirror the latest `top` into `displayedTop`. Called from a 4 Hz
+  // interval in App.tsx (via useDisplayThrottle), this throttles
+  // rendering of the editorial cells without throttling the underlying
+  // wire stream.
+  flushDisplayed: () =>
+    set((prev) => (prev.top === prev.displayedTop ? {} : { displayedTop: prev.top })),
+
   reset: () =>
     set({
       connectionState: 'connecting',
       top: null,
+      displayedTop: null,
       prevLast: null,
       lastTickColor: 'flat',
       ticksSinceConnect: 0,