react-threat-map 0.1.1 → 0.2.0

package/DECISIONS.md

@@ -273,3 +273,59 @@ one line per origin→destination region pair. Pure origin collapsing is availab
 containing one critical and forty low attacks renders critical. For a security display,
 under-reporting the worst thing in a bucket is the more dangerous failure mode. This is
 overridable via `aggregation.severity`.
+
+---
+
+## 6. Same-place threats render as a loop, not a point
+
+An attack can legitimately begin and end in the same place. Germany has no subdivisions in
+the region table, so a domestic German incident is `DE → DE` and both ends resolve to one
+country anchor. The same happens for `US-CA → US-CA`, and for two hosts given identical
+city coordinates.
+
+Geometrically this is a zero-length chord, and the arc builder's whole model — sample a
+geodesic, push each sample perpendicular to the chord by a sine-weighted lift — degenerates:
+there is no direction to travel and no perpendicular to lift along. Every sample lands on
+the same pixel.
+
+### What that used to look like
+
+Nothing, essentially. The renderer accumulates polylines and skips any arc of zero length,
+so a same-place threat drew no track and no trail. What remained was the origin dot, the
+head sitting on top of it, and the impact ripple firing in place. It also could not be
+hovered: hit-testing measures distance to line segments, and there were none.
+
+That is a defensible reading — the library has one coordinate for California, so it cannot
+draw a journey across it — but it is the wrong one for a threat map. A domestic incident is
+an event, and it disappeared into a dot indistinguishable from a static origin marker.
+
+### What it does instead
+
+`buildArc` detects the degenerate case and emits a circle tangent to the shared point: the
+origin marker sits on the point, the head travels the loop, and the ripple fires back on the
+point as it closes. It is ordinary geometry, so batching, fading, and hit-testing all work
+with no special cases downstream.
+
+Three parameter choices, all of which were the actual decisions:
+
+**The threshold is half a pixel, not exact equality.** Endpoints do not have to be *equal*
+to be indistinguishable. Two hosts in one city, or any pair on a far-zoomed view, project
+sub-pixel apart. A half-pixel line cannot be seen or hovered, so drawing it as a line is
+strictly worse than drawing it as a loop. The cost is that two genuinely distinct points
+can render as a loop when the viewport is zoomed far enough out.
+
+**The radius is clamped in pixels (6–18), scaled off the map's lift ceiling.** A radius
+derived from the geometry would be zero, and one derived from the viewport alone would
+vanish on a world map — which is exactly where a same-city attack most needs to stay
+visible.
+
+**The radius ignores `curvature`.** Tempting, since curvature controls arc height
+elsewhere. But curvature is the height of a lift applied to a chord, and a self-loop has no
+chord. Coupling them would make `curvature: 0` — a reasonable choice for flat, straight
+lines — silently erase every self-directed threat on the map.
+
+### Tradeoff accepted
+
+Consumers upgrading from 0.1.x see new animated loops wherever their feed contains
+same-region attacks that previously rendered as static dots. This is why the change went
+out as a minor bump rather than a patch.

package/README.md

@@ -315,6 +315,35 @@ arcs render statically and the component costs nothing per frame. The map also r
 `prefers-reduced-motion` automatically; opt out with
 `animation={{ respectReducedMotion: false }}`.
 
+### Attacks that start and end in the same place
+
+An attack whose origin and destination resolve to the same point — a domestic incident in
+a country with no subdivisions, lateral movement inside one US state, two hosts in one
+city — has no chord to draw a line along:
+
+```tsx
+<ThreatMap
+  attacks={[
+    { id: '1', from: 'DE', to: 'DE', severity: 'high' },
+    { id: '2', from: 'US-CA', to: 'US-CA', severity: 'critical' },
+    { id: '3', from: { lat: 50.11, lng: 8.68 }, to: { lat: 50.11, lng: 8.68 } },
+  ]}
+/>
+```
+
+These render as a **self-loop**: a small circle tangent to the shared point, with the
+origin marker on the point, the head travelling the loop, and the impact ripple firing
+back on the same spot. It is hoverable like any other arc.
+
+The loop radius scales with the map and is clamped to 6–18 px, so a same-place attack
+stays visible on a world map instead of shrinking to nothing. It deliberately does **not**
+scale with `curvature`: curvature is the height of a lift applied to a chord, and a
+self-loop has no chord — tying them together would make `curvature: 0` erase these
+threats entirely.
+
+Endpoints do not have to be exactly equal. Anything projecting to within half a pixel
+counts as the same place, because a sub-pixel line cannot be seen or hovered anyway.
+
 ### Projections
 
 ```tsx
@@ -625,8 +654,9 @@ npm run dev
 
 [DECISIONS.md](./DECISIONS.md) covers the load-bearing choices and their tradeoffs:
 why `d3-geo` + Canvas over MapLibre/Leaflet/react-simple-maps, why Canvas 2D over SVG and
-WebGL, how the Natural Earth data is bundled and split, and why resolving and drawing
-deliberately use different datasets.
+WebGL, how the Natural Earth data is bundled and split, why resolving and drawing
+deliberately use different datasets, and why an attack that starts and ends in the same
+place is drawn as a loop rather than a point.
 
 ## Data
 

package/dist/index.cjs

@@ -454,6 +454,40 @@ function useReducedMotion() {
   }, []);
   return reduced;
 }
+function configEqual(a, b) {
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  for (const key of aKeys) {
+    const av = a[key];
+    const bv = b[key];
+    if (Object.is(av, bv)) continue;
+    if (isPlainObject(av) && isPlainObject(bv)) {
+      if (!shallowEqual(av, bv)) return false;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+function shallowEqual(a, b) {
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  for (const key of aKeys) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function useStableConfig(defaults, overrides) {
+  const resolved = mergeDefined(defaults, overrides);
+  const ref = react.useRef(resolved);
+  if (!configEqual(ref.current, resolved)) {
+    ref.current = resolved;
+  }
+  return ref.current;
+}
 function drawBaseMap(options) {
   const { ctx, width, height, projection, geo, theme, regions } = options;
   ctx.clearRect(0, 0, width, height);
@@ -558,6 +592,7 @@ function buildArc(from, to, projection, curvature, segments, maxLift = Infinity)
   const dx = endPx[0] - startPx[0];
   const dy = endPx[1] - startPx[1];
   const chord = Math.hypot(dx, dy);
+  if (chord <= SAME_PLACE_EPSILON) return buildSelfLoop(startPx, count, steps, maxLift);
   const nx = chord > 0 ? -dy / chord : 0;
   const ny = chord > 0 ? dx / chord : 0;
   const rawLift = chord * curvature;
@@ -594,6 +629,28 @@ function buildArc(from, to, projection, curvature, segments, maxLift = Infinity)
   return { points, breakAt, distances, length };
 }
 var ANTIMERIDIAN_JUMP = 180;
+var SAME_PLACE_EPSILON = 0.5;
+var SELF_LOOP_LIFT_FRACTION = 0.06;
+var SELF_LOOP_MIN_RADIUS = 6;
+var SELF_LOOP_MAX_RADIUS = 18;
+var SELF_LOOP_DEFAULT_RADIUS = 10;
+function selfLoopRadius(maxLift) {
+  const derived = Number.isFinite(maxLift) ? maxLift * SELF_LOOP_LIFT_FRACTION : SELF_LOOP_DEFAULT_RADIUS;
+  return Math.min(SELF_LOOP_MAX_RADIUS, Math.max(SELF_LOOP_MIN_RADIUS, derived));
+}
+function buildSelfLoop(center, count, steps, maxLift) {
+  const radius = selfLoopRadius(maxLift);
+  const points = new Float32Array(count * 2);
+  const cx = center[0];
+  const cy = center[1] - radius;
+  for (let i = 0; i < count; i++) {
+    const angle = i / steps * Math.PI * 2;
+    points[i * 2] = cx + Math.sin(angle) * radius;
+    points[i * 2 + 1] = cy + Math.cos(angle) * radius;
+  }
+  const { distances, length } = measure(points, count, -1);
+  return { points, breakAt: -1, distances, length };
+}
 function isFinitePoint(p) {
   return Number.isFinite(p[0]) && Number.isFinite(p[1]);
 }
@@ -1195,17 +1252,23 @@ function ThreatMap(props) {
     ariaLabel = "Cyberattack threat map"
   } = props;
   const containerRef = react.useRef(null);
-  const theme = react.useMemo(() => {
-    const merged = mergeDefined(defaultTheme, props.theme);
-    return props.theme?.severityColors ? { ...merged, severityColors: { ...defaultTheme.severityColors, ...props.theme.severityColors } } : merged;
+  const themeOverrides = react.useMemo(() => {
+    if (!props.theme?.severityColors) return props.theme;
+    return { ...props.theme, severityColors: { ...defaultTheme.severityColors, ...props.theme.severityColors } };
   }, [props.theme]);
-  const line = react.useMemo(() => mergeDefined(defaultLineStyle, props.line), [props.line]);
-  const regions = react.useMemo(() => mergeDefined(defaultRegions, props.regions), [props.regions]);
+  const theme = useStableConfig(defaultTheme, themeOverrides);
+  const line = useStableConfig(defaultLineStyle, props.line);
+  const regions = useStableConfig(defaultRegions, props.regions);
   const reducedMotion = useReducedMotion();
-  const animation = react.useMemo(() => {
-    const merged = mergeDefined(defaultAnimation, props.animation);
-    return merged.respectReducedMotion && reducedMotion ? { ...merged, enabled: false } : merged;
-  }, [props.animation, reducedMotion]);
+  const baseAnimation = useStableConfig(defaultAnimation, props.animation);
+  const animation = react.useMemo(
+    () => (
+      // Someone who has asked their OS for less motion should not be handed a
+      // screen of racing lines. The arcs still render; they just hold still.
+      baseAnimation.respectReducedMotion && reducedMotion ? { ...baseAnimation, enabled: false } : baseAnimation
+    ),
+    [baseAnimation, reducedMotion]
+  );
   const measured = useElementSize(containerRef, widthProp === void 0 || heightProp === void 0);
   const pixelRatio = usePixelRatio();
   const width = widthProp ?? measured?.width ?? 0;

package/dist/index.js

@@ -453,6 +453,40 @@ function useReducedMotion() {
   }, []);
   return reduced;
 }
+function configEqual(a, b) {
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  for (const key of aKeys) {
+    const av = a[key];
+    const bv = b[key];
+    if (Object.is(av, bv)) continue;
+    if (isPlainObject(av) && isPlainObject(bv)) {
+      if (!shallowEqual(av, bv)) return false;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+function shallowEqual(a, b) {
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  for (const key of aKeys) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function useStableConfig(defaults, overrides) {
+  const resolved = mergeDefined(defaults, overrides);
+  const ref = useRef(resolved);
+  if (!configEqual(ref.current, resolved)) {
+    ref.current = resolved;
+  }
+  return ref.current;
+}
 function drawBaseMap(options) {
   const { ctx, width, height, projection, geo, theme, regions } = options;
   ctx.clearRect(0, 0, width, height);
@@ -557,6 +591,7 @@ function buildArc(from, to, projection, curvature, segments, maxLift = Infinity)
   const dx = endPx[0] - startPx[0];
   const dy = endPx[1] - startPx[1];
   const chord = Math.hypot(dx, dy);
+  if (chord <= SAME_PLACE_EPSILON) return buildSelfLoop(startPx, count, steps, maxLift);
   const nx = chord > 0 ? -dy / chord : 0;
   const ny = chord > 0 ? dx / chord : 0;
   const rawLift = chord * curvature;
@@ -593,6 +628,28 @@ function buildArc(from, to, projection, curvature, segments, maxLift = Infinity)
   return { points, breakAt, distances, length };
 }
 var ANTIMERIDIAN_JUMP = 180;
+var SAME_PLACE_EPSILON = 0.5;
+var SELF_LOOP_LIFT_FRACTION = 0.06;
+var SELF_LOOP_MIN_RADIUS = 6;
+var SELF_LOOP_MAX_RADIUS = 18;
+var SELF_LOOP_DEFAULT_RADIUS = 10;
+function selfLoopRadius(maxLift) {
+  const derived = Number.isFinite(maxLift) ? maxLift * SELF_LOOP_LIFT_FRACTION : SELF_LOOP_DEFAULT_RADIUS;
+  return Math.min(SELF_LOOP_MAX_RADIUS, Math.max(SELF_LOOP_MIN_RADIUS, derived));
+}
+function buildSelfLoop(center, count, steps, maxLift) {
+  const radius = selfLoopRadius(maxLift);
+  const points = new Float32Array(count * 2);
+  const cx = center[0];
+  const cy = center[1] - radius;
+  for (let i = 0; i < count; i++) {
+    const angle = i / steps * Math.PI * 2;
+    points[i * 2] = cx + Math.sin(angle) * radius;
+    points[i * 2 + 1] = cy + Math.cos(angle) * radius;
+  }
+  const { distances, length } = measure(points, count, -1);
+  return { points, breakAt: -1, distances, length };
+}
 function isFinitePoint(p) {
   return Number.isFinite(p[0]) && Number.isFinite(p[1]);
 }
@@ -1194,17 +1251,23 @@ function ThreatMap(props) {
     ariaLabel = "Cyberattack threat map"
   } = props;
   const containerRef = useRef(null);
-  const theme = useMemo(() => {
-    const merged = mergeDefined(defaultTheme, props.theme);
-    return props.theme?.severityColors ? { ...merged, severityColors: { ...defaultTheme.severityColors, ...props.theme.severityColors } } : merged;
+  const themeOverrides = useMemo(() => {
+    if (!props.theme?.severityColors) return props.theme;
+    return { ...props.theme, severityColors: { ...defaultTheme.severityColors, ...props.theme.severityColors } };
   }, [props.theme]);
-  const line = useMemo(() => mergeDefined(defaultLineStyle, props.line), [props.line]);
-  const regions = useMemo(() => mergeDefined(defaultRegions, props.regions), [props.regions]);
+  const theme = useStableConfig(defaultTheme, themeOverrides);
+  const line = useStableConfig(defaultLineStyle, props.line);
+  const regions = useStableConfig(defaultRegions, props.regions);
   const reducedMotion = useReducedMotion();
-  const animation = useMemo(() => {
-    const merged = mergeDefined(defaultAnimation, props.animation);
-    return merged.respectReducedMotion && reducedMotion ? { ...merged, enabled: false } : merged;
-  }, [props.animation, reducedMotion]);
+  const baseAnimation = useStableConfig(defaultAnimation, props.animation);
+  const animation = useMemo(
+    () => (
+      // Someone who has asked their OS for less motion should not be handed a
+      // screen of racing lines. The arcs still render; they just hold still.
+      baseAnimation.respectReducedMotion && reducedMotion ? { ...baseAnimation, enabled: false } : baseAnimation
+    ),
+    [baseAnimation, reducedMotion]
+  );
   const measured = useElementSize(containerRef, widthProp === void 0 || heightProp === void 0);
   const pixelRatio = usePixelRatio();
   const width = widthProp ?? measured?.width ?? 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-threat-map",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A React component that renders animated cyberattack threats on a static world map, with intelligent per-region aggregation and first-class US state support.",
   "keywords": [
     "react",