@diagrammo/dgmo 0.20.3 → 0.21.0

package/src/map/parser.ts

@@ -28,7 +28,7 @@ import type {
   MapRegion,
   MapPoi,
   MapRoute,
-  MapRouteStop,
+  MapRouteLeg,
   MapEdge,
   PoiPos,
   MapScale,
@@ -42,13 +42,16 @@ const SCOPE_RE = /^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/;
 // whitespace, so hyphens inside names (`office-east`) and `foo-bar` are safe.
 const ARROW_SPLIT = /\s+(-[^>]*?->|->|~[^>]*?~>|~>|--)\s+/;
 const HUB_RE = /^(->|~>)\s+(.+)$/;
+// A route leg line: an optional leading arrow (with in-arrow label) + a destination.
+const LEG_ARROW_RE = /^(-[^>]*?->|->|~[^>]*?~>|~>|--)\s+(.+)$/;
 const AT_RE = /(^|[\s,])at\s*:/i; // the removed `at:` coord form (§24B.9)
 
 const DIRECTIVE_SET: ReadonlySet<string> = new Set([
   'region',
   'projection',
-  'metric',
-  'size-metric',
+  'region-metric',
+  'poi-metric',
+  'flow-metric',
   'scale',
   'region-labels',
   'poi-labels',
@@ -177,9 +180,10 @@ export function parseMap(content: string): ParsedMap {
       addTagEntry(open.tag, trimmed, lineNumber);
       continue;
     }
-    // (1a) Indented child of an open route → a stop.
+    // (1a) Indented child of an open route → a leg (an edge from the prev stop).
     if (open.route && indent > open.route.indent) {
-      open.route.route.stops.push(parseStop(trimmed, lineNumber));
+      const leg = parseLeg(trimmed, lineNumber, open.route.route.style);
+      (open.route.route.legs as MapRouteLeg[]).push(leg);
       continue;
     }
     // (1b) Indented child of an open POI → hub edge or extra metadata.
@@ -217,6 +221,15 @@ export function parseMap(content: string): ParsedMap {
       handleTag(trimmed, lineNumber);
       continue;
     }
+    // Bare-flag directives (no value) — only when the line is exactly the flag,
+    // so a region named e.g. "Natural Bridge" still parses as a region.
+    if (
+      (firstWord === 'muted' || firstWord === 'natural') &&
+      trimmed === firstWord
+    ) {
+      handleDirective(firstWord, '', lineNumber);
+      continue;
+    }
     if (
       DIRECTIVE_SET.has(firstWord) &&
       !trimmed.slice(firstWord.length).trimStart().startsWith(':')
@@ -297,13 +310,17 @@ export function parseMap(content: string): ParsedMap {
           );
         d.projection = value;
         break;
-      case 'metric':
-        dup(d.metric);
-        d.metric = value;
+      case 'region-metric':
+        dup(d.regionMetric);
+        d.regionMetric = value;
         break;
-      case 'size-metric':
-        dup(d.sizeMetric);
-        d.sizeMetric = value;
+      case 'poi-metric':
+        dup(d.poiMetric);
+        d.poiMetric = value;
+        break;
+      case 'flow-metric':
+        dup(d.flowMetric);
+        d.flowMetric = value;
         break;
       case 'scale':
         dup(d.scale);
@@ -345,6 +362,15 @@ export function parseMap(content: string): ParsedMap {
       case 'no-legend':
         d.noLegend = true;
         break;
+      case 'muted':
+      case 'natural':
+        if (d.basemapStyle !== undefined && d.basemapStyle !== key)
+          pushWarning(
+            line,
+            `Conflicting basemap dress — "${d.basemapStyle}" then "${key}"; last wins.`
+          );
+        d.basemapStyle = key;
+        break;
       case 'subtitle':
         dup(d.subtitle);
         d.subtitle = value;
@@ -431,18 +457,18 @@ export function parseMap(content: string): ParsedMap {
       line
     );
     const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
-    let scoreNum: number | undefined;
-    const score = meta['score'];
-    if (score !== undefined) {
-      delete (meta as Record<string, string>)['score']; // lifted out of inert meta
-      scoreNum = Number(score);
-      if (!Number.isFinite(scoreNum)) {
-        pushError(line, `score must be a number (got "${score}").`);
-        scoreNum = undefined;
+    let valueNum: number | undefined;
+    const value = meta['value'];
+    if (value !== undefined) {
+      delete (meta as Record<string, string>)['value']; // lifted out of meta
+      valueNum = Number(value);
+      if (!Number.isFinite(valueNum)) {
+        pushError(line, `value must be a number (got "${value}").`);
+        valueNum = undefined;
       }
     }
-    // A region may carry BOTH a `score:` and a tag value — they are two
-    // selectable colouring dimensions (the legend flips between the score ramp
+    // A region may carry BOTH a `value:` and a tag value — they are two
+    // selectable colouring dimensions (the legend flips between the value ramp
     // and the tag group), so this is no longer warned (bivariate is handled).
     // Peel a trailing ISO scope token (§24B.8) — same qualifier POIs accept,
     // so `Georgia US-GA` / `Georgia US` can force the country-vs-state pick.
@@ -461,7 +487,7 @@ export function parseMap(content: string): ParsedMap {
       lineNumber: line,
     };
     if (regionScope !== undefined) region.scope = regionScope;
-    if (scoreNum !== undefined) region.score = scoreNum;
+    if (valueNum !== undefined) region.value = valueNum;
     regions.push(region);
   }
 
@@ -482,7 +508,7 @@ export function parseMap(content: string): ParsedMap {
     const pos = parsePos(split.name, line);
     if (!pos) return; // error already pushed
     const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
-    const label = meta['label']; // label lifted out of meta; `score`/`size`/`date` stay inert (#2)
+    const label = meta['label']; // label lifted out of meta; `value` (→ marker size) stays in meta
     if (label !== undefined) delete (meta as Record<string, string>)['label'];
     const poi: Writable<MapPoi> = { pos, tags, meta, lineNumber: line };
     if (split.alias) poi.alias = split.alias;
@@ -492,25 +518,88 @@ export function parseMap(content: string): ParsedMap {
   }
 
   function handleRoute(rest: string, line: number, indent: number): void {
-    const meta = rest ? splitNameAndMeta(rest, registry(), aliasMap).meta : {};
-    const route: Writable<MapRoute> = { stops: [], meta, lineNumber: line };
+    const split = rest
+      ? splitNameAndMeta(
+          rest,
+          registry(),
+          aliasMap,
+          undefined,
+          diagnostics,
+          line
+        )
+      : { name: '', meta: {} as Record<string, string>, alias: undefined };
+    const pos = parsePos(split.name, line);
+    if (!pos || (pos.kind === 'name' && !pos.name)) {
+      pushError(
+        line,
+        'route requires an origin: `route <origin> [style: arc]`.'
+      );
+      return;
+    }
+    const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
+    const originLabel = meta['label'];
+    const originValue = meta['value'];
+    const style: 'straight' | 'arc' =
+      meta['style'] === 'arc' ? 'arc' : 'straight';
+    const route: Writable<MapRoute> = {
+      origin: pos,
+      ...(split.alias !== undefined && { originAlias: split.alias }),
+      ...(originLabel !== undefined && { originLabel }),
+      ...(originValue !== undefined && { originValue }),
+      originTags: tags,
+      style,
+      legs: [],
+      lineNumber: line,
+    };
     routes.push(route);
     open.route = { route, indent };
   }
 
-  function parseStop(trimmed: string, line: number): MapRouteStop {
-    const split = splitNameAndMeta(trimmed, registry(), aliasMap);
-    const ref = parsePos(split.name, line) ?? {
+  /** Parse one route body line into a leg: `[-label->] <destination> [keys]`.
+   *  The arrow (if any) gives the leg label + shape; `value:` is leg thickness;
+   *  a tag / `label:` decorate the destination stop. Bare `<dest>` = plain leg. */
+  function parseLeg(
+    trimmed: string,
+    line: number,
+    headerStyle: 'straight' | 'arc'
+  ): MapRouteLeg {
+    let arrowStyle: 'straight' | 'arc' = 'straight';
+    let label: string | undefined;
+    let rest = trimmed;
+    const m = trimmed.match(LEG_ARROW_RE);
+    if (m) {
+      const arr = classifyArrow(m[1]!, line);
+      arrowStyle = arr.style;
+      label = arr.label;
+      rest = m[2]!;
+    }
+    const split = splitNameAndMeta(
+      rest,
+      registry(),
+      aliasMap,
+      undefined,
+      diagnostics,
+      line
+    );
+    const pos = parsePos(split.name, line) ?? {
       kind: 'name',
       name: split.name,
     };
-    const stop: Writable<MapRouteStop> = {
-      ref,
-      meta: split.meta,
+    const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
+    const value = meta['value'];
+    const destLabel = meta['label'];
+    const style: 'straight' | 'arc' =
+      arrowStyle === 'arc' || headerStyle === 'arc' ? 'arc' : 'straight';
+    return {
+      ...(label !== undefined && { label }),
+      style,
+      ...(value !== undefined && { value }),
+      dest: pos,
+      ...(split.alias !== undefined && { destAlias: split.alias }),
+      ...(destLabel !== undefined && { destLabel }),
+      destTags: tags,
       lineNumber: line,
     };
-    if (split.alias) stop.alias = split.alias;
-    return stop;
   }
 
   function handleEdges(trimmed: string, line: number): void {

package/src/map/renderer.ts

@@ -101,11 +101,11 @@ export function renderMap(
       .attr('stroke', r.stroke)
       .attr('stroke-width', strokeWidth);
     // Data layer? Tag it so the app can highlight on legend hover / gradient
-    // scrub. `data-score` for ramp-proximity, `data-tag-<group>` per tag value
+    // scrub. `data-value` for ramp-proximity, `data-tag-<group>` per tag value
     // (both lowercased to match the lowercased legend-entry attributes).
     if (r.layer !== 'base') {
       p.classed('dgmo-map-region', true).attr('data-region', r.id);
-      if (r.score !== undefined) p.attr('data-score', r.score);
+      if (r.value !== undefined) p.attr('data-value', r.value);
       if (r.tags) {
         for (const [group, value] of Object.entries(r.tags)) {
           p.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
@@ -230,6 +230,13 @@ export function renderMap(
       .attr('stroke-width', 1)
       .attr('data-line-number', poi.lineNumber)
       .attr('data-poi', poi.id);
+    // Tag the marker per tag value (lowercased, matching the lowercased
+    // legend-entry attributes) so the app can spotlight it on legend hover.
+    if (poi.tags) {
+      for (const [group, value] of Object.entries(poi.tags)) {
+        c.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
+      }
+    }
     if (onClickItem) {
       c.style('cursor', 'pointer').on('click', () =>
         onClickItem(poi.lineNumber)
@@ -296,14 +303,14 @@ export function renderMap(
       .append('g')
       .attr('class', 'dgmo-map-legend')
       .attr('transform', `translate(0, ${legendY})`);
-    // The score ramp is a selectable colouring group alongside the tag groups
+    // The value ramp is a selectable colouring group alongside the tag groups
     // (the user flips between them); its capsule renders the gradient inline.
-    // Reserved name "Score" when no metric label is set — must match SCORE_NAME
-    // in layout.ts so the resolved activeGroup selects it.
+    // Reserved name "Value" when no region-metric label is set — must match
+    // VALUE_NAME in layout.ts so the resolved activeGroup selects it.
     const ramp = layout.legend.ramp;
     const scoreGroup = ramp
       ? {
-          name: ramp.metric?.trim() || 'Score',
+          name: ramp.metric?.trim() || 'Value',
           entries: [],
           gradient: {
             min: ramp.min,

package/src/map/resolved-types.ts

@@ -46,7 +46,7 @@ export interface ResolvedRegion {
   readonly iso: string;
   readonly name: string; // display name
   readonly layer: 'country' | 'us-state';
-  readonly score?: number;
+  readonly value?: number;
   readonly tags: Readonly<Record<string, string>>;
   readonly meta: Readonly<Record<string, string>>;
   readonly lineNumber: number;
@@ -79,9 +79,20 @@ export interface ResolvedEdge {
   readonly lineNumber: number;
 }
 
+export interface ResolvedRouteLeg {
+  readonly fromId: string;
+  readonly toId: string;
+  readonly label?: string;
+  readonly style: 'straight' | 'arc';
+  readonly value?: string; // leg thickness
+  readonly lineNumber: number;
+}
+
 export interface ResolvedRoute {
+  /** Ordered UNIQUE stop ids (for numbering + the origin marker). A loop-closing
+   *  leg whose destination is an earlier stop adds a leg but no duplicate stop. */
   readonly stopIds: readonly string[];
-  readonly meta: Readonly<Record<string, string>>;
+  readonly legs: readonly ResolvedRouteLeg[];
   readonly lineNumber: number;
 }
 

package/src/map/resolver.ts

@@ -14,6 +14,7 @@ import type {
   ResolvedPoi,
   ResolvedEdge,
   ResolvedRoute,
+  ResolvedRouteLeg,
   ProjectionFamily,
   GeoExtent,
 } from './resolved-types';
@@ -64,6 +65,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 +198,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) ──
@@ -212,7 +288,7 @@ 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 }),
       tags: r.tags,
       meta: r.meta,
       lineNumber: r.lineNumber,
@@ -289,11 +365,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) {
@@ -455,36 +534,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 ──

package/src/map/types.ts

@@ -21,8 +21,12 @@ 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;
+  /** 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
@@ -32,6 +36,12 @@ export interface MapDirectives {
   noLegend?: 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';
 }
 
 /** A region-fill: a subdivision name with an optional score and/or tag values
@@ -42,16 +52,17 @@ 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;
   /** 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;
@@ -61,18 +72,32 @@ export interface MapPoi {
   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;
 }