@diagrammo/dgmo 0.21.1 → 0.23.0

package/src/map/dimensions.ts

@@ -0,0 +1,117 @@
+// Content-aware export dimensions for maps (§ export-content-aspect).
+//
+// Outside the app — CLI, MCP, SSG embeds (remark/astro/docusaurus/fumadocs), and
+// Obsidian — maps were rendered into a fixed 1200×800 canvas. A world map is
+// ~2.3:1, so the global stretch-fill distorted it vertically to fill the too-tall
+// box. These helpers derive the canvas HEIGHT from the map's intrinsic projected
+// aspect so the export matches the content's natural shape.
+//
+// dgmo emits the intrinsic aspect; the host context decides display fit (Obsidian
+// sets the embedded <svg> to width:100% + aspect-ratio from the viewBox). Aspect
+// is the invariant; `baseWidth` is just a resolution knob.
+import { geoPath } from 'd3-geo';
+import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
+import { buildMapProjection } from './layout';
+import type { ResolvedMap } from './resolved-types';
+import type { MapData } from './resolved-types';
+
+// Mirror the layout constants so the chrome reserve matches what the renderer
+// actually reserves (layout.ts FIT_PAD / TITLE_GAP).
+const FIT_PAD = 24;
+const TITLE_GAP = 16;
+
+// Clamp guardrails (w/h). The clamp is for PATHOLOGICAL extents, not the common
+// case — world/continent/country must land at their true projected aspect.
+//   ASPECT_MAX = 3.0  → never wider/shorter than 3:1. The default world projection
+//                       is EQUIRECTANGULAR (see resolver.ts ~L744); a full-world
+//                       extent measures ~2.4:1 and a narrower-latitude world up to
+//                       ~2.65:1 — all comfortably under 3.0, so any reasonable world
+//                       renders at its true aspect (no letterbox). Only a genuinely
+//                       extreme >3:1 band (e.g. a thin trans-global route) is clamped.
+//   ASPECT_MIN = 0.9  → never taller than ~1:1.1, so a tall country embedded at
+//                       width:100% in a narrow note column stays sane.
+const ASPECT_MAX = 3.0;
+const ASPECT_MIN = 0.9;
+// Minimum px of actual map area (below the chrome band) — keeps a short canvas
+// (very wide extent) from being crowded out by the title/caption.
+const MIN_MAP_BAND = 200;
+// Defensive fallback when the content aspect is non-finite (NaN/0/Infinity). The
+// resolver always pads the extent to a non-degenerate box, so in practice this is
+// not reached via the public pipeline — it guards a degenerate `fitTarget` directly.
+const FALLBACK_ASPECT = 1.5; // 3:2
+// Square reference box for aspect measurement. Uniform `fitSize` scaling makes the
+// measured aspect invariant to this value — it MUST be square (a non-square box
+// would leak into the ratio).
+const REF = 1000;
+
+/** The map's intrinsic projected aspect (width / height) for a resolved map.
+ *
+ *  Measured by fitting the projection + fit target (the SAME `buildMapProjection`
+ *  output the renderer draws with) into a square reference box and reading the
+ *  projected bounds of the fit target. `fitSize` scales uniformly, so the ratio is
+ *  independent of the box size (see the reference-box invariance test).
+ *
+ *  Returns {@link FALLBACK_ASPECT} (3:2) if the result is non-finite or ≤ 0 — the
+ *  helper never emits a NaN/0/Infinity aspect. */
+export function mapContentAspect(
+  resolved: ResolvedMap,
+  data: MapData,
+  /** Square reference box for the measurement. Uniform `fitSize` scaling makes the
+   *  result invariant to this value; exposed only so tests can assert that. */
+  ref = REF
+): number {
+  const { projection, fitTarget } = buildMapProjection(resolved, data);
+  projection.fitSize([ref, ref], fitTarget as never);
+  const b = geoPath(projection).bounds(fitTarget as never);
+  const w = b[1][0] - b[0][0];
+  const h = b[1][1] - b[0][1];
+  const aspect = w / h;
+  return Number.isFinite(aspect) && aspect > 0 ? aspect : FALLBACK_ASPECT;
+}
+
+/** Content-aware export dimensions for a map: `width` fixed at `baseWidth`,
+ *  `height` derived from the clamped intrinsic aspect, with a minimum-map-band
+ *  floor for very wide extents. `preferContain` is true when the clamp or floor
+ *  forced the canvas off the content aspect — the renderer then contain-fits
+ *  (letterbox) instead of stretching, so the off-aspect canvas doesn't re-distort. */
+export interface MapExportDimensions {
+  readonly width: number;
+  readonly height: number;
+  readonly preferContain: boolean;
+}
+
+export function mapExportDimensions(
+  resolved: ResolvedMap,
+  data: MapData,
+  baseWidth = 1200
+): MapExportDimensions {
+  const raw = mapContentAspect(resolved, data);
+  const clamped = Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
+  const width = baseWidth;
+  let height = Math.round(width / clamped);
+
+  // Chrome reserve mirrors layout.ts `topPad` EXACTLY — the only chrome the layout
+  // actually subtracts from the map's fit box. The top banner reserves space ONLY
+  // when a title AND POIs are present (a POI-less choropleth lets the title overlay
+  // the land). The legend (foreground, top-center) and the caption (drawn at
+  // height-8, overlapping the bottom) reserve NO layout height in the renderer, so
+  // they are deliberately excluded — adding them would over-reserve.
+  let chromeReserve = 0;
+  if (resolved.title && resolved.pois.length > 0) {
+    const bannerBottom =
+      (resolved.subtitle ? TITLE_Y + TITLE_FONT_SIZE : TITLE_Y) +
+      TITLE_FONT_SIZE / 2;
+    chromeReserve += Math.max(FIT_PAD, bannerBottom + TITLE_GAP) - FIT_PAD;
+  }
+
+  let floored = false;
+  if (height - chromeReserve < MIN_MAP_BAND) {
+    height = Math.round(chromeReserve + MIN_MAP_BAND);
+    floored = true;
+  }
+
+  // The canvas was forced off the content aspect ⇒ tell the renderer to
+  // contain-fit (letterbox) rather than stretch-distort.
+  const preferContain = clamped !== raw || floored;
+  return { width, height, preferContain };
+}

package/src/map/geo-query.ts

@@ -21,14 +21,19 @@ import type { DecodedFeature } from './geo';
 import { pixelToLonLat, lonLatToPixel } from './invert';
 import type { MapData, GeoExtent } from './resolved-types';
 import type { Gazetteer } from './data/types';
+import type { DgmoError } from '../diagnostics';
 
 /** Nearest gazetteer city to a point: the real haversine distance, plus the
- *  canonical name + ISO + (US-only) subdivision for token shaping. */
+ *  canonical name + ISO + (US-only) subdivision for token shaping. `lon`/`lat`
+ *  are the city's own gazetteer coordinates (so callers can mark it on the map,
+ *  distinct from the inspected point). */
 export interface NearestCity {
   readonly name: string;
   readonly iso: string;
   readonly sub?: string;
   readonly distanceKm: number;
+  readonly lon: number;
+  readonly lat: number;
 }
 
 /** A region declaration with its canonical/primary form plus bare alternates
@@ -85,6 +90,10 @@ export interface MapGeoQuery {
   locate(px: number, py: number): ResultCard | null;
   /** Culled + projected cities for the all-cities layer (population-primary). */
   cities(extent?: GeoExtent): ProjectedCity[];
+  /** Layout-time, dimension-dependent diagnostics. They live on the geo-query
+   *  (bound to the rendered layout) rather than the resolver. Callers merge them
+   *  with `resolved.diagnostics`. (No producers currently — always empty.) */
+  readonly diagnostics: readonly DgmoError[];
 }
 
 export interface CreateMapGeoQueryOptions {
@@ -144,6 +153,8 @@ function nearestCity(
     iso: c[2],
     ...(c[5] !== undefined && { sub: c[5] }),
     distanceKm: best.dist,
+    lat: c[0],
+    lon: c[1],
   };
 }
 
@@ -206,7 +217,14 @@ 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. */
+ *  fitted projection the rendered SVG used, so inverted clicks align.
+ *
+ *  INVARIANT: this is the PREVIEW path — it never passes `preferContain`, so its
+ *  layout matches the in-app preview (stretch-fill), where geo-query is used. It is
+ *  NOT valid against a content-aware EXPORT canvas (which may set `preferContain` →
+ *  contain-fit): the inverted positions would not match that export's pixels. If
+ *  geo-query is ever pointed at an export canvas, thread `preferContain` through
+ *  `CreateMapGeoQueryOptions` to keep the projection in sync. */
 export function createMapGeoQuery(opts: CreateMapGeoQueryOptions): MapGeoQuery {
   const { content, width, height, data, palette, isDark } = opts;
   const resolved = resolveMap(parseMap(content), data);
@@ -273,5 +291,5 @@ export function createMapGeoQuery(opts: CreateMapGeoQueryOptions): MapGeoQuery {
     return out;
   };
 
-  return { invert, project, locate, cities };
+  return { invert, project, locate, cities, diagnostics: layout.diagnostics };
 }

package/src/map/geo.ts

@@ -1,7 +1,7 @@
 // Geometry helpers for the resolver: topology indexing + antimeridian-correct
 // 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 { feature, neighbors } from 'topojson-client';
 import { geoBounds, geoArea } from 'd3-geo';
 import type { BoundaryTopology } from './data/types';
 import type { GeoExtent } from './resolved-types';
@@ -47,6 +47,52 @@ export function idSet(topo: BoundaryTopology): Set<string> {
   return new Set(geomObject(topo).geometries.map((g) => g.id));
 }
 
+// Memoize adjacency on the RAW asset object (never the per-render-mutated
+// `worldLayer`). Keyed by topology identity — the assets are stable singletons
+// from load-data.ts, so one build per topology lasts the process (G13).
+const adjacencyCache = new WeakMap<BoundaryTopology, Map<string, string[]>>();
+
+/** Per-topology arc-adjacency: ISO → neighbour ISOs, from shared TopoJSON arcs
+ *  (`topojson-client.neighbors()` on the RAW topology geometries — arcs live on
+ *  the topology, independent of any `feature()` decode — F2/ADR-4). Computed
+ *  per-topology (a country never neighbours a state) and memoized.
+ *
+ *  DATA HYGIENE (G1): the raw geometry array can carry (a) `type: null`
+ *  sovereignty stubs with no arcs (e.g. "Ashmore & Cartier Is." tagged `AU`) and
+ *  (b) genuine duplicate ISO ids. Null stubs are skipped (no arcs → no
+ *  adjacency), and every geometry sharing one ISO is UNIONED into a single ISO
+ *  node — matching the merged layer `decodeLayer` actually draws. Without this
+ *  the ISO-keyed graph corrupts and the AC9 no-collision guarantee degrades. */
+export function buildAdjacency(topo: BoundaryTopology): Map<string, string[]> {
+  const cached = adjacencyCache.get(topo);
+  if (cached) return cached;
+  const geometries = geomObject(topo).geometries as Array<{
+    id: string;
+    type?: string;
+  }>;
+  // neighbors() returns, per geometry BY ARRAY POSITION, the indices of
+  // arc-sharing geometries. Null-geometry stubs share no arcs → empty lists.
+  const nb = neighbors(geometries as never);
+  const sets = new Map<string, Set<string>>();
+  geometries.forEach((g, i) => {
+    if (!g.type || g.type === 'null') return; // skip arc-less sovereignty stubs
+    let set = sets.get(g.id);
+    if (!set) {
+      set = new Set<string>();
+      sets.set(g.id, set);
+    }
+    for (const j of nb[i] ?? []) {
+      const nid = geometries[j]?.id;
+      if (nid && nid !== g.id) set.add(nid); // union; never self
+    }
+  });
+  const out = new Map<string, string[]>();
+  // Deterministic neighbour order (sorted) so downstream coloring is stable.
+  for (const [iso, set] of sets) out.set(iso, [...set].sort());
+  adjacencyCache.set(topo, out);
+  return out;
+}
+
 /** 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. */