@diagrammo/dgmo 0.21.0 → 0.21.1

package/src/map/layout.ts

@@ -17,7 +17,8 @@ import {
   type GeoPath,
 } from 'd3-geo';
 import { feature } from 'topojson-client';
-import { mix, contrastText } from '../palettes/color-utils';
+import { mix, contrastText, relativeLuminance } from '../palettes/color-utils';
+import { resolveColor } from '../colors';
 import type { PaletteColors } from '../palettes/types';
 import {
   rectsOverlap,
@@ -58,36 +59,51 @@ const W_MIN = 1.25; // edge stroke width
 const W_MAX = 8;
 const FONT = 11; // on-map label font px
 const COLO_EPS = 1.5; // px: POIs closer than this are "co-located"
-// % palette-yellow of bg for unscored land. Higher on dark so the soft palette
-// yellow reads as yellow rather than muddying toward tan against the dark bg.
-const LAND_TINT_LIGHT = 58;
-const LAND_TINT_DARK = 75;
+// % palette-green of bg for unscored land — a VERY faded green so every map
+// (plain reference OR data-coloured) wears the same subtle dress and the green
+// never competes with saturated tag/score tints. Dark lifts a touch off the
+// near-black surface so the faint green stays legible.
+const LAND_TINT_LIGHT = 12;
+const LAND_TINT_DARK = 24;
 // Categorical (tag) region fill: a flat, fairly saturated tint of the tag
 // colour so a tagged region reads as its CATEGORY against the tinted land base
 // — the generic 25% shape tint washes out and lets the olive land dominate.
 const TAG_TINT_LIGHT = 60;
 const TAG_TINT_DARK = 68;
-const WATER_TINT = 55; // % palette-blue of bg for the ocean / backdrop
+// % palette-blue of bg for the ocean / backdrop — a VERY faded blue, matching
+// the land's subtlety so the whole basemap reads as a quiet dress under the data.
+const WATER_TINT_LIGHT = 13;
+const WATER_TINT_DARK = 14;
 const RIVER_WIDTH = 1.3; // px stroke width for river lines
+// Relief (mountain-range shading). A projected range below this px² area is
+// dropped (no confetti slivers at world zoom).
+const RELIEF_MIN_AREA = 12; // px²
+// Each projected bbox side must clear this — drop near-degenerate slivers.
+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 = 3; // px between lines
+const RELIEF_HATCH_WIDTH = 0.25; // 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;
 // % palette-gray of bg for non-US neighbour land. Higher on dark so it reads as
 // a clear gray rather than sinking into the dark background.
 const FOREIGN_TINT_LIGHT = 30;
 const FOREIGN_TINT_DARK = 62;
 // MUTED basemap — used when a colouring dimension (score ramp or a tag group) is
-// active. The data hues may themselves be blue or green (e.g. `Core blue`,
-// `Growth teal`), which collide with the decorative blue-water / green-land
-// dress: a blue region vanishes into the ocean, a green one into the land. So
-// when regions carry the data signal the basemap RECEDES to neutral grays —
-// water and unscored/neighbour land become low-saturation gray, leaving the data
-// fills as the only saturated thing on the map (the cartographic norm for a
-// choropleth). Plain reference maps with no data keep the blue/green dress.
-// Light land is left at the page bg (cleanest white ground for the data hues);
-// dark land lifts off the near-black surface so dark-mixed tints stay legible.
-const MUTED_WATER_LIGHT = 14; // % gray of bg — pale sea
-const MUTED_WATER_DARK = 10;
-const MUTED_FOREIGN_LIGHT = 28; // neighbour land — grayer than the sea
+// active. The subject water + land are ALWAYS the same faded blue/green dress
+// (WATER_TINT_* / LAND_TINT_*); muted only pushes NEIGHBOUR land to a recessive
+// gray so the subject country reads as the subject and the data fills own the
+// saturation. Plain reference maps keep neighbour land at the fuller gray tint.
+const MUTED_FOREIGN_LIGHT = 28; // neighbour land — recessive gray, not green
 const MUTED_FOREIGN_DARK = 16;
-const MUTED_LAND_DARK = 24; // subject land on dark (light land = palette.bg)
 const COLO_R = 9; // spiderfy radius
 const GOLDEN_ANGLE = 2.399963229728653; // rad (137.5deg) -- even spiral, no random
 const FAN_STEP = 16; // px perpendicular offset between parallel edges
@@ -121,6 +137,24 @@ export interface MapLayoutInset {
   readonly w: number;
   readonly h: number;
   readonly points: ReadonlyArray<readonly [number, number]>;
+  /** The FITTED inset projection (fit to this frame's screen box inside
+   *  `placeInset`). Load-bearing for pixel↔lonLat over the AK/HI insets: the
+   *  un-fitted `alaskaProjection()`/`hawaiiProjection()` factories would invert
+   *  to garbage, so the geo-query inverts against THIS instance. */
+  readonly projection: GeoProjection;
+}
+
+/** Post-projection non-uniform stretch applied to GLOBAL fits (fill-the-canvas).
+ *  `null` for regional fits. The geo-query applies the forward form when
+ *  projecting and the inverse before `projection.invert`. Mirrors the `stretch`
+ *  closure used for the path stream:  px = ox + (x - bx0) * sx. */
+export interface MapLayoutStretch {
+  readonly sx: number;
+  readonly sy: number;
+  readonly ox: number;
+  readonly oy: number;
+  readonly bx0: number;
+  readonly by0: number;
 }
 
 export interface MapLayoutPoi {
@@ -194,6 +228,23 @@ export interface MapLayoutRiver {
   readonly width: number;
 }
 
+/** A drawn mountain-range relief shape — a projected polygon path. The renderer
+ *  unions these into one clip and rules horizontal hachure lines through them. */
+export interface MapLayoutRelief {
+  readonly d: string;
+}
+
+/** The shared hachure style for the relief lines. `null` when relief is off or
+ *  no range survives the gates. */
+export interface MapLayoutReliefHatch {
+  /** Line stroke — palette.text mixed into the land colour (so it's dark-on-
+   *  light and light-on-dark automatically as palette.text flips with theme). */
+  readonly color: string;
+  /** Vertical gap between lines in SCREEN px (constant density, zoom-stable). */
+  readonly spacing: number;
+  readonly width: number;
+}
+
 export interface MapLayout {
   readonly width: number;
   readonly height: number;
@@ -204,6 +255,12 @@ export interface MapLayout {
   readonly regions: readonly MapLayoutRegion[];
   /** Major river centerlines, drawn over land/lakes and under POIs/edges. */
   readonly rivers: readonly MapLayoutRiver[];
+  /** Mountain-range relief shapes (empty unless `relief` is on + the asset is
+   *  present); the renderer clips horizontal hachure lines to their union,
+   *  drawn over base land, under rivers/POIs/data fills. */
+  readonly relief: readonly MapLayoutRelief[];
+  /** Hachure style for the relief lines (null = relief off / none survived). */
+  readonly reliefHatch: MapLayoutReliefHatch | null;
   readonly legs: readonly MapLayoutLeg[];
   readonly pois: readonly MapLayoutPoi[];
   readonly labels: readonly PlacedLabel[];
@@ -213,6 +270,12 @@ export interface MapLayout {
   /** AK/HI region paths drawn inside the inset boxes (foreground, over an
    *  opaque ocean fill). Paired positionally with `insets`. */
   readonly insetRegions: readonly MapLayoutRegion[];
+  /** The fitted MAIN projection (the conus conic for albers-usa). Exposed for
+   *  the geo-query's pixel↔lonLat inversion — the app NEVER reconstructs it from
+   *  metadata; it binds to this exact instance. */
+  readonly projection: GeoProjection;
+  /** Non-uniform stretch applied for GLOBAL fits (null for regional fits). */
+  readonly stretch: MapLayoutStretch | null;
 }
 
 export interface LayoutOptions {
@@ -294,37 +357,34 @@ const US_NON_CONUS = new Set([
 
 /** The map's water / backdrop colour for a palette — the single source of truth
  *  shared by the renderer's `<rect>` fill and any host wrapper that needs to
- *  match it (so letterbox gaps around the SVG don't show a stray band). When
- *  `dataActive` (a score ramp or tag group is colouring regions) the sea recedes
- *  to a pale neutral so blue/green data hues don't blend into it. */
+ *  match it (so letterbox gaps around the SVG don't show a stray band). Always a
+ *  VERY faded blue — uniform whether or not a colouring dimension is active — so
+ *  it reads as water without competing with saturated blue/green data hues.
+ *  `_dataActive` is retained for signature stability (the sea no longer changes
+ *  with data; only neighbour land recedes — see layout's `foreignFill`). */
 export function mapBackgroundColor(
   palette: PaletteColors,
   isDark = false,
-  dataActive = false
+  _dataActive = false
 ): string {
-  if (dataActive)
-    return mix(
-      palette.colors.gray,
-      palette.bg,
-      isDark ? MUTED_WATER_DARK : MUTED_WATER_LIGHT
-    );
-  return mix(palette.colors.blue, palette.bg, WATER_TINT);
+  return mix(
+    palette.colors.blue,
+    palette.bg,
+    isDark ? WATER_TINT_DARK : WATER_TINT_LIGHT
+  );
 }
 
 /** The map's neutral (unscored/untagged) LAND colour — the base every region
  *  blends from. Exported so a host can DIM a region to plain land (rather than
  *  lowering opacity, which would let the water show through and make the shape
- *  read as ocean). Matches the layout's `neutralFill`. Green reference dress by
- *  default; neutral (page bg on light, lifted gray on dark) when `dataActive`. */
+ *  read as ocean). Matches the layout's `neutralFill`. Always a VERY faded green
+ *  — uniform whether or not data is active — so saturated tag/score tints read
+ *  clearly against it. `_dataActive` is retained for signature stability. */
 export function mapNeutralLandColor(
   palette: PaletteColors,
   isDark: boolean,
-  dataActive = false
+  _dataActive = false
 ): string {
-  if (dataActive)
-    return isDark
-      ? mix(palette.colors.gray, palette.bg, MUTED_LAND_DARK)
-      : palette.bg;
   return mix(
     palette.colors.green,
     palette.bg,
@@ -389,6 +449,14 @@ export function layoutMap(
   const regionStroke = isDark
     ? mix(palette.bg, palette.text, 78) // dark theme: near-bg dark outline
     : mix(palette.text, palette.bg, 78); // light theme: near-text dark outline
+  // Lake shoreline. Lakes are painted as water OVER the land and the region
+  // borders, so without an edge they read as a featureless patch that simply
+  // erases whatever state/country border ran beneath them (worst in muted/data
+  // mode, where the water is a pale gray barely distinct from the land). A soft
+  // coastline — between the border colour and the water, not a hard black line —
+  // gives the lake a defined edge; that edge legitimately REPLACES the border
+  // running through it (real choropleths carve lakes out of the land, so the
+  // shoreline IS the boundary at the water). Defined here; `water` is below.
 
   // -- Region fill model (choropleth + categorical; AR4/AR6) --
   const values = resolved.regions
@@ -397,9 +465,12 @@ export function layoutMap(
   const scaleOverride = resolved.directives.scale;
   const rampMin = scaleOverride ? scaleOverride.min : Math.min(...values);
   const rampMax = scaleOverride ? scaleOverride.max : Math.max(...values);
-  // Value ramp is red so valued regions stand out against the blue water
-  // (palette.primary is a blue in most palettes and would blend in).
-  const rampHue = palette.colors.red;
+  // Value ramp defaults to red so valued regions stand out against the blue
+  // water (palette.primary is a blue in most palettes and would blend in). A
+  // trailing color on `region-metric` (§24B.3) overrides the hue idiomatically.
+  const rampHue =
+    resolveColor(resolved.directives.regionMetricColor ?? '', palette) ??
+    palette.colors.red;
   const hasRamp = values.length > 0;
 
   // Colouring dimension (AR4, bivariate): the value ramp and each tag group are
@@ -433,14 +504,14 @@ export function layoutMap(
   }
   const activeIsScore = VALUE_NAME !== null && activeGroup === VALUE_NAME;
 
-  // Basemap dress. When a colouring dimension is active the regions carry the
-  // signal, so the sea/land recede to neutral grays (the data hues — which may be
-  // blue or green — would otherwise blend into a blue ocean / green land). A
-  // plain reference map (no score, no tag → activeGroup null) keeps the blue
-  // water + green land. The bare `muted` / `natural` flags force either dress
-  // regardless (so two maps in a deck can match); absent → this auto rule. In a
-  // US view the surrounding world layer is always recessive gray so the US reads
-  // as the subject.
+  // Basemap dress. Subject water + land always wear the SAME faded blue/green
+  // dress (subtle enough that saturated tag/score tints never blend into it), so
+  // every map looks consistent. `mutedBasemap` now governs only the NEIGHBOUR
+  // land: when a colouring dimension is active (or `muted` is forced) the
+  // surrounding world recedes to a paler gray so the subject + its data fills
+  // dominate; a plain reference map keeps neighbour land at the fuller gray. The
+  // bare `muted` / `natural` flags force either neighbour treatment regardless
+  // (so two maps in a deck can match); absent → this auto rule.
   const mutedBasemap =
     resolved.directives.basemapStyle === 'muted'
       ? true
@@ -449,6 +520,7 @@ export function layoutMap(
         : activeGroup !== null;
   const neutralFill = mapNeutralLandColor(palette, isDark, mutedBasemap);
   const water = mapBackgroundColor(palette, isDark, mutedBasemap);
+  const lakeStroke = mix(regionStroke, water, 45); // soft coastline (see above)
   const foreignFill = mix(
     palette.colors.gray,
     palette.bg,
@@ -503,13 +575,27 @@ export function layoutMap(
     );
   };
 
-  /** A region's fill under the ACTIVE colouring dimension (AR4, bivariate):
-   *  value-active → ramp for valued regions, neutral otherwise; a tag group
-   *  active → that group's tag colour, neutral otherwise (value ignored). */
+  /** A §1.5 trailing-token color on a region/POI → flat categorical fill, the
+   *  same saturated tint a tag entry gets (so direct colors and tag colors read
+   *  alike). Resolves the NAME against the active palette; null if unrecognized. */
+  const directFill = (name: string | undefined): string | null => {
+    const hex = name ? resolveColor(name, palette) : null;
+    if (!hex) return null;
+    return mix(hex, palette.bg, isDark ? TAG_TINT_DARK : TAG_TINT_LIGHT);
+  };
+
+  /** A region's fill. A direct trailing color (§24B.4) is a flat override that
+   *  paints regardless of the active dimension (no legend entry). Otherwise the
+   *  ACTIVE colouring dimension (AR4, bivariate): value-active → ramp for valued
+   *  regions, neutral otherwise; a tag group active → that group's tag colour,
+   *  neutral otherwise (value ignored). */
   const regionFill = (r: {
     value?: number;
+    color?: string;
     tags: Readonly<Record<string, string>>;
   }): string => {
+    const direct = directFill(r.color);
+    if (direct) return direct;
     if (activeIsScore) {
       return r.value !== undefined ? fillForValue(r.value) : neutralFill;
     }
@@ -611,6 +697,8 @@ export function layoutMap(
     fitGB[1][0] - fitGB[0][0] >= 270 || fitGB[1][1] - fitGB[0][1] >= 130;
   let path: GeoPath;
   let project: (lon: number, lat: number) => [number, number] | null;
+  // Captured for the geo-query (null unless this is a global stretch fit).
+  let stretchParams: MapLayoutStretch | null = null;
   if (fitIsGlobal) {
     const cb = geoPath(projection).bounds(fitTarget as never);
     const bx0 = cb[0][0];
@@ -621,6 +709,7 @@ export function layoutMap(
     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;
+    stretchParams = { sx, sy, ox, oy, bx0, by0 };
     const stretch = (x: number, y: number): [number, number] => [
       ox + (x - bx0) * sx,
       oy + (y - by0) * sy,
@@ -681,7 +770,11 @@ export function layoutMap(
     name: string;
     lineNumber: number;
   }[] = [];
-  if (resolved.projection === 'albers-usa' && usLayer) {
+  if (
+    resolved.projection === 'albers-usa' &&
+    usLayer &&
+    !resolved.directives.noInsets
+  ) {
     const PAD = 8;
     const GAP = 12; // px the top edge rides below the coast
     const yB = height - FIT_PAD; // lowest a box may reach (canvas bottom pad)
@@ -719,53 +812,20 @@ export function layoutMap(
       }
       return y;
     };
-    // Top edge for a box over [x0, xr]: a straight line PARALLEL to the local
-    // coast (least-squares over the land samples), pushed down so it clears every
-    // land sample by GAP. Parallel → uniform, maximal clearance for how close it
-    // sits, tilting the way the coast tilts. Open-ocean samples are skipped, so a
-    // box reaching past the coast isn't dragged down by water. Falls back to a
-    // flat line just under the lowest land if the fit is underdetermined.
-    const coastTop = (x0: number, xr: number): ((x: number) => number) => {
+    // Lowest the coast reaches across [x0, xr], or -Infinity over open ocean.
+    const coastFloor = (x0: number, xr: number): number => {
       const n = 24;
-      const pts: Array<[number, number]> = [];
       let maxY = -Infinity;
       for (let i = 0; i <= n; i++) {
-        const x = x0 + ((xr - x0) * i) / n;
-        const y = at(x);
-        if (y > -Infinity) {
-          pts.push([x, y]);
-          if (y > maxY) maxY = y;
-        }
-      }
-      if (pts.length === 0) return () => yB - height * 0.42; // all ocean
-      let m = 0;
-      if (pts.length >= 2) {
-        let sx = 0,
-          sy = 0,
-          sxx = 0,
-          sxy = 0;
-        for (const [x, y] of pts) {
-          sx += x;
-          sy += y;
-          sxx += x * x;
-          sxy += x * y;
-        }
-        const den = pts.length * sxx - sx * sx;
-        if (den !== 0) m = (pts.length * sxy - sx * sy) / den;
-      }
-      // Cap the tilt so a steep coast (e.g. California's) doesn't turn the box
-      // into a tall triangle — keep it a compact, gently-angled quad.
-      m = Math.max(-0.35, Math.min(0.35, m));
-      let c = -Infinity; // raise the line until it clears every land sample + GAP
-      for (const [x, y] of pts) {
-        const need = y - m * x + GAP;
-        if (need > c) c = need;
+        const y = at(x0 + ((xr - x0) * i) / n);
+        if (y > maxY) maxY = y;
       }
-      return (x: number) => m * x + c;
+      return maxY;
     };
     // A snug floating box that just contains the state, tucked up under the coast
-    // with a coast-parallel slanted top. `iwReq` is the requested inner width.
-    // Returns the box's right edge so the next inset can sit beside it.
+    // with a flat top sitting GAP below the lowest the coast reaches over its
+    // span. `iwReq` is the requested inner width. Returns the box's right edge so
+    // the next inset can sit beside it.
     const placeInset = (
       iso: string,
       proj: GeoProjection,
@@ -779,23 +839,19 @@ export function layoutMap(
       const iw = Math.min(iwReq, width - FIT_PAD - x0 - 2 * PAD);
       if (iw < 24) return boxX; // canvas truly too narrow for another inset
       const xr = x0 + iw + 2 * PAD;
-      const top = coastTop(x0, xr);
-      const yL = top(x0);
-      const yR = top(xr);
+      const floor = coastFloor(x0, xr);
+      const topGuess = floor > -Infinity ? floor + GAP : yB - height * 0.42;
       // Learn the state's height at this width, then size the box to just hold it.
       proj.fitWidth(iw, f as never);
       const bb = geoPath(proj).bounds(f as never);
       const sh = Number.isFinite(bb[0][0]) ? bb[1][1] - bb[0][1] : iw;
-      // State sits below the lower top corner. If the coast runs so low the state
-      // wouldn't fit above yB, raise the top (the corner stays over ocean) — the
-      // box must never collapse and vanish.
+      // Flat top sits just under the coast. If the coast runs so low the state
+      // wouldn't fit above yB, raise the top (it stays over ocean) — the box must
+      // never collapse and vanish.
       const needH = sh + 2 * PAD;
-      let topFit = Math.max(yL, yR);
+      let topFit = topGuess;
       const bottom = Math.min(topFit + needH, yB);
       if (bottom - topFit < needH) topFit = bottom - needH;
-      const lift = topFit - Math.max(yL, yR); // keep the slanted top straight
-      const topL = yL + lift;
-      const topR = yR + lift;
       proj.fitExtent(
         [
           [x0 + PAD, topFit + PAD],
@@ -814,15 +870,18 @@ export function layoutMap(
       }
       insets.push({
         x: x0,
-        y: Math.min(topL, topR),
+        y: topFit,
         w: xr - x0,
-        h: bottom - Math.min(topL, topR),
+        h: bottom - topFit,
         points: [
-          [x0, topL],
-          [xr, topR],
+          [x0, topFit],
+          [xr, topFit],
           [xr, bottom],
           [x0, bottom],
         ],
+        // The FITTED inset projection (just fit to this box) — captured so the
+        // geo-query can invert pixels inside the frame back to AK/HI coords.
+        projection: proj,
       });
       insetRegions.push({
         id: iso,
@@ -1098,17 +1157,70 @@ export function layoutMap(
         id: 'lake',
         d,
         fill: water,
-        stroke: 'none',
+        stroke: lakeStroke,
         lineNumber: -1,
         layer: 'base',
       });
     }
   }
 
-  // Rivers (Amazon, Nile, Mississippi, …) as thin water lines over the land,
-  // the SAME blue as the ocean/lakes so a river reads as continuous with the
-  // water it drains into. Open paths: stroked, no fill; under POIs/edges/labels.
-  const riverColor = water;
+  // Relief (notable mountain ranges) — horizontal hachure lines clipped to each
+  // range, drawn over the base land and under rivers/POIs/data fills. Opt-in via
+  // the `relief` flag; needs the optional `mountainRanges` asset. Each surviving
+  // range is projected to a polygon path; the renderer unions them into a clip
+  // and rules screen-spaced horizontal lines through it — a distinct texture
+  // that reads as "mountains here" without elevation data. Ranges below a min
+  // projected area/dimension are dropped (no slivers). Data-region suppression
+  // (ADR-2) is handled at the RENDER clip — relief is clipped to land MINUS the
+  // data-coloured regions, so a range that crosses a valued state still shows on
+  // the un-valued land around it (a bbox drop here would nuke the whole range).
+  const relief: MapLayoutRelief[] = [];
+  let reliefHatch: MapLayoutReliefHatch | null = null;
+  if (resolved.directives.relief === true && data.mountainRanges) {
+    for (const [, f] of decodeLayer(data.mountainRanges)) {
+      const viewF = isGlobalView ? dropFrameFillers(f) : cullFeatureToView(f);
+      if (!viewF) continue;
+      const area = path.area(viewF as never);
+      if (!Number.isFinite(area) || area < RELIEF_MIN_AREA) continue;
+      const box = path.bounds(viewF as never) as [
+        [number, number],
+        [number, number],
+      ];
+      if (
+        box[1][0] - box[0][0] < RELIEF_MIN_DIM ||
+        box[1][1] - box[0][1] < RELIEF_MIN_DIM
+      )
+        continue;
+      const d = path(viewF as never) ?? '';
+      if (!d) continue;
+      relief.push({ d });
+    }
+    if (relief.length) {
+      // Prefer DARK hachure (blend land toward the dark tone — bg on dark
+      // themes, text on light). But on a muted/data map the un-valued land is
+      // already near-black, so darkness can't show: if the dark tone barely
+      // differs from the land, flip to the light tone so the lines stay visible.
+      const darkTone = isDark ? palette.bg : palette.text;
+      const lightTone = isDark ? palette.text : palette.bg;
+      const landLum = relativeLuminance(neutralFill);
+      const tone =
+        Math.abs(landLum - relativeLuminance(darkTone)) > 0.04
+          ? darkTone
+          : lightTone;
+      reliefHatch = {
+        color: mix(tone, neutralFill, RELIEF_HATCH_STRENGTH),
+        spacing: RELIEF_HATCH_SPACING,
+        width: RELIEF_HATCH_WIDTH,
+      };
+    }
+  }
+
+  // Rivers (Amazon, Nile, Mississippi, …) as thin water lines over the land.
+  // Nudged slightly toward the border tone (off flat `water`) so the line reads
+  // as a deliberate water course rather than a gap where it crosses a border —
+  // in muted/data mode flat water is a pale gray that just looks like a broken
+  // boundary. Open paths: stroked, no fill; under POIs/edges/labels.
+  const riverColor = mix(water, regionStroke, 16);
   const rivers: MapLayoutRiver[] = [];
   if (data.rivers) {
     for (const [, f] of decodeLayer(data.rivers)) {
@@ -1138,8 +1250,12 @@ export function layoutMap(
     return R_MIN + Math.max(0, Math.min(1, t)) * (R_MAX - R_MIN);
   };
 
-  // POI tag color: FIRST declared group for which the POI has a value (AR4).
+  // POI fill precedence (§24B.5): a direct §1.5 trailing color wins, then the
+  // FIRST declared tag group for which the POI has a value (AR4), then orange.
   const poiFill = (p: ResolvedPoi): { fill: string; stroke: string } => {
+    const directHex = p.color ? resolveColor(p.color, palette) : null;
+    if (directHex)
+      return { fill: directHex, stroke: mix(directHex, palette.text, 18) };
     for (const group of resolved.tagGroups) {
       const val = p.tags[group.name.toLowerCase()];
       if (!val) continue;
@@ -1671,11 +1787,15 @@ export function layoutMap(
     ...(resolved.caption !== undefined && { caption: resolved.caption }),
     regions,
     rivers,
+    relief,
+    reliefHatch,
     legs,
     pois,
     labels,
     legend,
     insets,
     insetRegions,
+    projection,
+    stretch: stretchParams,
   };
 }

package/src/map/load-data.ts

@@ -43,6 +43,7 @@ const FILES = {
   usStates: 'us-states.json',
   lakes: 'lakes.json',
   rivers: 'rivers.json',
+  mountainRanges: 'mountain-ranges.json',
   naLand: 'na-land.json',
   naLakes: 'na-lakes.json',
   gazetteer: 'gazetteer.json',
@@ -131,6 +132,7 @@ export function loadMapData(): Promise<MapData> {
       usStates,
       lakes,
       rivers,
+      mountainRanges,
       naLand,
       naLakes,
       gazetteer,
@@ -138,9 +140,12 @@ export function loadMapData(): Promise<MapData> {
       readJson<BoundaryTopology>(nb, dir, FILES.worldCoarse),
       readJson<BoundaryTopology>(nb, dir, FILES.worldDetail),
       readJson<BoundaryTopology>(nb, dir, FILES.usStates),
-      // Lakes/rivers/NA assets are optional — older bundles may predate them.
+      // Lakes/rivers/mountain/NA assets are optional — older bundles may predate them.
       readJson<BoundaryTopology>(nb, dir, FILES.lakes).catch(() => undefined),
       readJson<BoundaryTopology>(nb, dir, FILES.rivers).catch(() => undefined),
+      readJson<BoundaryTopology>(nb, dir, FILES.mountainRanges).catch(
+        () => undefined
+      ),
       readJson<BoundaryTopology>(nb, dir, FILES.naLand).catch(() => undefined),
       readJson<BoundaryTopology>(nb, dir, FILES.naLakes).catch(() => undefined),
       readJson<Gazetteer>(nb, dir, FILES.gazetteer),
@@ -152,6 +157,7 @@ export function loadMapData(): Promise<MapData> {
       gazetteer,
       ...(lakes && { lakes }),
       ...(rivers && { rivers }),
+      ...(mountainRanges && { mountainRanges }),
       ...(naLand && { naLand }),
       ...(naLakes && { naLakes }),
     });

package/src/map/parser.ts

@@ -9,6 +9,7 @@ import {
   measureIndent,
   splitNameAndMeta,
   extractColor,
+  peelTrailingColorName,
 } from '../utils/parsing';
 import {
   MAP_REGISTRY,
@@ -59,6 +60,8 @@ const DIRECTIVE_SET: ReadonlySet<string> = new Set([
   'default-state',
   'active-tag',
   'no-legend',
+  'no-insets',
+  'relief',
   'subtitle',
   'caption',
 ]);
@@ -310,10 +313,16 @@ export function parseMap(content: string): ParsedMap {
           );
         d.projection = value;
         break;
-      case 'region-metric':
+      case 'region-metric': {
         dup(d.regionMetric);
-        d.regionMetric = value;
+        // A trailing color names the choropleth ramp hue (§24B.3): the
+        // label keeps the rest. `region-metric Sales ($M) blue` → blue ramp.
+        const { label: rmLabel, colorName: rmColor } =
+          peelTrailingColorName(value);
+        d.regionMetric = rmLabel;
+        if (rmColor) d.regionMetricColor = rmColor;
         break;
+      }
       case 'poi-metric':
         dup(d.poiMetric);
         d.poiMetric = value;
@@ -362,6 +371,13 @@ export function parseMap(content: string): ParsedMap {
       case 'no-legend':
         d.noLegend = true;
         break;
+      case 'no-insets':
+        d.noInsets = true;
+        break;
+      case 'relief':
+        // Bare flag (idempotent like no-insets — `relief\nrelief` is no warning).
+        d.relief = true;
+        break;
       case 'muted':
       case 'natural':
         if (d.basemapStyle !== undefined && d.basemapStyle !== key)
@@ -488,6 +504,8 @@ export function parseMap(content: string): ParsedMap {
     };
     if (regionScope !== undefined) region.scope = regionScope;
     if (valueNum !== undefined) region.value = valueNum;
+    // §1.5 trailing color → flat categorical override fill (§24B.4).
+    if (split.color) region.color = split.color;
     regions.push(region);
   }
 
@@ -513,6 +531,8 @@ export function parseMap(content: string): ParsedMap {
     const poi: Writable<MapPoi> = { pos, tags, meta, lineNumber: line };
     if (split.alias) poi.alias = split.alias;
     if (label !== undefined) poi.label = label;
+    // §1.5 trailing color → flat marker fill (§24B.5); wins over a tag color.
+    if (split.color) poi.color = split.color;
     pois.push(poi);
     open.poi = { poi, indent };
   }