@diagrammo/dgmo 0.7.2 → 0.8.0

package/src/echarts.ts

@@ -2,6 +2,9 @@ import * as echarts from 'echarts';
 import type { EChartsOption } from 'echarts';
 import { FONT_FAMILY } from './fonts';
 import { injectBranding } from './branding';
+import { renderLegendSvg } from './utils/legend-svg';
+import type { LegendGroupData } from './utils/legend-svg';
+import { LEGEND_HEIGHT } from './utils/legend-constants';
 
 // ============================================================
 // Types
@@ -27,6 +30,7 @@ export interface ParsedSankeyLink {
   target: string;
   value: number;
   color?: string;
+  directed?: boolean;
   lineNumber: number;
 }
 
@@ -60,7 +64,9 @@ export interface ParsedExtendedChart {
   title?: string;
   titleLineNumber?: number;
   series?: string;
+  seriesLineNumber?: number;
   seriesNames?: string[];
+  seriesNameLineNumbers?: number[];
   seriesNameColors?: (string | undefined)[];
   data: ExtendedChartDataPoint[];
   links?: ParsedSankeyLink[];
@@ -71,10 +77,13 @@ export interface ParsedExtendedChart {
   rows?: string[];
   xRange?: { min: number; max: number };
   xlabel?: string;
+  xlabelLineNumber?: number;
   ylabel?: string;
+  ylabelLineNumber?: number;
   sizelabel?: string;
   showLabels?: boolean;
   categoryColors?: Record<string, string>;
+  categoryLineNumbers?: Record<string, number>;
   nodeColors?: Record<string, string>;
   diagnostics: DgmoError[];
   error: string | null;
@@ -91,13 +100,19 @@ import { parseChart } from './chart';
 import type { ParsedChart, ChartEra } from './chart';
 import { makeDgmoError, formatDgmoError, suggest } from './diagnostics';
 import { resolveColor } from './colors';
-import { collectIndentedValues, extractColor, measureIndent, parseSeriesNames } from './utils/parsing';
+import { collectIndentedValues, extractColor, measureIndent, normalizeGroupedNumber, parseFirstLine, parseSeriesNames } from './utils/parsing';
+import { parseDataRowValues } from './chart';
 
 // ============================================================
 // Shared Constants
 // ============================================================
 
 const EMPHASIS_SELF = { focus: 'self' as const, blurScope: 'global' as const };
+const EMPHASIS_LINE = {
+  ...EMPHASIS_SELF,
+  scale: 2.5,
+  itemStyle: { borderWidth: 2, borderColor: '#fff', shadowBlur: 8, shadowColor: 'rgba(0,0,0,0.4)' },
+};
 const CHART_BASE: Pick<EChartsOption, 'backgroundColor' | 'animation'> = { backgroundColor: 'transparent', animation: false };
 const CHART_BORDER_WIDTH = 2;
 
@@ -105,18 +120,50 @@ const CHART_BORDER_WIDTH = 2;
 // Parser
 // ============================================================
 
+const VALID_EXTENDED_TYPES = new Set<ExtendedChartType>([
+  'sankey', 'chord', 'function', 'scatter', 'heatmap', 'funnel',
+]);
+
+/** Known option keywords for the extended chart parser. */
+const KNOWN_EXTENDED_OPTIONS = new Set([
+  'chart', 'title', 'series', 'xlabel', 'ylabel', 'sizelabel', 'labels',
+  'columns', 'rows', 'x',
+]);
+
+/**
+ * Parse a scatter data row: "Name x, y[, size]" or "Name(color) x, y[, size]"
+ * Returns a ParsedScatterPoint or null if the line doesn't match.
+ */
+function parseScatterRow(
+  line: string,
+  palette: PaletteColors | undefined,
+  currentCategory: string,
+  lineNumber: number,
+): ParsedScatterPoint | null {
+  const dataRow = parseDataRowValues(line);
+  if (!dataRow || dataRow.values.length < 2) return null;
+  const { label: rawLabel, color: pointColor } = extractColor(dataRow.label, palette);
+  return {
+    name: rawLabel,
+    x: dataRow.values[0],
+    y: dataRow.values[1],
+    size: dataRow.values[2] !== undefined ? dataRow.values[2] : undefined,
+    ...(pointColor && { color: pointColor }),
+    ...(currentCategory !== 'Default' && { category: currentCategory }),
+    lineNumber,
+  };
+}
+
 /**
  * Parses extended chart content into a structured object.
  *
- * Format:
+ * Format (colon-free):
  * ```
- * chart: bar
- * title: My Chart
- * series: Revenue
+ * scatter My Chart
+ * xlabel Weight
  *
- * Jan: 120
- * Feb: 200
- * Mar: 150
+ * Alice 165, 60
+ * Bob 180, 85
  * ```
  */
 export function parseExtendedChart(
@@ -136,6 +183,7 @@ export function parseExtendedChart(
 
   // Sankey indentation state: stack of source nodes by indent level
   const sankeyStack: { name: string; indent: number }[] = [];
+  let firstLineParsed = false;
 
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trim();
@@ -154,145 +202,64 @@ export function parseExtendedChart(
     // Skip comments
     if (trimmed.startsWith('//')) continue;
 
-    // [Category] container header with optional color: [Category Name] or [Category Name](color)
-    const categoryMatch = trimmed.match(/^\[(.+?)\](?:\s*\(([^)]+)\))?\s*$/);
-    if (categoryMatch) {
-      const catName = categoryMatch[1].trim();
-      const catColor = categoryMatch[2] ? resolveColor(categoryMatch[2].trim(), palette) : null;
-      if (catColor) {
-        if (!result.categoryColors) result.categoryColors = {};
-        result.categoryColors[catName] = catColor;
-      }
-      currentCategory = catName;
-      continue;
-    }
-
-    // Parse key: value pairs
-    const colonIndex = trimmed.indexOf(':');
-
-    // Sankey: bare label (no colon) at any indent = source node for indented children
-    if (result.type === 'sankey' && colonIndex === -1) {
-      const indent = measureIndent(lines[i]);
-      while (sankeyStack.length && sankeyStack.at(-1)!.indent >= indent) {
-        sankeyStack.pop();
-      }
-      const { label: nodeName, color: nodeColor } = extractColor(trimmed, palette);
-      if (nodeColor) {
-        if (!result.nodeColors) result.nodeColors = {};
-        result.nodeColors[nodeName] = nodeColor;
+    // First non-empty, non-comment line: chart type + optional title
+    if (!firstLineParsed) {
+      firstLineParsed = true;
+      const firstLine = parseFirstLine(trimmed);
+      if (firstLine) {
+        const chartType = firstLine.chartType.toLowerCase() as ExtendedChartType;
+        if (VALID_EXTENDED_TYPES.has(chartType)) {
+          result.type = chartType;
+          if (firstLine.title) {
+            result.title = firstLine.title;
+            result.titleLineNumber = lineNumber;
+          }
+          continue;
+        } else {
+          const validTypes = [...VALID_EXTENDED_TYPES];
+          let msg = `Unsupported chart type: ${firstLine.chartType}. Supported types: ${validTypes.join(', ')}.`;
+          const hint = suggest(chartType, validTypes);
+          if (hint) msg += ` ${hint}`;
+          const diag = makeDgmoError(lineNumber, msg);
+          result.diagnostics.push(diag);
+          result.error = formatDgmoError(diag);
+          return result;
+        }
       }
-      sankeyStack.push({ name: nodeName, indent });
-      continue;
-    }
-
-    if (colonIndex === -1) continue;
-
-    const key = trimmed.substring(0, colonIndex).trim().toLowerCase();
-    const value = trimmed.substring(colonIndex + 1).trim();
-
-    // Handle metadata
-    if (key === 'chart') {
-      const chartType = value.toLowerCase();
-      if (
-        chartType === 'sankey' ||
-        chartType === 'chord' ||
-        chartType === 'function' ||
-        chartType === 'scatter' ||
-        chartType === 'heatmap' ||
-        chartType === 'funnel'
-      ) {
-        result.type = chartType;
-      } else {
-        const validTypes = ['scatter', 'sankey', 'chord', 'function', 'heatmap', 'funnel'];
-        let msg = `Unsupported chart type: ${value}. Supported types: ${validTypes.join(', ')}.`;
-        const hint = suggest(chartType, validTypes);
+      // If the first line is a single word (no spaces, no colon, no numbers),
+      // treat it as an unrecognized chart type rather than falling through
+      if (!trimmed.includes(' ') && !trimmed.includes(':') && !/\d/.test(trimmed)) {
+        const validTypes = [...VALID_EXTENDED_TYPES];
+        let msg = `Unsupported chart type: ${trimmed}. Supported types: ${validTypes.join(', ')}.`;
+        const hint = suggest(trimmed.toLowerCase(), validTypes);
         if (hint) msg += ` ${hint}`;
         const diag = makeDgmoError(lineNumber, msg);
         result.diagnostics.push(diag);
         result.error = formatDgmoError(diag);
         return result;
       }
-      continue;
-    }
-
-    if (key === 'title') {
-      result.title = value;
-      result.titleLineNumber = lineNumber;
-      continue;
-    }
-
-    if (key === 'series') {
-      const parsed = parseSeriesNames(value, lines, i, palette);
-      i = parsed.newIndex;
-      result.series = parsed.series;
-      if (parsed.names.length > 1) {
-        result.seriesNames = parsed.names;
-      }
-      if (parsed.nameColors.some(Boolean)) result.seriesNameColors = parsed.nameColors;
-      continue;
-    }
-
-    // Axis labels
-    if (key === 'xlabel') {
-      result.xlabel = value;
-      continue;
-    }
-
-    if (key === 'ylabel') {
-      result.ylabel = value;
-      continue;
-    }
-
-    if (key === 'sizelabel') {
-      result.sizelabel = value;
-      continue;
-    }
-
-    if (key === 'labels') {
-      result.showLabels =
-        value.toLowerCase() === 'on' || value.toLowerCase() === 'true';
-      continue;
-    }
-
-    // Heatmap columns and rows headers
-    if (key === 'columns') {
-      if (value) {
-        result.columns = value.split(',').map((s) => s.trim());
-      } else {
-        const collected = collectIndentedValues(lines, i);
-        i = collected.newIndex;
-        result.columns = collected.values;
-      }
-      continue;
-    }
-
-    if (key === 'rows') {
-      if (value) {
-        result.rows = value.split(',').map((s) => s.trim());
-      } else {
-        const collected = collectIndentedValues(lines, i);
-        i = collected.newIndex;
-        result.rows = collected.values;
-      }
-      continue;
+      // Fall through — first line might be a data row or option
     }
 
-    // Check for x range: "x: min to max"
-    if (key === 'x') {
-      const rangeMatch = value.match(/^(-?[\d.]+)\s+to\s+(-?[\d.]+)$/);
-      if (rangeMatch) {
-        result.xRange = {
-          min: parseFloat(rangeMatch[1]),
-          max: parseFloat(rangeMatch[2]),
-        };
+    // [Category] container header with optional color: [Category Name] or [Category Name](color)
+    const categoryMatch = trimmed.match(/^\[(.+?)\](?:\s*\(([^)]+)\))?\s*$/);
+    if (categoryMatch) {
+      const catName = categoryMatch[1].trim();
+      const catColor = categoryMatch[2] ? resolveColor(categoryMatch[2].trim(), palette) : null;
+      if (catColor) {
+        if (!result.categoryColors) result.categoryColors = {};
+        result.categoryColors[catName] = catColor;
       }
+      if (!result.categoryLineNumbers) result.categoryLineNumbers = {};
+      result.categoryLineNumbers[catName] = lineNumber;
+      currentCategory = catName;
       continue;
     }
 
-    // Check for Sankey arrow syntax: Source (color) -> Target (color): Value (color)
-    const arrowMatch = trimmed.match(/^(.+?)\s*->\s*(.+?):\s*(\d+(?:\.\d+)?)\s*(?:\(([^)]+)\))?\s*$/);
+    // Sankey/chord link syntax: Source -> Target Value (directed) or Source -- Target Value (undirected)
+    const arrowMatch = trimmed.match(/^(.+?)\s*(->|--)\s*(.+?)\s+(\d+(?:\.\d+)?)\s*(?:\(([^)]+)\))?\s*$/);
     if (arrowMatch) {
-      const [, rawSource, rawTarget, val, rawLinkColor] = arrowMatch;
+      const [, rawSource, arrow, rawTarget, val, rawLinkColor] = arrowMatch;
       const { label: source, color: sourceColor } = extractColor(rawSource.trim(), palette);
       const { label: target, color: targetColor } = extractColor(rawTarget.trim(), palette);
       if (sourceColor || targetColor) {
@@ -307,93 +274,221 @@ export function parseExtendedChart(
         target,
         value: parseFloat(val),
         ...(linkColor && { color: linkColor }),
+        directed: arrow === '->',
         lineNumber,
       });
       continue;
     }
 
-    // Sankey: indented "Target: Value" under a source node on the indent stack
-    if (result.type === 'sankey' && sankeyStack.length > 0) {
+    // Sankey: bare label (no numeric value) at any indent = source node for indented children
+    if (result.type === 'sankey') {
       const indent = measureIndent(lines[i]);
-      if (indent > 0) {
+      // Sankey indented child: "  Target value (color)" under a source on the stack
+      if (indent > 0 && sankeyStack.length > 0) {
         // Pop entries at same or deeper indent to find the parent
         while (sankeyStack.length && sankeyStack.at(-1)!.indent >= indent) {
           sankeyStack.pop();
         }
         if (sankeyStack.length > 0) {
-          const source = sankeyStack.at(-1)!.name;
-          const { label: target, color: targetColor } = extractColor(trimmed.substring(0, colonIndex).trim(), palette);
-          if (targetColor) {
-            if (!result.nodeColors) result.nodeColors = {};
-            result.nodeColors[target] = targetColor;
-          }
-          // Parse value with optional trailing (color) for link color
-          const valColorMatch = value.match(/^(\d+(?:\.\d+)?)\s*(?:\(([^)]+)\))?\s*$/);
-          const val = valColorMatch ? parseFloat(valColorMatch[1]) : NaN;
-          const linkColor = valColorMatch?.[2] ? resolveColor(valColorMatch[2].trim(), palette) : undefined;
-          if (!isNaN(val)) {
+          // Parse "TargetName value (linkColor)" or "TargetName(nodeColor) value (linkColor)"
+          // Strip trailing (color) annotation before parseDataRowValues — it can't handle it
+          const valColorMatch = trimmed.match(/(\d+(?:\.\d+)?)\s*\(([^)]+)\)\s*$/);
+          const strippedLine = valColorMatch ? trimmed.replace(/\s*\([^)]+\)\s*$/, '') : trimmed;
+          const dataRow = parseDataRowValues(strippedLine);
+          if (dataRow && dataRow.values.length === 1) {
+            const source = sankeyStack.at(-1)!.name;
+            const linkColor = valColorMatch?.[2] ? resolveColor(valColorMatch[2].trim(), palette) : undefined;
+            const { label: target, color: targetColor } = extractColor(dataRow.label, palette);
+            if (targetColor) {
+              if (!result.nodeColors) result.nodeColors = {};
+              result.nodeColors[target] = targetColor;
+            }
             if (!result.links) result.links = [];
-            result.links.push({ source, target, value: val, ...(linkColor && { color: linkColor }), lineNumber });
-            // Push target as potential source for deeper nesting
+            result.links.push({ source, target, value: dataRow.values[0], ...(linkColor && { color: linkColor }), lineNumber });
             sankeyStack.push({ name: target, indent });
             continue;
           }
         }
       }
+
+      // Bare label at indent 0 (or any indent without a value) = new source node
+      const spaceIdx = trimmed.indexOf(' ');
+      const hasNumericSuffix = spaceIdx >= 0 && !isNaN(parseFloat(trimmed.substring(trimmed.lastIndexOf(' ') + 1)));
+      if (!hasNumericSuffix) {
+        while (sankeyStack.length && sankeyStack.at(-1)!.indent >= indent) {
+          sankeyStack.pop();
+        }
+        const { label: nodeName, color: nodeColor } = extractColor(trimmed, palette);
+        if (nodeColor) {
+          if (!result.nodeColors) result.nodeColors = {};
+          result.nodeColors[nodeName] = nodeColor;
+        }
+        sankeyStack.push({ name: nodeName, indent });
+        continue;
+      }
     }
 
-    // For function charts, treat non-numeric values as function expressions
-    if (result.type === 'function') {
-      const { label: fnName, color: fnColor } = extractColor(trimmed.substring(0, colonIndex).trim(), palette);
-      if (!result.functions) result.functions = [];
-      result.functions.push({
-        name: fnName,
-        expression: value,
-        ...(fnColor && { color: fnColor }),
-        lineNumber,
-      });
+    // Extract first token to check for known options
+    const spaceIdx = trimmed.indexOf(' ');
+    const firstToken = (spaceIdx >= 0 ? trimmed.substring(0, spaceIdx) : trimmed).toLowerCase();
+
+    // Known option with a value
+    if (KNOWN_EXTENDED_OPTIONS.has(firstToken) && spaceIdx >= 0) {
+      const value = trimmed.substring(spaceIdx + 1).trim();
+
+      if (firstToken === 'chart') {
+        const chartType = value.toLowerCase() as ExtendedChartType;
+        if (VALID_EXTENDED_TYPES.has(chartType)) {
+          result.type = chartType;
+        } else {
+          const validTypes = [...VALID_EXTENDED_TYPES];
+          let msg = `Unsupported chart type: ${value}. Supported types: ${validTypes.join(', ')}.`;
+          const hint = suggest(chartType, validTypes);
+          if (hint) msg += ` ${hint}`;
+          const diag = makeDgmoError(lineNumber, msg);
+          result.diagnostics.push(diag);
+          result.error = formatDgmoError(diag);
+          return result;
+        }
+        continue;
+      }
+
+      if (firstToken === 'title') {
+        result.title = value;
+        result.titleLineNumber = lineNumber;
+        continue;
+      }
+
+      if (firstToken === 'series') {
+        const parsed = parseSeriesNames(value, lines, i, palette);
+        i = parsed.newIndex;
+        result.series = parsed.series;
+        result.seriesLineNumber = lineNumber;
+        if (parsed.names.length > 1) {
+          result.seriesNames = parsed.names;
+          result.seriesNameLineNumbers = parsed.nameLineNumbers;
+        }
+        if (parsed.nameColors.some(Boolean)) result.seriesNameColors = parsed.nameColors;
+        continue;
+      }
+
+      if (firstToken === 'xlabel') { result.xlabel = value; result.xlabelLineNumber = lineNumber; continue; }
+      if (firstToken === 'ylabel') { result.ylabel = value; result.ylabelLineNumber = lineNumber; continue; }
+      if (firstToken === 'sizelabel') { result.sizelabel = value; continue; }
+
+      if (firstToken === 'labels') {
+        result.showLabels = value.toLowerCase() === 'on' || value.toLowerCase() === 'true';
+        continue;
+      }
+
+      if (firstToken === 'columns') {
+        if (value) {
+          result.columns = value.split(',').map((s) => s.trim());
+        } else {
+          const collected = collectIndentedValues(lines, i);
+          i = collected.newIndex;
+          result.columns = collected.values;
+        }
+        continue;
+      }
+
+      if (firstToken === 'rows') {
+        if (value) {
+          result.rows = value.split(',').map((s) => s.trim());
+        } else {
+          const collected = collectIndentedValues(lines, i);
+          i = collected.newIndex;
+          result.rows = collected.values;
+        }
+        continue;
+      }
+
+      if (firstToken === 'x') {
+        const rangeMatch = value.match(/^(-?[\d.]+)\s+to\s+(-?[\d.]+)$/);
+        if (rangeMatch) {
+          result.xRange = {
+            min: parseFloat(rangeMatch[1]),
+            max: parseFloat(rangeMatch[2]),
+          };
+        }
+        continue;
+      }
+    }
+
+    // Bare keyword options (no value)
+    if (firstToken === 'series' && spaceIdx === -1) {
+      const parsed = parseSeriesNames('', lines, i, palette);
+      i = parsed.newIndex;
+      result.series = parsed.series;
+      result.seriesLineNumber = lineNumber;
+      if (parsed.names.length > 1) {
+        result.seriesNames = parsed.names;
+        result.seriesNameLineNumbers = parsed.nameLineNumbers;
+      }
+      if (parsed.nameColors.some(Boolean)) result.seriesNameColors = parsed.nameColors;
       continue;
     }
 
-    // For scatter charts, parse "Name: x, y" or "Name: x, y, size"
-    if (result.type === 'scatter') {
-      const scatterMatch = value.match(
-        /^(-?[\d.]+)\s*,\s*(-?[\d.]+)(?:\s*,\s*(-?[\d.]+))?$/
-      );
-      if (scatterMatch) {
-        const { label: scatterName, color: scatterColor } = extractColor(trimmed.substring(0, colonIndex).trim(), palette);
-        if (!result.scatterPoints) result.scatterPoints = [];
-        result.scatterPoints.push({
-          name: scatterName,
-          x: parseFloat(scatterMatch[1]),
-          y: parseFloat(scatterMatch[2]),
-          size: scatterMatch[3] ? parseFloat(scatterMatch[3]) : undefined,
-          ...(scatterColor && { color: scatterColor }),
-          ...(currentCategory !== 'Default' && { category: currentCategory }),
+    if (firstToken === 'columns' && spaceIdx === -1) {
+      const collected = collectIndentedValues(lines, i);
+      i = collected.newIndex;
+      result.columns = collected.values;
+      continue;
+    }
+
+    if (firstToken === 'rows' && spaceIdx === -1) {
+      const collected = collectIndentedValues(lines, i);
+      i = collected.newIndex;
+      result.rows = collected.values;
+      continue;
+    }
+
+    // Function chart: "name expression" where name may contain parens like f(x)
+    // Must use colon to separate name from expression since both can contain spaces
+    if (result.type === 'function') {
+      const colonIndex = trimmed.indexOf(':');
+      if (colonIndex >= 0) {
+        const { label: fnName, color: fnColor } = extractColor(trimmed.substring(0, colonIndex).trim(), palette);
+        const fnValue = trimmed.substring(colonIndex + 1).trim();
+        if (!result.functions) result.functions = [];
+        result.functions.push({
+          name: fnName,
+          expression: fnValue,
+          ...(fnColor && { color: fnColor }),
           lineNumber,
         });
+        continue;
+      }
+    }
+
+    // Scatter chart: "Name x, y" or "Name x, y, size"
+    if (result.type === 'scatter') {
+      // Parse from right: trailing comma-separated numbers are x, y [, size]
+      const scatterData = parseScatterRow(trimmed, palette, currentCategory, lineNumber);
+      if (scatterData) {
+        if (!result.scatterPoints) result.scatterPoints = [];
+        result.scatterPoints.push(scatterData);
+        continue;
       }
-      continue;
     }
 
-    // For heatmap, parse "RowLabel: val1, val2, val3, ..."
+    // Heatmap data row: "RowLabel val1, val2, val3, ..."
     if (result.type === 'heatmap') {
-      const values = value.split(',').map((v) => parseFloat(v.trim()));
-      if (values.length > 0 && values.every((v) => !isNaN(v))) {
-        const originalKey = trimmed.substring(0, colonIndex).trim();
+      const dataRow = parseDataRowValues(trimmed);
+      if (dataRow && dataRow.values.length > 0) {
         if (!result.heatmapRows) result.heatmapRows = [];
-        result.heatmapRows.push({ label: originalKey, values, lineNumber });
+        result.heatmapRows.push({ label: dataRow.label, values: dataRow.values, lineNumber });
+        continue;
       }
-      continue;
     }
 
-    // Otherwise treat as data point (label: value)
-    const numValue = parseFloat(value);
-    if (!isNaN(numValue)) {
-      const { label: rawLabel, color: pointColor } = extractColor(trimmed.substring(0, colonIndex).trim(), palette);
+    // Funnel / generic data point: "Label value"
+    const dataRow = parseDataRowValues(trimmed);
+    if (dataRow && dataRow.values.length === 1) {
+      const { label: rawLabel, color: pointColor } = extractColor(dataRow.label, palette);
       result.data.push({
         label: rawLabel,
-        value: numValue,
+        value: dataRow.values[0],
         ...(pointColor && { color: pointColor }),
         lineNumber,
       });
@@ -584,6 +679,8 @@ function buildSankeyOption(
   return {
     ...CHART_BASE,
     title: titleConfig,
+    xAxis: { show: false },
+    yAxis: { show: false },
     tooltip: {
       show: false,
       ...tooltipTheme,
@@ -681,13 +778,8 @@ function buildChordOption(
         return '';
       },
     },
-    legend: {
-      data: nodeNames,
-      bottom: 10,
-      textStyle: {
-        color: textColor,
-      },
-    },
+    xAxis: { show: false },
+    yAxis: { show: false },
     series: [
       {
         type: 'graph',
@@ -707,17 +799,35 @@ function buildChordOption(
             color: textColor,
           },
         })),
-        links: (parsed.links ?? []).map((link) => ({
-          source: link.source,
-          target: link.target,
-          value: link.value,
-          lineStyle: {
-            width: Math.max(1, Math.min(link.value / 20, 10)),
-            color: colors[nodeNames.indexOf(link.source) % colors.length],
-            curveness: 0.3,
-            opacity: 0.6,
-          },
-        })),
+        links: (() => {
+          const allLinks = parsed.links ?? [];
+          // Detect opposing link pairs to offset curvatures
+          const pairKeys = new Set<string>();
+          for (const l of allLinks) {
+            const rev = allLinks.find((r) => r.source === l.target && r.target === l.source && r !== l);
+            if (rev) pairKeys.add(`${l.source}\0${l.target}`);
+          }
+          return allLinks.map((link) => {
+            const hasOpposite = pairKeys.has(`${link.source}\0${link.target}`);
+            // Offset curvature for opposing pairs: one curves more, the other less
+            const baseCurve = 0.3;
+            const curveness = hasOpposite
+              ? (link.source < link.target ? baseCurve + 0.15 : baseCurve - 0.15)
+              : baseCurve;
+            return {
+              source: link.source,
+              target: link.target,
+              value: link.value,
+              ...(link.directed && { symbol: ['none', 'arrow'], symbolSize: [0, 10] }),
+              lineStyle: {
+                width: Math.max(1, Math.min(link.value / 20, 10)),
+                color: colors[nodeNames.indexOf(link.source) % colors.length],
+                curveness,
+                opacity: 0.6,
+              },
+            };
+          });
+        })(),
         roam: true,
         label: {
           position: 'right',
@@ -874,6 +984,286 @@ function buildFunctionOption(
   };
 }
 
+/**
+ * Extracts legend group data from standard chart types (multi-line, bar-stacked).
+ * Returns empty array if chart has no multi-series legend.
+ */
+export function getSimpleChartLegendGroups(
+  parsed: ParsedChart,
+  colors: string[],
+): LegendGroupData[] {
+  if (!parsed.seriesNames || parsed.seriesNames.length <= 1) return [];
+  return [{
+    name: 'Series',
+    entries: parsed.seriesNames.map((name, i) => ({
+      value: name,
+      color: parsed.seriesNameColors?.[i] ?? colors[i % colors.length],
+    })),
+  }];
+}
+
+/**
+ * Extracts legend group data from extended chart types.
+ * Supports scatter (categories), chord (nodes), and function (series).
+ */
+export function getExtendedChartLegendGroups(
+  parsed: ParsedExtendedChart,
+  colors: string[],
+): LegendGroupData[] {
+  if (parsed.type === 'scatter') {
+    const points = parsed.scatterPoints ?? [];
+    const categories = [...new Set(points.map((p) => p.category).filter(Boolean))] as string[];
+    if (categories.length === 0) return [];
+    return [{
+      name: 'Group',
+      entries: categories.map((cat, i) => ({
+        value: cat,
+        color: parsed.categoryColors?.[cat] ?? colors[i % colors.length],
+      })),
+    }];
+  }
+
+  if (parsed.type === 'function') {
+    const fns = parsed.functions ?? [];
+    if (fns.length === 0) return [];
+    return [{
+      name: 'Function',
+      entries: fns.map((fn, i) => ({
+        value: fn.name,
+        color: fn.color ?? colors[i % colors.length],
+      })),
+    }];
+  }
+
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Scatter label collision avoidance — greedy placement algorithm
+// ---------------------------------------------------------------------------
+
+interface LabelRect { x: number; y: number; w: number; h: number }
+interface PointCircle { cx: number; cy: number; r: number }
+
+/** Axis-aligned bounding box overlap test. @internal exported for testing */
+export function rectsOverlap(a: LabelRect, b: LabelRect): boolean {
+  return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+
+/** Rect vs circle overlap using nearest-point-on-rect distance check. @internal exported for testing */
+export function rectCircleOverlap(rect: LabelRect, circle: PointCircle): boolean {
+  const nearestX = Math.max(rect.x, Math.min(circle.cx, rect.x + rect.w));
+  const nearestY = Math.max(rect.y, Math.min(circle.cy, rect.y + rect.h));
+  const dx = nearestX - circle.cx;
+  const dy = nearestY - circle.cy;
+  return dx * dx + dy * dy < circle.r * circle.r;
+}
+
+export interface ScatterLabelPoint {
+  name: string;
+  px: number;
+  py: number;
+  color: string;
+  size?: number; // per-point symbol size (for bubble charts)
+}
+
+/**
+ * Greedy label placement for scatter charts.
+ * Returns ECharts `graphic` elements (text + background rects + optional connector lines).
+ * Pure function — no ECharts instance dependency.
+ *
+ * @param bg - chart background color, used for label background rects that mask connector lines
+ */
+export function computeScatterLabelGraphics(
+  points: ScatterLabelPoint[],
+  chartBounds: { top: number; bottom: number },
+  fontSize: number,
+  symbolSize: number,
+  bg?: string
+): Record<string, unknown>[] {
+  const labelHeight = fontSize + 4;
+  const stepSize = labelHeight + 2;
+
+  // Build collision circles for ALL points (per-point size for bubble charts)
+  const pointCircles: PointCircle[] = points.map((p) => ({
+    cx: p.px,
+    cy: p.py,
+    r: (p.size ?? symbolSize) / 2,
+  }));
+
+  const placedLabels: LabelRect[] = [];
+  const elements: Record<string, unknown>[] = [];
+
+  for (let i = 0; i < points.length; i++) {
+    const pt = points[i];
+    const ptSize = pt.size ?? symbolSize;
+    const minGap = ptSize / 2 + 4;
+    const labelWidth = pt.name.length * fontSize * 0.6 + 8;
+    const labelX = pt.px - labelWidth / 2; // centered horizontally
+
+    // Try both directions, pick whichever keeps the label closest to the point
+    let bestLabelY = 0;
+    let bestOffset = Infinity;
+    let placed = false;
+
+    for (const dir of [-1, 1]) {
+      for (let offset = minGap; ; offset += stepSize) {
+        const labelY =
+          dir === -1
+            ? pt.py - offset - labelHeight // above: label bottom edge is offset above point center
+            : pt.py + offset; // below: label top edge is offset below point center
+
+        // Check chart bounds
+        if (labelY < chartBounds.top || labelY + labelHeight > chartBounds.bottom) break;
+
+        const candidate: LabelRect = { x: labelX, y: labelY, w: labelWidth, h: labelHeight };
+
+        // Check collisions with all placed labels
+        let collision = false;
+        for (const pl of placedLabels) {
+          if (rectsOverlap(candidate, pl)) {
+            collision = true;
+            break;
+          }
+        }
+
+        // Check collisions with all point circles
+        if (!collision) {
+          for (const circle of pointCircles) {
+            if (rectCircleOverlap(candidate, circle)) {
+              collision = true;
+              break;
+            }
+          }
+        }
+
+        if (!collision) {
+          // Found closest slot in this direction — keep if it beats the other
+          if (offset < bestOffset) {
+            bestOffset = offset;
+            bestLabelY = labelY;
+          }
+          placed = true;
+          break; // best for this direction found, try the other
+        }
+      }
+    }
+
+    // Fallback: try above first, then below — prefer whichever is within bounds
+    if (!placed) {
+      const aboveY = pt.py - minGap - labelHeight;
+      const belowY = pt.py + minGap;
+      if (aboveY >= chartBounds.top) {
+        bestLabelY = aboveY;
+      } else if (belowY + labelHeight <= chartBounds.bottom) {
+        bestLabelY = belowY;
+      } else {
+        bestLabelY = aboveY; // last resort — may clip
+      }
+    }
+
+    const labelRect: LabelRect = { x: labelX, y: bestLabelY, w: labelWidth, h: labelHeight };
+    placedLabels.push(labelRect);
+
+    const textY = bestLabelY + labelHeight / 2;
+
+    // Connector line (z=1, rendered below labels)
+    const isAbove = bestLabelY + labelHeight <= pt.py;
+    const pointEdge = isAbove ? pt.py - ptSize / 2 : pt.py + ptSize / 2;
+    const labelEdge = isAbove ? bestLabelY + labelHeight : bestLabelY;
+    const gap = Math.abs(pointEdge - labelEdge);
+
+    if (gap > 4) {
+      elements.push({
+        type: 'line',
+        id: `scatter-line-${i}`,
+        z: 1,
+        shape: {
+          x1: pt.px,
+          y1: pointEdge,
+          x2: pt.px,
+          y2: labelEdge,
+        },
+        style: {
+          stroke: pt.color,
+          lineWidth: 1,
+        },
+        silent: true,
+      });
+    }
+
+    // Background rect (z=2, masks connector lines behind label text)
+    if (bg) {
+      const bgPad = 2;
+      elements.push({
+        type: 'rect',
+        id: `scatter-bg-${i}`,
+        z: 2,
+        shape: {
+          x: labelX - bgPad,
+          y: bestLabelY - bgPad,
+          width: labelWidth + bgPad * 2,
+          height: labelHeight + bgPad * 2,
+        },
+        style: { fill: bg },
+        silent: true,
+      });
+    }
+
+    // Text element (z=3, rendered on top)
+    elements.push({
+      type: 'text',
+      id: `scatter-label-${i}`,
+      z: 3,
+      x: pt.px,
+      y: textY,
+      style: {
+        text: pt.name,
+        fill: pt.color,
+        fontSize,
+        fontFamily: FONT_FAMILY,
+        textAlign: 'center',
+        textVerticalAlign: 'middle',
+      },
+      silent: true,
+    });
+  }
+
+  return elements;
+}
+
+/**
+ * Convert data coordinates to pixel coordinates using linear interpolation.
+ * For SSR path where chart instance is not available for convertToPixel.
+ */
+function dataToPixel(
+  dataX: number,
+  dataY: number,
+  xMin: number,
+  xMax: number,
+  yMin: number,
+  yMax: number,
+  gridLeftPct: number,
+  gridRightPct: number,
+  gridTopPct: number,
+  gridBottomPct: number,
+  chartWidth: number,
+  chartHeight: number
+): { px: number; py: number } {
+  // containLabel: true shrinks the plot area — apply conservative 30px inset
+  const inset = 30;
+  const gridLeftPx = gridLeftPct * chartWidth / 100 + inset;
+  const gridRightPx = chartWidth - gridRightPct * chartWidth / 100 - inset;
+  const gridTopPx = gridTopPct * chartHeight / 100 + inset;
+  const gridBottomPx = chartHeight - gridBottomPct * chartHeight / 100 - inset;
+  const plotWidth = gridRightPx - gridLeftPx;
+  const plotHeight = gridBottomPx - gridTopPx;
+
+  const px = gridLeftPx + ((dataX - xMin) / (xMax - xMin)) * plotWidth;
+  const py = gridTopPx + ((yMax - dataY) / (yMax - yMin)) * plotHeight;
+  return { px, py };
+}
+
 /**
  * Builds ECharts option for scatter plots.
  * Auto-detects categories and size from point data:
@@ -897,12 +1287,16 @@ function buildScatterOption(
   const hasCategories = points.some((p) => p.category !== undefined);
   const hasSize = points.some((p) => p.size !== undefined);
 
+  const showLabels = parsed.showLabels ?? false;
+  const labelFontSize = 11;
+
+  // When showLabels is on, we render labels ourselves via graphic — disable ECharts labels
   const labelConfig = {
-    show: parsed.showLabels ?? false,
+    show: false,
     formatter: '{b}',
     position: 'top' as const,
     color: textColor,
-    fontSize: 11,
+    fontSize: labelFontSize,
   };
 
   const emphasisConfig = {
@@ -915,13 +1309,11 @@ function buildScatterOption(
 
   // Build series based on whether categories are present
   let series;
-  let legendData: string[] | undefined;
 
   if (hasCategories) {
     const categories = [
       ...new Set(points.map((p) => p.category).filter(Boolean)),
     ] as string[];
-    legendData = categories;
 
     series = categories.map((category, catIndex) => {
       const categoryPoints = points.filter((p) => p.category === category);
@@ -1002,22 +1394,71 @@ function buildScatterOption(
   const xPad = (xMax - xMin) * 0.1 || 1;
   const yPad = (yMax - yMin) * 0.1 || 1;
 
+  const axisXMin = Math.floor(xMin - xPad);
+  const axisXMax = Math.ceil(xMax + xPad);
+  const axisYMin = Math.floor(yMin - yPad);
+  const axisYMax = Math.ceil(yMax + yPad);
+
+  const gridLeft = parsed.ylabel ? 12 : 3;
+  const gridRight = 4;
+  const gridBottom = parsed.xlabel ? 10 : 3;
+  const gridTop = parsed.title ? 15 : 5;
+
+  // Compute custom label graphics for SSR when labels are enabled
+  let graphic: Record<string, unknown>[] | undefined;
+  if (showLabels && points.length > 0) {
+    // Collect label points with resolved colors
+    const labelPoints: ScatterLabelPoint[] = [];
+    if (hasCategories) {
+      const categories = [
+        ...new Set(points.map((p) => p.category).filter(Boolean)),
+      ] as string[];
+      for (let idx = 0; idx < points.length; idx++) {
+        const pt = points[idx];
+        const catIndex = pt.category ? categories.indexOf(pt.category) : -1;
+        const catColor = pt.category
+          ? (parsed.categoryColors?.[pt.category] ?? colors[catIndex % colors.length])
+          : colors[idx % colors.length];
+        const color = pt.color ?? catColor;
+        const { px, py } = dataToPixel(
+          pt.x, pt.y, axisXMin, axisXMax, axisYMin, axisYMax,
+          gridLeft, gridRight, gridTop, gridBottom,
+          ECHART_EXPORT_WIDTH, ECHART_EXPORT_HEIGHT
+        );
+        labelPoints.push({ name: pt.name, px, py, color, size: pt.size });
+      }
+    } else {
+      points.forEach((pt, index) => {
+        const color = pt.color ?? colors[index % colors.length];
+        const { px, py } = dataToPixel(
+          pt.x, pt.y, axisXMin, axisXMax, axisYMin, axisYMax,
+          gridLeft, gridRight, gridTop, gridBottom,
+          ECHART_EXPORT_WIDTH, ECHART_EXPORT_HEIGHT
+        );
+        labelPoints.push({ name: pt.name, px, py, color, size: pt.size });
+      });
+    }
+
+    const chartBoundsTop = gridTop * ECHART_EXPORT_HEIGHT / 100;
+    const chartBoundsBottom = ECHART_EXPORT_HEIGHT - gridBottom * ECHART_EXPORT_HEIGHT / 100;
+    graphic = computeScatterLabelGraphics(
+      labelPoints,
+      { top: chartBoundsTop, bottom: chartBoundsBottom },
+      labelFontSize,
+      defaultSize,
+      bg
+    );
+  }
+
   return {
     ...CHART_BASE,
     title: titleConfig,
     tooltip,
-    ...(legendData && {
-      legend: {
-        data: legendData,
-        bottom: 10,
-        textStyle: { color: textColor },
-      },
-    }),
     grid: {
-      left: parsed.ylabel ? '12%' : '3%',
-      right: '4%',
-      bottom: hasCategories ? '15%' : parsed.xlabel ? '10%' : '3%',
-      top: parsed.title ? '15%' : '5%',
+      left: `${gridLeft}%`,
+      right: `${gridRight}%`,
+      bottom: `${gridBottom}%`,
+      top: `${gridTop}%`,
       containLabel: true,
     },
     xAxis: {
@@ -1029,8 +1470,8 @@ function buildScatterOption(
         color: textColor,
         fontSize: 18,
       },
-      min: Math.floor(xMin - xPad),
-      max: Math.ceil(xMax + xPad),
+      min: axisXMin,
+      max: axisXMax,
       axisLine: {
         lineStyle: { color: axisLineColor },
       },
@@ -1054,8 +1495,8 @@ function buildScatterOption(
         color: textColor,
         fontSize: 18,
       },
-      min: Math.floor(yMin - yPad),
-      max: Math.ceil(yMax + yPad),
+      min: axisYMin,
+      max: axisYMax,
       axisLine: {
         lineStyle: { color: axisLineColor },
       },
@@ -1071,6 +1512,7 @@ function buildScatterOption(
       },
     },
     series,
+    ...(graphic && { graphic }),
   };
 }
 
@@ -1248,6 +1690,8 @@ function buildFunnelOption(
   return {
     ...CHART_BASE,
     title: titleConfig,
+    xAxis: { show: false },
+    yAxis: { show: false },
     tooltip: {
       trigger: 'item',
       ...tooltipTheme,
@@ -1521,7 +1965,7 @@ function buildBarOption(
 // Targets ~5 visible labels — conservative enough to prevent ECharts stagger.
 function buildIntervalStep(labels: string[]): number {
   const count = labels.length;
-  if (count <= 6) return 0; // show all
+  if (count <= 12) return 0; // show all
   const snapSteps = [1, 2, 5, 10, 25, 50, 100];
   const raw = Math.ceil(count / 5); // target ~5 visible labels
   const N = [...snapSteps].reverse().find((s) => s <= raw) ?? 1; // snap down
@@ -1549,7 +1993,7 @@ function buildMarkArea(
           xAxis: era.start,
           itemStyle: { color, opacity: 0.15 },
           label: {
-            show: bandSlots >= 3,
+            show: bandSlots >= 2,
             position: 'insideTop',
             fontSize: 11,
             color: textColor,
@@ -1601,7 +2045,7 @@ function buildLineOption(
         symbolSize: 8,
         lineStyle: { color: lineColor, width: 3 },
         itemStyle: { color: lineColor },
-        emphasis: EMPHASIS_SELF,
+        emphasis: EMPHASIS_LINE,
         ...(markArea && { markArea }),
       },
     ],
@@ -1642,7 +2086,7 @@ function buildMultiLineOption(
       symbolSize: 8,
       lineStyle: { color, width: 3 },
       itemStyle: { color },
-      emphasis: EMPHASIS_SELF,
+      emphasis: EMPHASIS_LINE,
       ...(idx === 0 && markArea && { markArea }),
     };
   });
@@ -1708,7 +2152,7 @@ function buildAreaOption(
         lineStyle: { color: lineColor, width: 3 },
         itemStyle: { color: lineColor },
         areaStyle: { opacity: 0.25 },
-        emphasis: EMPHASIS_SELF,
+        emphasis: EMPHASIS_LINE,
         ...(markArea && { markArea }),
       },
     ],
@@ -1737,6 +2181,7 @@ function buildPieOption(
   tooltipTheme: Record<string, unknown>,
   isDoughnut: boolean
 ): EChartsOption {
+  const HIDE_AXES = { xAxis: { show: false }, yAxis: { show: false } };
   const data = parsed.data.map((d, i) => {
     const stroke = d.color ?? colors[i % colors.length];
     return {
@@ -1748,6 +2193,7 @@ function buildPieOption(
 
   return {
     ...CHART_BASE,
+    ...HIDE_AXES,
     title: titleConfig,
     tooltip: {
       trigger: 'item',
@@ -1795,6 +2241,8 @@ function buildRadarOption(
   return {
     ...CHART_BASE,
     title: titleConfig,
+    xAxis: { show: false },
+    yAxis: { show: false },
     tooltip: {
       trigger: 'item',
       ...tooltipTheme,
@@ -1863,6 +2311,8 @@ function buildPolarAreaOption(
   return {
     ...CHART_BASE,
     title: titleConfig,
+    xAxis: { show: false },
+    yAxis: { show: false },
     tooltip: {
       trigger: 'item',
       ...tooltipTheme,
@@ -1989,21 +2439,41 @@ export async function renderExtendedChartForExport(
     palette ?? (isDark ? getPalette('nord').dark : getPalette('nord').light);
 
   // Detect chart type to dispatch to the right parser/builder
-  const chartLine = content.match(/^chart\s*:\s*(.+)/im);
-  const chartType = chartLine?.[1]?.trim().toLowerCase();
+  // Find first non-empty, non-comment line and use parseFirstLine for new-style detection
+  let chartType: string | undefined;
+  for (const rawLine of content.split('\n')) {
+    const t = rawLine.trim();
+    if (!t || t.startsWith('//')) continue;
+    const fl = parseFirstLine(t);
+    if (fl) chartType = fl.chartType.toLowerCase();
+    break;
+  }
+
+  // No recognised chart type on the first line → nothing to render
+  if (!chartType) return '';
 
   let option: EChartsOption;
-  if (chartType && STANDARD_CHART_TYPES.has(chartType)) {
+  let legendGroups: LegendGroupData[] = [];
+  const colors = getSeriesColors(effectivePalette);
+
+  if (STANDARD_CHART_TYPES.has(chartType)) {
     const parsed = parseChart(content, effectivePalette);
     if (parsed.error) return '';
     option = buildSimpleChartOption(parsed, effectivePalette, isDark, ECHART_EXPORT_WIDTH);
+    legendGroups = getSimpleChartLegendGroups(parsed, colors);
   } else {
     const parsed = parseExtendedChart(content, effectivePalette);
     if (parsed.error) return '';
     option = buildExtendedChartOption(parsed, effectivePalette, isDark);
+    legendGroups = getExtendedChartLegendGroups(parsed, colors);
   }
   if (!option || Object.keys(option).length === 0) return '';
 
+  // When using custom legend, strip ECharts' built-in legend
+  if (legendGroups.length > 0) {
+    option = { ...option, legend: undefined };
+  }
+
   const chart = echarts.init(null, null, {
     renderer: 'svg',
     ssr: true,
@@ -2024,6 +2494,31 @@ export async function renderExtendedChartForExport(
       `<svg style="${bgStyle}font-family: ${FONT_FAMILY}" `
     );
 
+    // Inject custom legend SVG when present
+    if (legendGroups.length > 0) {
+      const titleHeight = option.title && (option.title as { text?: string }).text ? 40 : 0;
+      const legendY = 8 + titleHeight;
+      // In static export, expand the first group so entries are visible
+      // Extract grid offsets for plot-area-centered legend
+      const grid = option.grid as Record<string, unknown> | undefined;
+      const gridLeftPct = grid?.left ? parseFloat(String(grid.left)) : undefined;
+      const gridRightPct = grid?.right ? parseFloat(String(grid.right)) : undefined;
+      const { svg: legendSvgStr } = renderLegendSvg(legendGroups, {
+        palette: effectivePalette,
+        isDark,
+        containerWidth: ECHART_EXPORT_WIDTH,
+        gridLeftPct,
+        gridRightPct,
+        activeGroup: legendGroups[0].name,
+        className: 'chart-legend',
+      });
+      // Insert legend group right after the opening <svg ...> tag
+      result = result.replace(
+        /(<svg[^>]*>)/,
+        `$1<g transform="translate(0,${legendY})">${legendSvgStr}</g>`,
+      );
+    }
+
     if (options?.branding !== false) {
       const brandColor = theme === 'transparent' ? '#888' : effectivePalette.textMuted;
       result = injectBranding(result, brandColor);