@diagrammo/dgmo 0.20.0 → 0.20.2

package/docs/language-reference.md

@@ -74,7 +74,8 @@ tag GroupName as <alias>
 - Alias: optional postfix `as <alias>` per §2A (universal alias syntax — `[A-Za-z][A-Za-z0-9_]{0,11}`)
 - Inline values also supported: `tag Priority as p Low green, High red`
 - Color follows the value as a bare trailing token (see §1.5). Capitalize the color word (`Red`, `Yellow`) to keep it as a literal value with no color.
-- First entry is the default — reorder to change
+- First entry is the default value — reorder to change
+- The first declared group is active by default (colors nodes immediately); `active-tag <GroupName>` only matters with ≥2 groups to pick a non-first group, and `active-tag none` suppresses all coloring
 - Must appear before diagram content
 - Legacy bare shorthand (`tag Priority p`) and `alias` keyword (`tag Priority alias p`) emit `E_TAG_SHORTHAND_REMOVED` per TD-18
 
@@ -1362,7 +1363,7 @@ recruit crew 1 2 4 c: Quartermaster
 load powder 0.5 1 2 c: Bosun
 ```
 
-Coloring is opt-in: without an `active-tag <GroupName>` directive (or a click in the app), the legend renders all groups as collapsed pills and nodes stay neutral. When a group is active, the activity card's middle (name) band picks up the tag color while the border continues to communicate criticality. Milestone diamonds adopt the tag color across the full pill.
+The first declared tag group is active by default and colors nodes; `active-tag <GroupName>` only matters with two or more groups when you want a non-first group active, and `active-tag none` suppresses coloring entirely. When a group is active, the activity card's middle (name) band picks up the tag color while the border continues to communicate criticality. Milestone diamonds adopt the tag color across the full pill.
 
 ### Date anchoring
 
@@ -2672,7 +2673,7 @@ Florida score: 51
 
 ### Region fill — categorical (tags)
 
-Uses the universal tag model (§1.3): declare a `tag` group, apply its alias as a key, `active-tag` to color.
+Uses the universal tag model (§1.3): declare a `tag` group and apply its alias as a key. The first declared group colors regions by default; `active-tag` only selects a different dimension (another group, or the `score` ramp).
 
 ```
 map Global Presence
@@ -2682,7 +2683,6 @@ tag Market as m
   HQ blue
   Region teal
   Prospect orange
-active-tag Market
 
 United States m: HQ
 Germany m: Region

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

package/src/advanced.ts

@@ -631,10 +631,7 @@ export {
 } from './echarts';
 export type { ScatterLabelPoint } from './echarts';
 export { ScaleContext } from './utils/scaling';
-export {
-  renderLegendSvg,
-  renderLegendSvgFromConfig,
-} from './utils/legend-svg';
+export { renderLegendSvg, renderLegendSvgFromConfig } from './utils/legend-svg';
 export type { LegendGroupData } from './utils/legend-types';
 export { LEGEND_HEIGHT, LEGEND_GEAR_PILL_W } from './utils/legend-constants';
 export { renderLegendD3 } from './utils/legend-d3';

package/src/map/layout.ts

@@ -313,12 +313,35 @@ export function layoutMap(
   // Lakes match the states' resolution. Falls back to the world tiers otherwise.
   const usCrisp =
     resolved.projection === 'albers-usa' && wantsUsStates && !!data.naLand;
+  // Base world layer. In a US view use the DETAIL tier (full global coverage) so
+  // distant context — South America, northern Canada, etc. — is present and can
+  // draw when it falls inside the frame. (`naLand` alone is bbox-clipped to lon
+  // -140..-52 / lat 10..66, so it has no S. America and a truncated Canada; using
+  // it as the base would leave ocean where that land belongs.)
   const worldTopo = usCrisp
-    ? data.naLand!
+    ? data.worldDetail
     : resolved.basemaps.world === 'detail'
       ? data.worldDetail
       : data.worldCoarse;
   const worldLayer = decodeLayer(worldTopo);
+  // Crisp upgrade: `naLand` is 10m country land (vs the base's 50m) but clipped to
+  // a North-America bbox. Swap a country's geometry to the crisp version ONLY when
+  // its full (base) bounds lie inside that clip box — so contained neighbours
+  // (Mexico, Central America, the Caribbean) sharpen to match the 10m states,
+  // while countries the clip would truncate (Canada, Greenland) keep their full
+  // base shape. Coast off-frame still bleeds; nothing is lost.
+  if (usCrisp && data.naLand) {
+    // NA clip bbox from the data build (scripts/build-map-data.mjs NA_BBOX).
+    const [nbW, nbS, nbE, nbN] = [-140, 10, -52, 66];
+    const crisp = decodeLayer(data.naLand);
+    for (const [iso, cf] of crisp) {
+      const base = worldLayer.get(iso);
+      if (!base) continue; // crisp-only id with no base → skip (avoid orphans)
+      const [[bw, bs], [be, bn]] = geoBounds(base as never);
+      if (bw >= nbW && be <= nbE && bs >= nbS && bn <= nbN)
+        worldLayer.set(iso, cf);
+    }
+  }
   const usLayer = wantsUsStates ? decodeLayer(data.usStates) : null;
 
   // Land is a muted green; the ocean/backdrop is blue. Scored/tagged regions
@@ -571,6 +594,19 @@ export function layoutMap(
       return p ? stretch(p[0], p[1]) : null;
     };
   } else {
+    // Clip the projected geometry to the canvas. fitExtent frames the focus
+    // region, but the rest of the world mesh still projects to coordinates far
+    // off-canvas — invisible under our viewBox, but they bloat the SVG and,
+    // critically, blow up any downstream getBBox()/bbox recompute (remark-dgmo
+    // embeddings tighten the viewBox to real content bounds, which would
+    // otherwise shrink the map to a dot). clipExtent trims the path `d` data to
+    // the viewport so drawn content == frame. Point projection (POIs/edges,
+    // albers-usa coast sampling) ignores clipExtent so positions are unaffected,
+    // and the AK/HI insets use their own dedicated projection — both safe.
+    projection.clipExtent([
+      [0, 0],
+      [width, height],
+    ]);
     path = geoPath(projection);
     project = (lon, lat) => projection([lon, lat]) ?? null;
   }
@@ -777,67 +813,72 @@ export function layoutMap(
   // unclipped conic doesn't paint frame-filling garbage; the us-states layer
   // itself is never culled (every conus state is in frame by construction).
   const conusFit = resolved.projection === 'albers-usa' && !!usLayer;
-  const cullExtent = conusFit
+  // Extent used only to classify a near-global view (draw everything) vs a
+  // regional one (cull to the canvas). For an albers fit that's the CONUS bounds;
+  // else the resolved data extent.
+  const classifyExtent = conusFit
     ? (geoBounds(fitTarget as never) as [[number, number], [number, number]])
     : resolved.extent;
-  const [[exW, exS], [exE, exN]] = cullExtent;
-  const lonSpan = exE - exW;
-  const latSpan = exN - exS;
-  // A near-global view draws everything. (albers-usa is handled per-layer at the
-  // pushRegionLayer calls: the world layer IS culled by the contiguous-US extent
-  // so far countries don't project to frame-filling garbage, while the us-states
-  // layer is NEVER culled so Alaska & Hawaii — far outside that extent — survive.)
-  const isGlobalView = lonSpan >= 270 || latSpan >= 130;
-  const padLon = Math.max(8, lonSpan * 0.35);
-  const padLat = Math.max(8, latSpan * 0.35);
-  const vW = exW - padLon;
-  const vE = exE + padLon;
-  const vS = exS - padLat;
-  const vN = exN + padLat;
-  // Pacific-crossing extents use extended longitudes (e.g. 247 = 113°W), but
-  // ring vertices are in [-180,180]. Shift each vertex into the extent's frame
-  // so the overlap test compares like-for-like.
-  const vLonCenter = (exW + exE) / 2;
+  const dLonSpan = classifyExtent[1][0] - classifyExtent[0][0];
+  const dLatSpan = classifyExtent[1][1] - classifyExtent[0][1];
+  // A near-global view draws everything; a regional one culls each ring to what
+  // actually projects onto the canvas (see ringOverlapsView — projection-based,
+  // so it's correct for the US conic and for route maps alike).
+  const isGlobalView = dLonSpan >= 270 || dLatSpan >= 130;
+  // Pacific-crossing extents use extended longitudes (e.g. 247 = 113°W), but ring
+  // vertices are in [-180,180]. Normalize each ring lon into the view's frame so
+  // the circumpolar / antimeridian-sliver guards compare like-for-like.
+  const vLonCenter = (classifyExtent[0][0] + classifyExtent[1][0]) / 2;
   const normLon = (lon: number): number => {
     let L = lon;
     while (L < vLonCenter - 180) L += 360;
     while (L > vLonCenter + 180) L -= 360;
     return L;
   };
-  // True if an outer ring overlaps the padded view box. A ring with a vertex
-  // inside is in; otherwise a non-wrapping bbox overlap also counts (a big
-  // coastal polygon whose edge clips the box). Antimeridian-wrapping rings with
-  // no in-view vertex are dropped — they are the frame-fill artifact source.
+  // True if an outer ring should be drawn in a regional view. Visibility is
+  // decided by the PROJECTION, not a lat/lon box: the ring is kept iff its
+  // projected screen bbox intersects the canvas (the projection's clipExtent then
+  // trims it to the viewport). A lat/lon box can't model what a conic actually
+  // shows — under the US Albers conic, Panama/Colombia land on-canvas at a tall
+  // aspect yet sit outside any tidy CONUS-ish box. Two geometry guards still drop
+  // the antimeridian/circumpolar rings that would otherwise project to a
+  // frame-filling garbage fill (their projected bbox spuriously covers the
+  // canvas): a near-circumpolar ring (>270° span) and an antimeridian sliver
+  // (raw span >180° but a small normalized arc, e.g. Fiji).
   type Ring = ReadonlyArray<readonly [number, number]>;
   const ringOverlapsView = (ring: Ring): boolean => {
-    let anyIn = false;
     let loMin = Infinity,
       loMax = -Infinity,
-      laMin = Infinity,
-      laMax = -Infinity,
       rawMin = Infinity,
       rawMax = -Infinity;
-    for (const [rawLon, lat] of ring) {
+    for (const [rawLon] of ring) {
       const lon = normLon(rawLon);
-      if (lon >= vW && lon <= vE && lat >= vS && lat <= vN) anyIn = true;
       if (lon < loMin) loMin = lon;
       if (lon > loMax) loMax = lon;
       if (rawLon < rawMin) rawMin = rawLon;
       if (rawLon > rawMax) rawMax = rawLon;
-      if (lat < laMin) laMin = lat;
-      if (lat > laMax) laMax = lat;
     }
-    // A near-circumpolar ring (Antarctica, polar wrap) spans almost all
-    // longitudes and projects to a frame-filling fill at regional zoom — drop it.
-    if (loMax - loMin > 270) return false;
-    // An antimeridian-crossing ring (raw lons span >180 but normalize to a small
-    // arc — e.g. Fiji at 177°E..178°W) inverts under a rotated projection and
-    // fills the frame. At coarse tier these are tiny islands; drop them in
-    // regional views rather than paint the whole ocean as land.
-    if (rawMax - rawMin > 180 && loMax - loMin < 90) return false;
-    if (anyIn) return true;
-    if (loMax - loMin > 180) return false; // wraps antimeridian, none in view
-    return !(loMax < vW || loMin > vE || laMax < vS || laMin > vN);
+    if (loMax - loMin > 270) return false; // circumpolar/polar-wrap garbage
+    if (rawMax - rawMin > 180 && loMax - loMin < 90) return false; // seam sliver
+    // Projected-bbox ∩ canvas. project() honours the active projection (and
+    // ignores clipExtent, so positions are true), so this is exactly "does any
+    // of this ring fall on the canvas".
+    let px0 = Infinity,
+      py0 = Infinity,
+      px1 = -Infinity,
+      py1 = -Infinity,
+      anyFinite = false;
+    for (const [lon, lat] of ring) {
+      const p = project(lon, lat);
+      if (!p || !Number.isFinite(p[0]) || !Number.isFinite(p[1])) continue;
+      anyFinite = true;
+      if (p[0] < px0) px0 = p[0];
+      if (p[0] > px1) px1 = p[0];
+      if (p[1] < py0) py0 = p[1];
+      if (p[1] > py1) py1 = p[1];
+    }
+    if (!anyFinite) return false;
+    return !(px1 < 0 || px0 > width || py1 < 0 || py0 > height);
   };
   // Drop a feature's sub-polygons that don't touch the view (e.g. Alaska's
   // Aleutians on a US feature framed over the Caribbean). Returns null if the
@@ -1364,24 +1405,50 @@ export function layoutMap(
       const text = labelText(p);
       return { text, w: measureLegendText(text, FONT) };
     };
+    // Candidate inline placements around a marker, in escalation order: the two
+    // horizontal sides first (most legible), then above/below for a hub whose
+    // edges all leave sideways and block both flanks (e.g. a POI fed by routes
+    // from the east AND west — Boulder in the route-cluster gauntlet).
+    type Side = 'right' | 'left' | 'above' | 'below';
+    const GAP = 3;
+    const inlineRect = (p: MapLayoutPoi, w: number, side: Side): LabelRect => {
+      switch (side) {
+        case 'right':
+          return { x: p.cx + p.r + GAP, y: p.cy - poiLabH / 2, w, h: poiLabH };
+        case 'left':
+          return {
+            x: p.cx - p.r - GAP - w,
+            y: p.cy - poiLabH / 2,
+            w,
+            h: poiLabH,
+          };
+        case 'above':
+          return {
+            x: p.cx - w / 2,
+            y: p.cy - p.r - GAP - poiLabH,
+            w,
+            h: poiLabH,
+          };
+        case 'below':
+          return { x: p.cx - w / 2, y: p.cy + p.r + GAP, w, h: poiLabH };
+      }
+    };
     const pushInline = (
       p: MapLayoutPoi,
       text: string,
       w: number,
-      side: 'right' | 'left'
+      side: Side
     ): void => {
-      const tx = side === 'right' ? p.cx + p.r + 3 : p.cx - p.r - 3;
-      obstacles.push({
-        x: side === 'right' ? tx : tx - w,
-        y: p.cy - poiLabH / 2,
-        w,
-        h: poiLabH,
-      });
+      const rect = inlineRect(p, w, side);
+      obstacles.push(rect);
+      const anchor =
+        side === 'right' ? 'start' : side === 'left' ? 'end' : 'middle';
+      const x = side === 'right' ? rect.x : side === 'left' ? rect.x + w : p.cx;
       labels.push({
-        x: tx,
-        y: p.cy + FONT / 3,
+        x,
+        y: rect.y + poiLabH / 2 + FONT / 3,
         text,
-        anchor: side === 'right' ? 'start' : 'end',
+        anchor,
         color: palette.text,
         halo: true,
         haloColor: palette.bg,
@@ -1389,19 +1456,15 @@ export function layoutMap(
         lineNumber: p.lineNumber,
       });
     };
-    const inlineFits = (
-      p: MapLayoutPoi,
-      w: number,
-      side: 'right' | 'left'
-    ): boolean => {
-      const tx = side === 'right' ? p.cx + p.r + 3 : p.cx - p.r - 3;
-      const rect: LabelRect = {
-        x: side === 'right' ? tx : tx - w,
-        y: p.cy - poiLabH / 2,
-        w,
-        h: poiLabH,
-      };
-      return rect.x >= 0 && rect.x + rect.w <= width && !collides(rect);
+    const inlineFits = (p: MapLayoutPoi, w: number, side: Side): boolean => {
+      const rect = inlineRect(p, w, side);
+      return (
+        rect.x >= 0 &&
+        rect.x + rect.w <= width &&
+        rect.y >= 0 &&
+        rect.y + rect.h <= height &&
+        !collides(rect)
+      );
     };
 
     // Pre-group POIs by proximity. A tight cluster (offshore platforms, a metro
@@ -1477,12 +1540,11 @@ export function layoutMap(
       if (g.length === 1) {
         const p = g[0]!;
         const { text, w } = labelInfo(p);
-        if (inlineFits(p, w, 'right')) {
-          pushInline(p, text, w, 'right');
-          continue;
-        }
-        if (inlineFits(p, w, 'left')) {
-          pushInline(p, text, w, 'left');
+        const side = (['right', 'left', 'above', 'below'] as const).find((s) =>
+          inlineFits(p, w, s)
+        );
+        if (side) {
+          pushInline(p, text, w, side);
           continue;
         }
       }

package/src/map/load-data.ts

@@ -10,12 +10,33 @@
 // build must inject `MapData` (or supply a fetch/bundle loader) — `resolveMap`
 // takes `MapData` by DI precisely so the browser path can differ. Do NOT assume
 // a green Node smoke test proves the browser load.
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
+//
+// Node builtins (`fs/promises`, `url`, `path`) are imported LAZILY inside
+// `loadMapData` — never at module top level — so this file can be pulled into a
+// browser bundle (Obsidian's esbuild `platform: browser`, the app's Vite/Rollup
+// web build) without the bundler trying to resolve `node:*`. Mirrors the
+// `await import('jsdom')` seam in render.ts. The web build injects `MapData` via
+// DI and never calls `loadMapData`, so the dynamic import only runs in Node.
 import type { MapData } from './resolved-types';
 import type { BoundaryTopology, Gazetteer } from './data/types';
 
+type NodeBuiltins = {
+  readFile: typeof import('node:fs/promises').readFile;
+  fileURLToPath: typeof import('node:url').fileURLToPath;
+  dirname: typeof import('node:path').dirname;
+  resolve: typeof import('node:path').resolve;
+};
+
+async function loadNodeBuiltins(): Promise<NodeBuiltins> {
+  const [{ readFile }, { fileURLToPath }, { dirname, resolve }] =
+    await Promise.all([
+      import('node:fs/promises'),
+      import('node:url'),
+      import('node:path'),
+    ]);
+  return { readFile, fileURLToPath, dirname, resolve };
+}
+
 const FILES = {
   worldCoarse: 'world-coarse.json',
   worldDetail: 'world-detail.json',
@@ -37,15 +58,22 @@ const CANDIDATE_DIRS = [
 
 let cache: Promise<MapData> | undefined;
 
-async function readJson<T>(dir: string, name: string): Promise<T> {
-  return JSON.parse(await readFile(resolve(dir, name), 'utf8')) as T;
+async function readJson<T>(
+  nb: NodeBuiltins,
+  dir: string,
+  name: string
+): Promise<T> {
+  return JSON.parse(await nb.readFile(nb.resolve(dir, name), 'utf8')) as T;
 }
 
-async function firstExistingDir(baseDir: string): Promise<string> {
+async function firstExistingDir(
+  nb: NodeBuiltins,
+  baseDir: string
+): Promise<string> {
   for (const rel of CANDIDATE_DIRS) {
-    const dir = resolve(baseDir, rel);
+    const dir = nb.resolve(baseDir, rel);
     try {
-      await readFile(resolve(dir, FILES.gazetteer), 'utf8');
+      await nb.readFile(nb.resolve(dir, FILES.gazetteer), 'utf8');
       return dir;
     } catch {
       /* try next candidate */
@@ -78,10 +106,10 @@ function validate(data: MapData): MapData {
  *  (dist/cli.cjs, where `import.meta.url` is `undefined` → `fileURLToPath`
  *  throws). The `typeof __dirname` guard is safe in ESM (evaluates to
  *  'undefined' without a ReferenceError). */
-function moduleBaseDir(): string {
+function moduleBaseDir(nb: NodeBuiltins): string {
   try {
     const url = import.meta.url;
-    if (url) return dirname(fileURLToPath(url));
+    if (url) return nb.dirname(nb.fileURLToPath(url));
   } catch {
     /* CJS: import.meta unavailable — fall through */
   }
@@ -95,7 +123,8 @@ function moduleBaseDir(): string {
  *  call can retry rather than inheriting a poisoned promise. */
 export function loadMapData(): Promise<MapData> {
   cache ??= (async (): Promise<MapData> => {
-    const dir = await firstExistingDir(moduleBaseDir());
+    const nb = await loadNodeBuiltins();
+    const dir = await firstExistingDir(nb, moduleBaseDir(nb));
     const [
       worldCoarse,
       worldDetail,
@@ -106,15 +135,15 @@ export function loadMapData(): Promise<MapData> {
       naLakes,
       gazetteer,
     ] = await Promise.all([
-      readJson<BoundaryTopology>(dir, FILES.worldCoarse),
-      readJson<BoundaryTopology>(dir, FILES.worldDetail),
-      readJson<BoundaryTopology>(dir, FILES.usStates),
+      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.
-      readJson<BoundaryTopology>(dir, FILES.lakes).catch(() => undefined),
-      readJson<BoundaryTopology>(dir, FILES.rivers).catch(() => undefined),
-      readJson<BoundaryTopology>(dir, FILES.naLand).catch(() => undefined),
-      readJson<BoundaryTopology>(dir, FILES.naLakes).catch(() => undefined),
-      readJson<Gazetteer>(dir, FILES.gazetteer),
+      readJson<BoundaryTopology>(nb, dir, FILES.lakes).catch(() => undefined),
+      readJson<BoundaryTopology>(nb, dir, FILES.rivers).catch(() => undefined),
+      readJson<BoundaryTopology>(nb, dir, FILES.naLand).catch(() => undefined),
+      readJson<BoundaryTopology>(nb, dir, FILES.naLakes).catch(() => undefined),
+      readJson<Gazetteer>(nb, dir, FILES.gazetteer),
     ]);
     return validate({
       worldCoarse,

package/src/map/resolver.ts

@@ -519,8 +519,15 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
   // 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.
+  // albers-usa is the US-only composite projection — it insets AK/HI and clips
+  // out all non-US land. Use it only when the map actually renders US STATES (an
+  // explicit `region us-states` or US-state region fills), NOT merely because the
+  // POIs happen to be US: a pure POI/route map across the US should stay on a
+  // geographic projection so neighbour land (Mexico, Central America, the
+  // Caribbean, Canada) still draws.
   const usDominant =
-    (inferredCountry === 'US' || subdivisions.includes('us-states')) &&
+    (subdivisions.includes('us-states') ||
+      regions.some((r) => r.layer === 'us-state')) &&
     !regions.some((r) => r.layer === 'country' && r.iso !== 'US') &&
     !anyNonUsPoi;