@diagrammo/dgmo 0.34.0 → 0.36.0

package/dist/index.js

@@ -35,6 +35,17 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 function makeDgmoError(line11, message, severity = "error", code) {
   return code !== void 0 ? { line: line11, message, severity, code } : { line: line11, message, severity };
 }
+function dedupeDiagnostics(diagnostics) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const d of diagnostics) {
+    const key = `${d.line}\0${d.column ?? ""}\0${d.severity}\0${d.code ?? ""}\0${d.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(d);
+  }
+  return out;
+}
 function formatDgmoError(err) {
   return err.line > 0 ? `Line ${err.line}: ${err.message}` : err.message;
 }
@@ -92,7 +103,7 @@ function vennAliasKeywordRemovedMessage(args) {
   return `Venn 'alias' keyword was removed. Use 'as' instead \u2014 '${args.name} as ${args.alias}'.`;
 }
 function pipeOperatorRemovedMessage() {
-  return `'|' removed \u2014 'Node | c: red' \u2192 'Node c: red'. Run 'dgmo migrate'`;
+  return `'|' removed \u2014 'Node | c: red' \u2192 'Node c: red'`;
 }
 function ganttBarePercentRemovedMessage(percent) {
   return `Bare-percent progress shorthand '| ${percent}' was removed. Use 'progress: ${percent.replace(/%$/, "")}' (integer 0\u2013100, no '%').`;
@@ -1148,7 +1159,7 @@ var init_parsing = __esm({
       "no-title",
       "no-notes"
     ]);
-    MULTIPLE_PIPE_ERROR = 'Use a single "|" to start metadata, then separate items with commas.';
+    MULTIPLE_PIPE_ERROR = "'|' is no longer metadata syntax \u2014 put metadata on the same line as 'key: value, key2: value2' (no pipes), per \xA71.4.";
     RESERVED_KEY_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
     AS_ALIAS_RE = /\s+as\s+([A-Za-z][A-Za-z0-9_]{0,11})$/;
     POTENTIAL_META_RE = /\b([\w-]+)\s*:/;
@@ -1329,12 +1340,10 @@ function validateTagValues(entities, tagGroups, pushWarning, suggestFn) {
         );
         if (!isPrefix) {
           const defined = group.entries.map((e) => e.value);
-          let msg = `Unknown value '${value}' for tag group '${group.name}'`;
+          let msg = `Unknown value '${value}' for tag group '${group.name}' \u2014 use one of: ${defined.join(", ")}`;
           const hint = suggestFn?.(value, defined);
           if (hint) {
             msg += `. ${hint}`;
-          } else {
-            msg += ` \u2014 defined values: ${defined.join(", ")}`;
           }
           pushWarning(entity.lineNumber, msg);
         }
@@ -2110,7 +2119,10 @@ function parseVisualizationFull(content, palette) {
             lineNumber
           });
         } else {
-          warn(lineNumber, `Unrecognized era entry: "${line11}"`);
+          warn(
+            lineNumber,
+            `Unrecognized era entry: "${line11}" \u2014 use '<start> -> <end> Label [color]' (e.g. '1716 -> 1717 Reign').`
+          );
         }
         continue;
       }
@@ -2138,7 +2150,10 @@ function parseVisualizationFull(content, palette) {
             lineNumber
           });
         } else {
-          warn(lineNumber, `Unrecognized marker entry: "${line11}"`);
+          warn(
+            lineNumber,
+            `Unrecognized marker entry: "${line11}" \u2014 use '<date> Label [color]' (e.g. '1776 Independence').`
+          );
         }
         continue;
       }
@@ -2816,7 +2831,7 @@ function parseVisualizationFull(content, palette) {
           result.diagnostics.push(
             makeDgmoError(
               ov.lineNumber,
-              `Intersection references unknown set or alias "${ref}"`
+              `Intersection references unknown set or alias "${ref}" \u2014 declare the set first on its own line ('Name [as <alias>] [color]', e.g. 'Navigation as nav blue'), then reference it by that name or alias. (\xA716.4)`
             )
           );
           if (!result.error)
@@ -6260,10 +6275,10 @@ function parseSequenceDgmo(content, palette) {
         const rawInside = fallbackMatch[1];
         const pipeIdx = rawInside.indexOf("|");
         const cleanName = rawInside.substring(0, pipeIdx).trim().replace(/\([^)]*\)$/, "").trim();
-        const metaPart = rawInside.substring(pipeIdx).trim();
+        const metaPart = rawInside.substring(pipeIdx).replace(/^\|\s*/, "").trim();
         pushError(
           lineNumber,
-          `Pipe metadata must go outside brackets \u2014 use '[${cleanName}] ${metaPart}' instead of '[${rawInside.trim()}]'`
+          `Metadata goes after the bracket with no pipe \u2014 use '[${cleanName}] ${metaPart}' (e.g. '[Backend] t: Product'), not '[${rawInside.trim()}]'`
         );
         continue;
       }
@@ -6873,7 +6888,7 @@ function parseSequenceDgmo(content, palette) {
     }
     pushWarning(
       lineNumber,
-      `Unexpected line: '${trimmed}'. Expected a message (A -> B), participant, section (== Name ==), or block keyword (if/loop/parallel).`
+      `Unexpected line: '${trimmed}'. Expected a message ('A -> B' or 'A -label-> B'), participant ('Name' or 'Name is a actor'), note ('note right of A Text'), section ('== Name =='), or block ('if/loop/parallel <label>').`
     );
   }
   if (!hasExplicitChart && result.messages.length === 0) {
@@ -8035,7 +8050,11 @@ function parseFlowchart(content, palette) {
         const value = optMatch[2].trim();
         if (key === "no-color") {
           result.diagnostics.push(
-            makeDgmoError(lineNumber, '"no-color" has been removed.', "warning")
+            makeDgmoError(
+              lineNumber,
+              '"no-color" was removed \u2014 node colors are assigned automatically by shape; delete this line.',
+              "warning"
+            )
           );
           continue;
         }
@@ -8364,7 +8383,11 @@ function parseState(content, palette) {
         const value = optMatch[2].trim();
         if (key === "no-color") {
           result.diagnostics.push(
-            makeDgmoError(lineNumber, '"no-color" has been removed.', "warning")
+            makeDgmoError(
+              lineNumber,
+              '"no-color" was removed \u2014 state colors are assigned automatically; delete this line.',
+              "warning"
+            )
           );
           continue;
         }
@@ -8679,7 +8702,7 @@ function parseClassDiagram(content, palette) {
         result.diagnostics.push(
           makeDgmoError(
             lineNumber,
-            '"no-auto-color" has been removed.',
+            '"no-auto-color" was removed \u2014 colors are always auto-assigned from the palette; delete this line.',
             "warning"
           )
         );
@@ -8794,7 +8817,11 @@ function parseClassDiagram(content, palette) {
       continue;
     }
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, "warning")
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. Classes start uppercase at indent 0 ('Ship'); members are indented and colon-typed ('+ name: string', '+ sail(): void'); relationships are indented arrows ('--|> Vessel'). (\xA710)`,
+        "warning"
+      )
     );
   }
   if (notes.length > 0) {
@@ -9272,7 +9299,11 @@ function parseERDiagram(content, palette) {
       continue;
     }
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, "warning")
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. A table is a bare name at indent 0 ('users'); columns are indented and SPACE-separated, no colon ('id int pk'); relationships are indented ('1--* orders'). (\xA79)`,
+        "warning"
+      )
     );
   }
   if (result.tables.length === 0 && !result.error) {
@@ -9616,7 +9647,10 @@ function parseOrg(content, palette) {
       const value = metadataMatch[2].trim();
       const parent = findMetadataParent(indent, indentStack);
       if (!parent) {
-        pushError(lineNumber, "Metadata has no parent node");
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a node \u2014 no node precedes it."
+        );
       } else {
         parent.metadata = { ...parent.metadata, [key]: value };
       }
@@ -9634,7 +9668,10 @@ function parseOrg(content, palette) {
         );
         attachNode(node, indent, indentStack, result);
       } else {
-        pushError(lineNumber, "Metadata has no parent node");
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a node \u2014 no node precedes it."
+        );
       }
     } else {
       const node = parseNodeLabel(
@@ -9983,7 +10020,10 @@ function parseSitemap(content, palette) {
     if (arrowInfo) {
       const source = findParentNode(indent, indentStack);
       if (!source) {
-        pushError(lineNumber, "Arrow has no source node");
+        pushError(
+          lineNumber,
+          "Arrow '-> target' must be indented under its source page \u2014 no page precedes it."
+        );
       } else {
         deferredArrows.push({
           sourceNode: source,
@@ -10053,7 +10093,10 @@ function parseSitemap(content, palette) {
       const value = metadataMatch[2].trim();
       const parent = findParentNode(indent, indentStack);
       if (!parent) {
-        pushError(lineNumber, "Metadata has no parent node");
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a page \u2014 no page precedes it."
+        );
       } else {
         parent.metadata = { ...parent.metadata, [key]: value };
       }
@@ -10073,7 +10116,10 @@ function parseSitemap(content, palette) {
         const key = normalizeName(node.label);
         labelToNode.set(key, node);
       } else {
-        pushError(lineNumber, "Metadata has no parent node");
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a page \u2014 no page precedes it."
+        );
       }
     } else {
       const descResult = tryStripDescriptionKeyword(trimmed);
@@ -11891,7 +11937,7 @@ function parseChart(content, palette) {
       result.diagnostics.push(
         makeDgmoError(
           lineNumber,
-          `'${trimmed}' \u2014 ## syntax is no longer supported. Use [Group] containers instead`
+          `'${trimmed}' removed \u2014 use a bracket container '[${trimmed.replace(/^#+\s*/, "")}]' instead (## headers are no longer supported).`
         )
       );
       continue;
@@ -12870,7 +12916,11 @@ function parseExtendedChartFull(content, palette) {
       continue;
     }
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, "warning")
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. Expected a data row ('Label value', space-separated) or a known option.`,
+        "warning"
+      )
     );
   }
   const warn = (line11, message) => {
@@ -15228,7 +15278,10 @@ function parseKanban(content, palette) {
       continue;
     }
     if (!currentColumn) {
-      warn(lineNumber, "Card line found before any column");
+      warn(
+        lineNumber,
+        "Card line found before any column. Declare a column first with '[Column Name]', then indent cards beneath it. (\xA711)"
+      );
       continue;
     }
     if (currentCard && indent > cardBaseIndent) {
@@ -15367,7 +15420,7 @@ var init_parser13 = __esm({
     KNOWN_OPTIONS4 = /* @__PURE__ */ new Set(["hide", "active-tag"]);
     KNOWN_BOOLEANS3 = /* @__PURE__ */ new Set(["solid-fill", "no-title"]);
     REMOVED_BOOLEANS = {
-      "no-auto-color": '"no-auto-color" has been removed.'
+      "no-auto-color": '"no-auto-color" was removed \u2014 colors are always auto-assigned from the palette; delete this line.'
     };
   }
 });
@@ -15604,7 +15657,7 @@ function parseC4(content, palette) {
           } else {
             pushError(
               lineNumber,
-              `"container ${refName}" must be inside a deployment node`
+              `"container ${refName}" must be indented under a deployment node (e.g. under 'Prod is a deployment-node')`
             );
           }
           continue;
@@ -15659,7 +15712,10 @@ function parseC4(content, palette) {
           indent
         });
       } else {
-        pushError(lineNumber, `"${sectionType}" must be inside an element`);
+        pushError(
+          lineNumber,
+          `"${sectionType}" must be indented under an element (e.g. under 'Web App is a container')`
+        );
       }
       continue;
     }
@@ -15686,7 +15742,10 @@ function parseC4(content, palette) {
           indent
         });
       } else {
-        pushError(lineNumber, `Group [${groupName}] must be inside an element`);
+        pushError(
+          lineNumber,
+          `Group [${groupName}] must be indented under an element (e.g. under 'Web App is a container')`
+        );
       }
       continue;
     }
@@ -16016,7 +16075,10 @@ function parseC4(content, palette) {
       }
       desc.push(descResult.text);
     } else {
-      pushError(lineNumber, `Unexpected content: "${trimmed}"`);
+      pushError(
+        lineNumber,
+        `Unexpected content: "${trimmed}". Expected an element ('Web App is a container'), a relationship ('-Uses-> Database'), indented metadata ('tech: React'), or a group ('[Backend]'). (\xA78)`
+      );
     }
   }
   finalizeAutoTagColors(result.tagGroups, palette);
@@ -16078,7 +16140,7 @@ function validateRelationshipTargets(result, knownNames, pushWarning) {
     for (const el of elements) {
       for (const rel of el.relationships) {
         if (!knownNames.has(normalizeName(rel.target))) {
-          let msg = `Relationship target "${rel.target}" not found`;
+          let msg = `Relationship target "${rel.target}" not found \u2014 declare it first (e.g. '${rel.target} is a container'), then reference it in the arrow`;
           const hint = suggest(normalizeName(rel.target), allNames);
           if (hint) msg += `. ${hint}`;
           pushWarning(rel.lineNumber, msg, "warning");
@@ -16106,7 +16168,7 @@ function validateDeploymentRefs(result, knownNames, pushWarning) {
     for (const node of nodes) {
       for (const ref of node.containerRefs) {
         if (!knownNames.has(normalizeName(ref))) {
-          let msg = `Deployment reference "container ${ref}" not found`;
+          let msg = `Deployment reference "container ${ref}" not found \u2014 declare the container element first, then reference it under the deployment node`;
           const hint = suggest(normalizeName(ref), allNames);
           if (hint) msg += `. ${hint}`;
           pushWarning(node.lineNumber, msg, "warning");
@@ -16825,7 +16887,7 @@ function parseInfra(content) {
       }
       warn(
         lineNumber,
-        `Invalid tag value '${trimmed}' in tag group '${currentTagGroup.name}'.`
+        `Invalid tag value '${trimmed}' in tag group '${currentTagGroup.name}' \u2014 a value is a bare word with an optional trailing color (e.g. 'Production red'); no ':' or '|'.`
       );
       continue;
     }
@@ -16898,7 +16960,7 @@ function parseInfra(content) {
         const n = deprecatedFanout[1];
         setError(
           lineNumber,
-          `'x${n}' fanout syntax is no longer supported \u2014 use '| fanout: ${n}' instead`
+          `'x${n}' fanout syntax is no longer supported \u2014 use 'fanout: ${n}' instead`
         );
         continue;
       }
@@ -17072,8 +17134,10 @@ function parseInfra(content) {
           const hint = suggest(key, allKeys);
           const valueLooksNumeric = /^[\d.]+%?$/.test(rawVal);
           if (hint || valueLooksNumeric) {
-            let msg = `Unknown property '${key}'.`;
+            let msg = `Unknown infra property '${key}'.`;
             if (hint) msg += ` ${hint}`;
+            else
+              msg += ` Properties are colon-keyed 'key: value' from the known schema (e.g. latency-ms, max-rps, cache-hit, instances, concurrency).`;
             warn(lineNumber, msg);
           } else if (!currentNode.isEdge) {
             pushDescription(currentNode, trimmed);
@@ -17084,7 +17148,7 @@ function parseInfra(content) {
         if (EDGE_ONLY_KEYS.has(key) && !currentNode.isEdge) {
           warn(
             lineNumber,
-            `Property '${key}' is only valid on the entry point (Edge/Internet).`
+            `Property '${key}' belongs on the entry point \u2014 declare it indented under an 'internet' or 'edge' node, not on '${currentNode.label}'.`
           );
         }
         const value = parsePropertyValue(rawVal);
@@ -17191,7 +17255,7 @@ function parseInfra(content) {
     }
     warn(
       lineNumber,
-      currentGroup ? `Unexpected line: '${trimmed}'. Expected an indented component name.` : `Unexpected line: '${trimmed}'. Expected a component name, [Group Name], tag group, or option.`
+      currentGroup ? `Unexpected line: '${trimmed}'. Inside a group, indent a component name under the '[Group]'.` : `Unexpected line: '${trimmed}'. Expected a node ('Api Gateway'), a group ('[Backend]'), a tag group ('tag Tier as t'), or an option ('default-rps 100'); node properties go indented under a node as 'key: value'.`
     );
   }
   finishCurrentNode();
@@ -17567,7 +17631,10 @@ function parseGantt(content, palette) {
           continue;
         }
         if (COMMENT_RE.test(line11)) continue;
-        warn(lineNumber, `Unrecognized holiday entry: "${line11}"`);
+        warn(
+          lineNumber,
+          `Unrecognized holiday entry: "${line11}". Use a date '2024-02-19 Presidents Day' or a range '2024-05-27 -> 2024-05-29 Memorial Weekend'. (\xA713.3)`
+        );
         continue;
       }
     }
@@ -17593,7 +17660,10 @@ function parseGantt(content, palette) {
             lineNumber
           });
         } else {
-          warn(lineNumber, `Unrecognized era entry: "${line11}"`);
+          warn(
+            lineNumber,
+            `Unrecognized era entry: "${line11}". Use 'YYYY-MM-DD -> YYYY-MM-DD Label [color]' (e.g. '2026-04-06 -> 2026-04-10 Conference purple'). (\xA713.5)`
+          );
         }
         continue;
       }
@@ -17619,7 +17689,10 @@ function parseGantt(content, palette) {
             lineNumber
           });
         } else {
-          warn(lineNumber, `Unrecognized marker entry: "${line11}"`);
+          warn(
+            lineNumber,
+            `Unrecognized marker entry: "${line11}". Use 'YYYY-MM-DD Label [color]' (e.g. '2026-03-27 Board Review' or '2026-06-15 Release green'). (\xA713.6)`
+          );
         }
         continue;
       }
@@ -17785,7 +17858,7 @@ function parseGantt(content, palette) {
           } else {
             softError(
               lineNumber,
-              `Arrow reference "${content2.name}" has no parent task context.`
+              `Arrow '-> ${content2.name}' has no source task \u2014 indent it under the task it follows (e.g. 'Design 5bd' then indented '-> ${content2.name} 3bd'). (\xA713)`
             );
           }
         }
@@ -19005,7 +19078,10 @@ function parseMap(content, palette) {
   function handleTag(trimmed, line11) {
     const m = matchTagBlockHeading(trimmed);
     if (!m) {
-      pushError(line11, `Malformed tag declaration: "${trimmed}".`);
+      pushError(
+        line11,
+        `Malformed tag declaration: "${trimmed}" \u2014 write 'tag <Group>' (optionally 'tag <Group> as <alias>'), e.g. 'tag Market as m', with indented 'Value color' entries below.`
+      );
       return;
     }
     emitTagLegacyDiagnostic(m, line11, diagnostics);
@@ -19117,7 +19193,7 @@ function parseMap(content, palette) {
     if (!pos || pos.kind === "name" && !pos.name) {
       pushError(
         line11,
-        "route requires an origin: `route <origin> [style: arc]`."
+        "route needs an origin place \u2014 `route <origin>` then indented legs (`-> dest`); origin may be a city name, IATA code, or `<lat> <lon>`. (\xA724B)"
       );
       return;
     }
@@ -19180,7 +19256,10 @@ function parseMap(content, palette) {
   function handleEdges(trimmed, line11) {
     const parts = trimmed.split(ARROW_SPLIT);
     if (parts.length < 3) {
-      pushError(line11, `Malformed edge: "${trimmed}".`);
+      pushError(
+        line11,
+        `Malformed edge: "${trimmed}" \u2014 an edge is 'A -> B' (or 'A -label-> B', '~>' for arc, '--' undirected), both endpoints non-empty. (\xA724B)`
+      );
       return;
     }
     const endpoints = [];
@@ -19203,7 +19282,10 @@ function parseMap(content, palette) {
       const from = endpoints[k];
       const to = endpoints[k + 1];
       if (!from || !to) {
-        pushError(line11, `Edge has an empty endpoint: "${trimmed}".`);
+        pushError(
+          line11,
+          `Edge has an empty endpoint: "${trimmed}" \u2014 both sides of the arrow need a place, e.g. 'Paris -> Berlin'. (\xA724B)`
+        );
         continue;
       }
       const isLast = k === links.length - 1;
@@ -21322,7 +21404,10 @@ function parseTechRadar(content) {
     }
     if (indent === 0 && trimmed.toLowerCase() === "rings") {
       if (result.rings.length > 0) {
-        warn(lineNumber, 'Duplicate "rings" block \u2014 using last one');
+        warn(
+          lineNumber,
+          'Duplicate "rings" block \u2014 only the last is kept; merge all ring names into one "rings" block.'
+        );
         result.rings = [];
       }
       inRingsBlock = true;
@@ -21541,7 +21626,7 @@ function parseTechRadar(content) {
       result.diagnostics.push(
         makeDgmoError(
           lineNumber,
-          `Blip "${trimmed}" has no ring assignment. Place it under a ring section header or use: ${trimmed} | ring: RingName`
+          `Blip "${trimmed}" has no ring. Put it under a ring section header, or add a colon-keyed ring \u2014 '${trimmed} ring: RingName' (per \xA720).`
         )
       );
       continue;
@@ -21550,7 +21635,7 @@ function parseTechRadar(content) {
       if (!trimmed.includes("|") && headerParsed && result.rings.length > 0) {
         warn(
           lineNumber,
-          `Unrecognized line "${trimmed}". Quadrant headers require pipe metadata: ${trimmed} | quadrant: top-left`
+          `Unrecognized line "${trimmed}". A quadrant header is 'Name quadrant: <top-left|top-right|bottom-left|bottom-right>' (per \xA720).`
         );
       }
     }
@@ -21843,7 +21928,10 @@ function parseCycle(content) {
         currentNode.description.push(descLine);
         continue;
       }
-      warn(lineNum, `Unexpected indented line: "${trimmed}".`);
+      warn(
+        lineNum,
+        `Indented line "${trimmed}" has no step above it \u2014 add a step on a non-indented line first, then indent its details. (\xA721)`
+      );
       continue;
     }
   }
@@ -22146,7 +22234,7 @@ function parseJourneyMap(content, palette) {
       if (trimmed.includes("|") || !PHASE_RE.test(trimmed)) {
         warn(
           lineNumber,
-          "Steps outside phases will be ignored when phases are present"
+          `Step "${trimmed}" sits outside any phase and is ignored \u2014 indent it under a '[Phase]' header (per \xA722).`
         );
         continue;
       }
@@ -22203,7 +22291,10 @@ function parseJourneyMap(content, palette) {
       continue;
     }
     if (indent > 0 && !currentPhase && hasPhases) {
-      warn(lineNumber, `Unexpected indented line outside of a phase`);
+      warn(
+        lineNumber,
+        `Indented line outside any phase \u2014 add a '[Phase]' header above it, or unindent it to a top-level step. (\xA722)`
+      );
     }
   }
   if (currentStep) {
@@ -22549,7 +22640,10 @@ function parsePyramid(content) {
       continue;
     }
     if (!currentLayer) {
-      warn(lineNum, `Unexpected indented line: "${trimmed}".`);
+      warn(
+        lineNum,
+        `Indented description "${trimmed}" has no layer above it \u2014 add a layer name on a non-indented line first. (\xA723)`
+      );
       continue;
     }
     const descLine = trimmed.startsWith("- ") ? `\u2022 ${trimmed.substring(2)}` : trimmed;
@@ -22723,7 +22817,10 @@ function parseRing(content) {
       continue;
     }
     if (!currentLayer) {
-      warn(lineNum, `Unexpected indented line: "${trimmed}".`);
+      warn(
+        lineNum,
+        `Indented description "${trimmed}" has no layer above it \u2014 add a layer name on a non-indented line first. (\xA724)`
+      );
       continue;
     }
     const descLine = trimmed.startsWith("- ") ? `\u2022 ${trimmed.substring(2)}` : trimmed;
@@ -23449,7 +23546,10 @@ function parseRaci(content, palette) {
       continue;
     }
     if (bodyStarted) {
-      errorAt(lineNumber, `Unexpected line: '${trimmed}'.`);
+      errorAt(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. In the body expect a '[Phase]' header, an indented task name, or an assignment 'Role: A R C I' under a task. (\xA724A)`
+      );
     } else {
       warn(lineNumber, `Unrecognized directive: '${trimmed}'.`);
     }
@@ -23996,6 +24096,13 @@ function getAllChartTypes() {
   return chartTypes.map((c) => c.id);
 }
 function parseDgmo(content) {
+  const result = parseDgmoUndeduped(content);
+  return {
+    diagnostics: dedupeDiagnostics(result.diagnostics),
+    chartType: result.chartType
+  };
+}
+function parseDgmoUndeduped(content) {
   const chartType = parseDgmoChartType(content);
   if (!chartType) {
     const colonDiag = detectColonChartType(content);
@@ -51323,7 +51430,7 @@ function resolveMap(parsed, data) {
       const hint = suggest(r.name, allNames);
       err(
         r.lineNumber,
-        `Unknown subdivision "${r.name}".${hint ? " " + hint : ""}`,
+        `Unknown region "${r.name}" \u2014 not a known country or US state.${hint ? " " + hint : ""} Search the exact token with \`dgmo map-search "${r.name}"\` (or the lookup_map_location tool), use an ISO code (e.g. FR, US-CA), or coordinates.`,
         "E_MAP_UNKNOWN_SUBDIVISION"
       );
       continue;
@@ -51403,7 +51510,7 @@ function resolveMap(parsed, data) {
       const hint = suggest(name, cityNames);
       err(
         line11,
-        `Unknown place "${name}" (not in the gazetteer; use coordinates).${hint ? " " + hint : ""}`,
+        `Unknown place "${name}" \u2014 not in the gazetteer.${hint ? " " + hint : ""} Search the exact token with \`dgmo map-search "${name}"\` (or the lookup_map_location tool), or use coordinates \`poi <lat> <lon>\`.`,
         "E_MAP_UNKNOWN_PLACE"
       );
       return { kind: "miss" };
@@ -51945,6 +52052,21 @@ function mapLegendBand(legend, opts) {
   if (height <= 0) return 0;
   return mapLegendTop(opts.hasTitle, opts.hasSubtitle) + height + LEGEND_BOTTOM_GAP2;
 }
+function mapLegendBox(legend, opts) {
+  if (!legend) return null;
+  const groups = mapLegendGroups(legend);
+  if (groups.length === 0) return null;
+  const config = mapLegendConfig(groups, opts.mode);
+  const state = { activeGroup: legend.activeGroup };
+  const { width, height } = computeLegendLayout(config, state, opts.width);
+  if (height <= 0 || width <= 0) return null;
+  return {
+    x: (opts.width - width) / 2,
+    y: mapLegendTop(opts.hasTitle, opts.hasSubtitle),
+    width,
+    height
+  };
+}
 var LEGEND_TOP_GAP2, LEGEND_BOTTOM_GAP2;
 var init_legend_band = __esm({
   "src/map/legend-band.ts"() {
@@ -52069,6 +52191,8 @@ function placeContextLabels(args) {
     waterBodies,
     countries,
     palette,
+    countryTone,
+    waterTone,
     project,
     collides,
     contentPoints,
@@ -52078,8 +52202,8 @@ function placeContextLabels(args) {
   const band = tierBand(Math.max(dLonSpan, dLatSpan));
   const budget = labelBudget(width, height, band);
   if (budget <= 0) return [];
-  const waterColor = mix(palette.colors.blue, palette.textMuted, 50);
-  const countryColor = palette.textMuted;
+  const waterColor = waterTone ?? mix(palette.colors.blue, palette.textMuted, 50);
+  const countryColor = countryTone ?? palette.textMuted;
   const haloColor = palette.bg;
   const candidates = [];
   const center = [width / 2, height / 2];
@@ -52168,8 +52292,7 @@ function placeContextLabels(args) {
       )
     );
     const fontSize = Math.round(FONT + t * (COUNTRY_FONT_MAX - FONT));
-    const fade = Math.round(t * COUNTRY_FADE_MAX);
-    const color = fade > 0 ? mix(countryColor, palette.bg, 100 - fade) : countryColor;
+    const color = countryColor;
     const text = c.name;
     const tw = labelWidth(text, 0, fontSize);
     if (tw > w || fontSize + 2 * PADY > h) continue;
@@ -52263,7 +52386,7 @@ function placeContextLabels(args) {
   }
   return placed;
 }
-var FONT, LINE_HEIGHT, PADX, PADY, WATER_LETTER_SPACING, CONTEXT_PAD, EDGE_CLAMP_MARGIN, EDGE_CLAMP_OVERSHOOT, COUNTRY_FONT_MAX, COUNTRY_SIZE_FRAC_MIN, COUNTRY_SIZE_FRAC_MAX, COUNTRY_FADE_MAX, MAX_COUNTRY_POSITIONS, COUNTRY_POS_GRID, COUNTRY_POS_TOPN_MARGIN, KIND_ORDER;
+var FONT, LINE_HEIGHT, PADX, PADY, WATER_LETTER_SPACING, CONTEXT_PAD, EDGE_CLAMP_MARGIN, EDGE_CLAMP_OVERSHOOT, COUNTRY_FONT_MAX, COUNTRY_SIZE_FRAC_MIN, COUNTRY_SIZE_FRAC_MAX, MAX_COUNTRY_POSITIONS, COUNTRY_POS_GRID, COUNTRY_POS_TOPN_MARGIN, KIND_ORDER;
 var init_context_labels = __esm({
   "src/map/context-labels.ts"() {
     "use strict";
@@ -52280,7 +52403,6 @@ var init_context_labels = __esm({
     COUNTRY_FONT_MAX = 22;
     COUNTRY_SIZE_FRAC_MIN = 0.06;
     COUNTRY_SIZE_FRAC_MAX = 0.32;
-    COUNTRY_FADE_MAX = 45;
     MAX_COUNTRY_POSITIONS = 4;
     COUNTRY_POS_GRID = 5;
     COUNTRY_POS_TOPN_MARGIN = 3;
@@ -52418,36 +52540,23 @@ function countryLabelPositions(args) {
     return n;
   };
   const dist2ToCentre = (c) => (c.sx - cx) ** 2 + (c.sy - cy) ** 2;
-  const pool = [...kept];
-  pool.sort((a, b) => {
-    const d = interiorness(b) - interiorness(a);
-    return d !== 0 ? d : dist2ToCentre(a) - dist2ToCentre(b);
-  });
-  const ordered = [pool.shift()];
-  while (ordered.length < MAX_COUNTRY_POSITIONS && pool.length) {
-    let bestIdx = 0;
-    let bestMin = -1;
-    for (let k = 0; k < pool.length; k++) {
-      const c = pool[k];
-      let minD = Infinity;
-      for (const o of ordered) {
-        const d = (c.sx - o.sx) ** 2 + (c.sy - o.sy) ** 2;
-        if (d < minD) minD = d;
-      }
-      if (minD > bestMin) {
-        bestMin = minD;
-        bestIdx = k;
-      }
+  const centreLon = kept.reduce((s, c) => s + c.lon, 0) / kept.length;
+  const centreLat = kept.reduce((s, c) => s + c.lat, 0) / kept.length;
+  const centreScreen = project(centreLon, centreLat);
+  const lead = pointInGeometry(geometry, centreLon, centreLat) && centreScreen && Number.isFinite(centreScreen[0]) && Number.isFinite(centreScreen[1]) && centreScreen[0] >= 0 && centreScreen[0] <= width && centreScreen[1] >= 0 && centreScreen[1] <= height ? [
+    {
+      lonLat: [centreLon, centreLat],
+      screen: [centreScreen[0], centreScreen[1]]
     }
-    ordered.push(pool.splice(bestIdx, 1)[0]);
-  }
-  const grid = ordered.map((c) => ({
+  ] : [];
+  const grid = [...kept].sort(
+    (a, b) => interiorness(b) - interiorness(a) || dist2ToCentre(a) - dist2ToCentre(b)
+  ).map((c) => ({
     lonLat: [c.lon, c.lat],
     screen: [c.sx, c.sy]
   }));
   const curatedPos = curated ? mkCurated(curated, project) : [];
-  const out = [...curatedPos, ...grid].slice(0, MAX_COUNTRY_POSITIONS);
-  return out;
+  return [...curatedPos, ...lead, ...grid].slice(0, MAX_COUNTRY_POSITIONS);
 }
 function mkCurated(curated, project) {
   if (!curated) return [];
@@ -52713,6 +52822,25 @@ function layoutMap(resolvedIn, data, size, opts) {
     palette.bg,
     mutedBasemap ? isDark ? MUTED_FOREIGN_DARK : MUTED_FOREIGN_LIGHT : isDark ? FOREIGN_TINT_DARK : FOREIGN_TINT_LIGHT
   );
+  const contrastFloorTone = (tone, ...substrates) => {
+    const clears = (t) => substrates.every((s) => contrastRatio(t, s) >= REGION_LABEL_HALO_RATIO);
+    if (clears(tone)) return tone;
+    for (let s = 10; s <= 100; s += 10) {
+      const t = mix(palette.text, tone, s);
+      if (clears(t)) return t;
+    }
+    return palette.text;
+  };
+  const backdropLandTone = contrastFloorTone(
+    palette.textMuted,
+    neutralFill,
+    water
+  );
+  const backdropWaterTone = contrastFloorTone(
+    mix(palette.colors.blue, palette.textMuted, 50),
+    water,
+    neutralFill
+  );
   const hasDirectColor = resolved.regions.some((r) => r.color !== void 0);
   const colorizeActive = resolved.directives.noColorize !== true && !hasRamp && !hasDirectColor && fillGroupNames.size === 0;
   const colorByIso = /* @__PURE__ */ new Map();
@@ -52827,6 +52955,33 @@ function layoutMap(resolvedIn, data, size, opts) {
     hasSubtitle: Boolean(resolved.subtitle)
   });
   if (legendBand > topPad) topPad = legendBand;
+  const topReserved = [];
+  if (shownTitle) {
+    const lines = resolved.subtitle ? 2 : 1;
+    const tw = Math.max(
+      measureLegendText(shownTitle, TITLE_FONT_SIZE),
+      resolved.subtitle ? measureLegendText(resolved.subtitle, TITLE_FONT_SIZE) : 0
+    ) + 2 * TITLE_FONT_SIZE;
+    topReserved.push({
+      x: width / 2 - tw / 2,
+      y: TITLE_Y - TITLE_FONT_SIZE,
+      w: tw,
+      h: TITLE_FONT_SIZE * (lines + 0.5)
+    });
+  }
+  const legendBox = mapLegendBox(legend, {
+    width,
+    mode: opts.legendMode ?? "preview",
+    hasTitle: Boolean(shownTitle),
+    hasSubtitle: Boolean(resolved.subtitle)
+  });
+  if (legendBox)
+    topReserved.push({
+      x: legendBox.x,
+      y: legendBox.y,
+      w: legendBox.width,
+      h: legendBox.height
+    });
   const reserve = opts._calloutReserve;
   const fitLeft = FIT_PAD + (reserve?.left ?? 0);
   const fitRight = width - FIT_PAD - (reserve?.right ?? 0);
@@ -53556,6 +53711,19 @@ function layoutMap(resolvedIn, data, size, opts) {
     const by = b.cy - (b.cy - py) / tb * trimB;
     return `M${ax},${ay}Q${px},${py} ${bx},${by}`;
   };
+  const legLabelPoint = (a, b, curved, offset) => {
+    const mx = (a.cx + b.cx) / 2;
+    const my = (a.cy + b.cy) / 2;
+    if (!curved && offset === 0) return { x: mx, y: my - 4 };
+    const dx = b.cx - a.cx;
+    const dy = b.cy - a.cy;
+    const len = Math.hypot(dx, dy) || 1;
+    const nx = -dy / len;
+    const ny = dx / len;
+    const bow = offset !== 0 ? offset : len * ARC_CURVE_FRAC;
+    const off = bow * 0.5 + Math.sign(bow || 1) * 8;
+    return { x: mx + nx * off, y: my + ny * off };
+  };
   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;
@@ -53569,13 +53737,12 @@ function layoutMap(resolvedIn, data, size, opts) {
       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;
+      const lp = legLabelPoint(a, b, leg.style === "arc", 0);
       const bow = {
         curved: leg.style === "arc",
         offset: 0,
-        labelX: mx,
-        labelY: my - 4
+        labelX: lp.x,
+        labelY: lp.y
       };
       const routeLabelStyle = leg.label !== void 0 ? labelOnFill(fillAt(bow.labelX, bow.labelY)) : void 0;
       legs.push({
@@ -53622,13 +53789,13 @@ function layoutMap(resolvedIn, data, size, opts) {
       const b = poiScreen.get(e.toId);
       if (!a || !b) return;
       const fanOffset = n > 1 ? (i - (n - 1) / 2) * FAN_STEP : 0;
-      const mx = (a.cx + b.cx) / 2;
-      const my = (a.cy + b.cy) / 2;
+      const curved = e.style === "arc" || n > 1;
+      const lp = legLabelPoint(a, b, curved, fanOffset);
       const bow = {
-        curved: e.style === "arc" || n > 1,
+        curved,
         offset: fanOffset,
-        labelX: mx,
-        labelY: my - 4
+        labelX: lp.x,
+        labelY: lp.y
       };
       const edgeLabelStyle = e.label !== void 0 ? labelOnFill(fillAt(bow.labelX, bow.labelY)) : void 0;
       legs.push({
@@ -53652,7 +53819,7 @@ function layoutMap(resolvedIn, data, size, opts) {
     });
   }
   const labels = [];
-  const obstacles = [];
+  const obstacles = [...topReserved];
   const regionLabelGuards = [];
   const markers = pois.map((p) => ({
     cx: p.cx,
@@ -53690,6 +53857,7 @@ function layoutMap(resolvedIn, data, size, opts) {
   }
   const collides = (rect) => markers.some((m) => rectCircleOverlap(rect, m)) || obstacles.some((o) => rectsOverlap(rect, o)) || legSegments.some((s) => segmentRectOverlap(s[0], s[1], s[2], s[3], rect));
   const showRegionLabels = resolved.directives.noRegionLabels !== true;
+  const labeledRegionIds = /* @__PURE__ */ new Set();
   const showRegionValues = resolved.directives.noRegionValue !== true && activeIsScore;
   const regionValueStr = (value) => showRegionValues && value !== void 0 ? compactNumber(value) : void 0;
   const isCompact = width < COMPACT_WIDTH_PX;
@@ -53710,7 +53878,9 @@ function layoutMap(resolvedIn, data, size, opts) {
   const REGION_FONT_MAX_ORIENT = 22;
   const REGION_SIZE_FRAC_MIN = 0.06;
   const REGION_SIZE_FRAC_MAX = 0.32;
-  const REGION_FADE_ORIENT = 45;
+  const SUBJECT_FONT_MAX = 18;
+  const SUBJECT_MIN_PROMINENCE = 13;
+  const SUBJECT_LEADER_FONT = 15;
   const canvasLinear = Math.sqrt(Math.max(1, width * height));
   const sizeT = (boxW, boxH) => {
     const frac = Math.sqrt(Math.max(0, boxW * boxH)) / canvasLinear;
@@ -53722,9 +53892,9 @@ function layoutMap(resolvedIn, data, size, opts) {
       )
     );
   };
-  const pushRegionLabel = (x, y, text, fill2, lineNumber, valueLine, fontSize = FONT2, fade = 0) => {
+  const pushRegionLabel = (x, y, text, fill2, lineNumber, valueLine, fontSize = FONT2, colorOverride) => {
     const { color: baseColor, haloColor } = labelOnFill(fill2);
-    const color = fade > 0 ? mix(baseColor, palette.bg, fade) : baseColor;
+    const color = colorOverride ?? baseColor;
     const vf = Math.round(fontSize * 0.82);
     const halfW = Math.max(
       measureLegendText(text, fontSize),
@@ -53739,7 +53909,11 @@ function layoutMap(resolvedIn, data, size, opts) {
       text,
       anchor: "middle",
       color,
-      halo: overflows,
+      // A backdrop label (colorOverride) NEVER haloes: the placement gate above
+      // guarantees it sits on a floored-readable substrate (own fill, neutral
+      // land, foreign land, or water), so a halo is pure noise. Data labels keep
+      // the containment-gated halo until the role-tier pass (Phase 3).
+      halo: colorOverride ? false : overflows,
       haloColor,
       ...fontSize !== FONT2 && { fontSize },
       ...valueLine !== void 0 && { valueLine },
@@ -53775,7 +53949,7 @@ function layoutMap(resolvedIn, data, size, opts) {
       if (!c || !Number.isFinite(c[0])) return null;
       return { r, c, boxW, boxH, area: boxW * boxH, candidates };
     }).filter((e) => e !== null).sort((a, b) => b.area - a.area || a.r.lineNumber - b.r.lineNumber);
-    const placedRegionRects = [];
+    const placedRegionRects = [...topReserved];
     const placedLeaders = [];
     const isEmptyFill = (f) => f === water || f === neutralFill || f === foreignFill;
     const POI_LABEL_PAD = 14;
@@ -53788,9 +53962,9 @@ function layoutMap(resolvedIn, data, size, opts) {
     const SHORT_HOP_MAX = Math.max(46, Math.min(width, height) * 0.11);
     const STEP = 4;
     const HOP_GAP = 9;
-    const tryShortHopCallout = (cx, cy, fill2, name, value) => {
-      const chipW = stackW(name, value);
-      const chipH = stackH(value !== void 0);
+    const tryShortHopCallout = (cx, cy, fill2, name, value, font = FONT2, gap = HOP_GAP, maxLen = SHORT_HOP_MAX) => {
+      const chipW = stackW(name, value, font);
+      const chipH = stackH(value !== void 0, font);
       const dirs = [
         [0, -1],
         // north (over Canada)
@@ -53806,7 +53980,7 @@ function layoutMap(resolvedIn, data, size, opts) {
         let ex = cx;
         let ey = cy;
         let steps = 0;
-        const maxSteps = Math.ceil(SHORT_HOP_MAX / STEP) + 1;
+        const maxSteps = Math.ceil(maxLen / STEP) + 1;
         while (steps < maxSteps && fillAt(ex, ey) === fill2) {
           ex += dx * STEP;
           ey += dy * STEP;
@@ -53814,8 +53988,8 @@ function layoutMap(resolvedIn, data, size, opts) {
         }
         if (fillAt(ex, ey) === fill2) continue;
         const halfAlong = (Math.abs(dx) * chipW + Math.abs(dy) * chipH) / 2;
-        const ccx = ex + dx * (HOP_GAP + halfAlong);
-        const ccy = ey + dy * (HOP_GAP + halfAlong);
+        const ccx = ex + dx * (gap + halfAlong);
+        const ccy = ey + dy * (gap + halfAlong);
         const rect = {
           x: ccx - chipW / 2,
           y: ccy - chipH / 2,
@@ -53840,7 +54014,7 @@ function layoutMap(resolvedIn, data, size, opts) {
         const innerX = ccx - dx * (chipW / 2);
         const innerY = ccy - dy * (chipH / 2);
         const len = Math.hypot(innerX - cx, innerY - cy);
-        if (len > SHORT_HOP_MAX) continue;
+        if (len > maxLen) continue;
         if (placedLeaders.some(
           (l) => segmentsCross(cx, cy, innerX, innerY, l[0], l[1], l[2], l[3])
         ))
@@ -53864,6 +54038,78 @@ function layoutMap(resolvedIn, data, size, opts) {
       const valStr = regionValueStr(r.value);
       const fitsRegions = (rect) => !placedRegionRects.some((p) => rectsOverlap(rect, p));
       const fitsPois = (rect) => !poiObstacles.some((o) => rectsOverlap(rect, o));
+      const isSubject = regionById.has(r.id);
+      const extremesOnFill = (ax, ay, text) => {
+        const halfW = measureLegendText(text, FONT2) / 2;
+        return fillAt(ax - halfW, ay) === r.fill && fillAt(ax + halfW, ay) === r.fill;
+      };
+      if (isSubject && valStr === void 0 && r.label !== void 0) {
+        const name = candidates[0];
+        let best = -1;
+        for (let f = SUBJECT_FONT_MAX; f >= FONT2; f--) {
+          if (measureLegendText(name, f) > boxW || f + 2 * LABEL_PADY > boxH)
+            continue;
+          const rect = regionLabelRect(c[0], c[1], name, void 0, f);
+          if (!fitsRegions(rect) || !fitsPois(rect) || collides(rect)) continue;
+          const halfW = measureLegendText(name, f) / 2;
+          if (fillAt(c[0] - halfW, c[1]) !== r.fill || fillAt(c[0] + halfW, c[1]) !== r.fill)
+            continue;
+          best = f;
+          break;
+        }
+        if (best >= SUBJECT_MIN_PROMINENCE) {
+          const rect = regionLabelRect(c[0], c[1], name, void 0, best);
+          placedRegionRects.push(rect);
+          pushRegionLabel(
+            c[0],
+            c[1],
+            name,
+            r.fill,
+            r.lineNumber,
+            void 0,
+            best
+          );
+          labeledRegionIds.add(r.id);
+          regionLabelGuards.push({ label: labels[labels.length - 1], rect });
+        } else {
+          const hop = tryShortHopCallout(
+            c[0],
+            c[1],
+            r.fill,
+            r.label,
+            void 0,
+            SUBJECT_LEADER_FONT,
+            HOP_GAP + SUBJECT_LEADER_FONT,
+            SHORT_HOP_MAX * 2.2
+          );
+          if (hop) {
+            placedRegionRects.push(hop.rect);
+            placedLeaders.push(hop.leader);
+            const dark = mix(r.fill, palette.text, 60);
+            labels.push({
+              x: hop.x,
+              y: hop.y,
+              text: r.label,
+              anchor: "middle",
+              color: palette.text,
+              halo: false,
+              haloColor: palette.bg,
+              fontSize: SUBJECT_LEADER_FONT,
+              leader: {
+                x1: hop.leader[0],
+                y1: hop.leader[1],
+                x2: hop.leader[2],
+                y2: hop.leader[3]
+              },
+              leaderColor: dark,
+              calloutDot: { x: c[0], y: c[1], color: dark },
+              lineNumber: r.lineNumber
+            });
+            labeledRegionIds.add(r.id);
+          }
+        }
+        continue;
+      }
       const seekAnchors = [
         { x: c[0], y: c[1], guard: false }
       ];
@@ -53886,13 +54132,13 @@ function layoutMap(resolvedIn, data, size, opts) {
           const nameRect = regionLabelRect(a.x, a.y, t);
           if (valStr && stackW(t, valStr) <= boxW && stackH(true) <= boxH) {
             const stackRect = regionLabelRect(a.x, a.y, t, valStr);
-            if (fitsRegions(stackRect) && fitsPois(nameRect)) {
+            if (fitsRegions(stackRect) && fitsPois(nameRect) && extremesOnFill(a.x, a.y, t)) {
               chosen = { text: t, valueLine: valStr, ax: a.x, ay: a.y };
               break;
             }
           }
           if (labelW(t) <= boxW && labelH <= boxH) {
-            if (fitsRegions(nameRect) && fitsPois(nameRect)) {
+            if (fitsRegions(nameRect) && fitsPois(nameRect) && (valStr === void 0 || extremesOnFill(a.x, a.y, t))) {
               chosen = { text: t, ax: a.x, ay: a.y };
               break;
             }
@@ -53900,7 +54146,7 @@ function layoutMap(resolvedIn, data, size, opts) {
         }
         if (chosen) break;
       }
-      if (chosen === void 0 && valStr && r.label !== void 0) {
+      if (chosen === void 0 && r.label !== void 0 && isSubject) {
         const hop = tryShortHopCallout(c[0], c[1], r.fill, r.label, valStr);
         if (hop) {
           placedRegionRects.push(hop.rect);
@@ -53912,9 +54158,9 @@ function layoutMap(resolvedIn, data, size, opts) {
             text: r.label,
             anchor: "middle",
             color: palette.text,
-            halo: true,
+            halo: false,
             haloColor: palette.bg,
-            valueLine: valStr,
+            ...valStr !== void 0 && { valueLine: valStr },
             leader: {
               x1: hop.leader[0],
               y1: hop.leader[1],
@@ -53925,20 +54171,28 @@ function layoutMap(resolvedIn, data, size, opts) {
             calloutDot: { x: c[0], y: c[1], color: dark },
             lineNumber: r.lineNumber
           });
+          labeledRegionIds.add(r.id);
         }
         continue;
       }
       if (chosen === void 0) continue;
       const isOrient = r.value === void 0 && r.layer === "base";
       let font = FONT2;
-      let fade = 0;
       if (isOrient) {
         const growT = sizeT(boxW, boxH);
         const desiredFont = Math.round(
           FONT2 + growT * (REGION_FONT_MAX_ORIENT - FONT2)
         );
         const hasVal = chosen.valueLine !== void 0;
-        for (let f = desiredFont; f > FONT2; f--) {
+        const extremesClean = (f) => {
+          const halfW = measureLegendText(chosen.text, f) / 2;
+          return [chosen.ax - halfW, chosen.ax + halfW].every((sx) => {
+            const fAt = fillAt(sx, chosen.ay);
+            return fAt === r.fill || isEmptyFill(fAt);
+          });
+        };
+        let fit = -1;
+        for (let f = desiredFont; f >= FONT2; f--) {
           if (stackW(chosen.text, chosen.valueLine, f) > boxW || stackH(hasVal, f) > boxH)
             continue;
           const gRect = regionLabelRect(
@@ -53955,14 +54209,18 @@ function layoutMap(resolvedIn, data, size, opts) {
             void 0,
             f
           );
-          if (!fitsRegions(gRect) || !fitsPois(gName)) continue;
-          const halfW = measureLegendText(chosen.text, f) / 2;
-          if (fillAt(chosen.ax - halfW, chosen.ay) !== r.fill || fillAt(chosen.ax + halfW, chosen.ay) !== r.fill)
+          if (!fitsRegions(gRect) || !fitsPois(gName) || collides(gName))
             continue;
-          font = f;
+          if (!extremesClean(f)) continue;
+          fit = f;
           break;
         }
-        fade = font > FONT2 ? Math.round(growT * REGION_FADE_ORIENT) : 0;
+        if (fit < 0) {
+          if (!frameContainers.has(r.id)) continue;
+          font = FONT2;
+        } else {
+          font = fit;
+        }
       }
       const rRect = regionLabelRect(
         chosen.ax,
@@ -53980,8 +54238,9 @@ function layoutMap(resolvedIn, data, size, opts) {
         r.lineNumber,
         chosen.valueLine,
         font,
-        fade
+        isOrient ? backdropLandTone : void 0
       );
+      labeledRegionIds.add(r.id);
       regionLabelGuards.push({
         label: labels[labels.length - 1],
         rect: rRect
@@ -53999,6 +54258,7 @@ function layoutMap(resolvedIn, data, size, opts) {
         seed.lineNumber,
         valStr
       );
+      labeledRegionIds.add(seed.iso);
       regionLabelGuards.push({
         label: labels[labels.length - 1],
         rect: regionLabelRect(seed.x, seed.y, text, valStr)
@@ -54430,13 +54690,30 @@ function layoutMap(resolvedIn, data, size, opts) {
       const nx = -dy / len;
       const ny = dx / len;
       const perp = labelH + 2;
+      const pm = /^M(-?[\d.]+),(-?[\d.]+)(?:L(-?[\d.]+),(-?[\d.]+)|Q(-?[\d.]+),(-?[\d.]+) (-?[\d.]+),(-?[\d.]+))$/.exec(
+        lg.d
+      );
+      const pointAt = (t) => {
+        if (pm?.[5] !== void 0) {
+          const u = 1 - t;
+          return [
+            u * u * +pm[1] + 2 * u * t * +pm[5] + t * t * +pm[7],
+            u * u * +pm[2] + 2 * u * t * +pm[6] + t * t * +pm[8]
+          ];
+        }
+        if (pm?.[3] !== void 0)
+          return [
+            +pm[1] + (+pm[3] - +pm[1]) * t,
+            +pm[2] + (+pm[4] - +pm[2]) * t
+          ];
+        return [a.cx + dx * t, a.cy + dy * t];
+      };
       const candidates = [];
       for (const off of [0, perp, -perp, 2 * perp, -2 * perp])
-        for (const t of T_LIST)
-          candidates.push([
-            a.cx + dx * t + nx * off,
-            a.cy + dy * t + ny * off - 4
-          ]);
+        for (const t of T_LIST) {
+          const [bx, by] = pointAt(t);
+          candidates.push([bx + nx * off, by + ny * off - 4]);
+        }
       const clean = ([cx2, cy2]) => {
         const rect2 = { x: cx2 - w / 2, y: cy2 - labelH / 2, w, h: labelH };
         if (rect2.x < 0 || rect2.x + w > width || rect2.y < 0 || rect2.y + rect2.h > height)
@@ -54446,10 +54723,8 @@ function layoutMap(resolvedIn, data, size, opts) {
         if (placedEdge.some((o) => rectsOverlap(o, rect2))) return false;
         return true;
       };
-      const [cx, cy] = candidates.find(clean) ?? [
-        a.cx + dx * 0.5,
-        a.cy + dy * 0.5 - 4
-      ];
+      const mid = pointAt(0.5);
+      const [cx, cy] = candidates.find(clean) ?? [mid[0], mid[1] - 4];
       const style = labelOnFill(fillAt(cx, cy));
       legs[i] = {
         ...lg,
@@ -54477,7 +54752,7 @@ function layoutMap(resolvedIn, data, size, opts) {
     const rawCountries = [];
     for (const f of worldLayer.values()) {
       const iso = typeof f.id === "string" ? f.id : String(f.id ?? "");
-      if (!iso || regionById.has(iso)) continue;
+      if (!iso || regionById.has(iso) || labeledRegionIds.has(iso)) continue;
       let hasReferencedSub = false;
       for (const k of regionById.keys())
         if (k.startsWith(iso + "-")) {
@@ -54551,7 +54826,7 @@ function layoutMap(resolvedIn, data, size, opts) {
     );
     if (usLayer && framedStateContainers) {
       for (const [iso, f] of usLayer) {
-        if (regionById.has(iso)) continue;
+        if (regionById.has(iso) || labeledRegionIds.has(iso)) continue;
         const viewF = cullFeatureToView(f);
         if (!viewF) continue;
         const b = path.bounds(viewF);
@@ -54575,6 +54850,11 @@ function layoutMap(resolvedIn, data, size, opts) {
       waterBodies: data.waterBodies,
       countries: countryCandidates,
       palette,
+      // One muted, contrast-floored tone shared with the orientation backdrop
+      // (region pass) so a context country (Canada) and an orientation region
+      // (Minnesota) read identically — never below the WCAG-AA floor, no fade.
+      countryTone: backdropLandTone,
+      waterTone: backdropWaterTone,
       project,
       collides,
       contentPoints,
@@ -55128,19 +55408,60 @@ function renderMap(container, resolved, data, palette, isDark, onClickItem, expo
       sel.style("cursor", "pointer").on("click", () => onClickItem(lineNumber));
   };
   const gLegs = svg.append("g").attr("class", "dgmo-map-legs").attr("fill", "none");
-  layout.legs.forEach((leg, i) => {
-    const p = gLegs.append("path").attr("d", leg.d).attr("stroke", leg.color).attr("stroke-width", leg.width).attr("stroke-linecap", "round").attr("data-from-id", leg.fromId).attr("data-to-id", leg.toId);
+  const legEnd = (d) => {
+    const m = /^M(-?[\d.]+),(-?[\d.]+)(?:L(-?[\d.]+),(-?[\d.]+)|Q(-?[\d.]+),(-?[\d.]+) (-?[\d.]+),(-?[\d.]+))$/.exec(
+      d
+    );
+    if (!m) return null;
+    const x0 = +m[1];
+    const y0 = +m[2];
+    let ex;
+    let ey;
+    let fromX;
+    let fromY;
+    if (m[3] !== void 0) {
+      ex = +m[3];
+      ey = +m[4];
+      fromX = x0;
+      fromY = y0;
+    } else {
+      ex = +m[7];
+      ey = +m[8];
+      fromX = +m[5];
+      fromY = +m[6];
+    }
+    const dx = ex - fromX;
+    const dy = ey - fromY;
+    const len = Math.hypot(dx, dy);
+    if (!(len > 0)) return null;
+    return { ex, ey, tx: dx / len, ty: dy / len };
+  };
+  layout.legs.forEach((leg) => {
+    const end = leg.arrow ? legEnd(leg.d) : null;
+    let drawD = leg.d;
+    let arrowTri = null;
+    if (end) {
+      const aLen = arrowSize(leg.width);
+      const aHalf = Math.max(aLen * 0.5, leg.width * 0.6 + 1);
+      const bx = end.ex - end.tx * aLen;
+      const by = end.ey - end.ty * aLen;
+      const px = -end.ty;
+      const py = end.tx;
+      arrowTri = `M${bx + px * aHalf},${by + py * aHalf}L${end.ex},${end.ey}L${bx - px * aHalf},${by - py * aHalf}z`;
+      drawD = leg.d.replace(
+        /(-?[\d.]+),(-?[\d.]+)$/,
+        `${bx.toFixed(2)},${by.toFixed(2)}`
+      );
+    }
+    const p = gLegs.append("path").attr("d", drawD).attr("stroke", leg.color).attr("stroke-width", leg.width).attr("stroke-linecap", "round").attr("data-from-id", leg.fromId).attr("data-to-id", leg.toId);
     if (leg.tags) {
       for (const [group, value] of Object.entries(leg.tags)) {
         p.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
       }
     }
     wireSync(p, leg.lineNumber);
-    if (leg.arrow) {
-      const id = nid(`dgmo-map-arrow-${i}`);
-      const s = arrowSize(leg.width);
-      defs.append("marker").attr("id", id).attr("viewBox", "0 0 10 10").attr("refX", 10).attr("refY", 5).attr("markerUnits", "userSpaceOnUse").attr("markerWidth", s).attr("markerHeight", s).attr("orient", "auto-start-reverse").append("path").attr("d", "M0,0L10,5L0,10z").attr("fill", leg.color);
-      p.attr("marker-end", `url(#${id})`);
+    if (arrowTri) {
+      gLegs.append("path").attr("d", arrowTri).attr("fill", leg.color).attr("stroke", leg.color).attr("stroke-width", 1).attr("stroke-linejoin", "round").attr("data-from-id", leg.fromId).attr("data-to-id", leg.toId);
     }
     if (leg.label !== void 0 && leg.labelX !== void 0) {
       const lt = emitText(