react-threat-map 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,301 @@
+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';
+
+/**
+ * The `<ThreatMap>` component.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A world map with animated cyberattack threats drawn over it.
+ *
+ * In the simplest case, pass attacks and nothing else — the map sizes itself to
+ * its container, loads its own geography, aggregates by origin region, and
+ * animates:
+ *
+ * ```tsx
+ * <ThreatMap attacks={[{ from: 'CN', to: 'US-CA', severity: 'high' }]} />
+ * ```
+ *
+ * Every layer is then customizable via props. See {@link ThreatMapProps}, and
+ * the README for the full guide.
+ *
+ * **Layout**: the component renders a positioned wrapper containing two stacked
+ * canvases. Give the wrapper a size via `style`/`className`, or pass explicit
+ * `width`/`height`. With neither, it fills its container's width and derives a
+ * height from the projection's aspect ratio.
+ *
+ * @example Streaming feed with custom theme and state borders
+ * ```tsx
+ * <ThreatMap
+ *   attacks={attacks}
+ *   regions={{ showStates: true }}
+ *   theme={{ ocean: '#000', severityColors: { critical: '#f0f' } }}
+ *   animation={{ speed: 1.2 }}
+ *   onThreatClick={(threat) => console.log(threat.count, 'attacks from', threat.fromRegion.name)}
+ * />
+ * ```
+ */
+declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): JSX.Element;
+
+/**
+ * Default theme and configuration objects.
+ *
+ * Every one is exported and frozen, so you can read them, spread them, or derive
+ * your own variants:
+ *
+ * ```ts
+ * import { defaultTheme } from 'react-threat-map';
+ * const lightTheme = { ...defaultTheme, ocean: '#f4f6fa', land: '#d8dfe8' };
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The default dark theme.
+ *
+ * Tuned for a SOC wall display: a desaturated navy map so that saturated threat
+ * lines carry all the visual salience. Severity runs cyan → amber → orange → red,
+ * which reads as escalating for viewers with the common forms of colour-vision
+ * deficiency because it varies lightness as well as hue.
+ */
+declare const defaultTheme: ThreatMapTheme;
+/** Default arc geometry and styling. */
+declare const defaultLineStyle: LineStyleConfig;
+/** Default animation settings. */
+declare const defaultAnimation: AnimationConfig;
+/** Default boundary-drawing settings. */
+declare const defaultRegions: RegionsConfig;
+
+/**
+ * The aggregation stage: many {@link Attack}s in, few {@link Threat}s out.
+ *
+ * A pure function. No React, no canvas, no async, no geometry — which is what
+ * makes it exhaustively unit-testable and reusable outside the component (for a
+ * table view, a CSV export, a test assertion).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * An {@link AggregationConfig} with every default filled in.
+ *
+ * `key` and `maxGroups` stay optional because "absent" is a meaningful state for
+ * both — there is no sentinel value that means "no custom key function" or
+ * "no cap" as naturally as their absence does.
+ */
+type ResolvedAggregationConfig<TMeta = unknown> = Required<Omit<AggregationConfig<TMeta>, 'key' | 'maxGroups'>> & {
+    readonly key?: AggregationConfig<TMeta>['key'];
+    readonly maxGroups?: number;
+};
+/**
+ * Defaults for {@link AggregationConfig}.
+ *
+ * Exported so you can read or extend them:
+ *
+ * ```ts
+ * import { defaultAggregation } from 'react-threat-map';
+ * const scale = defaultAggregation.scale; // the built-in log ramp
+ * ```
+ */
+declare const defaultAggregation: ResolvedAggregationConfig;
+/** Options for {@link aggregateAttacks} beyond the aggregation config itself. */
+interface AggregateOptions<TMeta = unknown> {
+    /** Aggregation settings. Merged over {@link defaultAggregation}. Pass `false` to disable. */
+    readonly config?: Partial<AggregationConfig<TMeta>> | false;
+    /** Boundary index, enabling reverse resolution of bare coordinates. Optional. */
+    readonly index?: RegionIndex | null;
+    /** Reports attacks that could not be resolved. */
+    readonly onError?: (message: string, attack: Attack<TMeta>) => void;
+}
+/**
+ * Aggregate attacks into renderable threats.
+ *
+ * Pipeline:
+ * 1. **Resolve** each attack's endpoints to coordinates + regions. Unresolvable
+ *    attacks are reported via `onError` and dropped.
+ * 2. **Group** by key — derived from the origin region (and destination, by
+ *    default), or from a custom `key` function.
+ * 3. **Split out undersized groups.** Groups below `minCount` are emitted as
+ *    individual threats: merging two attacks into a "group of 2" adds visual
+ *    weight without adding information.
+ * 4. **Collapse** each surviving group into one threat, summing weight, taking
+ *    max severity, and scaling intensity by count.
+ * 5. **Cap** to `maxGroups`, keeping the heaviest.
+ *
+ * Output order is deterministic — descending `totalWeight`, ties broken by `id` —
+ * so renders are stable across calls and snapshot tests do not flake.
+ *
+ * @param attacks - The attacks to aggregate.
+ * @param options - See {@link AggregateOptions}.
+ * @returns Threats to render, heaviest first.
+ *
+ * @example Aggregation on (the default)
+ * ```ts
+ * const threats = aggregateAttacks([
+ *   { from: { lat: 34.0, lng: -118.2, region: 'US-CA' }, to: 'FR' },
+ *   { from: { lat: 37.8, lng: -122.4, region: 'US-CA' }, to: 'FR' },
+ *   { from: 'US-TX', to: 'FR' },
+ * ]);
+ * // 2 threats: California→France (count 2, heavier) and Texas→France (count 1).
+ * ```
+ *
+ * @example Aggregation off
+ * ```ts
+ * const threats = aggregateAttacks(attacks, { config: false });
+ * // one threat per attack, every count === 1
+ * ```
+ */
+declare function aggregateAttacks<TMeta = unknown>(attacks: readonly Attack<TMeta>[], options?: AggregateOptions<TMeta>): Threat<TMeta>[];
+
+/**
+ * Mapping attack counts to visual weight.
+ *
+ * @packageDocumentation
+ */
+
+/** Upper bound on intensity, so one runaway group cannot black out the map. */
+declare const MAX_INTENSITY = 6;
+/**
+ * The default count → visual weight ramp: `1 + log2(count) * 0.5`, clamped to
+ * `[1, 6]`.
+ *
+ * Logarithmic rather than linear, because attack volume per region is heavily
+ * long-tailed. Linear scaling on a feed where one region sends 500 attacks and
+ * another sends 5 gives you a 500 px-wide smear next to a hairline — the busiest
+ * region erases the map it is drawn on. The log ramp keeps the ordering legible:
+ *
+ * | count | intensity |
+ * | ----- | --------- |
+ * | 1     | 1.0       |
+ * | 2     | 1.5       |
+ * | 10    | 2.7       |
+ * | 100   | 4.3       |
+ * | 500   | 5.5       |
+ * | 5000  | 6.0 (clamped) |
+ *
+ * Swap it for anything you like via {@link AggregationConfig.scale} — e.g.
+ * `(count) => 1 + count / 10` for a linear ramp, or `() => 1` to size every
+ * threat identically while still merging them.
+ *
+ * @param count - Attacks in the group, `>= 1`.
+ * @returns A multiplier in `[1, 6]`.
+ */
+declare const defaultIntensityScale: IntensityScale;
+
+/**
+ * Grouping-key derivation — the rule that decides what "the same threat" means.
+ *
+ * @packageDocumentation
+ */
+
+/** Severity order, low → critical. Index doubles as the numeric rank. */
+declare const SEVERITY_ORDER: readonly Severity[];
+/**
+ * Rank a severity for comparison.
+ *
+ * @param severity - A known or custom severity.
+ * @returns `0`–`3` for known severities. Unknown/custom values rank as `medium`
+ *   (`1`), matching how they fall back for color — a custom severity should not
+ *   silently outrank `critical` or sink below `low`.
+ */
+declare function severityRank(severity: Severity): number;
+/**
+ * Reduce a group's severities to the one it renders as: the **maximum**.
+ *
+ * A bucket holding one `critical` and forty `low` renders `critical`. For a
+ * security display, hiding the worst event in a group is the more dangerous
+ * failure — under-reporting a real incident beats over-reporting a benign one.
+ * Override via {@link AggregationConfig.severity}.
+ *
+ * @param severities - Member severities. Must not be empty.
+ * @returns The highest-ranked severity present.
+ */
+declare function maxSeverity(severities: readonly Severity[]): Severity;
+/**
+ * Reduce a resolved region to the id aggregation groups on, at a given granularity.
+ *
+ * This is the function that makes US states first-class origins:
+ *
+ * | granularity | region        | key    |
+ * | ----------- | ------------- | ------ |
+ * | `'auto'`    | `US-CA` state | `US-CA` |
+ * | `'auto'`    | `FR` country  | `FR`   |
+ * | `'country'` | `US-CA` state | `US`   |
+ * | `'state'`   | `FR` country  | `FR`   |
+ *
+ * `'auto'` — the default — keeps California and Texas apart while leaving the
+ * rest of the world at country level, which is the behavior a threat map wants:
+ * US-internal detail without shattering every other country into subdivisions we
+ * do not have data for.
+ *
+ * @param region - The resolved region.
+ * @param granularity - How specific to be.
+ * @returns The group key component for this region.
+ */
+declare function regionKey(region: ResolvedRegion, granularity: AggregationGranularity): string;
+
+/**
+ * Turning an {@link AttackLocation} into a coordinate plus a region.
+ *
+ * Pure and synchronous. The one async ingredient — boundary geometry, needed
+ * only to reverse-resolve bare coordinates — is passed in as an optional
+ * {@link RegionIndex}, so this module and everything downstream of it (all of
+ * aggregation) stays testable without loading a single byte of geometry.
+ *
+ * @packageDocumentation
+ */
+
+/** A location resolved to a drawable point and a groupable region. */
+interface ResolvedLocation {
+    /** Where to draw. */
+    readonly point: LatLng;
+    /** What to group by. `kind: 'unknown'` when the region could not be determined. */
+    readonly region: ResolvedRegion;
+}
+/** Returned instead of throwing when a location cannot be resolved at all. */
+interface ResolveFailure {
+    readonly ok: false;
+    /** Why it failed, suitable for an `onError` message. */
+    readonly reason: string;
+}
+/** A successful resolution. */
+interface ResolveSuccess {
+    readonly ok: true;
+    readonly value: ResolvedLocation;
+}
+/** Result of {@link resolveLocation}. */
+type ResolveResult = ResolveSuccess | ResolveFailure;
+/**
+ * Resolve a location to a point and a region.
+ *
+ * Three input shapes, in increasing cost:
+ *
+ * - **Region code** (`"US-CA"`) — one Map lookup. The anchor coordinate is used
+ *   as the point.
+ * - **Coordinates + region** (`{lat, lng, region: 'US-CA'}`) — one Map lookup,
+ *   exact point. The cheapest option that also gives pixel-accurate placement.
+ * - **Bare coordinates** (`{lat, lng}`) — needs `index` to reverse-resolve via
+ *   point-in-polygon. Without an index the point still renders, but its region
+ *   is `unknown`, so it will not aggregate with anything.
+ *
+ * Never throws. Invalid input returns a {@link ResolveFailure} the caller can
+ * surface through `onError`, so one malformed row cannot take down the map.
+ *
+ * @param location - The location to resolve.
+ * @param index - Boundary index for reverse lookup. Omit if geometry is not loaded yet.
+ * @param preferStates - Resolve bare coordinates to US states where possible.
+ *   Ignored for explicit region codes, which are already as specific as they are.
+ *
+ * @example
+ * ```ts
+ * resolveLocation('US-CA');                          // ok, point = California anchor
+ * resolveLocation({ lat: 34, lng: -118 }, index, true); // ok, region = US-CA
+ * resolveLocation('NOPE');                           // { ok: false, reason: ... }
+ * ```
+ */
+declare function resolveLocation(location: AttackLocation, index?: RegionIndex | null, preferStates?: boolean): ResolveResult;
+
+export { type AggregateOptions, AggregationConfig, AggregationGranularity, AnimationConfig, Attack, AttackLocation, IntensityScale, LatLng, LineStyleConfig, MAX_INTENSITY, RegionsConfig, type ResolveResult, type ResolvedAggregationConfig, type ResolvedLocation, ResolvedRegion, SEVERITY_ORDER, Severity, Threat, ThreatMap, ThreatMapProps, ThreatMapTheme, aggregateAttacks, defaultAggregation, defaultAnimation, defaultIntensityScale, defaultLineStyle, defaultRegions, defaultTheme, maxSeverity, regionKey, resolveLocation, severityRank };

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+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';
+
+/**
+ * The `<ThreatMap>` component.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A world map with animated cyberattack threats drawn over it.
+ *
+ * In the simplest case, pass attacks and nothing else — the map sizes itself to
+ * its container, loads its own geography, aggregates by origin region, and
+ * animates:
+ *
+ * ```tsx
+ * <ThreatMap attacks={[{ from: 'CN', to: 'US-CA', severity: 'high' }]} />
+ * ```
+ *
+ * Every layer is then customizable via props. See {@link ThreatMapProps}, and
+ * the README for the full guide.
+ *
+ * **Layout**: the component renders a positioned wrapper containing two stacked
+ * canvases. Give the wrapper a size via `style`/`className`, or pass explicit
+ * `width`/`height`. With neither, it fills its container's width and derives a
+ * height from the projection's aspect ratio.
+ *
+ * @example Streaming feed with custom theme and state borders
+ * ```tsx
+ * <ThreatMap
+ *   attacks={attacks}
+ *   regions={{ showStates: true }}
+ *   theme={{ ocean: '#000', severityColors: { critical: '#f0f' } }}
+ *   animation={{ speed: 1.2 }}
+ *   onThreatClick={(threat) => console.log(threat.count, 'attacks from', threat.fromRegion.name)}
+ * />
+ * ```
+ */
+declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): JSX.Element;
+
+/**
+ * Default theme and configuration objects.
+ *
+ * Every one is exported and frozen, so you can read them, spread them, or derive
+ * your own variants:
+ *
+ * ```ts
+ * import { defaultTheme } from 'react-threat-map';
+ * const lightTheme = { ...defaultTheme, ocean: '#f4f6fa', land: '#d8dfe8' };
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The default dark theme.
+ *
+ * Tuned for a SOC wall display: a desaturated navy map so that saturated threat
+ * lines carry all the visual salience. Severity runs cyan → amber → orange → red,
+ * which reads as escalating for viewers with the common forms of colour-vision
+ * deficiency because it varies lightness as well as hue.
+ */
+declare const defaultTheme: ThreatMapTheme;
+/** Default arc geometry and styling. */
+declare const defaultLineStyle: LineStyleConfig;
+/** Default animation settings. */
+declare const defaultAnimation: AnimationConfig;
+/** Default boundary-drawing settings. */
+declare const defaultRegions: RegionsConfig;
+
+/**
+ * The aggregation stage: many {@link Attack}s in, few {@link Threat}s out.
+ *
+ * A pure function. No React, no canvas, no async, no geometry — which is what
+ * makes it exhaustively unit-testable and reusable outside the component (for a
+ * table view, a CSV export, a test assertion).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * An {@link AggregationConfig} with every default filled in.
+ *
+ * `key` and `maxGroups` stay optional because "absent" is a meaningful state for
+ * both — there is no sentinel value that means "no custom key function" or
+ * "no cap" as naturally as their absence does.
+ */
+type ResolvedAggregationConfig<TMeta = unknown> = Required<Omit<AggregationConfig<TMeta>, 'key' | 'maxGroups'>> & {
+    readonly key?: AggregationConfig<TMeta>['key'];
+    readonly maxGroups?: number;
+};
+/**
+ * Defaults for {@link AggregationConfig}.
+ *
+ * Exported so you can read or extend them:
+ *
+ * ```ts
+ * import { defaultAggregation } from 'react-threat-map';
+ * const scale = defaultAggregation.scale; // the built-in log ramp
+ * ```
+ */
+declare const defaultAggregation: ResolvedAggregationConfig;
+/** Options for {@link aggregateAttacks} beyond the aggregation config itself. */
+interface AggregateOptions<TMeta = unknown> {
+    /** Aggregation settings. Merged over {@link defaultAggregation}. Pass `false` to disable. */
+    readonly config?: Partial<AggregationConfig<TMeta>> | false;
+    /** Boundary index, enabling reverse resolution of bare coordinates. Optional. */
+    readonly index?: RegionIndex | null;
+    /** Reports attacks that could not be resolved. */
+    readonly onError?: (message: string, attack: Attack<TMeta>) => void;
+}
+/**
+ * Aggregate attacks into renderable threats.
+ *
+ * Pipeline:
+ * 1. **Resolve** each attack's endpoints to coordinates + regions. Unresolvable
+ *    attacks are reported via `onError` and dropped.
+ * 2. **Group** by key — derived from the origin region (and destination, by
+ *    default), or from a custom `key` function.
+ * 3. **Split out undersized groups.** Groups below `minCount` are emitted as
+ *    individual threats: merging two attacks into a "group of 2" adds visual
+ *    weight without adding information.
+ * 4. **Collapse** each surviving group into one threat, summing weight, taking
+ *    max severity, and scaling intensity by count.
+ * 5. **Cap** to `maxGroups`, keeping the heaviest.
+ *
+ * Output order is deterministic — descending `totalWeight`, ties broken by `id` —
+ * so renders are stable across calls and snapshot tests do not flake.
+ *
+ * @param attacks - The attacks to aggregate.
+ * @param options - See {@link AggregateOptions}.
+ * @returns Threats to render, heaviest first.
+ *
+ * @example Aggregation on (the default)
+ * ```ts
+ * const threats = aggregateAttacks([
+ *   { from: { lat: 34.0, lng: -118.2, region: 'US-CA' }, to: 'FR' },
+ *   { from: { lat: 37.8, lng: -122.4, region: 'US-CA' }, to: 'FR' },
+ *   { from: 'US-TX', to: 'FR' },
+ * ]);
+ * // 2 threats: California→France (count 2, heavier) and Texas→France (count 1).
+ * ```
+ *
+ * @example Aggregation off
+ * ```ts
+ * const threats = aggregateAttacks(attacks, { config: false });
+ * // one threat per attack, every count === 1
+ * ```
+ */
+declare function aggregateAttacks<TMeta = unknown>(attacks: readonly Attack<TMeta>[], options?: AggregateOptions<TMeta>): Threat<TMeta>[];
+
+/**
+ * Mapping attack counts to visual weight.
+ *
+ * @packageDocumentation
+ */
+
+/** Upper bound on intensity, so one runaway group cannot black out the map. */
+declare const MAX_INTENSITY = 6;
+/**
+ * The default count → visual weight ramp: `1 + log2(count) * 0.5`, clamped to
+ * `[1, 6]`.
+ *
+ * Logarithmic rather than linear, because attack volume per region is heavily
+ * long-tailed. Linear scaling on a feed where one region sends 500 attacks and
+ * another sends 5 gives you a 500 px-wide smear next to a hairline — the busiest
+ * region erases the map it is drawn on. The log ramp keeps the ordering legible:
+ *
+ * | count | intensity |
+ * | ----- | --------- |
+ * | 1     | 1.0       |
+ * | 2     | 1.5       |
+ * | 10    | 2.7       |
+ * | 100   | 4.3       |
+ * | 500   | 5.5       |
+ * | 5000  | 6.0 (clamped) |
+ *
+ * Swap it for anything you like via {@link AggregationConfig.scale} — e.g.
+ * `(count) => 1 + count / 10` for a linear ramp, or `() => 1` to size every
+ * threat identically while still merging them.
+ *
+ * @param count - Attacks in the group, `>= 1`.
+ * @returns A multiplier in `[1, 6]`.
+ */
+declare const defaultIntensityScale: IntensityScale;
+
+/**
+ * Grouping-key derivation — the rule that decides what "the same threat" means.
+ *
+ * @packageDocumentation
+ */
+
+/** Severity order, low → critical. Index doubles as the numeric rank. */
+declare const SEVERITY_ORDER: readonly Severity[];
+/**
+ * Rank a severity for comparison.
+ *
+ * @param severity - A known or custom severity.
+ * @returns `0`–`3` for known severities. Unknown/custom values rank as `medium`
+ *   (`1`), matching how they fall back for color — a custom severity should not
+ *   silently outrank `critical` or sink below `low`.
+ */
+declare function severityRank(severity: Severity): number;
+/**
+ * Reduce a group's severities to the one it renders as: the **maximum**.
+ *
+ * A bucket holding one `critical` and forty `low` renders `critical`. For a
+ * security display, hiding the worst event in a group is the more dangerous
+ * failure — under-reporting a real incident beats over-reporting a benign one.
+ * Override via {@link AggregationConfig.severity}.
+ *
+ * @param severities - Member severities. Must not be empty.
+ * @returns The highest-ranked severity present.
+ */
+declare function maxSeverity(severities: readonly Severity[]): Severity;
+/**
+ * Reduce a resolved region to the id aggregation groups on, at a given granularity.
+ *
+ * This is the function that makes US states first-class origins:
+ *
+ * | granularity | region        | key    |
+ * | ----------- | ------------- | ------ |
+ * | `'auto'`    | `US-CA` state | `US-CA` |
+ * | `'auto'`    | `FR` country  | `FR`   |
+ * | `'country'` | `US-CA` state | `US`   |
+ * | `'state'`   | `FR` country  | `FR`   |
+ *
+ * `'auto'` — the default — keeps California and Texas apart while leaving the
+ * rest of the world at country level, which is the behavior a threat map wants:
+ * US-internal detail without shattering every other country into subdivisions we
+ * do not have data for.
+ *
+ * @param region - The resolved region.
+ * @param granularity - How specific to be.
+ * @returns The group key component for this region.
+ */
+declare function regionKey(region: ResolvedRegion, granularity: AggregationGranularity): string;
+
+/**
+ * Turning an {@link AttackLocation} into a coordinate plus a region.
+ *
+ * Pure and synchronous. The one async ingredient — boundary geometry, needed
+ * only to reverse-resolve bare coordinates — is passed in as an optional
+ * {@link RegionIndex}, so this module and everything downstream of it (all of
+ * aggregation) stays testable without loading a single byte of geometry.
+ *
+ * @packageDocumentation
+ */
+
+/** A location resolved to a drawable point and a groupable region. */
+interface ResolvedLocation {
+    /** Where to draw. */
+    readonly point: LatLng;
+    /** What to group by. `kind: 'unknown'` when the region could not be determined. */
+    readonly region: ResolvedRegion;
+}
+/** Returned instead of throwing when a location cannot be resolved at all. */
+interface ResolveFailure {
+    readonly ok: false;
+    /** Why it failed, suitable for an `onError` message. */
+    readonly reason: string;
+}
+/** A successful resolution. */
+interface ResolveSuccess {
+    readonly ok: true;
+    readonly value: ResolvedLocation;
+}
+/** Result of {@link resolveLocation}. */
+type ResolveResult = ResolveSuccess | ResolveFailure;
+/**
+ * Resolve a location to a point and a region.
+ *
+ * Three input shapes, in increasing cost:
+ *
+ * - **Region code** (`"US-CA"`) — one Map lookup. The anchor coordinate is used
+ *   as the point.
+ * - **Coordinates + region** (`{lat, lng, region: 'US-CA'}`) — one Map lookup,
+ *   exact point. The cheapest option that also gives pixel-accurate placement.
+ * - **Bare coordinates** (`{lat, lng}`) — needs `index` to reverse-resolve via
+ *   point-in-polygon. Without an index the point still renders, but its region
+ *   is `unknown`, so it will not aggregate with anything.
+ *
+ * Never throws. Invalid input returns a {@link ResolveFailure} the caller can
+ * surface through `onError`, so one malformed row cannot take down the map.
+ *
+ * @param location - The location to resolve.
+ * @param index - Boundary index for reverse lookup. Omit if geometry is not loaded yet.
+ * @param preferStates - Resolve bare coordinates to US states where possible.
+ *   Ignored for explicit region codes, which are already as specific as they are.
+ *
+ * @example
+ * ```ts
+ * resolveLocation('US-CA');                          // ok, point = California anchor
+ * resolveLocation({ lat: 34, lng: -118 }, index, true); // ok, region = US-CA
+ * resolveLocation('NOPE');                           // { ok: false, reason: ... }
+ * ```
+ */
+declare function resolveLocation(location: AttackLocation, index?: RegionIndex | null, preferStates?: boolean): ResolveResult;
+
+export { type AggregateOptions, AggregationConfig, AggregationGranularity, AnimationConfig, Attack, AttackLocation, IntensityScale, LatLng, LineStyleConfig, MAX_INTENSITY, RegionsConfig, type ResolveResult, type ResolvedAggregationConfig, type ResolvedLocation, ResolvedRegion, SEVERITY_ORDER, Severity, Threat, ThreatMap, ThreatMapProps, ThreatMapTheme, aggregateAttacks, defaultAggregation, defaultAnimation, defaultIntensityScale, defaultLineStyle, defaultRegions, defaultTheme, maxSeverity, regionKey, resolveLocation, severityRank };