fix(awareness): stop the subject echoing itself and cover the echo wiring

Remaining review follow-ups for the sonar pulses.

No self-echo: pulses are born 5 km out (startFraction of the radius),
but contacts nearer than that, the subject included, still lit on every
pulse birth. They now never echo. Just past the birth ring, an echo is
scaled with the front's own fade-in, so a bracket no longer flashes
before a visible front reaches it. The ring flash at the full radius is
unchanged.

Older Safari: the reduced-motion listener falls back to the media
query's addListener / removeListener when addEventListener is missing,
as other modules here already do.

Echo wiring test: a detectionHost test now paints through the real
detection lane with an echo field set, and checks the echo stroke takes
the echo colour on the default style and each style's line colour under
CRT, NVG and FLIR. CURRENT-STATE notes the 5 km no-echo zone.

src/awarenessEcho.js

@@ -13,7 +13,7 @@ import * as Cesium from 'cesium';
  * @property {Cesium.Cartesian3} center Subject's ground point. The publisher
  *   may move it in place; it is read on every query.
  * @property {number} radiusM Range the pulses grow to.
- * @property {{count: number, periodMs: number, startFraction: number}} pulse
+ * @property {{count: number, periodMs: number, startFraction: number, fadeInFraction?: number}} pulse
  * @property {{fadeMs: number, layerIds: string[]}} echo
  * @property {(nowMs: number) => number} [level] How far the pulses are
  *   switched on, 0 to 1; echoes scale with it, so they rest with the pulses.
@@ -50,22 +50,27 @@ export function getAwarenessEchoField() {
  * its distance, fading as (1 - elapsed / `fadeMs`) squared, 0 otherwise. The
  * strongest pulse wins. A front that has wrapped back to the centre still
  * counts for the contact it last crossed, so rim contacts fade out instead of
- * cutting off.
+ * cutting off. Nothing nearer than the birth ring `startFraction` out echoes,
+ * and within the pulse's `fadeInFraction` the echo is scaled down with it.
  * @param {number} nowMs Monotonic clock in milliseconds.
  * @param {number} distanceM Contact's distance from the subject.
  * @param {number} radiusM Range the pulses grow to.
- * @param {{count: number, periodMs: number, startFraction: number}} pulse
+ * @param {{count: number, periodMs: number, startFraction: number, fadeInFraction?: number}} pulse
  * @param {{fadeMs: number}} echo
  * @returns {number} 0 to 1.
  */
 export function awarenessEchoStrength(nowMs, distanceM, radiusM, pulse, echo) {
-  if (!Number.isFinite(distanceM) || distanceM < 0 || distanceM > radiusM)
+  // Pulses are born `startFraction` out, so nothing nearer (the subject
+  // itself, its wingmen) is ever crossed; without this it lit on every birth.
+  if (
+    !Number.isFinite(distanceM) ||
+    distanceM < radiusM * pulse.startFraction ||
+    distanceM > radiusM
+  )
     return 0;
   // The phase at which a pulse front sits at this distance.
-  const touchPhase = Math.max(
-    0,
-    (distanceM / radiusM - pulse.startFraction) / (1 - pulse.startFraction),
-  );
+  const touchPhase =
+    (distanceM / radiusM - pulse.startFraction) / (1 - pulse.startFraction);
   let strength = 0;
   for (let index = 0; index < pulse.count; index++) {
     const cycle = nowMs / pulse.periodMs + index / pulse.count;
@@ -77,7 +82,10 @@ export function awarenessEchoStrength(nowMs, distanceM, radiusM, pulse, echo) {
     if (elapsedMs < echo.fadeMs)
       strength = Math.max(strength, (1 - elapsedMs / echo.fadeMs) ** 2);
   }
-  return strength;
+  // A front still fading in over `fadeInFraction` of its travel echoes no
+  // brighter than it shows.
+  const fadeIn = pulse.fadeInFraction ?? 0;
+  return fadeIn > 0 ? strength * Math.min(1, touchPhase / fadeIn) : strength;
 }
 
 /**

src/awarenessEcho.test.mjs

@@ -45,7 +45,14 @@ test('an echo lights as a pulse front reaches the contact, then fades', () => {
 test('rim contacts fade out after the front wraps; outside the range never', () => {
   const rim = R * 0.999;
   assert.ok(strength(arrival(rim) + echo.fadeMs / 2, rim) > 0.2);
-  assert.ok(strength(pulse.periodMs * 5, 1000) > 0.99, 'inside the start ring');
+  // Inside the ring pulses are born on, nothing is ever crossed: the
+  // subject and anything within 5 km never echo, at any moment.
+  const inner = R * pulse.startFraction;
+  for (let ms = 0; ms < pulse.periodMs; ms += 10) {
+    assert.equal(strength(ms, 0), 0, 'the subject itself');
+    assert.equal(strength(ms, inner - 1), 0);
+  }
+  assert.ok(strength(pulse.periodMs * 5, inner) > 0.99, 'the birth ring');
   for (let ms = 0; ms < pulse.periodMs; ms += 50)
     assert.equal(strength(ms, R + 1), 0);
   assert.equal(strength(0, Number.NaN), 0);
@@ -74,9 +81,12 @@ test('awarenessEchoAt reads the published field, by layer, at ground level', (t)
         awarenessEchoAt('flights', contact, t0 + 300),
     ) < 0.01,
   );
-  // The field's centre is read in place, so a moved subject moves the echo.
-  Cesium.Cartesian3.clone(contact, center);
-  assert.ok(awarenessEchoAt('flights', contact, pulse.periodMs * 7) > 0.99);
+  // The field's centre is read in place, so a moved subject moves the echo:
+  // about 50 km farther, the contact lights at its new distance's moment.
+  Cesium.Cartesian3.clone(Cesium.Cartesian3.fromDegrees(3.5, 26.1, 0), center);
+  const moved = Cesium.Cartesian3.distance(center, contact);
+  assert.ok(Math.abs(moved - d) > 1000);
+  assert.ok(awarenessEchoAt('flights', contact, arrival(moved)) > 0.99);
   assert.equal(awarenessEchoAt('flights', null, t0), 0);
   clearAwarenessEchoField();
   assert.equal(getAwarenessEchoField(), null);
@@ -107,3 +117,19 @@ test('echoes scale with the field level and rest with the pulses', (t) => {
   level = 0;
   assert.equal(awarenessEchoAt('flights', contact, t0), 0);
 });
+
+test('near the subject an echo is no brighter than the fading-in front', () => {
+  const fading = { ...pulse, fadeInFraction: 0.08 };
+  const at = (distanceM) =>
+    awarenessEchoStrength(arrival(distanceM), distanceM, R, fading, echo);
+  // Born at 5 km, the front reaches full strength 8% of the way out.
+  const full = R * (fading.startFraction + 0.08 * (1 - fading.startFraction));
+  assert.equal(at(R * fading.startFraction), 0);
+  const halfway = (R * fading.startFraction + full) / 2;
+  assert.ok(Math.abs(at(halfway) - 0.5) < 0.01, `${at(halfway)}`);
+  assert.ok(at(full + 1) > 0.99);
+  assert.ok(
+    at(R * 0.999) > 0.99,
+    'the rim, and so the ring flash, is unchanged',
+  );
+});

src/data/detectionHost.test.mjs

@@ -24,6 +24,10 @@ import {
   setOverlayEntries,
 } from '../overlays/worldOverlay.js';
 import { DETECTION_THEME_MAP } from '../overlays/worldOverlayTokens.js';
+import {
+  clearAwarenessEchoField,
+  setAwarenessEchoField,
+} from '../awarenessEcho.js';
 import { composeLabel, resolveTier } from './detectionDraw.js';
 
 test('detection diagnostics count rendered fading rows instead of absent selected identities', () => {
@@ -627,6 +631,54 @@ test('surveillance military tier reaches the dedicated render target as shipped
   }
 });
 
+test('Global Context echo brackets reach the canvas in the detection style colour', () => {
+  const env = installEnvironment();
+  // Fronts every millisecond with a long fade, so the contact is lit on
+  // whatever frame paints; a distinctive width picks the echo stroke out.
+  const echo = {
+    layerIds: ['military'],
+    fadeMs: 60_000,
+    color: 'rgb(1, 2, 3)',
+    spreadPx: 8,
+    lineWidth: 3.25,
+  };
+  const echoStrokes = () =>
+    env.detectionCtx.calls
+      .filter(([name, , , width]) => name === 'stroke' && width === echo.lineWidth)
+      .map(([, , style]) => style);
+  try {
+    setAwarenessEchoField({
+      center: Cesium.Cartesian3.fromDegrees(0, 89, 0),
+      radiusM: 250_000,
+      pulse: { count: 1000, periodMs: 1000, startFraction: 0 },
+      echo,
+    });
+    initWorldOverlay(env.viewer);
+    initDetection(env.viewer, [militaryLayer()], () => {});
+    setMode('DENSE');
+    setDetectionStyle('normal');
+    settleFrame(env);
+    assert.ok(echoStrokes().length > 0, 'the echo bracket is painted');
+    assert.ok(echoStrokes().every((style) => style === echo.color));
+
+    // CRT, NVG and FLIR keep their own palettes.
+    for (const style of ['retro', 'surveillance', 'thermal']) {
+      env.detectionCtx.calls.length = 0;
+      setDetectionStyle(style);
+      settleFrame(env);
+      const strokes = echoStrokes();
+      assert.ok(strokes.length > 0, style);
+      assert.ok(
+        strokes.every((stroke) => stroke === DETECTION_THEME_MAP[style].line),
+        `${style} echoes take the style line colour, got ${strokes}`,
+      );
+    }
+  } finally {
+    clearAwarenessEchoField();
+    env.cleanup();
+  }
+});
+
 test('pathological detection paint holds alternate frames without freezing shared lanes', () => {
   // Opts into the telemetry banner: the held-frame assertions count banner paints.
   const env = installEnvironment({ search: '?detectDebug=1' });

src/layers/awareness/rangeRing.test.mjs

@@ -49,20 +49,30 @@ function luminance(color) {
  * test; `motion.set(on)` flips it later and tells its listeners, as the
  * browser does.
  */
-function ringRendering(t, { reducedMotion = false } = {}) {
+function ringRendering(t, { reducedMotion = false, legacyQuery = false } = {}) {
   const previous = globalThis.matchMedia;
   const listeners = new Set();
-  const query = {
-    get matches() {
-      return reducedMotion;
-    },
-    addEventListener(type, listener) {
-      if (type === 'change') listeners.add(listener);
-    },
-    removeEventListener(type, listener) {
-      if (type === 'change') listeners.delete(listener);
-    },
-  };
+  // `legacyQuery` is a MediaQueryList as Safari before 14 shipped it, with
+  // only addListener / removeListener.
+  const query = legacyQuery
+    ? {
+        get matches() {
+          return reducedMotion;
+        },
+        addListener: (listener) => listeners.add(listener),
+        removeListener: (listener) => listeners.delete(listener),
+      }
+    : {
+        get matches() {
+          return reducedMotion;
+        },
+        addEventListener(type, listener) {
+          if (type === 'change') listeners.add(listener);
+        },
+        removeEventListener(type, listener) {
+          if (type === 'change') listeners.delete(listener);
+        },
+      };
   globalThis.matchMedia = (media) =>
     media === '(prefers-reduced-motion: reduce)'
       ? query
@@ -693,6 +703,21 @@ test('turning reduced motion on mid-session stops the pulses, and off restarts t
   assert.equal(motion.listeners(), 0);
 });
 
+test('a reduced-motion change reaches older Safari through addListener', (t) => {
+  const { entities, scene, rendering, motion, state } = ringRendering(t, {
+    legacyQuery: true,
+  });
+  state.subject = flight(3);
+  rendering.renderVisual(state.subject);
+  assert.equal(scene.primitives.length, 1);
+  assert.equal(motion.listeners(), 1);
+  motion.set(true);
+  assert.equal(scene.primitives.length, 0);
+  assert.equal(entities.values[0].polyline.material.color.isConstant, true);
+  rendering.clearVisual();
+  assert.equal(motion.listeners(), 0);
+});
+
 test('a refresh after reduced motion changed rebuilds the visual too', (t) => {
   const { entities, rendering, motion } = ringRendering(t);
   rendering.renderVisual(flight(3));

src/layers/awareness/rendering.js

@@ -758,7 +758,10 @@ export function createRendering({
     const onMotionChange = () => {
       if (layerState.subject) renderVisual(layerState.subject);
     };
-    motionQuery?.addEventListener?.('change', onMotionChange);
+    // Safari before 14 has only the older addListener / removeListener.
+    if (motionQuery?.addEventListener)
+      motionQuery.addEventListener('change', onMotionChange);
+    else motionQuery?.addListener?.(onMotionChange);
 
     layerState.visual = {
       key,
@@ -770,8 +773,11 @@ export function createRendering({
       reducedMotion,
       wake,
       stopPulses,
-      removeMotionListener: () =>
-        motionQuery?.removeEventListener?.('change', onMotionChange),
+      removeMotionListener: () => {
+        if (motionQuery?.removeEventListener)
+          motionQuery.removeEventListener('change', onMotionChange);
+        else motionQuery?.removeListener?.(onMotionChange);
+      },
     };
     governorRequestRender('awareness-visual');
   }