@diagrammo/dgmo 0.21.0 → 0.21.1

package/src/map/geo-query.ts

@@ -0,0 +1,277 @@
+// Map geo-query (step-5 inspector backend). A SEPARATE entry from the renderer:
+// `renderMap` returns void + mutates the DOM, so it cannot hand back a query
+// handle. `createMapGeoQuery` re-runs the deterministic parse→resolve→layout
+// pipeline (cheap, lazy — only when the app arms Inspect) and wraps the fitted
+// projection captured on the layout, exposing:
+//   - invert(px,py)  — composite/stretch-aware pixel → [lon,lat]
+//   - project(lonLat) — [lon,lat] → pixel (re-project pins/markers each render)
+//   - locate(px,py)  — ONE unified result card (coords + reverse-geocode + tokens)
+//   - cities(extent?) — culled + projected gazetteer cities for the all-cities layer
+//
+// DI: `data: MapData` is injected by the caller (the Node-only `loadMapData` is
+// never called here), so this is browser-safe — no `node:fs`, no boundary
+// TopoJSON pulled into the synchronous render bundle (F7/AC15).
+import type { PaletteColors } from '../palettes/types';
+import { parseMap } from './parser';
+import { resolveMap } from './resolver';
+import { layoutMap } from './layout';
+import type { MapLayout } from './layout';
+import { decodeFeatures, regionAt } from './geo';
+import type { DecodedFeature } from './geo';
+import { pixelToLonLat, lonLatToPixel } from './invert';
+import type { MapData, GeoExtent } from './resolved-types';
+import type { Gazetteer } from './data/types';
+
+/** Nearest gazetteer city to a point: the real haversine distance, plus the
+ *  canonical name + ISO + (US-only) subdivision for token shaping. */
+export interface NearestCity {
+  readonly name: string;
+  readonly iso: string;
+  readonly sub?: string;
+  readonly distanceKm: number;
+}
+
+/** A region declaration with its canonical/primary form plus bare alternates
+ *  (behind the card's "other forms" expander). */
+export interface RegionToken {
+  /** Explicit scoped form, shown first (`Florida US-FL` / `France FR`). */
+  readonly primary: string;
+  /** Bare forms (bare ISO, bare code, bare name). */
+  readonly alternates: string[];
+}
+
+/** Paste-ready DGMO tokens for one inspected point — each round-trips through the
+ *  map parser with zero diagnostics (the app inserts verbatim, never synthesizes
+ *  syntax). */
+export interface ResultTokens {
+  /** Positional POI line, e.g. `poi 40.7608 -111.891` (NEVER `@lat,lon`). */
+  readonly coordPoiLine: string;
+  /** US-state region tokens — null when the click isn't in a US state. */
+  readonly state: RegionToken | null;
+  /** Country region tokens — null over open ocean (no country). */
+  readonly country: RegionToken | null;
+  /** Scoped city token (`New York US-NY` / `Paris FR`), or a bare ambiguous name. */
+  readonly city: { readonly token: string; readonly ambiguous: boolean } | null;
+}
+
+/** The single unified Inspect result. */
+export interface ResultCard {
+  readonly lonLat: [number, number];
+  readonly country: { iso: string; name: string } | null;
+  readonly state: { iso: string; name: string } | null;
+  readonly nearestCity: NearestCity | null;
+  readonly tokens: ResultTokens;
+}
+
+/** A gazetteer city projected to screen pixels for the all-cities overlay. */
+export interface ProjectedCity {
+  readonly name: string;
+  readonly iso: string;
+  readonly sub?: string;
+  readonly lon: number;
+  readonly lat: number;
+  readonly px: number;
+  readonly py: number;
+  readonly pop: number;
+}
+
+export interface MapGeoQuery {
+  /** Pixel → `[lon,lat]`, or null for an out-of-domain pixel. */
+  invert(px: number, py: number): [number, number] | null;
+  /** `[lon,lat]` → pixel, or null if it projects nowhere. */
+  project(lonLat: readonly [number, number]): [number, number] | null;
+  /** One click → the unified result card, or null if the pixel inverts to
+   *  nothing (graceful "no location"). */
+  locate(px: number, py: number): ResultCard | null;
+  /** Culled + projected cities for the all-cities layer (population-primary). */
+  cities(extent?: GeoExtent): ProjectedCity[];
+}
+
+export interface CreateMapGeoQueryOptions {
+  readonly content: string;
+  readonly width: number;
+  readonly height: number;
+  /** Injected map assets — same `MapData` the app passes to `renderMap`. */
+  readonly data: MapData;
+  /** Same palette/isDark the app renders with (geometry is palette-independent,
+   *  but `layoutMap` mandates them). */
+  readonly palette: PaletteColors;
+  readonly isDark: boolean;
+}
+
+const EARTH_R_KM = 6371;
+const DEG = Math.PI / 180;
+
+/** Great-circle distance in km (haversine; no d3 dependency). */
+function haversineKm(
+  lat1: number,
+  lon1: number,
+  lat2: number,
+  lon2: number
+): number {
+  const dLat = (lat2 - lat1) * DEG;
+  const dLon = (lon2 - lon1) * DEG;
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1 * DEG) * Math.cos(lat2 * DEG) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_R_KM * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+
+// Each decade of population is worth this many km of "pull" — so a notable city
+// a little farther beats a tiny suburb that's technically closer (A4). Tuned so
+// a ~200k-pop city (log10≈5.3) outranks a ~5k hamlet (log10≈3.7) within ~20 km.
+const POP_PULL_KM = 12;
+
+/** Nearest gazetteer city, blending true distance with notability (A4). Returns
+ *  the chosen city's REAL `distanceKm` regardless of the ranking blend (F4). */
+function nearestCity(
+  lonLat: readonly [number, number],
+  gazetteer: Gazetteer
+): NearestCity | null {
+  const [lon, lat] = lonLat;
+  let best: { score: number; idx: number; dist: number } | null = null;
+  const cities = gazetteer.cities;
+  for (let i = 0; i < cities.length; i++) {
+    const c = cities[i]!;
+    const dist = haversineKm(lat, lon, c[0], c[1]);
+    const score = dist - POP_PULL_KM * Math.log10((c[3] || 0) + 1);
+    if (!best || score < best.score) best = { score, idx: i, dist };
+  }
+  if (!best) return null;
+  const c = cities[best.idx]!;
+  return {
+    name: c[4],
+    iso: c[2],
+    ...(c[5] !== undefined && { sub: c[5] }),
+    distanceKm: best.dist,
+  };
+}
+
+/** Round a coordinate to 2 dp (≈1 km — within a pixel even at single-state zoom;
+ *  a POI dot is 6+ px wide, so more decimals are false precision invisible on the
+ *  rendered map). */
+function roundCoord(n: number): number {
+  return Number(n.toFixed(2));
+}
+
+/** Build the paste-ready tokens for one inspected point. Display name + ISO come
+ *  from the matched boundary feature itself (no `region-names.json` dependency).*/
+function buildTokens(
+  lonLat: readonly [number, number],
+  region: {
+    country: { iso: string; name: string } | null;
+    state: { iso: string; name: string } | null;
+  },
+  city: NearestCity | null
+): ResultTokens {
+  const coordPoiLine = `poi ${roundCoord(lonLat[1])} ${roundCoord(lonLat[0])}`;
+
+  // Region token forms are validated against the RESOLVER, not just the parser
+  // (a token can parse yet fail to resolve). Verified resolving forms:
+  //   - US state: `Florida US-FL` (scoped) and bare `US-FL` / `Florida`. NOTE a
+  //     bare 2-letter code (`FL`) is REJECTED ("Unknown subdivision") — only the
+  //     `US-FL` form resolves — so it is intentionally NOT offered.
+  //   - Country: the BARE name (`United States of America`) or bare ISO (`US`).
+  //     The scoped `<name> <iso>` form does NOT resolve for a country whose
+  //     subdivisions are loaded (the scope makes the resolver hunt for a
+  //     SUBDIVISION named after the country) — so a country leads with its name.
+  let stateTok: RegionToken | null = null;
+  if (region.state) {
+    const { iso, name } = region.state; // iso like `US-FL`
+    stateTok = { primary: `${name} ${iso}`, alternates: [iso, name] };
+  }
+
+  let countryTok: RegionToken | null = null;
+  if (region.country) {
+    const { iso, name } = region.country; // iso like `FR` / `US`
+    countryTok = { primary: name, alternates: [iso] };
+  }
+
+  // The nearest-city row inserts a POI for that city, so the token is a POSITIONAL
+  // `poi <City> <scope>` line — a bare `<City> <scope>` would parse as a REGION
+  // declaration and fail to resolve. Scope = the US subdivision (US-only), else
+  // the country ISO; bare `poi <City>` when neither disambiguates.
+  let cityTok: ResultTokens['city'] = null;
+  if (city) {
+    const scope = city.sub ?? (city.iso || '');
+    cityTok = scope
+      ? { token: `poi ${city.name} ${scope}`, ambiguous: false }
+      : { token: `poi ${city.name}`, ambiguous: true };
+  }
+
+  return { coordPoiLine, state: stateTok, country: countryTok, city: cityTok };
+}
+
+const MAX_CITY_DOTS = 250;
+
+/** Construct a geo-query handle bound to the layout for `(content, width,
+ *  height, data, palette, isDark)`. Deterministic: identical inputs ⇒ the same
+ *  fitted projection the rendered SVG used, so inverted clicks align. */
+export function createMapGeoQuery(opts: CreateMapGeoQueryOptions): MapGeoQuery {
+  const { content, width, height, data, palette, isDark } = opts;
+  const resolved = resolveMap(parseMap(content), data);
+  const layout: MapLayout = layoutMap(
+    resolved,
+    data,
+    { width, height },
+    { palette, isDark }
+  );
+
+  // Decode the boundary features ONCE (review L3) — country containment against
+  // world-detail (50m); US-state against us-states (10m).
+  const countries: DecodedFeature[] = decodeFeatures(data.worldDetail);
+  const states: DecodedFeature[] = decodeFeatures(data.usStates);
+  const gazetteer = data.gazetteer;
+
+  const invert = (px: number, py: number): [number, number] | null =>
+    pixelToLonLat(layout, px, py);
+  const project = (
+    lonLat: readonly [number, number]
+  ): [number, number] | null => lonLatToPixel(layout, lonLat);
+
+  const locate = (px: number, py: number): ResultCard | null => {
+    const lonLat = invert(px, py);
+    if (!lonLat) return null;
+    const region = regionAt(lonLat, countries, states);
+    const city = nearestCity(lonLat, gazetteer);
+    return {
+      lonLat,
+      country: region.country,
+      state: region.state,
+      nearestCity: city,
+      tokens: buildTokens(lonLat, region, city),
+    };
+  };
+
+  const cities = (extent?: GeoExtent): ProjectedCity[] => {
+    // Population-primary cull (extent only a coarse secondary filter — review
+    // L-NEW-3): the data extent is NOT the visible viewport when a wide map is
+    // scrolled, so rank by population and cap, keeping only on-canvas dots.
+    const sorted = [...gazetteer.cities].sort((a, b) => b[3] - a[3]);
+    const out: ProjectedCity[] = [];
+    for (const c of sorted) {
+      const [lat, lon, iso, pop, name, sub] = c;
+      if (extent) {
+        const [[w, s], [e, n]] = extent;
+        if (lon < w || lon > e || lat < s || lat > n) continue;
+      }
+      const p = project([lon, lat]);
+      if (!p) continue;
+      if (p[0] < 0 || p[0] > width || p[1] < 0 || p[1] > height) continue;
+      out.push({
+        name,
+        iso,
+        ...(sub !== undefined && { sub }),
+        lon,
+        lat,
+        px: p[0],
+        py: p[1],
+        pop,
+      });
+      if (out.length >= MAX_CITY_DOTS) break;
+    }
+    return out;
+  };
+
+  return { invert, project, locate, cities };
+}

package/src/map/geo.ts

@@ -2,7 +2,7 @@
 // feature bounds (via d3-geo geoBounds — NOT naive min/max, which breaks on the
 // antimeridian and on multi-part features like US Alaska/Hawaii; R5/R6).
 import { feature } from 'topojson-client';
-import { geoBounds } from 'd3-geo';
+import { geoBounds, geoArea } from 'd3-geo';
 import type { BoundaryTopology } from './data/types';
 import type { GeoExtent } from './resolved-types';
 
@@ -47,6 +47,159 @@ export function idSet(topo: BoundaryTopology): Set<string> {
   return new Set(geomObject(topo).geometries.map((g) => g.id));
 }
 
+/** A decoded boundary feature: the GeoJSON geometry plus its ISO id and display
+ *  name (carried straight from the topology's `properties.name`). Used for
+ *  point-in-polygon reverse-geocoding by the geo-query. */
+export interface DecodedFeature {
+  readonly type: 'Feature';
+  readonly id: string;
+  readonly properties: { readonly name: string };
+  readonly geometry: unknown;
+}
+
+/** Decode every feature of a topology into GeoJSON, keyed nowhere — returned as a
+ *  flat array so the geo-query can decode ONCE at construction and reuse the
+ *  result across every `regionAt` call (no per-click re-decode). Uses this
+ *  module's own `geomObject`/`feature` (never layout.ts's private decoder). */
+export function decodeFeatures(topo: BoundaryTopology): DecodedFeature[] {
+  return geomObject(topo).geometries.map((g) => {
+    const f = feature(topo as never, g as never) as unknown as {
+      geometry: unknown;
+    };
+    return {
+      type: 'Feature',
+      id: g.id,
+      properties: g.properties,
+      geometry: f.geometry,
+    };
+  });
+}
+
+/** Even-odd ray-cast: is `[lon, lat]` inside a single lon/lat ring? Planar (NOT
+ *  spherical): d3-geo `geoContains` is winding-sensitive and the Natural-Earth
+ *  rings invert under it (a small country reads as covering the globe). A planar
+ *  ray-cast on the raw lon/lat coordinates is the correct, robust test at this
+ *  reverse-geocode resolution (antimeridian crossers ship as seam-split parts, so
+ *  no ring actually wraps ±180). */
+function pointInRing(
+  lon: number,
+  lat: number,
+  ring: ReadonlyArray<readonly number[]>
+): boolean {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const xi = ring[i]![0]!;
+    const yi = ring[i]![1]!;
+    const xj = ring[j]![0]!;
+    const yj = ring[j]![1]!;
+    const intersect =
+      yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi;
+    if (intersect) inside = !inside;
+  }
+  return inside;
+}
+
+// On-boundary tolerance (degrees). A click landing exactly on a shared border or
+// a ring vertex is otherwise float-dependent (ray-cast vertex double-count → the
+// point reads as inside neither neighbour, returning ocean over land). Treating
+// an on-edge point as INSIDE makes `regionAt` deterministic: the first iterated
+// country whose boundary the point sits on wins, rather than a rounding coin-flip.
+const EDGE_EPS = 1e-9;
+
+/** Is `[lon, lat]` on any edge of `ring` (within EDGE_EPS)? */
+function pointOnRingEdge(
+  lon: number,
+  lat: number,
+  ring: ReadonlyArray<readonly number[]>
+): boolean {
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const xi = ring[i]![0]!;
+    const yi = ring[i]![1]!;
+    const xj = ring[j]![0]!;
+    const yj = ring[j]![1]!;
+    // Bounding-box reject first (cheap).
+    if (lon < Math.min(xi, xj) - EDGE_EPS || lon > Math.max(xi, xj) + EDGE_EPS)
+      continue;
+    if (lat < Math.min(yi, yj) - EDGE_EPS || lat > Math.max(yi, yj) + EDGE_EPS)
+      continue;
+    // Collinear with the segment ⇒ on it (bbox already bounded the extent).
+    const cross = (xj - xi) * (lat - yi) - (yj - yi) * (lon - xi);
+    if (Math.abs(cross) <= EDGE_EPS) return true;
+  }
+  return false;
+}
+
+/** Point-in-polygon for a Polygon/MultiPolygon geometry (outer ring minus holes).
+ *  A point on the outer boundary counts as inside (deterministic border handling). */
+function pointInGeometry(geometry: unknown, lon: number, lat: number): boolean {
+  const g = geometry as {
+    type: string;
+    coordinates: number[][][] | number[][][][];
+  } | null;
+  if (!g) return false;
+  const polys: number[][][][] =
+    g.type === 'Polygon'
+      ? [g.coordinates as number[][][]]
+      : g.type === 'MultiPolygon'
+        ? (g.coordinates as number[][][][])
+        : [];
+  for (const rings of polys) {
+    if (!rings.length) continue;
+    // On the outer boundary ⇒ inside (deterministic; beats the ray-cast coin-flip).
+    if (pointOnRingEdge(lon, lat, rings[0]!)) return true;
+    if (!pointInRing(lon, lat, rings[0]!)) continue;
+    // Inside the outer ring — exclude if it falls strictly within a hole (a point
+    // on the hole boundary is still land, so it stays inside).
+    let inHole = false;
+    for (let h = 1; h < rings.length; h++) {
+      if (
+        pointInRing(lon, lat, rings[h]!) &&
+        !pointOnRingEdge(lon, lat, rings[h]!)
+      ) {
+        inHole = true;
+        break;
+      }
+    }
+    if (!inHole) return true;
+  }
+  return false;
+}
+
+/** Reverse-geocode a `[lon, lat]` to its containing country and (US-only) state
+ *  via planar point-in-polygon. Honest about misses: returns `country: null`
+ *  when no polygon contains the point (open ocean / outside any country) rather
+ *  than guessing (F4). State is tested only when the country is the US.
+ *  `countries` should be world-detail (50m) features; `states` the us-states
+ *  (10m) features. Both are pre-decoded by the caller. */
+export function regionAt(
+  lonLat: readonly [number, number],
+  countries: readonly DecodedFeature[],
+  states: readonly DecodedFeature[] | null
+): {
+  country: { iso: string; name: string } | null;
+  state: { iso: string; name: string } | null;
+} {
+  const lon = lonLat[0];
+  const lat = lonLat[1];
+  let country: { iso: string; name: string } | null = null;
+  for (const f of countries) {
+    if (pointInGeometry(f.geometry, lon, lat)) {
+      country = { iso: f.id, name: f.properties.name };
+      break;
+    }
+  }
+  let state: { iso: string; name: string } | null = null;
+  if (country?.iso === 'US' && states) {
+    for (const f of states) {
+      if (pointInGeometry(f.geometry, lon, lat)) {
+        state = { iso: f.id, name: f.properties.name };
+        break;
+      }
+    }
+  }
+  return { country, state };
+}
+
 /** Antimeridian-correct geographic bbox of one feature (by id), or null. */
 export function featureBbox(
   topo: BoundaryTopology,
@@ -65,6 +218,110 @@ export function featureBbox(
   ];
 }
 
+// Framing-extent thresholds for `featureBboxPrimary` (R5). A detached polygon is
+// kept in the framing bbox only if it is either near the dominant cluster
+// (within GAP degrees in both axes) or large enough to matter (≥ AREA_FRAC of
+// the largest polygon). This drops far-flung minor territories — French Guiana,
+// Hawaii, the Canaries are already absent from coarse Spain — so a "Europe"
+// choropleth that names France frames on metropolitan France, not the Atlantic,
+// while keeping near islands and large detached parts (Alaska) in frame.
+const DETACH_GAP_DEG = 10;
+const DETACH_AREA_FRAC = 0.25;
+
+/** Decompose a Polygon/MultiPolygon GeoJSON geometry into per-polygon features. */
+function explodePolygons(gj: {
+  type: string;
+  geometry?: { type: string; coordinates: unknown };
+}): Array<{
+  type: 'Feature';
+  geometry: { type: 'Polygon'; coordinates: unknown };
+}> {
+  const g = gj.geometry ?? (gj as never);
+  const t = (g as { type: string }).type;
+  const coords = (g as { coordinates: unknown[] }).coordinates;
+  if (t === 'Polygon') {
+    return [
+      { type: 'Feature', geometry: { type: 'Polygon', coordinates: coords } },
+    ];
+  }
+  if (t === 'MultiPolygon') {
+    return (coords as unknown[]).map((rings) => ({
+      type: 'Feature' as const,
+      geometry: { type: 'Polygon' as const, coordinates: rings },
+    }));
+  }
+  return [];
+}
+
+/** Gap (degrees) between two bboxes — 0 if they overlap/touch on an axis. */
+function bboxGap(a: GeoExtent, b: GeoExtent): number {
+  const lonGap = Math.max(0, a[0][0] - b[1][0], b[0][0] - a[1][0]);
+  const latGap = Math.max(0, a[0][1] - b[1][1], b[0][1] - a[1][1]);
+  return Math.max(lonGap, latGap);
+}
+
+/** Like `featureBbox`, but for FRAMING: ignores far-detached minor territories
+ *  (overseas DOM-TOM, distant small islands) so a multi-part country frames on
+ *  its dominant landmass cluster. Falls back to the full bbox for single-part
+ *  features or when decomposition fails. Antimeridian-spanning parts (geoBounds
+ *  west > east) are treated as full-bbox to avoid mis-clustering across the seam. */
+export function featureBboxPrimary(
+  topo: BoundaryTopology,
+  geomId: string
+): GeoExtent | null {
+  const geom = geomObject(topo).geometries.find((g) => g.id === geomId);
+  if (!geom) return null;
+  const gj = feature(topo as never, geom as never) as never;
+  const parts = explodePolygons(gj);
+  if (parts.length <= 1) return featureBbox(topo, geomId);
+
+  const polys = parts
+    .map((p) => {
+      const b = geoBounds(p as never);
+      if (!b || !Number.isFinite(b[0][0])) return null;
+      // Skip antimeridian-wrapping parts for clustering math (handled by full bbox).
+      const wraps = b[1][0] < b[0][0];
+      const bbox: GeoExtent = [
+        [b[0][0], b[0][1]],
+        [b[1][0], b[1][1]],
+      ];
+      return { bbox, area: geoArea(p as never), wraps };
+    })
+    .filter(
+      (p): p is { bbox: GeoExtent; area: number; wraps: boolean } => p !== null
+    );
+
+  if (polys.length <= 1 || polys.some((p) => p.wraps))
+    return featureBbox(topo, geomId);
+
+  const maxArea = Math.max(...polys.map((p) => p.area));
+  const anchor = polys.find((p) => p.area === maxArea)!;
+  // Grow the cluster: keep a part if it is near the current cluster OR large.
+  const cluster: GeoExtent = [
+    [anchor.bbox[0][0], anchor.bbox[0][1]],
+    [anchor.bbox[1][0], anchor.bbox[1][1]],
+  ];
+  const remaining = polys.filter((p) => p !== anchor);
+  let added = true;
+  while (added) {
+    added = false;
+    for (let i = remaining.length - 1; i >= 0; i--) {
+      const p = remaining[i]!;
+      const near = bboxGap(p.bbox, cluster) <= DETACH_GAP_DEG;
+      const large = p.area >= DETACH_AREA_FRAC * maxArea;
+      if (near || large) {
+        cluster[0][0] = Math.min(cluster[0][0], p.bbox[0][0]);
+        cluster[0][1] = Math.min(cluster[0][1], p.bbox[0][1]);
+        cluster[1][0] = Math.max(cluster[1][0], p.bbox[1][0]);
+        cluster[1][1] = Math.max(cluster[1][1], p.bbox[1][1]);
+        remaining.splice(i, 1);
+        added = true;
+      }
+    }
+  }
+  return cluster;
+}
+
 /** Union of bboxes + POI points into one extent; null if empty. Longitude union
  *  uses the smaller-arc rule so an antimeridian-crossing union doesn't span the
  *  globe.

package/src/map/invert.ts

@@ -0,0 +1,111 @@
+// Composite- + stretch-aware pixel↔lonLat for the geo-query (step-5 inspector).
+// This is the FIRST map code to call `projection.invert()`. It binds to the
+// REAL fitted projection(s) captured on the MapLayout (layout.ts Task 1) — the
+// caller never reconstructs a projection from metadata, so an inverted pixel
+// lands exactly where the rendered SVG drew the corresponding point.
+//
+// Three cases, in priority order:
+//   1. albers-usa insets — a pixel inside an AK/HI frame rect inverts against
+//      that inset's FITTED projection (the un-fitted factory would be garbage).
+//   2. global stretch fit — undo the non-uniform stretch BEFORE the main invert
+//      (and apply it AFTER the main project).
+//   3. plain regional/world fit — invert/project the main projection directly
+//      (clipExtent set on a regional projection is ignored by `.invert`).
+import type { MapLayout, MapLayoutInset } from './layout';
+
+/** True if `(px,py)` is inside an inset frame's bounding box. */
+function inInsetFrame(inset: MapLayoutInset, px: number, py: number): boolean {
+  return (
+    px >= inset.x &&
+    px <= inset.x + inset.w &&
+    py >= inset.y &&
+    py <= inset.y + inset.h
+  );
+}
+
+/** Undo the global stretch: screen px → base-projection px. */
+function unstretch(
+  layout: MapLayout,
+  px: number,
+  py: number
+): [number, number] {
+  const s = layout.stretch!;
+  return [
+    s.bx0 + (s.sx !== 0 ? (px - s.ox) / s.sx : 0),
+    s.by0 + (s.sy !== 0 ? (py - s.oy) / s.sy : 0),
+  ];
+}
+
+/** Apply the global stretch: base-projection px → screen px. */
+function applyStretch(
+  layout: MapLayout,
+  x: number,
+  y: number
+): [number, number] {
+  const s = layout.stretch!;
+  return [s.ox + (x - s.bx0) * s.sx, s.oy + (y - s.by0) * s.sy];
+}
+
+/** Screen pixel → `[lon, lat]`, or null for an out-of-domain pixel (e.g. deep
+ *  ocean beyond the projection's clip disc). */
+export function pixelToLonLat(
+  layout: MapLayout,
+  px: number,
+  py: number
+): [number, number] | null {
+  // (1) Inset hit-test first — AK/HI frames sit over the lower-left water of the
+  // conus, so their pixels would otherwise invert against the conus conic.
+  for (const inset of layout.insets) {
+    if (inInsetFrame(inset, px, py)) {
+      const ll = inset.projection.invert?.([px, py]);
+      return ll && Number.isFinite(ll[0]) && Number.isFinite(ll[1])
+        ? [ll[0], ll[1]]
+        : null;
+    }
+  }
+  // (2)/(3) main projection (undo the stretch first for a global fit).
+  const [x, y] = layout.stretch ? unstretch(layout, px, py) : [px, py];
+  const ll = layout.projection.invert?.([x, y]);
+  return ll && Number.isFinite(ll[0]) && Number.isFinite(ll[1])
+    ? [ll[0], ll[1]]
+    : null;
+}
+
+/** `[lon, lat]` → screen pixel, or null if it projects nowhere. AK/HI points
+ *  land in their inset frames; everything else projects via the main projection
+ *  (with the forward stretch for a global fit). */
+export function lonLatToPixel(
+  layout: MapLayout,
+  lonLat: readonly [number, number]
+): [number, number] | null {
+  const pt: [number, number] = [lonLat[0], lonLat[1]];
+  // Main projection first.
+  const main = layout.projection(pt);
+  const mainPx: [number, number] | null =
+    main && Number.isFinite(main[0]) && Number.isFinite(main[1])
+      ? layout.stretch
+        ? applyStretch(layout, main[0], main[1])
+        : [main[0], main[1]]
+      : null;
+  // If the main pixel is on-canvas, it's the lower-48/world position — use it.
+  const onCanvas =
+    !!mainPx &&
+    mainPx[0] >= 0 &&
+    mainPx[0] <= layout.width &&
+    mainPx[1] >= 0 &&
+    mainPx[1] <= layout.height;
+  if (onCanvas) return mainPx;
+  // Off-canvas under the main projection (AK/HI under the conus conic): see if an
+  // inset claims it — project via the inset and keep it if it lands in the frame.
+  for (const inset of layout.insets) {
+    const p = inset.projection(pt);
+    if (
+      p &&
+      Number.isFinite(p[0]) &&
+      Number.isFinite(p[1]) &&
+      inInsetFrame(inset, p[0], p[1])
+    )
+      return [p[0], p[1]];
+  }
+  return mainPx;
+}