@diagrammo/dgmo 0.20.3 → 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,21 +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 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 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
@@ -86,9 +117,9 @@ export interface MapLayoutRegion {
   readonly label?: string;
   readonly lineNumber: number;
   readonly layer: 'base' | 'country' | 'us-state';
-  /** The region's score (if any) — emitted as `data-score` so the app can
+  /** The region's value (if any) — emitted as `data-value` so the app can
    *  highlight by gradient-scrub proximity. */
-  readonly score?: number;
+  readonly value?: number;
   /** 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>>;
@@ -106,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 {
@@ -119,6 +168,9 @@ export interface MapLayoutPoi {
   readonly implicit: boolean;
   readonly isOrigin: boolean; // route origin -> distinct marker
   readonly routeNumber?: number; // route stop badge
+  /** Tag values keyed by lowercased group name — emitted as `data-tag-<group>`
+   *  so the app can spotlight markers on legend-entry hover (mirrors regions). */
+  readonly tags?: Readonly<Record<string, string>>;
 }
 
 /** A drawn connector -- an edge or a route leg (same geometry contract). */
@@ -176,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;
@@ -186,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[];
@@ -195,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 {
@@ -276,18 +357,33 @@ 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). */
-export function mapBackgroundColor(palette: PaletteColors): string {
-  return mix(palette.colors.blue, palette.bg, WATER_TINT);
+ *  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
+): string {
+  return mix(
+    palette.colors.blue,
+    palette.bg,
+    isDark ? WATER_TINT_DARK : WATER_TINT_LIGHT
+  );
 }
 
-/** The map's neutral (unscored/untagged) LAND colour — the green base every
- *  region blends from. Exported so a host can DIM a region to plain land
- *  (rather than lowering opacity, which would let the blue water show through
- *  and make the shape read as ocean). Matches the layout's `neutralFill`. */
+/** 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`. 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
+  isDark: boolean,
+  _dataActive = false
 ): string {
   return mix(
     palette.colors.green,
@@ -344,52 +440,52 @@ export function layoutMap(
   }
   const usLayer = wantsUsStates ? decodeLayer(data.usStates) : null;
 
-  // Land is a muted green; the ocean/backdrop is blue. Scored/tagged regions
-  // paint over the land base, and the score ramp blends FROM the land colour so
-  // low scores stay land-toned rather than fading out. In a US view the world
-  // layer is just neighbour context (Mexico/Canada at the frame edge) — fill it
-  // gray so the green US reads as the subject; world maps (no us-states layer)
-  // keep green land for every country.
-  const landTint = isDark ? LAND_TINT_DARK : LAND_TINT_LIGHT;
-  const neutralFill = mix(palette.colors.green, palette.bg, landTint);
-  const water = mapBackgroundColor(palette);
   const usContext = usLayer !== null;
-  const foreignFill = mix(
-    palette.colors.gray,
-    palette.bg,
-    isDark ? FOREIGN_TINT_DARK : FOREIGN_TINT_LIGHT
-  );
+  // Basemap fills (`water` / `neutralFill` / `foreignFill`) depend on whether a
+  // colouring dimension is active — defined below, once `activeGroup` is known.
   // Region borders: a clearly dark outline in BOTH themes. palette.text flips
   // (dark on light, light on dark), so mix toward whichever of text/bg is the
   // dark one — never a light hairline over the land fills.
   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 scores = resolved.regions
-    .filter((r) => r.score !== undefined)
-    .map((r) => r.score!);
+  const values = resolved.regions
+    .filter((r) => r.value !== undefined)
+    .map((r) => r.value!);
   const scaleOverride = resolved.directives.scale;
-  const rampMin = scaleOverride ? scaleOverride.min : Math.min(...scores);
-  const rampMax = scaleOverride ? scaleOverride.max : Math.max(...scores);
-  // Score ramp is red so scored regions stand out against the blue water
-  // (palette.primary is a blue in most palettes and would blend in).
-  const rampHue = palette.colors.red;
-  const hasRamp = scores.length > 0;
+  const rampMin = scaleOverride ? scaleOverride.min : Math.min(...values);
+  const rampMax = scaleOverride ? scaleOverride.max : Math.max(...values);
+  // 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 score ramp and each tag group are
-  // mutually-exclusive selectable groups. `SCORE_NAME` is the ramp's group name
-  // (the metric label, or "Score"); the reserved token `score` also selects it.
-  // Exactly one dimension is active and drives every region's fill.
-  const SCORE_NAME = hasRamp
-    ? resolved.directives.metric?.trim() || 'Score'
+  // Colouring dimension (AR4, bivariate): the value ramp and each tag group are
+  // mutually-exclusive selectable groups. `VALUE_NAME` is the ramp's group name
+  // (the region-metric label, or "Value"). Exactly one dimension is active and
+  // drives every region's fill. The value ramp is the default-active dimension
+  // whenever any region has a value (the old `active-tag score` token is gone —
+  // there is nothing to force; selecting a tag group is what `active-tag` does).
+  const VALUE_NAME = hasRamp
+    ? resolved.directives.regionMetric?.trim() || 'Value'
     : null;
   const matchColorGroup = (v: string): string | null => {
     const lv = v.trim().toLowerCase();
     if (lv === 'none') return null;
-    if (SCORE_NAME && (lv === 'score' || lv === SCORE_NAME.toLowerCase()))
-      return SCORE_NAME;
+    if (lv === VALUE_NAME?.toLowerCase()) return VALUE_NAME;
     const tg = resolved.tagGroups.find((g) => g.name.toLowerCase() === lv);
     return tg ? tg.name : v; // unknown name passes through → renders neutral
   };
@@ -400,13 +496,42 @@ export function layoutMap(
   } else if (resolved.directives.activeTag !== undefined) {
     activeGroup = matchColorGroup(resolved.directives.activeTag);
   } else {
-    // Default: colour by score when scores exist (preserves the historical
-    // "score wins" default), else the first declared tag group.
+    // Default: colour by the value ramp when values exist, else the first
+    // declared tag group.
     activeGroup =
-      SCORE_NAME ??
+      VALUE_NAME ??
       (resolved.tagGroups.length > 0 ? resolved.tagGroups[0]!.name : null);
   }
-  const activeIsScore = SCORE_NAME !== null && activeGroup === SCORE_NAME;
+  const activeIsScore = VALUE_NAME !== null && activeGroup === VALUE_NAME;
+
+  // 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
+      : resolved.directives.basemapStyle === 'natural'
+        ? false
+        : 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,
+    mutedBasemap
+      ? isDark
+        ? MUTED_FOREIGN_DARK
+        : MUTED_FOREIGN_LIGHT
+      : isDark
+        ? FOREIGN_TINT_DARK
+        : FOREIGN_TINT_LIGHT
+  );
 
   // Score ramp base: a NEUTRAL tint of the page, NOT the (green) land colour —
   // blending red toward green produced muddy brown mid-tones that blurred into
@@ -415,7 +540,7 @@ export function layoutMap(
   // off the near-black surface so the lowest scores read as a clear muted red
   // rather than sinking to maroon-black.
   const rampBase = isDark ? mix(palette.surface, palette.text, 28) : palette.bg;
-  const fillForScore = (s: number): string => {
+  const fillForValue = (s: number): string => {
     const t = rampMax > rampMin ? (s - rampMin) / (rampMax - rampMin) : 1;
     const pct = RAMP_FLOOR + Math.max(0, Math.min(1, t)) * (100 - RAMP_FLOOR);
     return mix(rampHue, rampBase, pct);
@@ -450,15 +575,29 @@ export function layoutMap(
     );
   };
 
-  /** A region's fill under the ACTIVE colouring dimension (AR4, bivariate):
-   *  score-active → ramp for scored regions, neutral otherwise; a tag group
-   *  active → that group's tag colour, neutral otherwise (score 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: {
-    score?: number;
+    value?: number;
+    color?: string;
     tags: Readonly<Record<string, string>>;
   }): string => {
+    const direct = directFill(r.color);
+    if (direct) return direct;
     if (activeIsScore) {
-      return r.score !== undefined ? fillForScore(r.score) : neutralFill;
+      return r.value !== undefined ? fillForValue(r.value) : neutralFill;
     }
     return tagFill(r.tags, activeGroup) ?? neutralFill;
   };
@@ -558,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];
@@ -568,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,
@@ -628,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)
@@ -666,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,
@@ -726,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],
@@ -761,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,
@@ -778,7 +890,7 @@ export function layoutMap(
         stroke: regionStroke,
         lineNumber,
         layer: 'us-state',
-        ...(r?.score !== undefined && { score: r.score }),
+        ...(r?.value !== undefined && { value: r.value }),
         ...(r && Object.keys(r.tags).length > 0 && { tags: r.tags }),
       });
       const ctr = geoPath(proj).centroid(f as never);
@@ -1012,7 +1124,7 @@ export function layoutMap(
         lineNumber,
         layer,
         ...(label !== undefined && { label }),
-        ...(isThisLayer && r.score !== undefined && { score: r.score }),
+        ...(isThisLayer && r.value !== undefined && { value: r.value }),
         ...(isThisLayer && Object.keys(r.tags).length > 0 && { tags: r.tags }),
       });
     }
@@ -1045,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)) {
@@ -1067,14 +1232,14 @@ export function layoutMap(
     }
   }
 
-  // -- POIs: project, size-scale, co-located spiderfy --
+  // -- POIs: project, value→size-scale, co-located spiderfy --
   const sizeVals = resolved.pois
-    .map((p) => Number(p.meta['size']))
+    .map((p) => Number(p.meta['value']))
     .filter((n) => Number.isFinite(n) && n > 0);
   const sizeMin = sizeVals.length ? Math.min(...sizeVals) : 0;
   const sizeMax = sizeVals.length ? Math.max(...sizeVals) : 0;
   const radiusFor = (p: ResolvedPoi): number => {
-    const v = Number(p.meta['size']);
+    const v = Number(p.meta['value']);
     if (!Number.isFinite(v) || v <= 0 || sizeMax <= 0) return R_DEFAULT;
     // sqrt so AREA encodes the value
     const t =
@@ -1085,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;
@@ -1160,6 +1329,7 @@ export function layoutMap(
         implicit: !!e.p.implicit,
         isOrigin: originIds.has(e.p.id),
         ...(num !== undefined && { routeNumber: num }),
+        ...(Object.keys(e.p.tags).length > 0 && { tags: e.p.tags }),
       });
     });
   }
@@ -1208,31 +1378,50 @@ export function layoutMap(
     return `M${ax},${ay}Q${px},${py} ${bx},${by}`;
   };
 
-  // Routes: legs between consecutive stops (loop closing leg included).
+  // Routes: each leg is an edge (fromId → toId) carrying its own label,
+  // value→thickness, and arc shape. Loop-closing legs are explicit in `rt.legs`;
+  // the origin is never double-marked because `stopIds` is unique.
+  const routeLegVals = resolved.routes
+    .flatMap((rt) => rt.legs)
+    .map((l) => Number(l.value))
+    .filter((n) => Number.isFinite(n) && n > 0);
+  const rlMin = routeLegVals.length ? Math.min(...routeLegVals) : 0;
+  const rlMax = routeLegVals.length ? Math.max(...routeLegVals) : 0;
+  const routeWidthFor = (v: number): number => {
+    if (!Number.isFinite(v) || v <= 0 || rlMax <= 0) return W_MIN;
+    const t = rlMax > rlMin ? (v - rlMin) / (rlMax - rlMin) : 1;
+    return W_MIN + t * (W_MAX - W_MIN);
+  };
   for (const rt of resolved.routes) {
-    const curved = rt.meta['style'] === 'arc';
-    for (let i = 1; i < rt.stopIds.length; i++) {
-      const a = poiScreen.get(rt.stopIds[i - 1]!);
-      const b = poiScreen.get(rt.stopIds[i]!);
+    for (const leg of rt.legs) {
+      const a = poiScreen.get(leg.fromId);
+      const b = poiScreen.get(leg.toId);
       if (!a || !b) continue;
+      const mx = (a.cx + b.cx) / 2;
+      const my = (a.cy + b.cy) / 2;
       legs.push({
-        d: legPath(a, b, curved, 0),
-        width: W_MIN,
+        d: legPath(a, b, leg.style === 'arc', 0),
+        width: routeWidthFor(Number(leg.value)),
         color: mix(palette.text, palette.bg, 72),
         arrow: true,
-        lineNumber: rt.lineNumber,
+        lineNumber: leg.lineNumber,
+        ...(leg.label !== undefined && {
+          label: leg.label,
+          labelX: mx,
+          labelY: my - 4,
+        }),
       });
     }
   }
 
   // Edges: group by unordered endpoint pair for deterministic fan-out (AR9).
   const weightVals = resolved.edges
-    .map((e) => Number(e.meta['weight']))
+    .map((e) => Number(e.meta['value']))
     .filter((n) => Number.isFinite(n) && n > 0);
   const wMin = weightVals.length ? Math.min(...weightVals) : 0;
   const wMax = weightVals.length ? Math.max(...weightVals) : 0;
   const widthFor = (e: ResolvedEdge): number => {
-    const v = Number(e.meta['weight']);
+    const v = Number(e.meta['value']);
     if (!Number.isFinite(v) || v <= 0 || wMax <= 0) return W_MIN;
     const t = wMax > wMin ? (v - wMin) / (wMax - wMin) : 1;
     return W_MIN + t * (W_MAX - W_MIN);
@@ -1566,17 +1755,18 @@ export function layoutMap(
       name: g.name,
       entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
     }));
-    // Only the colouring dimensions (score ramp + tag groups) get a legend.
-    // POI size and edge weight are self-evident from the marker/line scale and
-    // intentionally carry no key.
+    // 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.metric !== undefined && {
-              metric: resolved.directives.metric,
+            ...(resolved.directives.regionMetric !== undefined && {
+              metric: resolved.directives.regionMetric,
             }),
             min: rampMin,
             max: rampMax,
@@ -1597,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,
   };
 }