@diagrammo/dgmo 0.20.3 → 0.21.1

package/src/map/resolver.ts

@@ -14,10 +14,17 @@ import type {
   ResolvedPoi,
   ResolvedEdge,
   ResolvedRoute,
+  ResolvedRouteLeg,
   ProjectionFamily,
   GeoExtent,
 } from './resolved-types';
-import { featureIndex, featureBbox, unionExtent, fold } from './geo';
+import {
+  featureIndex,
+  featureBbox,
+  featureBboxPrimary,
+  unionExtent,
+  fold,
+} from './geo';
 
 /** Discriminated result of a gazetteer name lookup (#5): `defer` is "ambiguous,
  *  retry in pass B with inferred scope" — distinct from `miss` (errored, drop) so
@@ -29,7 +36,13 @@ type LookupResult =
 
 // Projection / tier thresholds (degrees of span) — tunable (R10).
 const WORLD_SPAN = 90;
-const MERCATOR_MAX_SPAN = 25;
+// Mercator is used for everything sub-world (tight clusters AND single-continent
+// regional views — a mid-latitude continent reads with its familiar conventional
+// shape, where equirectangular squashes it). Two guards push back to
+// equirectangular: a world/multi-continent `span` (> WORLD_SPAN), or a frame that
+// reaches into polar latitudes (> MERCATOR_MAX_LAT) where Mercator's sec(φ) area
+// blow-up turns gross. Europe (≈71°N) and East Asia stay comfortably on Mercator.
+const MERCATOR_MAX_LAT = 80;
 const PAD_FRACTION = 0.05;
 // Latitude band for a snapped world view — Tierra del Fuego (≈ −55°) to northern
 // Russia/Canada (≈ +78°). Excludes most of Antarctica + the high Arctic so the
@@ -64,6 +77,75 @@ const REGION_ALIASES: Readonly<Record<string, string>> = {
   'czech republic': 'czechia',
 };
 
+// US state (+ DC) postal abbreviations. A bare trailing two-letter scope token
+// that is one of these resolves to the US STATE `US-XX` (not the colliding
+// ISO 3166-1 country code — e.g. `CA` = California, not Canada) and signals US
+// scope (§24B.8, 2026-06-01). Non-state two-letter tokens (`CR`, `FR`) stay
+// country codes. Trade-off: a foreign country whose code collides with a state
+// (DE/IN/AR/CO/LA/PA/…) can't be picked by bare code — use the city name alone
+// (most-populous) or coordinates.
+const US_STATE_POSTAL: ReadonlySet<string> = new Set([
+  'AL',
+  'AK',
+  'AZ',
+  'AR',
+  'CA',
+  'CO',
+  'CT',
+  'DE',
+  'FL',
+  'GA',
+  'HI',
+  'ID',
+  'IL',
+  'IN',
+  'IA',
+  'KS',
+  'KY',
+  'LA',
+  'ME',
+  'MD',
+  'MA',
+  'MI',
+  'MN',
+  'MS',
+  'MO',
+  'MT',
+  'NE',
+  'NV',
+  'NH',
+  'NJ',
+  'NM',
+  'NY',
+  'NC',
+  'ND',
+  'OH',
+  'OK',
+  'OR',
+  'PA',
+  'RI',
+  'SC',
+  'SD',
+  'TN',
+  'TX',
+  'UT',
+  'VT',
+  'VA',
+  'WA',
+  'WV',
+  'WI',
+  'WY',
+  'DC',
+]);
+
+/** A bare two-letter scope token that names a US state → its `US-XX` 3166-2 id
+ *  (`OR` → `US-OR`), else null. Case-insensitive. */
+function usStateFromBareScope(scope: string | undefined): string | null {
+  if (!scope) return null;
+  const up = scope.toUpperCase();
+  return US_STATE_POSTAL.has(up) ? `US-${up}` : null;
+}
+
 /** Rough US bounding box (incl. AK across the dateline, HI, PR) for classifying
  *  bare coordinate POIs as US-or-not when deciding `albers-usa` (#13). */
 function looksUS(lat: number, lon: number): boolean {
@@ -128,10 +210,16 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       return usStateIndex.has(f) && !countryIndex.has(f);
     }) ||
     parsed.regions.some(
-      (r) => r.scope === 'US' || r.scope?.startsWith('US-')
+      (r) =>
+        r.scope === 'US' ||
+        r.scope?.startsWith('US-') ||
+        usStateFromBareScope(r.scope) !== null
     ) ||
     parsed.pois.some(
-      (p) => p.pos.kind === 'name' && p.pos.scope?.startsWith('US-')
+      (p) =>
+        p.pos.kind === 'name' &&
+        (p.pos.scope?.startsWith('US-') ||
+          usStateFromBareScope(p.pos.scope) !== null)
     );
 
   // ── Regions (R2/R12) ──
@@ -179,17 +267,19 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       }
     } else if (inCountry && inState) {
       if (usScoped) {
+        // A US scope (e.g. `region us-states`) makes the state the unambiguous
+        // intent — resolve silently, no disambiguation warning needed.
         chosen = { ...inState, layer: 'us-state' };
       } else {
         chosen = { ...inCountry, layer: 'country' };
+        // Teach the disambiguation syntax so the author can pin it explicitly.
+        // Suggest the non-redundant forms: a bare ISO code, or name + scope.
+        warn(
+          r.lineNumber,
+          `"${r.name}" is both a country and a US state — resolved as ${chosen.layer} (${chosen.id}). Pin it with an ISO code (${inState.id} / ${inCountry.id}) or name + scope ("${r.name} US" / "${r.name} ${inCountry.id}").`,
+          'W_MAP_REGION_AMBIGUOUS'
+        );
       }
-      // Teach the disambiguation syntax so the author can pin it explicitly.
-      // Suggest the non-redundant forms: a bare ISO code, or name + scope.
-      warn(
-        r.lineNumber,
-        `"${r.name}" is both a country and a US state — resolved as ${chosen.layer} (${chosen.id}). Pin it with an ISO code (${inState.id} / ${inCountry.id}) or name + scope ("${r.name} US" / "${r.name} ${inCountry.id}").`,
-        'W_MAP_REGION_AMBIGUOUS'
-      );
     } else if (inState) {
       chosen = { ...inState, layer: 'us-state' };
     } else if (inCountry) {
@@ -212,7 +302,8 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       iso: chosen.id,
       name: chosen.name,
       layer: chosen.layer,
-      ...(r.score !== undefined && { score: r.score }),
+      ...(r.value !== undefined && { value: r.value }),
+      ...(r.color !== undefined && { color: r.color }),
       tags: r.tags,
       meta: r.meta,
       lineNumber: r.lineNumber,
@@ -289,11 +380,14 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     let cands = idxs.map((i) => data.gazetteer.cities[i]!);
     const scopeUse = scope ?? scopeHint;
     if (scopeUse) {
-      // ISO 3166-2 subdivision scope is `XX-…` (two letters + dash); a bare
-      // 2-letter token is a country code (#9 — regex, not a brittle dash test).
-      const isSub = /^[A-Za-z]{2}-/.test(scopeUse);
+      // ISO 3166-2 subdivision scope is `XX-…` (two letters + dash). A bare
+      // two-letter token that names a US state resolves as the `US-XX`
+      // subdivision (`CA` = California, §24B.8) — NOT the colliding country
+      // code; any other bare two-letter token is a 3166-1 country code.
+      const bareState = usStateFromBareScope(scopeUse);
+      const subScope = /^[A-Za-z]{2}-/.test(scopeUse) ? scopeUse : bareState;
       const filtered = cands.filter((c) =>
-        isSub ? c[5] === scopeUse : c[2] === scopeUse
+        subScope ? c[5] === subScope : c[2] === scopeUse
       );
       if (filtered.length) cands = filtered;
       else if (scope) {
@@ -397,6 +491,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       lat,
       lon,
       ...(p.label !== undefined && { label: p.label }),
+      ...(p.color !== undefined && { color: p.color }),
       tags: p.tags,
       meta: p.meta,
       lineNumber: p.lineNumber,
@@ -455,36 +550,102 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     });
   }
 
-  const routes: ResolvedRoute[] = [];
-  for (const rt of parsed.routes) {
-    const stopIds: string[] = [];
-    for (const stop of rt.stops) {
-      let id: string | null;
-      if (stop.ref.kind === 'coords') {
-        id = stop.alias ? fold(stop.alias) : `@${stop.ref.lat},${stop.ref.lon}`;
-        if (!looksUS(stop.ref.lat, stop.ref.lon)) anyNonUsPoi = true;
-        if (!registry.has(id)) {
-          const poi: Writable<ResolvedPoi> = {
+  // Resolve a route stop to a POI id, registering it (with its inline tags/label/
+  // size value) or binding to an already-declared POI. Returns null if a named
+  // stop can't be geocoded. Unlike the old code, stop metadata is NO LONGER
+  // dropped — it rides onto the created POI (fixes the named-stop meta bug).
+  const resolveStop = (
+    pos: PoiPos,
+    alias: string | undefined,
+    label: string | undefined,
+    tags: Readonly<Record<string, string>>,
+    sizeValue: string | undefined,
+    line: number
+  ): string | null => {
+    const meta: Record<string, string> =
+      sizeValue !== undefined ? { value: sizeValue } : {};
+    if (pos.kind === 'coords') {
+      const id = alias ? fold(alias) : `@${pos.lat},${pos.lon}`;
+      if (!looksUS(pos.lat, pos.lon)) anyNonUsPoi = true;
+      if (!registry.has(id)) {
+        registerPoi(
+          id,
+          {
             id,
-            ...(stop.alias !== undefined && { name: stop.alias }),
-            lat: stop.ref.lat,
-            lon: stop.ref.lon,
-            tags: {},
-            meta: stop.meta,
-            lineNumber: stop.lineNumber,
-            implicit: true,
-          };
-          registerPoi(id, poi, stop.lineNumber);
-        }
-      } else {
-        id =
-          stop.alias && registry.has(fold(stop.alias))
-            ? fold(stop.alias)
-            : resolveEndpoint(stop.ref.name, stop.lineNumber);
+            ...(alias !== undefined && { name: alias }),
+            lat: pos.lat,
+            lon: pos.lon,
+            ...(label !== undefined && { label }),
+            tags,
+            meta,
+            lineNumber: line,
+          },
+          line
+        );
       }
-      if (id) stopIds.push(id);
+      return id;
+    }
+    // Named stop: bind to an existing declared POI if present, else geocode + create.
+    const f = fold(pos.name);
+    if (registry.has(f)) return f;
+    const aliased = declaredByName.get(f);
+    if (aliased) return aliased;
+    const got = lookupName(pos.name, pos.scope, line, inferredCountry, true);
+    if (got.kind !== 'ok') return null;
+    noteCountry(got.iso);
+    registerPoi(
+      f,
+      {
+        id: f,
+        name: pos.name,
+        lat: got.lat,
+        lon: got.lon,
+        ...(label !== undefined && { label }),
+        tags,
+        meta,
+        lineNumber: line,
+      },
+      line
+    );
+    return f;
+  };
+
+  const routes: ResolvedRoute[] = [];
+  for (const rt of parsed.routes) {
+    const originId = resolveStop(
+      rt.origin,
+      rt.originAlias,
+      rt.originLabel,
+      rt.originTags,
+      rt.originValue,
+      rt.lineNumber
+    );
+    if (!originId) continue; // can't anchor the route → drop (error already pushed)
+    const stopIds: string[] = [originId];
+    const legs: ResolvedRouteLeg[] = [];
+    let prevId = originId;
+    for (const leg of rt.legs) {
+      const destId = resolveStop(
+        leg.dest,
+        leg.destAlias,
+        leg.destLabel,
+        leg.destTags,
+        undefined, // a leg's `value:` is leg thickness, not the dest's size
+        leg.lineNumber
+      );
+      if (!destId) continue; // ungeocodable destination → skip this leg
+      legs.push({
+        fromId: prevId,
+        toId: destId,
+        ...(leg.label !== undefined && { label: leg.label }),
+        style: leg.style,
+        ...(leg.value !== undefined && { value: leg.value }),
+        lineNumber: leg.lineNumber,
+      });
+      if (!stopIds.includes(destId)) stopIds.push(destId); // unique markers (loop-close dedupe)
+      prevId = destId;
     }
-    routes.push({ stopIds, meta: rt.meta, lineNumber: rt.lineNumber });
+    routes.push({ stopIds, legs, lineNumber: rt.lineNumber });
   }
 
   // ── Basemaps + scope ──
@@ -498,10 +659,12 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     const bb = featureBbox(data.usStates, ref.id);
     if (bb) regionBoxes.push(bb);
   }
-  // country regions contribute their country bbox
+  // country regions contribute their country bbox — but framed on the dominant
+  // landmass, ignoring far-detached minor territories (e.g. French Guiana) so a
+  // Europe map naming France doesn't auto-fit across the Atlantic (R5).
   for (const r of regions) {
     if (r.layer === 'country') {
-      const bb = featureBbox(data.worldCoarse, r.iso);
+      const bb = featureBboxPrimary(data.worldCoarse, r.iso);
       if (bb) regionBoxes.push(bb);
     }
   }
@@ -516,6 +679,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
   const lonSpan = extent[1][0] - extent[0][0];
   const latSpan = extent[1][1] - extent[0][1];
   const span = Math.max(lonSpan, latSpan);
+  const maxAbsLat = Math.max(Math.abs(extent[0][1]), Math.abs(extent[1][1]));
   // albers-usa only covers US territory: choose it only when the map is truly
   // US-only — no non-US country region AND no POI outside the US (#13). Without
   // the POI guard a `default-country US` + Tokyo map projected to garbage.
@@ -542,16 +706,18 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     projection = override;
   } else if (usDominant) {
     projection = 'albers-usa';
-  } else if (span > WORLD_SPAN) {
-    // World/continental scale: equirectangular fills the frame edge-to-edge and
-    // never clips the continents at the boundary (naturalEarth's curved sides
-    // overrun a corner-based fit). `projection natural-earth` opts back into the
-    // curved look explicitly.
+  } else if (span > WORLD_SPAN || maxAbsLat > MERCATOR_MAX_LAT) {
+    // World/multi-continent scale (or a polar-reaching frame): equirectangular
+    // fills the frame edge-to-edge, never clips the continents at the boundary
+    // (naturalEarth's curved sides overrun a corner-based fit), and avoids
+    // Mercator's gross sec(φ) area blow-up near the poles. `projection
+    // natural-earth` opts back into the curved look explicitly.
     projection = 'equirectangular';
-  } else if (span < MERCATOR_MAX_SPAN) {
-    projection = 'mercator';
   } else {
-    projection = 'equirectangular';
+    // Tight clusters AND single-continent regional views: Mercator gives every
+    // mid-latitude landmass its familiar conventional shape (equirectangular
+    // squashes a continent like Europe horizontally).
+    projection = 'mercator';
   }
 
   // World-scale framing (R10): a multi-continent spread frames most cleanly as

package/src/map/types.ts

@@ -21,8 +21,15 @@ export interface MapScale {
 export interface MapDirectives {
   region?: string;
   projection?: string;
-  metric?: string;
-  sizeMetric?: string;
+  /** Legend label for the region value ramp (`region-metric <label>`). */
+  regionMetric?: string;
+  /** Recognized color NAME for the choropleth ramp hue, peeled off the
+   *  `region-metric` trailing token (§24B.3). Defaults to red when absent. */
+  regionMetricColor?: string;
+  /** Legend label for the POI value (marker size) channel (`poi-metric`). */
+  poiMetric?: string;
+  /** Legend label for the edge/leg value (thickness) channel (`flow-metric`). */
+  flowMetric?: string;
   scale?: MapScale;
   regionLabels?: string; // full | abbrev | off
   poiLabels?: string; // off | auto | all
@@ -30,8 +37,23 @@ export interface MapDirectives {
   defaultState?: string;
   activeTag?: string;
   noLegend?: boolean;
+  /** Suppress the Alaska & Hawaii inset boxes drawn under the `albers-usa`
+   *  projection (bare flag `no-insets`). Only meaningful for the US states
+   *  basemap; silently ignored under any other projection. */
+  noInsets?: boolean;
   subtitle?: string;
   caption?: string;
+  /** Basemap dress override (bare flags `muted` / `natural`). Forces the
+   *  land/water styling regardless of whether a colouring dimension is active —
+   *  `muted` recedes to neutral grays, `natural` keeps the green/blue reference
+   *  dress. Absent → auto (muted iff a score/tag dimension is active). Lets two
+   *  maps in one deck share a look. */
+  basemapStyle?: 'muted' | 'natural';
+  /** Opt-in subtle mountain-range relief shading (bare flag `relief`, §24B.2).
+   *  Draws a shared directional gradient ("degenerate hillshade") clipped to
+   *  each notable mountain-range polygon, over base land and under data fills.
+   *  Off by default; needs the optional `mountain-ranges.json` asset. */
+  relief?: boolean;
 }
 
 /** A region-fill: a subdivision name with an optional score and/or tag values
@@ -42,37 +64,58 @@ export interface MapRegion {
    *  (`Georgia US` → US context) or 3166-2 subdivision (`Georgia US-GA`).
    *  Forces the country-vs-state interpretation and silences the ambiguity warning. */
   readonly scope?: string;
-  readonly score?: number;
+  /** Numeric value → choropleth shade (§24B.3). Lifted out of `meta`. */
+  readonly value?: number;
+  /** §1.5 trailing-token color NAME → flat categorical override fill (§24B.4);
+   *  painted regardless of the active colouring dimension, no legend entry. */
+  readonly color?: string;
   /** Tag values keyed by lowercased tag GROUP name (alias is resolved away). */
   readonly tags: Readonly<Record<string, string>>;
-  /** Other reserved-but-inert keys (description/date/…) captured verbatim. */
+  /** Any remaining reserved keys captured verbatim (`label`/`style`/…). */
   readonly meta: Readonly<Record<string, string>>;
   readonly lineNumber: number;
 }
 
-/** A point of interest (§24B.5). `meta` holds reserved-but-inert keys
- *  (size/score/description/weight/date) verbatim; `label` is lifted out. */
+/** A point of interest (§24B.5). `meta` holds the numeric `value` (→ marker
+ *  size) and `style` verbatim; `label` is lifted out. */
 export interface MapPoi {
   readonly pos: PoiPos;
   readonly alias?: string;
   readonly label?: string;
+  /** §1.5 trailing-token color NAME → flat marker fill (§24B.5); wins over a
+   *  tag color and the default orange. */
+  readonly color?: string;
   readonly tags: Readonly<Record<string, string>>;
   readonly meta: Readonly<Record<string, string>>;
   readonly lineNumber: number;
 }
 
-/** A route stop (§24B.6); raw order preserved incl. a repeated first==last (loop). */
-export interface MapRouteStop {
-  readonly ref: PoiPos;
-  readonly alias?: string;
-  readonly meta: Readonly<Record<string, string>>;
+/** One leg of a route (§24B.6): an edge from the previous stop to `dest`. Reuses
+ *  the edge arrow idiom — in-arrow text = leg label, `value:` = leg thickness,
+ *  `->`/`~>` (or the header `style: arc`) = shape. Stop-targeted keys on the leg
+ *  line (`tag`, `label:`) decorate the DESTINATION point. */
+export interface MapRouteLeg {
+  readonly label?: string; // in-arrow leg label
+  readonly style: 'straight' | 'arc';
+  readonly value?: string; // leg thickness (numeric string, like an edge)
+  readonly dest: PoiPos;
+  readonly destAlias?: string;
+  readonly destLabel?: string;
+  readonly destTags: Readonly<Record<string, string>>;
   readonly lineNumber: number;
 }
 
-/** An ordered, auto-numbered route (§24B.6). `meta.style==='arc'` curves legs. */
+/** An ordered, auto-numbered route (§24B.6): `route <origin> [style: arc]` + a
+ *  sequence of indented arrow legs, each continuing from the previous stop.
+ *  Repeat the origin as a leg's destination to close a loop. */
 export interface MapRoute {
-  readonly stops: readonly MapRouteStop[];
-  readonly meta: Readonly<Record<string, string>>;
+  readonly origin: PoiPos;
+  readonly originAlias?: string;
+  readonly originLabel?: string;
+  readonly originValue?: string; // header value → origin marker size
+  readonly originTags: Readonly<Record<string, string>>;
+  readonly style: 'straight' | 'arc'; // header default leg shape
+  readonly legs: readonly MapRouteLeg[];
   readonly lineNumber: number;
 }
 

package/src/utils/reserved-key-registry.ts

@@ -75,16 +75,16 @@ export const INFRA_REGISTRY: ReservedKeyRegistry = staticRegistry([
 // NOTE: `color` is deliberately OMITTED (unlike sibling registries) — per
 // §24B.9 the map chart type carries color as a trailing token (peeled by
 // `peelTrailingColorName`) / via the tag system, not a `color:` metadata key.
-// `date`/`weight`/`style` are reserved seams (§24B.12): included so they require
-// colons and don't bleed into a name region, but inert in v1.
+// `value` is the single numeric data channel (§24B): it renders as region shade,
+// POI marker size, or edge/leg thickness depending on the element. `style` is the
+// route/edge shape key. `description`/`date`/`score`/`size`/`weight` were removed
+// in the 2026-06-01 syntax review — `value` collapses the old three numeric keys,
+// and description/date had no v1 surface (they now raise an unknown-key error
+// rather than silently no-op).
 export const MAP_REGISTRY: ReservedKeyRegistry = staticRegistry([
-  'score',
+  'value',
   'label',
-  'size',
-  'description',
-  'weight',
   'style',
-  'date',
 ]);
 
 export const ORG_REGISTRY: ReservedKeyRegistry = staticRegistry([