@diagrammo/dgmo 0.22.0 → 0.24.0

package/src/map/dimensions.ts

@@ -83,10 +83,24 @@ export interface MapExportDimensions {
 export function mapExportDimensions(
   resolved: ResolvedMap,
   data: MapData,
-  baseWidth = 1200
+  baseWidth = 1200,
+  /** WYSIWYG override (app export): the live preview pane's displayed aspect
+   *  (width / height). When provided, the canvas adopts it verbatim and
+   *  stretch-fills (no clamp, no contain) so the PNG matches exactly what's on
+   *  screen. Omitted by every headless consumer (CLI / MCP / SSG / Obsidian),
+   *  which keep the intrinsic-aspect sizing below. */
+  aspectOverride?: number
 ): MapExportDimensions {
-  const raw = mapContentAspect(resolved, data);
-  const clamped = Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
+  const useOverride =
+    aspectOverride !== undefined &&
+    Number.isFinite(aspectOverride) &&
+    aspectOverride > 0;
+  const raw = useOverride ? aspectOverride : mapContentAspect(resolved, data);
+  // The override is the user's on-screen aspect — honour it as-is (no clamp);
+  // only the intrinsic path guards against pathological extents.
+  const clamped = useOverride
+    ? raw
+    : Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
   const width = baseWidth;
   let height = Math.round(width / clamped);
 
@@ -111,7 +125,9 @@ export function mapExportDimensions(
   }
 
   // The canvas was forced off the content aspect ⇒ tell the renderer to
-  // contain-fit (letterbox) rather than stretch-distort.
-  const preferContain = clamped !== raw || floored;
+  // contain-fit (letterbox) rather than stretch-distort. The WYSIWYG override is
+  // exempt: it stretch-fills (mirroring the preview pane) unless the MIN_MAP_BAND
+  // floor had to grow the canvas off-aspect.
+  const preferContain = useOverride ? floored : clamped !== raw || floored;
   return { width, height, preferContain };
 }

package/src/map/layout.ts

@@ -36,6 +36,9 @@ import {
 import type { LabelRect, PointCircle } from '../label-layout';
 import { measureLegendText } from '../utils/legend-constants';
 import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
+import type { LegendMode } from '../utils/legend-types';
+import { mapLegendBand } from './legend-band';
+import type { MapLayoutLegend } from './types';
 import type { DgmoError } from '../diagnostics';
 import type { BoundaryTopology } from './data/types';
 import type {
@@ -69,6 +72,16 @@ const R_MAX = 22;
 const W_MIN = 1.25; // edge stroke width
 const W_MAX = 8;
 const FONT = 11; // on-map label font px
+
+// A few countries have far-flung territory that drags the area-weighted centroid
+// off the mainland (US → Alaska pulls it up into Canada). Anchor their world-layer
+// label/hover point to a mainland [lon, lat] instead. Antimeridian crossers whose
+// body dominates by area (Russia) are NOT listed — their area-weighted centroid
+// already lands on the mainland; only the naive bounding-box centre (which the app
+// previously used for hover) mistook the wrapped sliver for half the shape.
+const WORLD_LABEL_ANCHORS: Record<string, [number, number]> = {
+  US: [-98.5, 39.5], // CONUS geographic centre (near Lebanon, Kansas)
+};
 // POI-cluster hover-only gate (Decision #1). A ≥2-member cluster's callout
 // column falls back to hover-only labels when it would sprawl or overflow:
 //  - MAX_CLUSTER_EXTENT_FACTOR × min(width,height) = the px diagonal beyond which
@@ -112,16 +125,21 @@ const RELIEF_MIN_DIM = 2; // px
 // Relief = horizontal hachure lines clipped to each range: a subtle
 // dark-on-light / light-on-dark texture that reads as "mountains here". Spacing
 // is SCREEN-space so density is constant regardless of zoom (geo-space spacing
-// would collapse a small range to 1–2 lines and read as a glitch). Kept FAINT:
-// thin sub-pixel lines drawn with a non-scaling stroke (constant device width at
-// any zoom/DPR) and low-contrast colour. NOT crispEdges — that snaps the stroke
-// to a solid ~1px in WebKit and reads far too heavy; plain AA keeps them whisper-thin.
-const RELIEF_HATCH_SPACING = 2; // px between lines
-const RELIEF_HATCH_WIDTH = 0.15; // px stroke
+// would collapse a small range to 1–2 lines and read as a glitch). Drawn with a
+// non-scaling stroke (constant device width at any zoom/DPR) and a low-contrast
+// colour so it reads as faint, fine terrain hachure — dense thin lines that are
+// almost indistinguishable as individual strokes (a whisper of texture, not
+// stripes). NOT crispEdges — that snaps the stroke to a solid ~1px in WebKit and
+// reads too heavy; plain AA keeps the lines soft. The width is kept just ABOVE
+// sub-pixel: at ~0.15px the AA fuzz spreads each line to ~1px and tight spacing
+// merges them into a flat grey wash (a "blob"). 0.25px every 1.5px stays a fine,
+// faint hatch on both zoomed-out world maps and zoomed-in regional views.
+const RELIEF_HATCH_SPACING = 1.5; // px between lines
+const RELIEF_HATCH_WIDTH = 0.2; // px stroke
 // % of the DARK reference (palette.bg on dark themes, palette.text on light)
 // blended into the land colour — so the lines read DARKER than the land in both
 // themes (palette.text alone flips to light on dark themes).
-const RELIEF_HATCH_STRENGTH = 32;
+const RELIEF_HATCH_STRENGTH = 26;
 // Coastline water-lines (opt-in `coastline`, §24B.2). N equal-width coast-parallel
 // rings on the water side, evenly spaced and FADING seaward — the antique
 // nautical-chart depth-contour look. Offshore distances + thickness are
@@ -191,6 +209,14 @@ export interface MapLayoutRegion {
   /** The region's tag values keyed by group (lowercased) — emitted as
    *  `data-tag-<group>` so the app can highlight on legend-entry hover. */
   readonly tags?: Readonly<Record<string, string>>;
+  /** Area-weighted screen centroid (px) of the DRAWN geometry — emitted as
+   *  `data-label-x`/`data-label-y` so the app can anchor the hover label here
+   *  instead of the path's bounding-box centre. The bbox centre breaks for
+   *  antimeridian crossers (Russia's wrapped Chukotka sliver pins the box's left
+   *  edge to the far side of the map, dropping the centre into the Atlantic); the
+   *  area-weighted centroid stays on the body. Honours WORLD_LABEL_ANCHORS. */
+  readonly labelX?: number;
+  readonly labelY?: number;
 }
 
 /** A framed inset "cutout" (albers-usa AK/HI), in screen px. The frame is a
@@ -340,21 +366,11 @@ export interface PlacedLabel {
   readonly lineNumber: number;
 }
 
-export interface MapLayoutLegend {
-  readonly tagGroups: ReadonlyArray<{
-    name: string;
-    entries: ReadonlyArray<{ value: string; color: string }>;
-  }>;
-  readonly activeGroup: string | null;
-  readonly ramp?: {
-    metric?: string;
-    min: number;
-    max: number;
-    hue: string;
-    /** Low end of the ramp gradient (the land colour the fills blend from). */
-    base: string;
-  };
-}
+// MapLayoutLegend now lives in ./types (imported for local use + re-exported
+// below) so that ./legend-band can consume the type without importing this
+// module, which would re-introduce the layout↔legend-band cycle (this module
+// value-imports mapLegendBand from ./legend-band).
+export type { MapLayoutLegend };
 
 /** A drawn river centerline — an open stroked path (no fill). */
 export interface MapLayoutRiver {
@@ -459,6 +475,10 @@ export interface LayoutOptions {
    *  canvas away from the content aspect, so the off-aspect canvas doesn't
    *  re-distort. The in-app preview pane leaves this unset (keeps stretch-fill). */
   readonly preferContain?: boolean;
+  /** Which legend variant gets drawn — `'export'` shows only the active group,
+   *  `'preview'` keeps inactive pills. Used to size the reserved legend band so
+   *  the projected land starts below the legend. Defaults to `'preview'`. */
+  readonly legendMode?: LegendMode;
 }
 
 interface Size {
@@ -836,6 +856,60 @@ export function parsePathRings(d: string): Array<Array<[number, number]>> {
   return rings;
 }
 
+/** Drop antimeridian wrap-slivers from a GLOBAL-view region path. A landmass that
+ *  crosses ±180° (Russia's Chukotka, the western Aleutians, Fiji…) is clipped into
+ *  fragments; the far one is a small sliver pinned to the OPPOSITE vertical frame
+ *  edge — it reads as a stray island floating beside its true continent (e.g. the
+ *  "island left of Alaska"). We drop any ring that (a) has an edge collinear with
+ *  the LEFT or RIGHT canvas edge AND (b) is small AND (c) isn't the region's
+ *  largest ring. The mainland (large, on its own edge) and interior islands (not
+ *  frame-cut) are kept. Vertical edges only — a ring cut by the top/bottom lat
+ *  crop is real content, not a wrap. Global-only: regional clipExtent cuts ARE
+ *  real land at the viewport edge and must survive. */
+function dropAntimeridianWrapSlivers(
+  d: string,
+  width: number,
+  height: number
+): string {
+  const rings = parsePathRings(d);
+  if (rings.length <= 1) return d;
+  const eps = 0.75;
+  const minArea = 0.003 * width * height; // 0.3% of canvas
+  const ringArea = (r: ReadonlyArray<[number, number]>): number => {
+    let s = 0;
+    for (let i = 0; i < r.length; i++) {
+      const a = r[i]!;
+      const b = r[(i + 1) % r.length]!;
+      s += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(s) / 2;
+  };
+  const areas = rings.map(ringArea);
+  const maxArea = Math.max(...areas);
+  const onVEdge = (
+    a: readonly [number, number],
+    b: readonly [number, number]
+  ): boolean =>
+    (Math.abs(a[0]) <= eps && Math.abs(b[0]) <= eps) ||
+    (Math.abs(a[0] - width) <= eps && Math.abs(b[0] - width) <= eps);
+  let dropped = false;
+  const kept = rings.filter((r, idx) => {
+    if (areas[idx]! >= maxArea || areas[idx]! >= minArea) return true;
+    const touches = r.some((p, i) => onVEdge(p, r[(i + 1) % r.length]!));
+    if (touches) {
+      dropped = true;
+      return false;
+    }
+    return true;
+  });
+  if (!dropped) return d;
+  return kept
+    .map(
+      (r) => r.map((p, i) => (i ? 'L' : 'M') + p[0] + ',' + p[1]).join('') + 'Z'
+    )
+    .join('');
+}
+
 export function layoutMap(
   resolved: ResolvedMap,
   data: MapData,
@@ -1091,6 +1165,35 @@ export function layoutMap(
 
   const regionById = new Map(resolved.regions.map((r) => [r.iso, r]));
 
+  // -- Legend model (AR1: categorical via renderer's renderLegendD3). Built here
+  // (before the fit) so the fit can reserve a band for it. Only the colouring
+  // dimensions (value ramp + tag groups) get a legend; POI size and edge
+  // thickness are self-evident from the marker/line scale and carry no key. --
+  let legend: MapLayoutLegend | null = null;
+  if (!resolved.directives.noLegend) {
+    const legendTagGroups = resolved.tagGroups.map((g) => ({
+      name: g.name,
+      entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
+    }));
+    if (legendTagGroups.length > 0 || hasRamp) {
+      legend = {
+        tagGroups: legendTagGroups,
+        activeGroup,
+        ...(hasRamp && {
+          ramp: {
+            ...(resolved.directives.regionMetric !== undefined && {
+              metric: resolved.directives.regionMetric,
+            }),
+            min: rampMin,
+            max: rampMax,
+            hue: rampHue,
+            base: rampBase,
+          },
+        }),
+      };
+    }
+  }
+
   // -- Fit the projection to the canvas (size-dependent; the projection + fit
   // target themselves came from buildMapProjection above). --
   // Reserve top padding for the title/subtitle banner ONLY when there are POIs,
@@ -1106,6 +1209,18 @@ export function layoutMap(
       TITLE_FONT_SIZE / 2;
     topPad = Math.max(FIT_PAD, bannerBottom + TITLE_GAP);
   }
+  // Reserve a band for the top-center legend so the projected land starts BELOW
+  // it (the legend is a foreground overlay — without this it covers land, e.g.
+  // Europe on a world map). The band is measured from the SAME groups/config the
+  // renderer draws (mode-aware: export shows only the active group), so the
+  // reserve matches the rendered legend exactly.
+  const legendBand = mapLegendBand(legend, {
+    width,
+    mode: opts.legendMode ?? 'preview',
+    hasTitle: Boolean(resolved.title),
+    hasSubtitle: Boolean(resolved.subtitle),
+  });
+  if (legendBand > topPad) topPad = legendBand;
   const fitBox: [[number, number], [number, number]] = [
     [FIT_PAD, topPad],
     [
@@ -1140,10 +1255,20 @@ export function layoutMap(
     const by0 = cb[0][1];
     const cw = cb[1][0] - bx0;
     const ch = cb[1][1] - by0;
-    const ox = fitBox[0][0];
-    const oy = fitBox[0][1];
-    const sx = cw > 0 ? (fitBox[1][0] - ox) / cw : 1;
-    const sy = ch > 0 ? (fitBox[1][1] - oy) / ch : 1;
+    // A global stretch-fill runs the world to EVERY edge of the canvas — no
+    // FIT_PAD inset. The equirectangular rectangle is the map, so its edges ARE
+    // the render-area edges (the antimeridian sits exactly on the left/right
+    // edge, not 24px short of it with a coastline ringing the gap). The title
+    // overlays the top; we reserve a top band only when POIs are present (so
+    // their markers don't project up under the foreground title banner).
+    const topReserve =
+      (resolved.title && resolved.pois.length > 0) || legendBand > 0
+        ? topPad
+        : 0;
+    const ox = 0;
+    const oy = topReserve;
+    const sx = cw > 0 ? width / cw : 1;
+    const sy = ch > 0 ? (height - topReserve) / ch : 1;
     stretchParams = { sx, sy, ox, oy, bx0, by0 };
     const stretch = (x: number, y: number): [number, number] => [
       ox + (x - bx0) * sx,
@@ -1588,7 +1713,12 @@ export function layoutMap(
       // but still drop antimeridian frame-fillers (Fiji et al.).
       const viewF = shouldCull ? cullFeatureToView(f) : dropFrameFillers(f);
       if (!viewF) continue;
-      const d = path(viewF as never) ?? '';
+      const raw = path(viewF as never) ?? '';
+      // Global views: strip the wrap-sliver a crossing landmass leaves pinned to
+      // the far edge (Russia's Chukotka beside Alaska). Regional cuts are real.
+      const d = fitIsGlobal
+        ? dropAntimeridianWrapSlivers(raw, width, height)
+        : raw;
       if (!d) continue;
       const isThisLayer = r?.layer === layerKind;
       // Non-US neighbour land in a US view is gray context, not yellow land.
@@ -1614,6 +1744,15 @@ export function layoutMap(
         // (the same source the resolver/inset/context-label layers read).
         label = (f.properties as { name?: string } | null)?.name;
       }
+      // Label/hover anchor: a hardcoded mainland anchor when far-flung territory
+      // would skew it, else the area-weighted screen centroid of the drawn shape.
+      // The latter (unlike a bounding-box centre) survives antimeridian crossers.
+      const labelAnchor = WORLD_LABEL_ANCHORS[iso];
+      const c = labelAnchor
+        ? project(labelAnchor[0], labelAnchor[1])
+        : path.centroid(viewF as never);
+      const hasCentroid =
+        c != null && Number.isFinite(c[0]) && Number.isFinite(c[1]);
       regions.push({
         id: iso,
         d,
@@ -1622,6 +1761,7 @@ export function layoutMap(
         lineNumber,
         layer,
         ...(label !== undefined && { label }),
+        ...(hasCentroid && { labelX: c[0], labelY: c[1] }),
         ...(isThisLayer && r.value !== undefined && { value: r.value }),
         ...(isThisLayer && Object.keys(r.tags).length > 0 && { tags: r.tags }),
       });
@@ -2284,12 +2424,6 @@ export function layoutMap(
       lineNumber,
     });
   };
-  // A few countries have far-flung territory that drags the area-weighted
-  // centroid off the mainland (US → Alaska pulls it up into Canada). Anchor
-  // their world-layer label to a mainland [lon, lat] instead.
-  const WORLD_LABEL_ANCHORS: Record<string, [number, number]> = {
-    US: [-98.5, 39.5], // CONUS geographic centre (near Lebanon, Kansas)
-  };
   // A region label's screen footprint, middle-anchored on its centroid, used to
   // keep two region labels from overlapping (a small gap adds breathing room).
   const REGION_LABEL_GAP = 2;
@@ -2794,36 +2928,6 @@ export function layoutMap(
     labels.push(...contextLabels);
   }
 
-  // -- Legend model (AR1: categorical via renderer's renderLegendD3) --
-  let legend: MapLayoutLegend | null = null;
-  if (!resolved.directives.noLegend) {
-    const tagGroups = resolved.tagGroups.map((g) => ({
-      name: g.name,
-      entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
-    }));
-    // Only the colouring dimensions (value ramp + tag groups) get a legend.
-    // POI size and edge thickness are self-evident from the marker/line scale and
-    // intentionally carry no key (the poi-metric/flow-metric labels are captured
-    // for future use but not rendered as legend keys in v1).
-    if (tagGroups.length > 0 || hasRamp) {
-      legend = {
-        tagGroups,
-        activeGroup,
-        ...(hasRamp && {
-          ramp: {
-            ...(resolved.directives.regionMetric !== undefined && {
-              metric: resolved.directives.regionMetric,
-            }),
-            min: rampMin,
-            max: rampMax,
-            hue: rampHue,
-            base: rampBase,
-          },
-        }),
-      };
-    }
-  }
-
   return {
     width,
     height,

package/src/map/legend-band.ts

@@ -0,0 +1,99 @@
+// Vertical band reserved at the top of a map canvas for the choropleth / tag
+// legend, so the projected land starts BELOW the legend instead of being covered
+// by it. The legend (§24B.11) is drawn as a top-center foreground overlay; on a
+// world map that placement sits over land (e.g. Europe), hiding it. Reserving a
+// band in the fit box pushes the map down so the legend clears the land.
+//
+// Shared by `layoutMap` (grows `topPad`) and `mapExportDimensions` is intentionally
+// NOT a consumer — the canvas height is independent; the band only repositions the
+// map WITHIN the canvas. The group builder + config are reused by the renderer so
+// the measured band matches exactly what gets drawn.
+import { computeLegendLayout } from '../utils/legend-layout';
+import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
+import type {
+  LegendConfig,
+  LegendGroupData,
+  LegendMode,
+  LegendState,
+} from '../utils/legend-types';
+import type { MapLayoutLegend } from './types';
+
+// Gap between the title/subtitle banner and the legend top — mirrors the `+ 8`
+// in renderer.ts `legendY`.
+const LEGEND_TOP_GAP = 8;
+// Gap between the legend bottom and the start of the map content.
+const LEGEND_BOTTOM_GAP = 10;
+
+/** The legend's colouring groups (score ramp first, then non-empty tag groups) —
+ *  the SAME array the renderer draws, so a measured layout matches the rendered
+ *  one. Empty when the legend has neither a ramp nor any populated tag group. */
+export function mapLegendGroups(legend: MapLayoutLegend): LegendGroupData[] {
+  const ramp = legend.ramp;
+  // Reserved name "Value" when no region-metric label is set — must match
+  // VALUE_NAME in layout.ts so the resolved activeGroup selects it.
+  const scoreGroup: LegendGroupData | null = ramp
+    ? {
+        name: ramp.metric?.trim() || 'Value',
+        entries: [],
+        gradient: {
+          min: ramp.min,
+          max: ramp.max,
+          hue: ramp.hue,
+          base: ramp.base,
+        },
+      }
+    : null;
+  const tagGroups: LegendGroupData[] = legend.tagGroups
+    .filter((g) => g.entries.length > 0)
+    .map((g) => ({ name: g.name, entries: [...g.entries] }));
+  return [...(scoreGroup ? [scoreGroup] : []), ...tagGroups];
+}
+
+/** The shared map-legend config (top-center, below the title, inactive pills kept
+ *  so the preview can flip the active colouring dimension). `mode` gates the
+ *  export-only filtering (active group only). */
+export function mapLegendConfig(
+  groups: readonly LegendGroupData[],
+  mode: LegendMode
+): LegendConfig {
+  return {
+    groups,
+    position: { placement: 'top-center', titleRelation: 'below-title' },
+    mode,
+    showEmptyGroups: false,
+    showInactivePills: true,
+  };
+}
+
+/** Y of the legend's top edge — mirrors `legendY` in renderer.ts. */
+export function mapLegendTop(hasTitle: boolean, hasSubtitle: boolean): number {
+  return (
+    (hasTitle ? TITLE_Y + TITLE_FONT_SIZE : 0) +
+    (hasSubtitle ? TITLE_FONT_SIZE : 0) +
+    LEGEND_TOP_GAP
+  );
+}
+
+/** Total vertical band (px from the canvas top) the legend occupies = its top Y +
+ *  measured height + a bottom gap. Returns 0 when no legend is drawn, so callers
+ *  can `Math.max` it into their existing top reserve without special-casing. */
+export function mapLegendBand(
+  legend: MapLayoutLegend | null,
+  opts: {
+    width: number;
+    mode: LegendMode;
+    hasTitle: boolean;
+    hasSubtitle: boolean;
+  }
+): number {
+  if (!legend) return 0;
+  const groups = mapLegendGroups(legend);
+  if (groups.length === 0) return 0;
+  const config = mapLegendConfig(groups, opts.mode);
+  const state: LegendState = { activeGroup: legend.activeGroup };
+  const { height } = computeLegendLayout(config, state, opts.width);
+  if (height <= 0) return 0;
+  return (
+    mapLegendTop(opts.hasTitle, opts.hasSubtitle) + height + LEGEND_BOTTOM_GAP
+  );
+}