perf(map): cut INP input-delay — guard rebuild loops, throttle hover query, yield-schedule heavy commit (koala73#5042) (koala73#5045)

* perf(map): add isInputPending() input-path scheduling helper (koala73#5042)

U1 of the INP input-delay plan. Feature-detected (Chromium-only, graceful
false elsewhere), discrete-only no-arg call. Recurring animation loops use
it to skip a rebuild tick when input is queued.

Claude-Session: https://claude.ai/code/session_01Gc3t8s5cdgecwXGxzdq5Xn

* perf(map): cut input-path main-thread work — guard rebuild loops, throttle hover query, yield-schedule heavy commit (koala73#5042)

U2: gate the trade-animation and news-pulse rebuilds on !isInputPending()
so a queued interaction handler runs sooner (terminal pulse-settle render is
never guarded). U3: rAF-throttle the per-mousemove queryRenderedFeatures on the
canvas (the dominant input-delay surface per the 07-08 field pull); cancel the
pending query on mouseout and teardown so it can't re-highlight after leave.
U4: route the DeferredHeavyCommit flush through a yieldToMain-backed adapter
(scheduler.yield ahead of clamped timers) instead of setTimeout(0).

Claude-Session: https://claude.ai/code/session_01Gc3t8s5cdgecwXGxzdq5Xn

* perf(map): surface deferred-flush throws on window.onerror (koala73#5045 review)

A throw from the DeferredHeavyCommit flush was a floating promise rejection;
catch it and rethrow async so it reaches window.onerror -> Sentry exactly as
the replaced setTimeout(fn,0) did. (Greptile P2.)

Claude-Session: https://claude.ai/code/session_01Gc3t8s5cdgecwXGxzdq5Xn

* fix(map): keep throttled hover interactions coherent

* fix(map): skip hover raf when country clicks are disabled

Author: koala73

src/components/DeckGLMap.ts

@@ -75,8 +75,16 @@ import { getCachedFuelShortageRegistry } from '@/shared/fuel-shortage-registry-s
 import { tokenizeForMatch, matchKeyword, matchesAnyKeyword, findMatchingKeywords } from '@/utils/keyword-match';
 import { t } from '@/services/i18n';
 import { debounce, rafSchedule, getCurrentTheme } from '@/utils/index';
+import { isInputPending, scheduleYield } from '@/utils/after-paint';
 import { showLayerWarning } from '@/utils/layer-warning';
 import { localizeMapLabels } from '@/utils/map-locale';
+import {
+  createCountryHoverQueryController,
+  resolveCountryForPointerInteraction,
+  shouldRenderTradeAnimationFrame,
+  shouldRunInputSensitiveMapWork,
+  type CountryHoverQueryController,
+} from './map/input-delay-interactions';
 import { getCachedMilitaryBases, preloadMilitaryBases } from '@/services/military-base-config';
 import {
   INTEL_HOTSPOTS,
@@ -702,13 +710,18 @@ export class DeckGLMap {
     const y = e.clientY - rect.top;
     const lngLat = this.maplibreMap.unproject([x, y]);
     if (!Number.isFinite(lngLat.lng)) return;
+    const country = resolveCountryForPointerInteraction(
+      { code: this.hoveredCountryIso2, name: this.hoveredCountryName },
+      this.hoverQueryThrottle?.isPending() ?? false,
+      () => this.resolveCountryFromCoordinate(lngLat.lng, lngLat.lat),
+    );
     this.onMapContextMenu({
       lat: lngLat.lat,
       lon: lngLat.lng,
       screenX: e.clientX,
       screenY: e.clientY,
-      countryCode: this.hoveredCountryIso2 ?? undefined,
-      countryName: this.hoveredCountryName ?? undefined,
+      countryCode: country?.code,
+      countryName: country?.name,
     });
   };
   private onLayerChange?: (layer: keyof MapLayers, enabled: boolean, source: 'user' | 'programmatic') => void;
@@ -737,7 +750,9 @@ export class DeckGLMap {
    * lands off the measured frame. The gate skips the defer when data is unchanged.
    */
   private readonly heavyGate = new DeferredHeavyCommit<unknown>({
-    schedule: (fn) => { const id = setTimeout(fn, 0); return () => clearTimeout(id); },
+    // Yield the deferred heavy-layer flush off the interaction frame via
+    // scheduler.yield (ahead of clamped timers, behind queued input) — #5042 U4.
+    schedule: (fn) => scheduleYield(fn),
     isAlive: () => !this.renderPaused && !this.webglLost && !!this.maplibreMap,
     onCommit: () => this.updateLayers(true),
   });
@@ -4279,7 +4294,10 @@ export class DeckGLMap {
         return;
       }
       this.pulseTime = now;
-      this.rafUpdateLayers();
+      // Steady-state pulse rebuild: skip when input is queued (#5042 U2). The
+      // terminal settle branch above is never guarded — it must commit the
+      // static end state. pulseTime still advances so no visual state is lost.
+      if (shouldRunInputSensitiveMapWork(isInputPending)) this.rafUpdateLayers();
     }, PULSE_UPDATE_INTERVAL_MS);
   }
 
@@ -4954,11 +4972,12 @@ export class DeckGLMap {
         let country: { code: string; name: string } | null = null;
         if (isChoropleth && info.object?.properties) {
           country = { code: info.object.properties['ISO3166-1-Alpha-2'] as string, name: info.object.properties.name as string };
-        } else if (this.hoveredCountryIso2 && this.hoveredCountryName) {
-          // Use pre-resolved hover state for instant response
-          country = { code: this.hoveredCountryIso2, name: this.hoveredCountryName };
         } else {
-          country = this.resolveCountryFromCoordinate(lon, lat);
+          country = resolveCountryForPointerInteraction(
+            { code: this.hoveredCountryIso2, name: this.hoveredCountryName },
+            this.hoverQueryThrottle?.isPending() ?? false,
+            () => this.resolveCountryFromCoordinate(lon, lat),
+          );
         }
         // Only fire if we have a country — ocean/no-country clicks are silently ignored
         if (country?.code && country?.name) {
@@ -6300,7 +6319,10 @@ export class DeckGLMap {
       this.tradeAnimationTime = (this.tradeAnimationTime + delta * TRADE_ANIMATION_SPEED) % TRADE_ANIMATION_CYCLE;
       this.tradeAnimationFrame = requestAnimationFrame(animate);
       this.tradeAnimationFrameCount++;
-      if (this.tradeAnimationFrameCount % 2 === 0) this.render();
+      // Skip this decorative rebuild when input is queued so the pending
+      // interaction handler runs sooner (#5042 U2). Frame-predictive and
+      // discrete-only; graceful no-op where isInputPending is unsupported.
+      if (shouldRenderTradeAnimationFrame(this.tradeAnimationFrameCount, isInputPending)) this.render();
     };
     this.tradeAnimationFrame = requestAnimationFrame(animate);
   }
@@ -7496,11 +7518,14 @@ export class DeckGLMap {
       map.setFilter('country-hover-border', noMatch);
     };
 
-    map.on('mousemove', (e) => {
+    // rAF-throttle the per-mousemove feature query (#5042 U3). The canvas is the
+    // dominant input-delay surface and queryRenderedFeatures is synchronous, so
+    // coalesce to at most one query per frame; the latest pointer position wins.
+    const runHoverQuery = (point: maplibregl.Point) => {
       if (!this.onCountryClick) return;
       try {
         if (!map.getLayer('country-interactive')) return;
-        const features = map.queryRenderedFeatures(e.point, { layers: ['country-interactive'] });
+        const features = map.queryRenderedFeatures(point, { layers: ['country-interactive'] });
         const props = features?.[0]?.properties;
         const iso2 = props?.['ISO3166-1-Alpha-2'] as string | undefined;
         const name = props?.['name'] as string | undefined;
@@ -7518,9 +7543,25 @@ export class DeckGLMap {
           clearHover();
         }
       } catch { /* style not done loading during theme switch */ }
+    };
+    const hoverQueryThrottle = createCountryHoverQueryController<maplibregl.Point>(
+      rafSchedule,
+      runHoverQuery,
+    );
+    this.hoverQueryThrottle = hoverQueryThrottle;
+
+    map.on('mousemove', (e) => {
+      if (!this.onCountryClick) {
+        hoverQueryThrottle.cancel();
+        return;
+      }
+      hoverQueryThrottle.queue(e.point);
     });
 
     map.on('mouseout', () => {
+      // Cancel a queued query so a deferred rAF cannot re-highlight a country the
+      // pointer has already left (R8); clearHover stays immediate.
+      hoverQueryThrottle.cancel();
       if (hoveredIso2) {
         hoveredIso2 = null;
         try { clearHover(); } catch { /* style not done loading */ }
@@ -7529,6 +7570,7 @@ export class DeckGLMap {
   }
 
   private countryPulseRaf: number | null = null;
+  private hoverQueryThrottle: CountryHoverQueryController<maplibregl.Point> | null = null;
 
   private getHighlightRestOpacity(): { fill: number; border: number } {
     const theme = isLightMapTheme(getMapTheme(getMapProvider())) ? 'light' : 'dark';
@@ -7718,6 +7760,7 @@ export class DeckGLMap {
     this.debouncedFetchBases.cancel();
     this.debouncedFetchAircraft.cancel();
     this.rafUpdateLayers.cancel();
+    this.hoverQueryThrottle?.cancel();
     this.heavyGate.cancel();
 
     if (this.renderRafId !== null) {

src/components/map/input-delay-interactions.ts

@@ -0,0 +1,66 @@
+export interface CountryIdentity {
+  code: string;
+  name: string;
+}
+
+export interface CountryHoverCache {
+  code: string | null;
+  name: string | null;
+}
+
+export type CancelableFrameTask = (() => void) & { cancel(): void };
+
+export interface CountryHoverQueryController<TPoint> {
+  queue(point: TPoint): void;
+  cancel(): void;
+  isPending(): boolean;
+}
+
+export function shouldRunInputSensitiveMapWork(isInputPending: () => boolean): boolean {
+  return !isInputPending();
+}
+
+export function shouldRenderTradeAnimationFrame(frameCount: number, isInputPending: () => boolean): boolean {
+  return frameCount % 2 === 0 && shouldRunInputSensitiveMapWork(isInputPending);
+}
+
+export function resolveCountryForPointerInteraction(
+  hover: CountryHoverCache,
+  hoverQueryPending: boolean,
+  resolveFromCoordinate: () => CountryIdentity | null,
+): CountryIdentity | null {
+  if (!hoverQueryPending && hover.code && hover.name) {
+    return { code: hover.code, name: hover.name };
+  }
+  return resolveFromCoordinate();
+}
+
+export function createCountryHoverQueryController<TPoint>(
+  scheduleFrame: (run: () => void) => CancelableFrameTask,
+  runQuery: (point: TPoint) => void,
+): CountryHoverQueryController<TPoint> {
+  let pendingPoint: TPoint | null = null;
+  let pending = false;
+  const frameTask = scheduleFrame(() => {
+    const point = pendingPoint;
+    pendingPoint = null;
+    pending = false;
+    if (point !== null) runQuery(point);
+  });
+
+  return {
+    queue(point: TPoint): void {
+      pendingPoint = point;
+      pending = true;
+      frameTask();
+    },
+    cancel(): void {
+      pendingPoint = null;
+      pending = false;
+      frameTask.cancel();
+    },
+    isPending(): boolean {
+      return pending;
+    },
+  };
+}

src/utils/after-paint.ts

@@ -57,3 +57,53 @@ export function yieldToMain(): Promise<void> {
   }
   return new Promise((resolve) => { setTimeout(resolve, 0); });
 }
+
+/**
+ * Whether the browser currently has queued input (a click/keypress) waiting to
+ * be dispatched. Recurring, animation-driven work on the input path calls this
+ * and skips its tick when input is pending, so the interaction handler can run
+ * sooner (#5042).
+ *
+ * Feature-detected: `navigator.scheduling.isInputPending` is Chromium-only,
+ * which matches INP being a Chromium-measured metric. Returns `false` wherever
+ * the API is absent (Firefox/Safari/node), so callers degrade to today's
+ * behavior with no functional change.
+ *
+ * Called with no arguments, so it reports DISCRETE input (clicks/keys) only —
+ * `includeContinuous` defaults to `false`. That is the correct scope for the
+ * click/keypress control targets; passing `{ includeContinuous: true }` would
+ * also report pointermove/wheel/drag and stall callers during any hover/pan.
+ */
+export function isInputPending(): boolean {
+  const scheduling = (globalThis as unknown as {
+    navigator?: { scheduling?: { isInputPending?: () => boolean } };
+  }).navigator?.scheduling;
+  if (typeof scheduling?.isInputPending !== 'function') return false;
+  return scheduling.isInputPending();
+}
+
+/**
+ * Adapt `yieldToMain()` to a fire-once scheduler with a cancel handle:
+ * `scheduleYield(run)` runs `run` after the yield resolves and returns a cancel
+ * that prevents it. `DeferredHeavyCommit` (#4558) depends on this shape to
+ * coalesce a burst of stages into one flush and to drop the flush on teardown;
+ * the `yieldToMain` promise can't be cleared, so an abort flag preserves those
+ * semantics. Prefer this over `setTimeout(0)`: `scheduler.yield()` resumes ahead
+ * of clamped timer work (but still behind queued input), lowering commit latency
+ * without newly blocking the input path (#5042 U4).
+ */
+export function scheduleYield(run: () => void): () => void {
+  let aborted = false;
+  void yieldToMain().then(() => {
+    if (aborted) return;
+    try {
+      run();
+    } catch (err) {
+      // Surface a throw from the deferred flush on the global error channel
+      // (window.onerror -> Sentry) exactly as the replaced setTimeout(fn, 0)
+      // did, rather than leaving it as a floating promise rejection.
+      setTimeout(() => { throw err; });
+    }
+  });
+  return () => { aborted = true; };
+}

tests/after-paint-input-pending.test.mts

@@ -0,0 +1,60 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { isInputPending } from '@/utils/after-paint';
+
+type Scheduling = { isInputPending?: (...args: unknown[]) => boolean };
+
+/**
+ * Swap `globalThis.navigator` around a call. Node 22+ ships a real `navigator`
+ * global (configurable), so save/restore its property descriptor rather than a
+ * plain assignment — an ESM (strict-mode) assignment to a getter-only global
+ * would throw.
+ */
+function withNavigator<T>(value: { scheduling?: Scheduling } | undefined, run: () => T): T {
+  const desc = Object.getOwnPropertyDescriptor(globalThis, 'navigator');
+  if (value === undefined) {
+    delete (globalThis as { navigator?: unknown }).navigator;
+  } else {
+    Object.defineProperty(globalThis, 'navigator', { value, configurable: true, writable: true });
+  }
+  try {
+    return run();
+  } finally {
+    if (desc) Object.defineProperty(globalThis, 'navigator', desc);
+    else delete (globalThis as { navigator?: unknown }).navigator;
+  }
+}
+
+test('isInputPending returns true when the API reports pending input (#5042)', () => {
+  const val = withNavigator({ scheduling: { isInputPending: () => true } }, () => isInputPending());
+  assert.equal(val, true);
+});
+
+test('isInputPending returns false when the API reports no pending input', () => {
+  const val = withNavigator({ scheduling: { isInputPending: () => false } }, () => isInputPending());
+  assert.equal(val, false);
+});
+
+test('isInputPending returns false when navigator.scheduling lacks isInputPending (graceful, R6)', () => {
+  const val = withNavigator({ scheduling: {} }, () => isInputPending());
+  assert.equal(val, false);
+});
+
+test('isInputPending returns false when navigator.scheduling is absent (R6)', () => {
+  const val = withNavigator({}, () => isInputPending());
+  assert.equal(val, false);
+});
+
+test('isInputPending returns false when navigator is absent (node/SSR, R6)', () => {
+  const val = withNavigator(undefined, () => isInputPending());
+  assert.equal(val, false);
+});
+
+test('isInputPending calls the API with no arguments (discrete-only scope)', () => {
+  let receivedArgs: unknown[] | null = null;
+  withNavigator(
+    { scheduling: { isInputPending: (...args: unknown[]) => { receivedArgs = args; return false; } } },
+    () => isInputPending(),
+  );
+  assert.deepEqual(receivedArgs, [], 'no-arg call keeps includeContinuous at its false default');
+});

tests/after-paint-yield.test.mts

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { yieldToMain } from '@/utils/after-paint';
+import { yieldToMain, scheduleYield } from '@/utils/after-paint';
 
 type SchedulerHost = { scheduler?: { yield?: () => Promise<void> } };
 
@@ -51,3 +51,54 @@ test('yieldToMain returns a Promise in both paths (signature preserved)', () =>
   assert.ok(withoutYield instanceof Promise);
   return Promise.all([withYield, withoutYield]);
 });
+
+test('scheduleYield runs the callback after the yield resolves (#5042 U4)', async () => {
+  let ran = 0;
+  await withScheduler({ yield: () => Promise.resolve() }, async () => {
+    scheduleYield(() => { ran += 1; });
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+  assert.equal(ran, 1, 'callback fires once after the yield');
+});
+
+test('scheduleYield cancel before resolution prevents the callback (coalesce/teardown, U4)', async () => {
+  let ran = 0;
+  await withScheduler({ yield: () => Promise.resolve() }, async () => {
+    const cancel = scheduleYield(() => { ran += 1; });
+    cancel();
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+  assert.equal(ran, 0, 'a pre-resolution cancel drops the flush');
+});
+
+test('scheduleYield rethrows deferred callback errors on the timer channel (#5042 U4)', async () => {
+  const sentinel = new Error('deferred flush failed');
+  let timerHandler: (() => void) | null = null;
+  const originalSetTimeout = globalThis.setTimeout;
+  globalThis.setTimeout = ((handler: Parameters<typeof globalThis.setTimeout>[0]) => {
+    assert.equal(typeof handler, 'function', 'scheduleYield should surface errors with a function timer');
+    timerHandler = handler as () => void;
+    return 0 as ReturnType<typeof globalThis.setTimeout>;
+  }) as typeof globalThis.setTimeout;
+
+  try {
+    await withScheduler({ yield: () => Promise.resolve() }, async () => {
+      scheduleYield(() => { throw sentinel; });
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    assert.ok(timerHandler, 'failed deferred flush should be rethrown via setTimeout');
+    assert.throws(
+      () => { timerHandler?.(); },
+      (err) => err === sentinel,
+    );
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+  }
+});