react-threat-map 0.1.2 → 0.2.1

package/DECISIONS.md

@@ -247,7 +247,24 @@ Every runtime dependency, and why it earns its place:
 Both are declared `external`, so consumers dedupe them against their own copies of d3
 rather than shipping a second one.
 
-`react` is a **peer** dependency (>=18), never bundled.
+`react` is a **peer** dependency (>=16.14.0), never bundled.
+
+The floor is 16.14.0, not 16.8.0 (hooks) as one might expect: the compiled output uses
+the automatic JSX runtime, so it imports `react/jsx-runtime`, and that entry point first
+ships in **16.14.0**. On 16.8–16.13 the package installs and then fails at bundle time on
+an unresolved module, so those versions must stay outside the range.
+
+Nothing in the library needs more than that floor — it uses only `useState`, `useEffect`,
+`useRef`, `useMemo`, and `useCallback`. The range was originally `>=18` for no recorded
+reason, which excluded working consumers on React 16.14/17; widened in 0.2.1 after
+verifying typecheck and a mount/re-render/unmount render pass on 16.14, 17, 18, and 19.
+
+Supporting that range is also why the public types import `CSSProperties`, `MouseEvent`,
+`ReactElement`, and `RefObject` **by name** from `react` rather than reaching through the
+`React` UMD global or the global `JSX` namespace. A bare `JSX.Element` in an emitted `.d.ts`
+resolves against whatever `@types/react` the consumer has — and `@types/react@19` removed
+the global `JSX` namespace, so it broke React 19 consumers compiling with
+`skipLibCheck: false`. Named type imports are identical across `@types/react` 16 to 19.
 
 Deliberately **not** dependencies: no state manager, no styling library, no CSS-in-JS, no
 animation library, no `d3-selection`/`d3-zoom`/`d3-scale`. The library ships zero CSS —
@@ -273,3 +290,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

@@ -49,12 +49,17 @@ import { ThreatMap } from 'react-threat-map';
 npm install react-threat-map
 ```
 
-React 18+ is a peer dependency:
+React is a peer dependency:
 
 ```json
-{ "peerDependencies": { "react": ">=18.0.0" } }
+{ "peerDependencies": { "react": ">=16.14.0" } }
 ```
 
+16.14.0 is the floor because that is the first release to ship `react/jsx-runtime`,
+which the compiled output imports. The library uses only `useState`, `useEffect`,
+`useRef`, `useMemo`, and `useCallback`, so nothing above that floor is required —
+React 16.14, 17, 18, and 19 are all supported.
+
 ---
 
 ## Quick start
@@ -315,6 +320,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 +659,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/geo.d.cts

@@ -1,5 +1,6 @@
-import { G as GeoData } from './regions-neHSPgtu.cjs';
-export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.cjs';
+import { G as GeoData } from './regions-Bsys6EFr.cjs';
+export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.cjs';
+import 'react';
 
 /**
  * Boundary geometry loading — the `react-threat-map/geo` entry point.

package/dist/geo.d.ts

@@ -1,5 +1,6 @@
-import { G as GeoData } from './regions-neHSPgtu.js';
-export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.js';
+import { G as GeoData } from './regions-Bsys6EFr.js';
+export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.js';
+import 'react';
 
 /**
  * Boundary geometry loading — the `react-threat-map/geo` entry point.

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.d.cts

@@ -1,5 +1,6 @@
-import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-neHSPgtu.cjs';
-export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.cjs';
+import { ReactElement } from 'react';
+import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-Bsys6EFr.cjs';
+export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.cjs';
 
 /**
  * The `<ThreatMap>` component.
@@ -37,7 +38,7 @@ export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverit
  * />
  * ```
  */
-declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): JSX.Element;
+declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): ReactElement;
 
 /**
  * Default theme and configuration objects.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-neHSPgtu.js';
-export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.js';
+import { ReactElement } from 'react';
+import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-Bsys6EFr.js';
+export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.js';
 
 /**
  * The `<ThreatMap>` component.
@@ -37,7 +38,7 @@ export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverit
  * />
  * ```
  */
-declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): JSX.Element;
+declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): ReactElement;
 
 /**
  * Default theme and configuration objects.

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/dist/{regions-neHSPgtu.d.cts → regions-Bsys6EFr.d.cts}

@@ -1,3 +1,5 @@
+import { CSSProperties } from 'react';
+
 /**
  * Public data types for `react-threat-map`.
  *
@@ -6,6 +8,7 @@
  *
  * @packageDocumentation
  */
+
 /**
  * A raw geographic coordinate in degrees (WGS84).
  *
@@ -651,7 +654,7 @@ interface ThreatMapProps<TMeta = unknown> {
     /** Applied to the wrapper element. */
     readonly className?: string;
     /** Applied to the wrapper element. The canvases fill it. */
-    readonly style?: React.CSSProperties;
+    readonly style?: CSSProperties;
     /** Accessible label for the map. Default `"Cyberattack threat map"`. */
     readonly ariaLabel?: string;
 }

package/dist/{regions-neHSPgtu.d.ts → regions-Bsys6EFr.d.ts}

@@ -1,3 +1,5 @@
+import { CSSProperties } from 'react';
+
 /**
  * Public data types for `react-threat-map`.
  *
@@ -6,6 +8,7 @@
  *
  * @packageDocumentation
  */
+
 /**
  * A raw geographic coordinate in degrees (WGS84).
  *
@@ -651,7 +654,7 @@ interface ThreatMapProps<TMeta = unknown> {
     /** Applied to the wrapper element. */
     readonly className?: string;
     /** Applied to the wrapper element. The canvases fill it. */
-    readonly style?: React.CSSProperties;
+    readonly style?: CSSProperties;
     /** Accessible label for the map. Default `"Cyberattack threat map"`. */
     readonly ariaLabel?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-threat-map",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "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",
@@ -64,7 +64,7 @@
     "example": "npm --prefix examples/demo run dev"
   },
   "peerDependencies": {
-    "react": ">=18.0.0"
+    "react": ">=16.14.0"
   },
   "dependencies": {
     "d3-geo": "^3.1.1",