@diagrammo/dgmo 0.32.0 → 0.33.0

package/src/map/completion.ts

@@ -151,6 +151,122 @@ export function completeMapPlaces(
   return [...cityItems, ...airportItems].slice(0, limit);
 }
 
+/** A POI search hit — a city or airport the resolver can resolve, with the
+ *  exact `token` to paste into DGMO (a `poi`/route endpoint). Powers the CLI
+ *  `dgmo map search` command and the MCP `lookup_map_location` tool, so authors
+ *  (and AI agents) can DISCOVER valid place tokens instead of guessing — e.g.
+ *  learn that "New York" must be `New York City` and that `JFK` is bundled. */
+export interface MapLocationMatch {
+  /** Canonical display name (cities) or full airport name. */
+  readonly name: string;
+  /** Exact text to use in DGMO. Cities: the name, ISO-qualified when ambiguous
+   *  (`Portland US-OR`). Airports: the upper-case IATA code (`JFK`). */
+  readonly token: string;
+  readonly kind: 'city' | 'airport';
+  readonly iso: string;
+  readonly sub?: string;
+  /** City population (0 for airports). */
+  readonly pop: number;
+  /** Human detail, e.g. `US-OR · 652,503` or `Airport · John F Kennedy Intl`. */
+  readonly detail: string;
+}
+
+/**
+ * Substring-search cities + airports for a discovery surface (CLI / MCP), so an
+ * author can find the exact token the resolver expects. Unlike
+ * {@link completeMapPlaces} (prefix-only, editor type-ahead), this matches
+ * anywhere in a city name OR an airport code/name, so "york" finds
+ * `New York City` and "kennedy" finds `JFK`.
+ *
+ * Ranking: exact-name (or exact-IATA) → prefix → substring; within a tier,
+ * cities by population desc (deterministic index tie-break), cities before
+ * airports. Pure + deterministic. Empty query → `[]`.
+ */
+export function searchMapLocations(
+  query: string,
+  gazetteer: Gazetteer,
+  opts?: { readonly limit?: number; readonly airports?: AirportData }
+): MapLocationMatch[] {
+  const q = fold(query);
+  if (!q) return [];
+  const limit = opts?.limit ?? 20;
+
+  // rank: 0 exact, 1 prefix, 2 substring; -1 = no match.
+  const rankOf = (hay: string): number =>
+    hay === q ? 0 : hay.startsWith(q) ? 1 : hay.includes(q) ? 2 : -1;
+
+  // Cities — match on folded display name (via byName keys) + aliases.
+  const cityRank = new Map<number, number>(); // city index → best rank
+  const consider = (idx: number, rank: number): void => {
+    if (rank < 0) return;
+    const prev = cityRank.get(idx);
+    if (prev === undefined || rank < prev) cityRank.set(idx, rank);
+  };
+  for (const [key, list] of Object.entries(gazetteer.byName)) {
+    const r = rankOf(key);
+    if (r >= 0) for (const i of list) consider(i, r);
+  }
+  for (const [key, idx] of Object.entries(gazetteer.alt)) {
+    consider(idx, rankOf(key));
+  }
+
+  const cityItems: Array<MapLocationMatch & { _rank: number }> = [...cityRank]
+    .filter(([i]) => gazetteer.cities[i] !== undefined)
+    .map(([i, rank]) => {
+      const c = gazetteer.cities[i]!;
+      const [, , iso, pop, name, sub] = c;
+      const ambiguous = (gazetteer.byName[fold(name)]?.length ?? 0) > 1;
+      const qualifier = sub ?? iso;
+      return {
+        name,
+        token: ambiguous ? `${name} ${qualifier}` : name,
+        kind: 'city' as const,
+        iso,
+        ...(sub !== undefined && { sub }),
+        pop,
+        detail: `${qualifier} · ${groupThousands(pop)}`,
+        _rank: rank,
+      };
+    });
+
+  // Airports — match on folded IATA code OR folded airport name.
+  const airports = opts?.airports;
+  const airportItems: Array<MapLocationMatch & { _rank: number }> = [];
+  if (airports?.airportIata) {
+    for (const [code, idx] of Object.entries(airports.airportIata)) {
+      const a = airports.airports[idx];
+      if (!a) continue;
+      const codeRank = rankOf(code);
+      const nameRank = rankOf(fold(a[4]));
+      const rank = Math.min(
+        codeRank < 0 ? 99 : codeRank,
+        nameRank < 0 ? 99 : nameRank
+      );
+      if (rank > 2) continue;
+      airportItems.push({
+        name: a[4],
+        token: code.toUpperCase(),
+        kind: 'airport',
+        iso: a[2],
+        pop: 0,
+        detail: `Airport · ${a[4]}`,
+        _rank: rank,
+      });
+    }
+  }
+
+  return [...cityItems, ...airportItems]
+    .sort(
+      (x, y) =>
+        x._rank - y._rank || // best match tier first
+        (x.kind === y.kind ? 0 : x.kind === 'city' ? -1 : 1) || // city before airport
+        y.pop - x.pop || // populous city first
+        (x.token < y.token ? -1 : x.token > y.token ? 1 : 0)
+    )
+    .slice(0, limit)
+    .map(({ _rank, ...rest }) => rest);
+}
+
 export interface MapRegionCompletion {
   /** Display name = insert text (the resolver disambiguates cross-layer
    *  collisions like Georgia by map scope, §24B.8). */

package/src/map/layout.ts

@@ -5,6 +5,7 @@
 // POI radii + edge widths, and places labels with per-cluster collision
 // escalation. The SVG emission is renderer.ts (it only draws what we compute).
 // See spec section 24B.3-.7/.11 + the tech-spec Adversarial Review Resolutions AR1-AR9.
+import { tagAttrKey } from '../utils/tag-groups';
 import {
   geoPath,
   geoNaturalEarth1,
@@ -1582,7 +1583,7 @@ export function layoutMap(
       (g) => g.name.toLowerCase() === groupName.toLowerCase()
     );
     if (!group) return null;
-    const val = tags[group.name.toLowerCase()] ?? group.defaultValue;
+    const val = tags[tagAttrKey(group.name)] ?? group.defaultValue;
     if (!val) return null;
     const entry = group.entries.find(
       (e) => e.value.toLowerCase() === val.toLowerCase()
@@ -2656,7 +2657,7 @@ export function layoutMap(
     if (directHex)
       return { fill: directHex, stroke: mix(directHex, palette.text, 18) };
     for (const group of resolved.tagGroups) {
-      const val = p.tags[group.name.toLowerCase()];
+      const val = p.tags[tagAttrKey(group.name)];
       if (!val) continue;
       const entry = group.entries.find(
         (e) => e.value.toLowerCase() === val.toLowerCase()
@@ -2678,7 +2679,7 @@ export function layoutMap(
   // or null → caller falls back to the neutral connector mix.
   const lineColor = (tags: Readonly<Record<string, string>>): string | null => {
     for (const group of resolved.tagGroups) {
-      const val = tags[group.name.toLowerCase()];
+      const val = tags[tagAttrKey(group.name)];
       if (!val) continue;
       const entry = group.entries.find(
         (e) => e.value.toLowerCase() === val.toLowerCase()

package/src/map/parser.ts

@@ -25,6 +25,7 @@ import {
   validateTagGroupNames,
   finalizeAutoTagColors,
   AUTO_TAG_COLOR_SENTINEL,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import { parseInArrowLabel } from '../utils/arrows';
 import type {
@@ -157,7 +158,7 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
   // Declared tag-group names (lowercased) — the keys `partitionMeta` treats as
   // tag values (resolved from aliases). Recomputed as groups are declared.
   const tagGroupNames = (): ReadonlySet<string> =>
-    new Set(tagGroups.map((g) => g.name.toLowerCase()));
+    new Set(tagGroups.map((g) => tagAttrKey(g.name)));
 
   const closeBlocks = (): void => {
     open.tag = null;
@@ -378,7 +379,7 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
       entries: [],
       lineNumber: line,
     };
-    if (m.alias) aliasMap.set(m.alias.toLowerCase(), m.name.toLowerCase());
+    if (m.alias) aliasMap.set(m.alias.toLowerCase(), tagAttrKey(m.name));
     tagGroups.push(group);
     open.tag = group;
     // Inline form: `tag Market as m HQ indigo, Region teal` (R4).

package/src/mindmap/parser.ts

@@ -19,6 +19,7 @@ import {
   finalizeAutoTagColors,
   cascadeTagMetadata,
   AUTO_TAG_COLOR_SENTINEL,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import {
   measureIndent,
@@ -167,12 +168,12 @@ export function parseMindmap(
       if (tagBlockMatch.alias) {
         aliasMap.set(
           tagBlockMatch.alias.toLowerCase(),
-          tagBlockMatch.name.toLowerCase()
+          tagAttrKey(tagBlockMatch.name)
         );
       }
       aliasMap.set(
-        tagBlockMatch.name.toLowerCase(),
-        tagBlockMatch.name.toLowerCase()
+        tagAttrKey(tagBlockMatch.name),
+        tagAttrKey(tagBlockMatch.name)
       );
       result.tagGroups.push(currentTagGroup);
       continue;

package/src/mindmap/renderer.ts

@@ -2,6 +2,7 @@
 // Mindmap SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import { FONT_FAMILY } from '../fonts';
 import {
@@ -389,7 +390,7 @@ export function renderMindmap(
 
     // Expose active tag group value for legend-entry hover dimming
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const metaValue = node.metadata[tagKey];
       if (metaValue) {
         nodeG.attr(`data-tag-${tagKey}`, metaValue.toLowerCase());

package/src/org/layout.ts

@@ -2,6 +2,7 @@
 // Org Chart Tree Layout Engine (d3-hierarchy)
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import { hierarchy, tree } from 'd3-hierarchy';
 import type { ParsedOrg, OrgNode } from './parser';
 import type { Writable } from '../utils/brand';
@@ -303,7 +304,7 @@ function computeLegendGroups(
     if (group.entries.length === 0) continue;
 
     // Filter entries to only values actually used by nodes (if provided)
-    const usedValues = usedValuesByGroup?.get(group.name.toLowerCase());
+    const usedValues = usedValuesByGroup?.get(tagAttrKey(group.name));
     const visibleEntries = usedValues
       ? group.entries.filter((e) => usedValues.has(e.value.toLowerCase()))
       : group.entries;
@@ -1185,7 +1186,7 @@ export function layoutOrg(
   // Collect which tag group values are actually used by nodes
   const usedValuesByGroup = new Map<string, Set<string>>();
   for (const group of parsed.tagGroups) {
-    const key = group.name.toLowerCase();
+    const key = tagAttrKey(group.name);
     const used = new Set<string>();
     const walk = (node: OrgNode) => {
       if (!node.isContainer && node.metadata[key]) {

package/src/org/parser.ts

@@ -20,6 +20,7 @@ import {
   stripDefaultModifier,
   finalizeAutoTagColors,
   AUTO_TAG_COLOR_SENTINEL,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import {
   measureIndent,
@@ -219,14 +220,14 @@ export function parseOrg(content: string, palette?: PaletteColors): ParsedOrg {
       if (tagBlockMatch.alias) {
         metaAliasMap.set(
           normalizeName(tagBlockMatch.alias),
-          tagBlockMatch.name.toLowerCase()
+          tagAttrKey(tagBlockMatch.name)
         );
       }
       // §1.4 dispatch: register canonical name so `<name>:` triggers
       // the metadata cut even without an explicit `as <alias>`.
       metaAliasMap.set(
         normalizeName(tagBlockMatch.name),
-        tagBlockMatch.name.toLowerCase()
+        tagAttrKey(tagBlockMatch.name)
       );
       result.tagGroups.push(currentTagGroup);
       continue;

package/src/org/renderer.ts

@@ -2,6 +2,7 @@
 // Org Chart SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import { FONT_FAMILY } from '../fonts';
 import {
@@ -269,7 +270,7 @@ export function renderOrg(
   // Build display name map from tag groups (lowercase key → original casing)
   const displayNames = new Map<string, string>();
   for (const group of parsed.tagGroups) {
-    displayNames.set(group.name.toLowerCase(), group.name);
+    displayNames.set(tagAttrKey(group.name), group.name);
   }
 
   // Root node IDs — focus icon is suppressed on these (already the tree root)
@@ -288,7 +289,7 @@ export function renderOrg(
     // Use tagMetadata (unfiltered) so hover-highlight works even when the
     // active tag group is hidden from the visible card body via the eye toggle.
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const metaValue = c.tagMetadata[tagKey];
       if (metaValue) {
         cG.attr(`data-tag-${tagKey}`, metaValue.toLowerCase());
@@ -466,7 +467,7 @@ export function renderOrg(
     // Use tagMetadata (unfiltered) so hover-highlight works even when the
     // active tag group is hidden from the visible card body via the eye toggle.
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const metaValue = node.tagMetadata[tagKey];
       if (metaValue) {
         nodeG.attr(`data-tag-${tagKey}`, metaValue.toLowerCase());
@@ -781,7 +782,7 @@ export function renderOrg(
       const computedLayout = legendHandle.getLayout();
       if (computedLayout.activeCapsule?.addonX != null) {
         const capsule = computedLayout.activeCapsule;
-        const groupKey = capsule.groupName.toLowerCase();
+        const groupKey = tagAttrKey(capsule.groupName);
         const isHidden = hiddenAttributes?.has(groupKey) ?? false;
 
         // Find the rendered active group <g> and append eye icon

package/src/pert/parser.ts

@@ -36,6 +36,7 @@ import {
   finalizeAutoTagColors,
   AUTO_TAG_COLOR_SENTINEL,
   type TagGroup,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import type { Writable } from '../utils/brand';
 import type { Duration, DurationUnit } from '../gantt/types';
@@ -695,12 +696,12 @@ export function parsePert(
         if (tagBlockMatch.alias) {
           metaAliasMap.set(
             tagBlockMatch.alias.toLowerCase(),
-            tagBlockMatch.name.toLowerCase()
+            tagAttrKey(tagBlockMatch.name)
           );
         }
         metaAliasMap.set(
           normalizeName(tagBlockMatch.name),
-          tagBlockMatch.name.toLowerCase()
+          tagAttrKey(tagBlockMatch.name)
         );
         tagGroups.push(currentTagGroup);
         // Inline values (e.g. `tag Priority as p Low green, High red`).

package/src/sequence/renderer.ts

@@ -2,9 +2,15 @@
 // Sequence Diagram SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
+import {
+  contrastText,
+  mix,
+  shapeFill,
+  themeBaseBg,
+} from '../palettes/color-utils';
 import {
   parseInlineMarkdown,
   truncateBareUrl,
@@ -1062,7 +1068,7 @@ export function renderSequenceDiagram(
   }
   const getTagColor = (value: string | undefined): string | undefined =>
     value ? tagValueToColor.get(value.toLowerCase()) : undefined;
-  const tagKey = activeTagGroup?.toLowerCase();
+  const tagKey = activeTagGroup ? tagAttrKey(activeTagGroup) : undefined;
 
   // Build hidden message set for collapse support
   const hiddenMsgIndices = new Set<number>();
@@ -2008,11 +2014,7 @@ export function renderSequenceDiagram(
     const groupTagValue = tagKey && group.metadata?.[tagKey];
     const groupTagColor = getTagColor(groupTagValue || undefined);
     const fillColor = groupTagColor
-      ? mix(
-          groupTagColor,
-          themeBaseBg(palette, isDark),
-          isDark ? 15 : 20
-        )
+      ? mix(groupTagColor, themeBaseBg(palette, isDark), isDark ? 15 : 20)
       : isDark
         ? palette.surface
         : palette.bg;
@@ -2137,11 +2139,7 @@ export function renderSequenceDiagram(
 
       // Overlay a taller rect to replace the standard participant box
       const pFill = effectiveTagColor
-        ? mix(
-            effectiveTagColor,
-            themeBaseBg(palette, isDark),
-            isDark ? 30 : 40
-          )
+        ? mix(effectiveTagColor, themeBaseBg(palette, isDark), isDark ? 30 : 40)
         : isDark
           ? mix(palette.overlay, palette.surface, 50)
           : mix(palette.bg, palette.surface, 50);

package/src/sequence/tag-resolution.ts

@@ -5,6 +5,7 @@
 // Resolves effective tag values for participants and messages
 // using the priority chain: explicit > group > receiver-inherit > default > neutral
 
+import { tagAttrKey } from '../utils/tag-groups';
 import type {
   ParsedSequenceDgmo,
   SequenceParticipant,
@@ -116,7 +117,7 @@ export function resolveSequenceTags(
     return result;
   }
 
-  const groupKey = group.name.toLowerCase();
+  const groupKey = tagAttrKey(group.name);
 
   // Clone participant metadata (don't mutate parsed data)
   const participantMeta = new Map<string, Record<string, string>>();

package/src/sitemap/layout.ts

@@ -2,6 +2,7 @@
 // Sitemap Diagram Layout Engine (Dagre flat graph)
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import dagre from '@dagrejs/dagre';
 import type { Writable } from '../utils/brand';
 import type { ParsedSitemap, SitemapNode } from './types';
@@ -232,7 +233,7 @@ function computeLegendGroups(
   for (const group of tagGroups) {
     if (group.entries.length === 0) continue;
 
-    const usedValues = usedValuesByGroup?.get(group.name.toLowerCase());
+    const usedValues = usedValuesByGroup?.get(tagAttrKey(group.name));
     const visibleEntries = usedValues
       ? group.entries.filter((e) => usedValues.has(e.value.toLowerCase()))
       : group.entries;
@@ -866,7 +867,7 @@ export function layoutSitemap(
   // Collect used tag values
   const usedValuesByGroup = new Map<string, Set<string>>();
   for (const group of parsed.tagGroups) {
-    const key = group.name.toLowerCase();
+    const key = tagAttrKey(group.name);
     const used = new Set<string>();
     const walk = (node: SitemapNode) => {
       if (!node.isContainer && node.metadata[key]) {

package/src/sitemap/parser.ts

@@ -29,6 +29,7 @@ import {
   stripDefaultModifier,
   finalizeAutoTagColors,
   AUTO_TAG_COLOR_SENTINEL,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import {
   measureIndent,
@@ -273,12 +274,12 @@ export function parseSitemap(
       if (tagBlockMatch.alias) {
         metaAliasMap.set(
           normalizeName(tagBlockMatch.alias),
-          tagBlockMatch.name.toLowerCase()
+          tagAttrKey(tagBlockMatch.name)
         );
       }
       metaAliasMap.set(
         normalizeName(tagBlockMatch.name),
-        tagBlockMatch.name.toLowerCase()
+        tagAttrKey(tagBlockMatch.name)
       );
       result.tagGroups.push(newTagGroup);
       continue;
@@ -501,6 +502,16 @@ export function parseSitemap(
         }
       }
 
+      // §12: reject sub-pages nested under a page inside a container.
+      const enclosingContainer = nestedPageInsideContainer(indent, indentStack);
+      if (enclosingContainer) {
+        pushError(
+          lineNumber,
+          `Pages inside container '[${enclosingContainer}]' cannot have indented sub-pages. Containers hold a flat list of pages.`
+        );
+        continue;
+      }
+
       // Node label — possibly with pipe-delimited metadata
       const node = parseNodeLabel(
         trimmed,
@@ -702,6 +713,29 @@ function attachNode(
   indentStack.push({ node, indent });
 }
 
+/**
+ * §12: containers hold a flat list of pages — a page inside a `[Container]`
+ * may not have indented sub-pages. Returns the enclosing container's label
+ * when attaching a page at `indent` would nest it under a page that itself
+ * lives inside a container; otherwise null. Non-destructive (mirrors
+ * `attachNode`'s pop logic without mutating the stack).
+ */
+function nestedPageInsideContainer(
+  indent: number,
+  indentStack: { node: Writable<SitemapNode>; indent: number }[]
+): string | null {
+  let idx = indentStack.length - 1;
+  while (idx >= 0 && indentStack[idx]!.indent >= indent) idx--;
+  if (idx < 0) return null;
+  // Immediate parent. A container parent → flat member, allowed.
+  if (indentStack[idx]!.node.isContainer) return null;
+  // Parent is a page; flag only when an ancestor is a container.
+  for (let k = idx - 1; k >= 0; k--) {
+    if (indentStack[k]!.node.isContainer) return indentStack[k]!.node.label;
+  }
+  return null;
+}
+
 function findParentNode(
   indent: number,
   indentStack: { node: Writable<SitemapNode>; indent: number }[]

package/src/sitemap/renderer.ts

@@ -2,11 +2,17 @@
 // Sitemap Diagram SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
+import {
+  contrastText,
+  mix,
+  shapeFill,
+  themeBaseBg,
+} from '../palettes/color-utils';
 import type { ParsedSitemap } from './types';
 import type { SitemapLayoutResult, SitemapLegendGroup } from './layout';
 import { renderInlineText } from '../utils/inline-markdown';
@@ -284,10 +290,10 @@ export function renderSitemap(
   // tagColors: "groupkey:valueLower" → hex color
   const tagColors = new Map<string, string>();
   for (const group of parsed.tagGroups) {
-    displayNames.set(group.name.toLowerCase(), group.name);
+    displayNames.set(tagAttrKey(group.name), group.name);
     for (const entry of group.entries) {
       tagColors.set(
-        `${group.name.toLowerCase()}:${entry.value.toLowerCase()}`,
+        `${tagAttrKey(group.name)}:${entry.value.toLowerCase()}`,
         entry.color
       );
     }
@@ -317,7 +323,7 @@ export function renderSitemap(
 
     // Tag metadata for legend hover dimming
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const tagVal = c.tagMetadata[tagKey];
       if (tagVal) cG.attr(`data-tag-${tagKey}`, tagVal.toLowerCase());
     }
@@ -486,7 +492,7 @@ export function renderSitemap(
 
     // Tag metadata for legend hover dimming
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const tagVal = node.tagMetadata[tagKey];
       if (tagVal) nodeG.attr(`data-tag-${tagKey}`, tagVal.toLowerCase());
     }
@@ -721,7 +727,7 @@ function renderLegend(
     const computedLayout = legendHandle.getLayout();
     if (computedLayout.activeCapsule?.addonX != null) {
       const capsule = computedLayout.activeCapsule;
-      const groupKey = capsule.groupName.toLowerCase();
+      const groupKey = tagAttrKey(capsule.groupName);
       const isHidden = hiddenAttributes?.has(groupKey) ?? false;
 
       const activeGroupEl = parent.select(`[data-legend-group="${groupKey}"]`);

package/src/timeline/renderer.ts

@@ -2,6 +2,7 @@
 // Timeline renderer — Story 109.2 (arch-review). Extracted from d3.ts.
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Scale from 'd3-scale';
 import * as d3Selection from 'd3-selection';
 import { FONT_FAMILY } from '../fonts';
@@ -820,7 +821,7 @@ function setupTimeline(
   let tagLanes: Lane[] | null = null;
 
   if (resolvedSwimlaneTG) {
-    const tagKey = resolvedSwimlaneTG.toLowerCase();
+    const tagKey = tagAttrKey(resolvedSwimlaneTG);
     const tagGroup = parsed.timelineTagGroups.find(
       (g) => g.name.toLowerCase() === tagKey
     );
@@ -1322,7 +1323,7 @@ function renderTimelineTagLegendOverlay(
               onTagStateChange?.(currentActiveGroup, currentSwimlaneGroup);
             },
             onEntryHover: (groupName, entryValue) => {
-              const tagKey = groupName.toLowerCase();
+              const tagKey = tagAttrKey(groupName);
               if (entryValue) {
                 const tagVal = entryValue.toLowerCase();
                 fadeToTagValue(mainG, tagKey, tagVal);
@@ -1349,7 +1350,7 @@ function renderTimelineTagLegendOverlay(
               }
             },
             onGroupRendered: (groupName, groupEl, isActive) => {
-              const groupKey = groupName.toLowerCase();
+              const groupKey = tagAttrKey(groupName);
               groupEl.attr('data-tag-group', groupKey);
               if (isActive && !viewMode) {
                 const isSwimActive =

package/src/utils/legend-d3.ts

@@ -3,6 +3,7 @@
 // Thin adapter: layout engine → D3 DOM
 // ============================================================
 
+import { tagAttrKey } from './tag-groups';
 import {
   LEGEND_HEIGHT,
   LEGEND_PILL_FONT_SIZE,
@@ -164,7 +165,7 @@ function renderCapsule(
   const g = parent
     .append('g')
     .attr('transform', `translate(${capsule.x},${capsule.y})`)
-    .attr('data-legend-group', capsule.groupName.toLowerCase())
+    .attr('data-legend-group', tagAttrKey(capsule.groupName))
     .style('cursor', 'pointer');
 
   // Outer capsule background
@@ -211,7 +212,7 @@ function renderCapsule(
   // Continuous ramp (choropleth group): min | gradient | max, in place of dots.
   if (capsule.gradient) {
     const gr = capsule.gradient;
-    const gradId = `dgmo-legend-ramp-${capsule.groupName.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+    const gradId = `dgmo-legend-ramp-${tagAttrKey(capsule.groupName).replace(/[^a-z0-9]+/g, '-')}`;
     const def = g.append('defs').append('linearGradient').attr('id', gradId);
     // Sample the SAME ramp the fills use (direct = 2 endpoints; diverging =
     // stops through the neutral midpoint), so the legend matches the basemap.
@@ -318,7 +319,7 @@ function renderPill(
   const g = parent
     .append('g')
     .attr('transform', `translate(${pill.x},${pill.y})`)
-    .attr('data-legend-group', pill.groupName.toLowerCase())
+    .attr('data-legend-group', tagAttrKey(pill.groupName))
     .style('cursor', 'pointer');
 
   g.append('rect')

package/src/utils/legend-svg.ts

@@ -12,6 +12,7 @@
 // (not dominant-baseline) so resvg renders it correctly in PNG export.
 // ============================================================
 
+import { tagAttrKey } from './tag-groups';
 import type {
   LegendConfig,
   LegendState,
@@ -99,7 +100,7 @@ function emitCapsule(
     );
   }
 
-  return `<g transform="translate(${capsule.x},${capsule.y})" data-legend-group="${esc(capsule.groupName.toLowerCase())}" style="cursor:pointer">${inner.join('')}</g>`;
+  return `<g transform="translate(${capsule.x},${capsule.y})" data-legend-group="${esc(tagAttrKey(capsule.groupName))}" style="cursor:pointer">${inner.join('')}</g>`;
 }
 
 /** Collapsed group pill (no active group) → SVG string. */
@@ -109,7 +110,7 @@ function emitPill(
   groupBg: string
 ): string {
   return (
-    `<g transform="translate(${pill.x},${pill.y})" data-legend-group="${esc(pill.groupName.toLowerCase())}" style="cursor:pointer">` +
+    `<g transform="translate(${pill.x},${pill.y})" data-legend-group="${esc(tagAttrKey(pill.groupName))}" style="cursor:pointer">` +
     `<rect width="${pill.width}" height="${pill.height}" rx="${pill.height / 2}" fill="${esc(groupBg)}"/>` +
     `<text x="${pill.width / 2}" y="${pill.height / 2 + LEGEND_PILL_FONT_SIZE / 2 - 2}" font-size="${LEGEND_PILL_FONT_SIZE}" font-weight="500" fill="${esc(palette.textMuted)}" text-anchor="middle" font-family="${esc(FONT_FAMILY)}">${esc(pill.groupName)}</text>` +
     `</g>`