react-threat-map 0.1.2 → 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

@@ -592,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;
@@ -628,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]);
 }

package/dist/index.js

@@ -591,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;
@@ -627,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]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-threat-map",
-  "version": "0.1.2",
+  "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",