@diagrammo/dgmo 0.15.0 → 0.16.0

package/src/d3.ts

@@ -205,6 +205,7 @@ import {
   normalizeNumericToken,
   parseFirstLine,
   parsePipeMetadata,
+  peelTrailingColorName,
   MULTIPLE_PIPE_ERROR,
 } from './utils/parsing';
 import {
@@ -593,8 +594,12 @@ export function parseVisualization(
       currentTimelineTagGroup = null;
     }
 
-    // [Group] container headers for arc diagram node grouping and timeline eras
-    const groupMatch = line.match(/^\[(.+?)\](?:\s*\(([^)]+)\))?\s*$/);
+    // [Group] container headers for arc / timeline (§1.5 trailing-token):
+    //   `[Group]`           — no color
+    //   `[Group] color`     — trailing-token color (recognized palette word)
+    const groupMatch = line.match(
+      /^\[(.+?)\](?:\s+(red|orange|yellow|green|blue|purple|teal|cyan|gray|black|white))?\s*$/
+    );
     if (groupMatch) {
       if (result.type === 'arc') {
         const name = groupMatch[1].trim();
@@ -649,10 +654,11 @@ export function parseVisualization(
       currentTimelineGroup = null;
     }
 
-    // Arc link line: source -> target(color) weight
+    // Arc link line (§1.5 trailing-token):
+    //   `source -> target [color] [weight]` — color before weight
     if (result.type === 'arc') {
       const linkMatch = line.match(
-        /^(.+?)\s*->\s*(.+?)(?:\(([^)]+)\))?\s*(?:\s+(-?[\d,_]+(?:\.[\d]+)?))?$/
+        /^(.+?)\s*->\s*(.+?)(?:\s+(red|orange|yellow|green|blue|purple|teal|cyan|gray|black|white))?(?:\s+(-?[\d,_]+(?:\.[\d]+)?))?$/
       );
       if (linkMatch) {
         const source = linkMatch[1].trim();
@@ -698,8 +704,12 @@ export function parseVisualization(
         // fall through to process this line normally
       } else {
         if (line.startsWith('//')) continue;
+        // Timeline era block entry (\u00a71.5 trailing-token):
+        //   `<start> -> <end> Label`           (no color)
+        //   `<start> -> <end> Label color`     (trailing color word)
+        // Color (group 4) must be a recognized lowercase palette word.
         const eraEntryMatch = line.match(
-          /^(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s*(?:->|\u2013>)\s*(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s*\(([^)]+)\))?\s*$/
+          /^(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s*(?:->|\u2013>)\s*(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s+(red|orange|yellow|green|blue|purple|teal|cyan|gray|black|white))?\s*$/
         );
         if (eraEntryMatch) {
           const colorAnnotation = eraEntryMatch[4]?.trim() || null;
@@ -731,8 +741,9 @@ export function parseVisualization(
         // fall through to process this line normally
       } else {
         if (line.startsWith('//')) continue;
+        // Timeline marker block entry (§1.5 trailing-token).
         const markerEntryMatch = line.match(
-          /^(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s*\(([^)]+)\))?\s*$/
+          /^(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s+(red|orange|yellow|green|blue|purple|teal|cyan|gray|black|white))?\s*$/
         );
         if (markerEntryMatch) {
           const colorAnnotation = markerEntryMatch[3]?.trim() || null;
@@ -772,9 +783,11 @@ export function parseVisualization(
         continue;
       }
 
-      // Timeline era lines (inline): era YYYY->YYYY Label (color)
+      // Timeline era lines, inline (\u00a71.5 trailing-token):
+      //   `era YYYY->YYYY Label`        \u2014 no color
+      //   `era YYYY->YYYY Label color`  \u2014 trailing-token color (recognized palette word)
       const eraMatch = line.match(
-        /^era\s+(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s*(?:->|\u2013>)\s*(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s*\(([^)]+)\))?\s*$/
+        /^era\s+(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s*(?:->|\u2013>)\s*(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s+(red|orange|yellow|green|blue|purple|teal|cyan|gray|black|white))?\s*$/
       );
       if (eraMatch) {
         const colorAnnotation = eraMatch[4]?.trim() || null;
@@ -795,9 +808,11 @@ export function parseVisualization(
         continue;
       }
 
-      // Timeline marker lines (inline): marker YYYY Label (color)
+      // Timeline marker lines, inline (§1.5 trailing-token):
+      //   `marker YYYY Label`        — no color
+      //   `marker YYYY Label color`  — trailing-token color
       const markerMatch = line.match(
-        /^marker\s+(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s*\(([^)]+)\))?\s*$/
+        /^marker\s+(\d{4}(?:-\d{2})?(?:-\d{2}(?: \d{2}:\d{2})?)?)\s+(.+?)(?:\s+(red|orange|yellow|green|blue|purple|teal|cyan|gray|black|white))?\s*$/
       );
       if (markerMatch) {
         const colorAnnotation = markerMatch[3]?.trim() || null;
@@ -959,19 +974,20 @@ export function parseVisualization(
         }
       }
 
-      // Set declaration: "Name(color) as <alias>" / "Name as <alias>" / "Name(color)" / "Name"
-      // Legacy "Name(color) alias <token>" emits E_VENN_ALIAS_KEYWORD_REMOVED.
+      // Set declaration (§1.5 universal trailing-token):
+      //   `Name` / `Name color` / `Name as <alias>` / `Name color as <alias>`
+      // Legacy `Name color alias <token>` emits E_VENN_ALIAS_KEYWORD_REMOVED.
       // Only attempt set parsing if the line wasn't a bare-keyword option (handled above).
       if (!/^(solid-fill|no-name|no-value|no-percent|no-title)$/i.test(line)) {
         // Detect legacy `alias` keyword first — graceful degradation parses
         // the rest of the line so the set still appears.
-        const legacyAliasMatch = line.match(
-          /^([^(:]+?)(?:\(([^)]+)\))?\s+alias\s+(\S+)\s*$/i
-        );
+        const legacyAliasMatch = line.match(/^(.+?)\s+alias\s+(\S+)\s*$/i);
         if (legacyAliasMatch) {
-          const name = legacyAliasMatch[1].trim();
-          const colorName = legacyAliasMatch[2]?.trim() ?? null;
-          const aliasToken = legacyAliasMatch[3].trim();
+          const nameWithMaybeColor = legacyAliasMatch[1].trim();
+          const aliasToken = legacyAliasMatch[2].trim();
+          // Split off trailing-token color from the name region.
+          const { label: name, colorName } =
+            peelTrailingColorName(nameWithMaybeColor);
           let color: string | null = null;
           if (colorName) {
             color =
@@ -995,11 +1011,14 @@ export function parseVisualization(
         }
 
         const setDeclMatch = line.match(
-          /^([^(:]+?)(?:\(([^)]+)\))?(?:\s+as\s+([A-Za-z][A-Za-z0-9_]{0,11}))?\s*$/i
+          /^(.+?)(?:\s+as\s+([A-Za-z][A-Za-z0-9_]{0,11}))?\s*$/i
         );
         if (setDeclMatch) {
-          const name = setDeclMatch[1].trim();
-          const colorName = setDeclMatch[2]?.trim() ?? null;
+          const nameWithMaybeColor = setDeclMatch[1].trim();
+          const alias = setDeclMatch[2]?.trim() ?? null;
+          // Split off trailing-token color from the name region (before `as`).
+          const { label: name, colorName } =
+            peelTrailingColorName(nameWithMaybeColor);
           let color: string | null = null;
           if (colorName) {
             color =
@@ -1010,7 +1029,6 @@ export function parseVisualization(
                 palette
               ) ?? null;
           }
-          const alias = setDeclMatch[3]?.trim() ?? null;
           result.vennSets.push({ name, alias, color, lineNumber });
           continue;
         }
@@ -1057,19 +1075,20 @@ export function parseVisualization(
         continue;
       }
 
-      // Quadrant position labels: top-right Label (color)
+      // Quadrant position labels (§1.5 trailing-token):
+      //   `top-right Label`        — no color
+      //   `top-right Label color`  — trailing-token color (recognized palette word)
       const quadrantLabelRe =
         /^(top-right|top-left|bottom-left|bottom-right)\s+(.+)/i;
       const quadrantMatch = line.match(quadrantLabelRe);
       if (quadrantMatch) {
         const position = quadrantMatch[1].toLowerCase();
         const labelPart = quadrantMatch[2].trim();
-        // Check for color annotation: "Label (color)" or "Label(color)"
-        const labelColorMatch = labelPart.match(/^(.+?)\s*\(([^)]+)\)\s*$/);
-        const text = labelColorMatch ? labelColorMatch[1].trim() : labelPart;
-        const color = labelColorMatch
+        // Peel trailing recognized color word from the label.
+        const { label: text, colorName } = peelTrailingColorName(labelPart);
+        const color = colorName
           ? (resolveColorWithDiagnostic(
-              labelColorMatch[2].trim(),
+              colorName,
               lineNumber,
               result.diagnostics,
               palette
@@ -1325,12 +1344,12 @@ export function parseVisualization(
           continue;
         }
 
-        // Color annotation: `Label (color)` → extract color
-        const colorMatch = joinedLabel.match(/^(.+?)\(([^)]+)\)\s*$/);
-        const labelPart = colorMatch ? colorMatch[1].trim() : joinedLabel;
-        const colorPart = colorMatch
+        // Color annotation (§1.5 trailing-token): `Label color` → split.
+        const { label: labelPart, colorName: colorWord } =
+          peelTrailingColorName(joinedLabel);
+        const colorPart = colorWord
           ? (resolveColorWithDiagnostic(
-              colorMatch[2].trim(),
+              colorWord,
               lineNumber,
               result.diagnostics,
               palette
@@ -3481,25 +3500,51 @@ function renderTimelineGroupLegend(
   }
 }
 
+// ============================================================
+// Timeline — setup helper (extracted from renderTimeline)
+// ============================================================
+
+type Lane = { name: string; events: TimelineEvent[] };
+
+type TimelineSetup = {
+  width: number;
+  height: number;
+  isVertical: boolean;
+  tooltip: HTMLDivElement;
+  solid: boolean;
+  textColor: string;
+  mutedColor: string;
+  bgColor: string;
+  bg: string;
+  swimlaneTagGroup: string | null;
+  groupColorMap: Map<string, string>;
+  tagLanes: Lane[] | null;
+  eventColor: (ev: TimelineEvent) => string;
+  minDate: number;
+  maxDate: number;
+  datePadding: number;
+  earliestStartDateStr: string;
+  latestEndDateStr: string;
+  tagLegendReserve: number;
+};
+
 /**
- * Renders a timeline chart into the given container using D3.
- * Supports horizontal (default) and vertical orientation.
+ * Computes layout context (dimensions, colors, date domain, tag lanes,
+ * event-color resolver) for a timeline before the orientation-specific
+ * rendering branch runs. Returns null when there is nothing to render
+ * (empty events or zero-sized container).
+ *
+ * Side effects: clears the container and creates the tooltip element.
  */
-export function renderTimeline(
+function setupTimeline(
   container: HTMLDivElement,
   parsed: ParsedVisualization,
   palette: PaletteColors,
   isDark: boolean,
-  onClickItem?: (lineNumber: number) => void,
-  exportDims?: D3ExportDimensions,
-  activeTagGroup?: string | null,
-  swimlaneTagGroup?: string | null,
-  onTagStateChange?: (
-    activeTagGroup: string | null,
-    swimlaneTagGroup: string | null
-  ) => void,
-  viewMode?: boolean
-): void {
+  exportDims: D3ExportDimensions | undefined,
+  activeTagGroup: string | null | undefined,
+  swimlaneTagGroup: string | null | undefined
+): TimelineSetup | null {
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
   const solid = parsed.solidFill === true;
 
@@ -3509,55 +3554,46 @@ export function renderTimeline(
     timelineEras,
     timelineMarkers,
     timelineSort,
-    timelineScale,
-    timelineSwimlanes,
     orientation,
   } = parsed;
-  const title = parsed.noTitle ? null : parsed.title;
-  if (timelineEvents.length === 0) return;
+  if (timelineEvents.length === 0) return null;
 
-  // When sort: tag is set and no explicit swimlane param, use the default
+  let resolvedSwimlaneTG: string | null = swimlaneTagGroup ?? null;
   if (
-    swimlaneTagGroup == null &&
+    resolvedSwimlaneTG == null &&
     timelineSort === 'tag' &&
     parsed.timelineDefaultSwimlaneTG
   ) {
-    swimlaneTagGroup = parsed.timelineDefaultSwimlaneTG;
+    resolvedSwimlaneTG = parsed.timelineDefaultSwimlaneTG;
   }
 
   const tooltip = createTooltip(container, palette, isDark);
 
   const width = exportDims?.width ?? container.clientWidth;
   const height = exportDims?.height ?? container.clientHeight;
-  if (width <= 0 || height <= 0) return;
+  if (width <= 0 || height <= 0) return null;
 
   const isVertical = orientation === 'vertical';
 
-  // Theme colors
   const textColor = palette.text;
   const mutedColor = palette.border;
   const bgColor = palette.bg;
   const bg = isDark ? palette.surface : palette.bg;
   const colors = getSeriesColors(palette);
 
-  // Assign colors to groups
   const groupColorMap = new Map<string, string>();
   timelineGroups.forEach((grp, i) => {
     groupColorMap.set(grp.name, grp.color ?? colors[i % colors.length]);
   });
 
-  // When tag-based swimlanes are active, compute lanes from tag values
-  // and populate groupColorMap with tag entry colors for lane headers.
-  type Lane = { name: string; events: TimelineEvent[] };
   let tagLanes: Lane[] | null = null;
 
-  if (swimlaneTagGroup) {
-    const tagKey = swimlaneTagGroup.toLowerCase();
+  if (resolvedSwimlaneTG) {
+    const tagKey = resolvedSwimlaneTG.toLowerCase();
     const tagGroup = parsed.timelineTagGroups.find(
       (g) => g.name.toLowerCase() === tagKey
     );
     if (tagGroup) {
-      // Collect events per tag value
       const buckets = new Map<string, TimelineEvent[]>();
       const otherEvents: TimelineEvent[] = [];
       for (const ev of timelineEvents) {
@@ -3571,7 +3607,6 @@ export function renderTimeline(
         }
       }
 
-      // Order lanes by earliest event date
       const laneEntries = [...buckets.entries()].sort((a, b) => {
         const aMin = Math.min(...a[1].map((e) => parseTimelineDate(e.date)));
         const bMin = Math.min(...b[1].map((e) => parseTimelineDate(e.date)));
@@ -3583,18 +3618,15 @@ export function renderTimeline(
         tagLanes.push({ name: '(Other)', events: otherEvents });
       }
 
-      // Populate groupColorMap from tag entry colors
       for (const entry of tagGroup.entries) {
         groupColorMap.set(entry.value, entry.color);
       }
     }
   }
 
-  // Determine effective color source: explicit colorTG > swimlaneTG > group
-  const effectiveColorTG = activeTagGroup ?? swimlaneTagGroup ?? null;
+  const effectiveColorTG = activeTagGroup ?? resolvedSwimlaneTG ?? null;
 
   function eventColor(ev: TimelineEvent): string {
-    // Tag color takes priority when a tag group is active
     if (effectiveColorTG) {
       const tagColor = resolveTagColor(
         ev.metadata,
@@ -3609,7 +3641,6 @@ export function renderTimeline(
     return textColor;
   }
 
-  // Convert dates to numeric values and find boundary dates
   let minDate = Infinity;
   let maxDate = -Infinity;
   let earliestStartDateStr = '';
@@ -3629,8 +3660,6 @@ export function renderTimeline(
     }
   }
 
-  // Eras and markers anchor the time axis — fold their dates into the
-  // domain so out-of-range items still render within the chart.
   for (const era of timelineEras) {
     const eraStartNum = parseTimelineDate(era.startDate);
     const eraEndNum = parseTimelineDate(era.endDate);
@@ -3657,11 +3686,70 @@ export function renderTimeline(
   }
   const datePadding = (maxDate - minDate) * 0.05 || 0.5;
 
-  const FADE_OPACITY = 0.1;
+  const tagLegendReserve = parsed.timelineTagGroups.length > 0 ? 36 : 0;
+
+  return {
+    width,
+    height,
+    isVertical,
+    tooltip,
+    solid,
+    textColor,
+    mutedColor,
+    bgColor,
+    bg,
+    swimlaneTagGroup: resolvedSwimlaneTG,
+    groupColorMap,
+    tagLanes,
+    eventColor,
+    minDate,
+    maxDate,
+    datePadding,
+    earliestStartDateStr,
+    latestEndDateStr,
+    tagLegendReserve,
+  };
+}
+
+// ============================================================
+// Timeline — hover helpers (extracted from renderTimeline)
+// ============================================================
+
+type TimelineHoverHelpers = {
+  FADE_OPACITY: number;
+  fadeToGroup: (
+    g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    groupName: string
+  ) => void;
+  fadeToEra: (
+    g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    eraStart: number,
+    eraEnd: number
+  ) => void;
+  fadeToMarker: (
+    g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    markerDate: number
+  ) => void;
+  fadeReset: (
+    g: d3Selection.Selection<SVGGElement, unknown, null, undefined>
+  ) => void;
+  fadeToTagValue: (
+    g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    tagKey: string,
+    tagValue: string
+  ) => void;
+  setTagAttrs: (
+    evG: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    ev: TimelineEvent
+  ) => void;
+};
 
-  // ------------------------------------------------------------------
-  // Shared hover helpers (operate on CSS classes, orientation-agnostic)
-  // ------------------------------------------------------------------
+/**
+ * Shared hover helpers for timeline rendering. Operate on CSS classes,
+ * orientation-agnostic. Used by all three rendering branches.
+ */
+function makeTimelineHoverHelpers(): TimelineHoverHelpers {
+  const FADE_OPACITY = 0.1;
 
   function fadeToGroup(
     g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
@@ -3765,11 +3853,10 @@ export function renderTimeline(
       'opacity',
       FADE_OPACITY
     );
-    // Fade legend entry dots/labels that don't match (keep group pill visible)
     g.selectAll<SVGGElement, unknown>('.tl-tag-legend-entry').each(function () {
       const el = d3Selection.select(this);
       const entryValue = el.attr('data-legend-entry');
-      if (entryValue === '__group__') return; // keep group pill at full opacity
+      if (entryValue === '__group__') return;
       const entryGroup = el.attr('data-tag-group');
       el.attr(
         'opacity',
@@ -3788,632 +3875,1167 @@ export function renderTimeline(
     }
   }
 
-  // Reserve space for tag legend at the top of chart content (below title/headers)
-  const tagLegendReserve = parsed.timelineTagGroups.length > 0 ? 36 : 0;
+  return {
+    FADE_OPACITY,
+    fadeToGroup,
+    fadeToEra,
+    fadeToMarker,
+    fadeReset,
+    fadeToTagValue,
+    setTagAttrs,
+  };
+}
 
-  // ================================================================
-  // VERTICAL orientation (time flows top→bottom)
-  // ================================================================
-  if (isVertical) {
-    const useGroupedVertical =
-      tagLanes != null ||
-      (timelineSort === 'group' && timelineGroups.length > 0);
-    if (useGroupedVertical) {
-      // === GROUPED: one column/lane per group, vertical ===
-      let laneNames: string[];
-      let laneEventsByName: Map<string, TimelineEvent[]>;
-
-      if (tagLanes) {
-        laneNames = tagLanes.map((l) => l.name);
-        laneEventsByName = new Map(tagLanes.map((l) => [l.name, l.events]));
-      } else {
-        const groupNames = timelineGroups.map((gr) => gr.name);
-        const ungroupedEvents = timelineEvents.filter(
-          (ev) => ev.group === null || !groupNames.includes(ev.group)
-        );
-        laneNames =
-          ungroupedEvents.length > 0 ? [...groupNames, '(Other)'] : groupNames;
-        laneEventsByName = new Map(
-          laneNames.map((name) => [
-            name,
-            timelineEvents.filter((ev) =>
-              name === '(Other)'
-                ? ev.group === null || !groupNames.includes(ev.group)
-                : ev.group === name
-            ),
-          ])
-        );
-      }
+// ============================================================
+// Timeline — tag-legend overlay (extracted from renderTimeline)
+// ============================================================
+
+function renderTimelineTagLegendOverlay(
+  container: HTMLDivElement,
+  parsed: ParsedVisualization,
+  palette: PaletteColors,
+  isDark: boolean,
+  setup: TimelineSetup,
+  hovers: TimelineHoverHelpers,
+  onClickItem: ((lineNumber: number) => void) | undefined,
+  exportDims: D3ExportDimensions | undefined,
+  swimlaneTagGroup: string | null | undefined,
+  activeTagGroup: string | null | undefined,
+  onTagStateChange:
+    | ((activeTagGroup: string | null, swimlaneTagGroup: string | null) => void)
+    | undefined,
+  viewMode: boolean | undefined,
+  exportMode?: boolean
+): void {
+  if (parsed.timelineTagGroups.length === 0) return;
 
-      const laneCount = laneNames.length;
-      const scaleMargin = timelineScale ? 40 : 0;
-      const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
-      const margin = {
-        top: 104 + markerMargin + tagLegendReserve,
-        right: 40 + scaleMargin,
-        bottom: 40,
-        left: 60 + scaleMargin,
+  const { width, textColor, groupColorMap, solid } = setup;
+  const { FADE_OPACITY, fadeReset, fadeToTagValue } = hovers;
+  const title = parsed.noTitle ? null : parsed.title;
+  const { timelineEvents } = parsed;
+
+  const LG_HEIGHT = TL_LEGEND_HEIGHT;
+  const LG_PILL_PAD = TL_LEGEND_PILL_PAD;
+  const LG_PILL_FONT_SIZE = TL_LEGEND_PILL_FONT_SIZE;
+  const LG_CAPSULE_PAD = TL_LEGEND_CAPSULE_PAD;
+  const LG_DOT_R = TL_LEGEND_DOT_R;
+  const LG_ENTRY_FONT_SIZE = TL_LEGEND_ENTRY_FONT_SIZE;
+  const LG_ENTRY_DOT_GAP = TL_LEGEND_ENTRY_DOT_GAP;
+  const LG_ENTRY_TRAIL = TL_LEGEND_ENTRY_TRAIL;
+  // LG_GROUP_GAP no longer needed — centralized legend handles spacing
+  const LG_ICON_W = 20; // swimlane icon area (icon + surrounding space) — local
+
+  const mainSvg = d3Selection.select(container).select<SVGSVGElement>('svg');
+  const mainG = mainSvg.select<SVGGElement>('g');
+  if (!mainSvg.empty() && !mainG.empty()) {
+    // Position legend at top, below title
+    const legendY = title ? 50 : 10;
+
+    // Pre-compute group widths (minified and expanded)
+    type LegendGroup = {
+      group: TagGroup;
+      minifiedWidth: number;
+      expandedWidth: number;
+    };
+    const legendGroups: LegendGroup[] = parsed.timelineTagGroups.map((g) => {
+      const pillW = measureLegendText(g.name, LG_PILL_FONT_SIZE) + LG_PILL_PAD;
+      // Expanded: pill + icon (unless viewMode) + entries
+      const iconSpace = viewMode ? 8 : LG_ICON_W + 4;
+      let entryX = LG_CAPSULE_PAD + pillW + iconSpace;
+      for (const entry of g.entries) {
+        const textX = entryX + LG_DOT_R * 2 + LG_ENTRY_DOT_GAP;
+        entryX =
+          textX +
+          measureLegendText(entry.value, LG_ENTRY_FONT_SIZE) +
+          LG_ENTRY_TRAIL;
+      }
+      return {
+        group: g,
+        minifiedWidth: pillW,
+        expandedWidth: entryX + LG_CAPSULE_PAD,
       };
-      const innerWidth = width - margin.left - margin.right;
-      const innerHeight = height - margin.top - margin.bottom;
-      const laneWidth = innerWidth / laneCount;
-
-      const yScale = d3Scale
-        .scaleLinear()
-        .domain([minDate - datePadding, maxDate + datePadding])
-        .range([0, innerHeight]);
-
-      const svg = d3Selection
-        .select(container)
-        .append('svg')
-        .attr('viewBox', `0 0 ${width} ${height}`)
-        .attr('width', exportDims ? width : '100%')
-        .attr('preserveAspectRatio', 'xMidYMin meet')
-        .style('background', bgColor);
-
-      const g = svg
+    });
+
+    // Two independent state axes: swimlane source + color source
+    let currentActiveGroup: string | null = activeTagGroup ?? null;
+    let currentSwimlaneGroup: string | null = swimlaneTagGroup ?? null;
+
+    /** Render the swimlane icon (3 horizontal bars of varying width) */
+    function drawSwimlaneIcon(
+      parent: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+      x: number,
+      y: number,
+      isSwimActive: boolean
+    ) {
+      const iconG = parent
         .append('g')
-        .attr('transform', `translate(${margin.left},${margin.top})`);
+        .attr('class', 'tl-swimlane-icon')
+        .attr('transform', `translate(${x}, ${y})`)
+        .style('cursor', 'pointer');
+
+      const barColor = isSwimActive ? palette.primary : palette.textMuted;
+      const barOpacity = isSwimActive ? 1 : 0.35;
+      const bars = [
+        { y: 0, w: 8 },
+        { y: 4, w: 12 },
+        { y: 8, w: 6 },
+      ];
+      for (const bar of bars) {
+        iconG
+          .append('rect')
+          .attr('x', 0)
+          .attr('y', bar.y)
+          .attr('width', bar.w)
+          .attr('height', 2)
+          .attr('rx', 1)
+          .attr('fill', barColor)
+          .attr('opacity', barOpacity);
+      }
+      return iconG;
+    }
 
-      renderChartTitle(
-        svg,
-        title,
-        parsed.titleLineNumber,
-        width,
-        textColor,
-        onClickItem
+    /** Full re-render with updated swimlane state */
+    function relayout() {
+      renderTimeline(
+        container,
+        parsed,
+        palette,
+        isDark,
+        onClickItem,
+        exportDims,
+        currentActiveGroup,
+        currentSwimlaneGroup,
+        onTagStateChange,
+        viewMode
       );
+    }
 
-      renderEras(
-        g,
-        timelineEras,
-        yScale,
-        true,
-        innerWidth,
-        innerHeight,
-        (s, e) => fadeToEra(g, s, e),
-        () => fadeReset(g),
-        timelineScale,
-        tooltip,
-        palette
-      );
+    function drawLegend() {
+      // Remove previous legend
+      mainSvg.selectAll('.tl-tag-legend-group').remove();
+      mainSvg.selectAll('.tl-tag-legend-container').remove();
+
+      // Effective color source: explicit color group > swimlane group
+      const effectiveColorKey =
+        (currentActiveGroup ?? currentSwimlaneGroup)?.toLowerCase() ?? null;
+
+      // In view mode, only show the color-driving tag group (expanded, non-interactive).
+      // Skip the swimlane group if it's separate from the color group (lane headers already label it).
+      const visibleGroups = viewMode
+        ? legendGroups.filter(
+            (lg) =>
+              effectiveColorKey != null &&
+              lg.group.name.toLowerCase() === effectiveColorKey
+          )
+        : legendGroups;
 
-      renderMarkers(
-        g,
-        timelineMarkers,
-        yScale,
-        true,
-        innerWidth,
-        innerHeight,
-        (d) => fadeToMarker(g, d),
-        () => fadeReset(g),
-        timelineScale,
-        tooltip,
-        palette
-      );
+      if (visibleGroups.length === 0) return;
 
-      if (timelineScale) {
-        renderTimeScale(
-          g,
-          yScale,
-          true,
-          innerWidth,
-          innerHeight,
-          textColor,
-          minDate,
-          maxDate,
-          formatBoundaryLabel(earliestStartDateStr, latestEndDateStr),
-          formatBoundaryLabel(latestEndDateStr, earliestStartDateStr)
+      // Legend container for data-legend-active attribute
+      const legendContainer = mainSvg
+        .append('g')
+        .attr('class', 'tl-tag-legend-container');
+      if (currentActiveGroup) {
+        legendContainer.attr(
+          'data-legend-active',
+          currentActiveGroup.toLowerCase()
         );
       }
 
-      // Render swimlane backgrounds for vertical lanes
-      if (timelineSwimlanes || tagLanes) {
-        laneNames.forEach((laneName, laneIdx) => {
-          const laneX = laneIdx * laneWidth;
-          const fillColor = laneIdx % 2 === 0 ? textColor : 'transparent';
-          g.append('rect')
-            .attr('class', 'tl-swimlane')
-            .attr('data-group', laneName)
-            .attr('x', laneX)
-            .attr('y', 0)
-            .attr('width', laneWidth)
-            .attr('height', innerHeight)
-            .attr('fill', fillColor)
-            .attr('opacity', 0.06);
-        });
-      }
+      // Render tag groups via centralized legend system
+      const iconAddon = viewMode ? 0 : LG_ICON_W;
+      const centralGroups = visibleGroups.map((lg) => ({
+        name: lg.group.name,
+        entries: lg.group.entries.map((e) => ({
+          value: e.value,
+          color: e.color,
+        })),
+      }));
 
-      laneNames.forEach((laneName, laneIdx) => {
-        const laneX = laneIdx * laneWidth;
-        const laneColor = groupColorMap.get(laneName) ?? textColor;
-        const laneCenter = laneX + laneWidth / 2;
+      // Determine effective active group for centralized renderer
+      const centralActive = viewMode ? effectiveColorKey : currentActiveGroup;
 
-        const headerG = g
-          .append('g')
-          .attr('class', 'tl-lane-header')
-          .attr('data-group', laneName)
-          .style('cursor', 'pointer')
-          .on('mouseenter', () => fadeToGroup(g, laneName))
-          .on('mouseleave', () => fadeReset(g));
+      const centralConfig: LegendConfig = {
+        groups: centralGroups,
+        position: { placement: 'top-center', titleRelation: 'below-title' },
+        mode: exportMode ? 'export' : 'preview',
+        capsulePillAddonWidth: iconAddon,
+      };
+      const centralState: LegendState = { activeGroup: centralActive };
+
+      const centralCallbacks: LegendCallbacks = viewMode
+        ? {}
+        : {
+            onGroupToggle: (groupName) => {
+              currentActiveGroup =
+                currentActiveGroup === groupName.toLowerCase()
+                  ? null
+                  : groupName.toLowerCase();
+              drawLegend();
+              recolorEvents();
+              onTagStateChange?.(currentActiveGroup, currentSwimlaneGroup);
+            },
+            onEntryHover: (groupName, entryValue) => {
+              const tagKey = groupName.toLowerCase();
+              if (entryValue) {
+                const tagVal = entryValue.toLowerCase();
+                fadeToTagValue(mainG, tagKey, tagVal);
+                mainSvg
+                  .selectAll<SVGGElement, unknown>('[data-legend-entry]')
+                  .each(function () {
+                    const el = d3Selection.select(this);
+                    const ev = el.attr('data-legend-entry');
+                    const eg =
+                      el.attr('data-tag-group') ??
+                      (el.node() as Element)
+                        ?.closest?.('[data-tag-group]')
+                        ?.getAttribute('data-tag-group');
+                    el.attr(
+                      'opacity',
+                      eg === tagKey && ev === tagVal ? 1 : FADE_OPACITY
+                    );
+                  });
+              } else {
+                fadeReset(mainG);
+                mainSvg
+                  .selectAll<SVGGElement, unknown>('[data-legend-entry]')
+                  .attr('opacity', 1);
+              }
+            },
+            onGroupRendered: (groupName, groupEl, isActive) => {
+              const groupKey = groupName.toLowerCase();
+              groupEl.attr('data-tag-group', groupKey);
+              if (isActive && !viewMode) {
+                const isSwimActive =
+                  currentSwimlaneGroup != null &&
+                  currentSwimlaneGroup.toLowerCase() === groupKey;
+                const pillWidth =
+                  measureLegendText(groupName, LG_PILL_FONT_SIZE) + LG_PILL_PAD;
+                const pillXOff = LG_CAPSULE_PAD;
+                const iconX = pillXOff + pillWidth + 5;
+                const iconY = (LG_HEIGHT - 10) / 2;
+                const iconEl = drawSwimlaneIcon(
+                  groupEl,
+                  iconX,
+                  iconY,
+                  isSwimActive
+                );
+                iconEl
+                  .attr('data-swimlane-toggle', groupKey)
+                  .on('click', (event: MouseEvent) => {
+                    event.stopPropagation();
+                    currentSwimlaneGroup =
+                      currentSwimlaneGroup === groupKey ? null : groupKey;
+                    onTagStateChange?.(
+                      currentActiveGroup,
+                      currentSwimlaneGroup
+                    );
+                    relayout();
+                  });
+              }
+            },
+          };
+
+      const legendInnerG = legendContainer
+        .append('g')
+        .attr('transform', `translate(0, ${legendY})`);
+      renderLegendD3(
+        legendInnerG,
+        centralConfig,
+        centralState,
+        palette,
+        isDark,
+        centralCallbacks,
+        width
+      );
+    }
 
-        headerG
-          .append('text')
-          .attr('x', laneCenter)
-          .attr('y', -15)
-          .attr('text-anchor', 'middle')
-          .attr('fill', laneColor)
-          .attr('font-size', '12px')
-          .attr('font-weight', '600')
-          .text(laneName);
-
-        g.append('line')
-          .attr('x1', laneCenter)
-          .attr('y1', 0)
-          .attr('x2', laneCenter)
-          .attr('y2', innerHeight)
-          .attr('stroke', mutedColor)
-          .attr('stroke-width', 1)
-          .attr('stroke-dasharray', '4,4');
-
-        const laneEvents = laneEventsByName.get(laneName) ?? [];
-
-        for (const ev of laneEvents) {
-          const y = yScale(parseTimelineDate(ev.date));
-          const evG = g
-            .append('g')
-            .attr('class', 'tl-event')
-            .attr('data-group', laneName)
-            .attr('data-line-number', String(ev.lineNumber))
-            .attr('data-date', String(parseTimelineDate(ev.date)))
-            .attr(
-              'data-end-date',
-              ev.endDate ? String(parseTimelineDate(ev.endDate)) : null
-            )
-            .style('cursor', 'pointer')
-            .on('mouseenter', function (event: MouseEvent) {
-              fadeToGroup(g, laneName);
-              showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-            })
-            .on('mouseleave', function () {
-              fadeReset(g);
-              hideTooltip(tooltip);
-            })
-            .on('mousemove', function (event: MouseEvent) {
-              showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-            })
-            .on('click', () => {
-              if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
-            });
-          setTagAttrs(evG, ev);
-
-          const evColor = eventColor(ev);
-
-          if (ev.endDate) {
-            const y2 = yScale(parseTimelineDate(ev.endDate));
-            const rectH = Math.max(y2 - y, 4);
-
-            let fill: string = shapeFill(palette, evColor, isDark, { solid });
-            let stroke: string = evColor;
-            if (ev.uncertain) {
-              const gradientId = `uncertain-vg-${ev.lineNumber}`;
-              const strokeGradientId = `uncertain-vg-s-${ev.lineNumber}`;
-              const defs =
-                svg.select('defs').node() || svg.append('defs').node();
-              const defsEl = d3Selection.select(defs as Element);
-              defsEl
-                .append('linearGradient')
-                .attr('id', gradientId)
-                .attr('x1', '0%')
-                .attr('y1', '0%')
-                .attr('x2', '0%')
-                .attr('y2', '100%')
-                .selectAll('stop')
-                .data([
-                  { offset: '0%', opacity: 1 },
-                  { offset: '80%', opacity: 1 },
-                  { offset: '100%', opacity: 0 },
-                ])
-                .enter()
-                .append('stop')
-                .attr('offset', (d) => d.offset)
-                .attr('stop-color', mix(laneColor, bg, 30))
-                .attr('stop-opacity', (d) => d.opacity);
-              defsEl
-                .append('linearGradient')
-                .attr('id', strokeGradientId)
-                .attr('x1', '0%')
-                .attr('y1', '0%')
-                .attr('x2', '0%')
-                .attr('y2', '100%')
-                .selectAll('stop')
-                .data([
-                  { offset: '0%', opacity: 1 },
-                  { offset: '80%', opacity: 1 },
-                  { offset: '100%', opacity: 0 },
-                ])
-                .enter()
-                .append('stop')
-                .attr('offset', (d) => d.offset)
-                .attr('stop-color', evColor)
-                .attr('stop-opacity', (d) => d.opacity);
-              fill = `url(#${gradientId})`;
-              stroke = `url(#${strokeGradientId})`;
-            }
+    // Build a quick lineNumber→event lookup
+    const eventByLine = new Map<string, TimelineEvent>();
+    for (const ev of timelineEvents) {
+      eventByLine.set(String(ev.lineNumber), ev);
+    }
 
-            evG
-              .append('rect')
-              .attr('x', laneCenter - 6)
-              .attr('y', y)
-              .attr('width', 12)
-              .attr('height', rectH)
-              .attr('rx', 4)
-              .attr('fill', fill)
-              .attr('stroke', stroke)
-              .attr('stroke-width', 2);
-            evG
-              .append('text')
-              .attr('x', laneCenter + 14)
-              .attr('y', y + rectH / 2)
-              .attr('dy', '0.35em')
-              .attr('fill', textColor)
-              .attr('font-size', '10px')
-              .text(ev.label);
-          } else {
-            evG
-              .append('circle')
-              .attr('cx', laneCenter)
-              .attr('cy', y)
-              .attr('r', 4)
-              .attr('fill', shapeFill(palette, evColor, isDark, { solid }))
-              .attr('stroke', evColor)
-              .attr('stroke-width', 2);
-            evG
-              .append('text')
-              .attr('x', laneCenter + 10)
-              .attr('y', y)
-              .attr('dy', '0.35em')
-              .attr('fill', textColor)
-              .attr('font-size', '10px')
-              .text(ev.label);
-          }
+    function recolorEvents() {
+      const colorTG = currentActiveGroup ?? swimlaneTagGroup ?? null;
+      mainG.selectAll<SVGGElement, unknown>('.tl-event').each(function () {
+        const el = d3Selection.select(this);
+        const lineNum = el.attr('data-line-number');
+        const ev = lineNum ? eventByLine.get(lineNum) : undefined;
+        if (!ev) return;
+
+        let color: string;
+        if (colorTG) {
+          const tagColor = resolveTagColor(
+            ev.metadata,
+            parsed.timelineTagGroups,
+            colorTG
+          );
+          color =
+            tagColor ??
+            (ev.group && groupColorMap.has(ev.group)
+              ? groupColorMap.get(ev.group)!
+              : textColor);
+        } else {
+          color =
+            ev.group && groupColorMap.has(ev.group)
+              ? groupColorMap.get(ev.group)!
+              : textColor;
         }
+        el.selectAll('rect')
+          .attr('fill', shapeFill(palette, color, isDark, { solid }))
+          .attr('stroke', color);
+        el.selectAll('circle:not(.tl-event-point-outline)')
+          .attr('fill', shapeFill(palette, color, isDark, { solid }))
+          .attr('stroke', color);
       });
-    } else {
-      // === TIME SORT, vertical: single vertical axis ===
-      const scaleMargin = timelineScale ? 40 : 0;
-      const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
-      const margin = {
-        top: 104 + markerMargin + tagLegendReserve,
-        right: 200,
-        bottom: 40,
-        left: 60 + scaleMargin,
-      };
-      const innerWidth = width - margin.left - margin.right;
-      const innerHeight = height - margin.top - margin.bottom;
-      const axisX = 20;
+    }
 
-      const yScale = d3Scale
-        .scaleLinear()
-        .domain([minDate - datePadding, maxDate + datePadding])
-        .range([0, innerHeight]);
+    drawLegend();
+  }
+}
 
-      const sorted = timelineEvents
-        .slice()
-        .sort((a, b) => parseTimelineDate(a.date) - parseTimelineDate(b.date));
+// ============================================================
+// Timeline — horizontal-time-sort renderer (extracted from renderTimeline)
+// ============================================================
 
-      const svg = d3Selection
-        .select(container)
-        .append('svg')
-        .attr('viewBox', `0 0 ${width} ${height}`)
-        .attr('width', exportDims ? width : '100%')
-        .attr('preserveAspectRatio', 'xMidYMin meet')
-        .style('background', bgColor);
+function renderTimelineHorizontalTimeSort(
+  container: HTMLDivElement,
+  parsed: ParsedVisualization,
+  palette: PaletteColors,
+  isDark: boolean,
+  setup: TimelineSetup,
+  hovers: TimelineHoverHelpers,
+  onClickItem: ((lineNumber: number) => void) | undefined,
+  _exportDims: D3ExportDimensions | undefined,
+  _swimlaneTagGroup: string | null | undefined,
+  _activeTagGroup: string | null | undefined,
+  _onTagStateChange:
+    | ((activeTagGroup: string | null, swimlaneTagGroup: string | null) => void)
+    | undefined,
+  _viewMode: boolean | undefined
+): void {
+  const {
+    width,
+    height,
+    tooltip,
+    solid,
+    textColor,
+    bgColor,
+    bg,
+    groupColorMap,
+    eventColor,
+    minDate,
+    maxDate,
+    datePadding,
+    earliestStartDateStr,
+    latestEndDateStr,
+    tagLegendReserve,
+  } = setup;
+  const { fadeToGroup, fadeToEra, fadeToMarker, fadeReset, setTagAttrs } =
+    hovers;
+  const {
+    timelineEvents,
+    timelineGroups,
+    timelineEras,
+    timelineMarkers,
+    timelineScale,
+  } = parsed;
+  const title = parsed.noTitle ? null : parsed.title;
 
-      const g = svg
-        .append('g')
-        .attr('transform', `translate(${margin.left},${margin.top})`);
+  const BAR_H = 22;
+
+  // === TIME SORT, horizontal: each event on its own row ===
+  const sorted = timelineEvents
+    .slice()
+    .sort((a, b) => parseTimelineDate(a.date) - parseTimelineDate(b.date));
+
+  const scaleMargin = timelineScale ? 24 : 0;
+  // Per-feature header rows: era + marker each get their own row, reserved
+  // only when present (mirrors the gantt header stack).
+  const ERA_ROW_H = 22;
+  const MARKER_ROW_H = 22;
+  const eraReserve = timelineEras.length > 0 ? ERA_ROW_H : 0;
+  const markerReserve = timelineMarkers.length > 0 ? MARKER_ROW_H : 0;
+  const topScaleH = timelineScale ? 40 : 0;
+  const margin = {
+    top: 104 + topScaleH + eraReserve + markerReserve + tagLegendReserve,
+    right: 40,
+    bottom: 40 + scaleMargin,
+    left: 60,
+  };
+  const markerLabelY = markerReserve ? -(topScaleH + MARKER_ROW_H / 2) : 0;
+  const eraLabelY = eraReserve
+    ? -(topScaleH + markerReserve + ERA_ROW_H / 2)
+    : 0;
+  const innerWidth = width - margin.left - margin.right;
+  const innerHeight = height - margin.top - margin.bottom;
+  const rowH = Math.min(28, innerHeight / sorted.length);
 
-      renderChartTitle(
-        svg,
-        title,
-        parsed.titleLineNumber,
-        width,
-        textColor,
-        onClickItem
-      );
+  const xScale = d3Scale
+    .scaleLinear()
+    .domain([minDate - datePadding, maxDate + datePadding])
+    .range([0, innerWidth]);
 
-      renderEras(
-        g,
-        timelineEras,
-        yScale,
-        true,
-        innerWidth,
-        innerHeight,
-        (s, e) => fadeToEra(g, s, e),
-        () => fadeReset(g),
-        timelineScale,
-        tooltip,
-        palette
-      );
+  const svg = d3Selection
+    .select(container)
+    .append('svg')
+    .attr('width', width)
+    .attr('height', height)
+    .style('background', bgColor);
 
-      renderMarkers(
-        g,
-        timelineMarkers,
-        yScale,
-        true,
-        innerWidth,
-        innerHeight,
-        (d) => fadeToMarker(g, d),
-        () => fadeReset(g),
-        timelineScale,
-        tooltip,
-        palette
-      );
+  const g = svg
+    .append('g')
+    .attr('transform', `translate(${margin.left},${margin.top})`);
 
-      if (timelineScale) {
-        renderTimeScale(
-          g,
-          yScale,
-          true,
-          innerWidth,
-          innerHeight,
-          textColor,
-          minDate,
-          maxDate,
-          formatBoundaryLabel(earliestStartDateStr, latestEndDateStr),
-          formatBoundaryLabel(latestEndDateStr, earliestStartDateStr)
-        );
-      }
+  renderChartTitle(
+    svg,
+    title,
+    parsed.titleLineNumber,
+    width,
+    textColor,
+    onClickItem
+  );
 
-      // Group legend (pill style)
-      if (timelineGroups.length > 0) {
-        renderTimelineGroupLegend(
-          g,
-          timelineGroups,
-          groupColorMap,
-          textColor,
-          palette,
-          isDark,
-          -55,
-          (name) => fadeToGroup(g, name),
-          () => fadeReset(g)
-        );
-      }
+  renderEras(
+    g,
+    timelineEras,
+    xScale,
+    false,
+    innerWidth,
+    innerHeight,
+    (s, e) => fadeToEra(g, s, e),
+    () => fadeReset(g),
+    timelineScale,
+    tooltip,
+    palette,
+    eraReserve ? eraLabelY : undefined
+  );
 
-      g.append('line')
-        .attr('x1', axisX)
-        .attr('y1', 0)
-        .attr('x2', axisX)
-        .attr('y2', innerHeight)
-        .attr('stroke', mutedColor)
-        .attr('stroke-width', 1)
-        .attr('stroke-dasharray', '4,4');
+  renderMarkers(
+    g,
+    timelineMarkers,
+    xScale,
+    false,
+    innerWidth,
+    innerHeight,
+    (d) => fadeToMarker(g, d),
+    () => fadeReset(g),
+    timelineScale,
+    tooltip,
+    palette,
+    markerReserve ? markerLabelY : undefined
+  );
 
-      for (const ev of sorted) {
-        const y = yScale(parseTimelineDate(ev.date));
-        const color = eventColor(ev);
+  if (timelineScale) {
+    renderTimeScale(
+      g,
+      xScale,
+      false,
+      innerWidth,
+      innerHeight,
+      textColor,
+      minDate,
+      maxDate,
+      formatBoundaryLabel(earliestStartDateStr, latestEndDateStr),
+      formatBoundaryLabel(latestEndDateStr, earliestStartDateStr)
+    );
+  }
 
-        const evG = g
-          .append('g')
-          .attr('class', 'tl-event')
-          .attr('data-group', ev.group || '')
-          .attr('data-line-number', String(ev.lineNumber))
-          .attr('data-date', String(parseTimelineDate(ev.date)))
-          .attr(
-            'data-end-date',
-            ev.endDate ? String(parseTimelineDate(ev.endDate)) : null
-          )
-          .style('cursor', 'pointer')
-          .on('mouseenter', function (event: MouseEvent) {
-            if (ev.group && timelineGroups.length > 0) fadeToGroup(g, ev.group);
-            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-          })
-          .on('mouseleave', function () {
-            fadeReset(g);
-            hideTooltip(tooltip);
-          })
-          .on('mousemove', function (event: MouseEvent) {
-            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-          })
-          .on('click', () => {
-            if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
-          });
-        setTagAttrs(evG, ev);
+  // Group legend at top-left (pill style)
+  if (timelineGroups.length > 0) {
+    const legendY = timelineScale ? -75 : -55;
+    renderTimelineGroupLegend(
+      g,
+      timelineGroups,
+      groupColorMap,
+      textColor,
+      palette,
+      isDark,
+      legendY,
+      (name) => fadeToGroup(g, name),
+      () => fadeReset(g)
+    );
+  }
 
-        if (ev.endDate) {
-          const y2 = yScale(parseTimelineDate(ev.endDate));
-          const rectH = Math.max(y2 - y, 4);
+  sorted.forEach((ev, i) => {
+    // Marker labels live in their reserved row above the chart, so the
+    // first event sits at the chart top edge.
+    const y = i * rowH + rowH / 2;
+    const x = xScale(parseTimelineDate(ev.date));
+    const color = eventColor(ev);
 
-          let fill: string = shapeFill(palette, color, isDark, { solid });
-          let stroke: string = color;
-          if (ev.uncertain) {
-            const gradientId = `uncertain-v-${ev.lineNumber}`;
-            const strokeGradientId = `uncertain-v-s-${ev.lineNumber}`;
-            const defs = svg.select('defs').node() || svg.append('defs').node();
-            const defsEl = d3Selection.select(defs as Element);
-            defsEl
-              .append('linearGradient')
-              .attr('id', gradientId)
-              .attr('x1', '0%')
-              .attr('y1', '0%')
-              .attr('x2', '0%')
-              .attr('y2', '100%')
-              .selectAll('stop')
-              .data([
-                { offset: '0%', opacity: 1 },
-                { offset: '80%', opacity: 1 },
-                { offset: '100%', opacity: 0 },
-              ])
-              .enter()
-              .append('stop')
-              .attr('offset', (d) => d.offset)
-              .attr('stop-color', mix(color, bg, 30))
-              .attr('stop-opacity', (d) => d.opacity);
-            defsEl
-              .append('linearGradient')
-              .attr('id', strokeGradientId)
-              .attr('x1', '0%')
-              .attr('y1', '0%')
-              .attr('x2', '0%')
-              .attr('y2', '100%')
-              .selectAll('stop')
-              .data([
-                { offset: '0%', opacity: 1 },
-                { offset: '80%', opacity: 1 },
-                { offset: '100%', opacity: 0 },
-              ])
-              .enter()
-              .append('stop')
-              .attr('offset', (d) => d.offset)
-              .attr('stop-color', color)
-              .attr('stop-opacity', (d) => d.opacity);
-            fill = `url(#${gradientId})`;
-            stroke = `url(#${strokeGradientId})`;
+    const evG = g
+      .append('g')
+      .attr('class', 'tl-event')
+      .attr('data-group', ev.group || '')
+      .attr('data-line-number', String(ev.lineNumber))
+      .attr('data-date', String(parseTimelineDate(ev.date)))
+      .attr(
+        'data-end-date',
+        ev.endDate ? String(parseTimelineDate(ev.endDate)) : null
+      )
+      .style('cursor', 'pointer')
+      .on('mouseenter', function (event: MouseEvent) {
+        if (ev.group && timelineGroups.length > 0) fadeToGroup(g, ev.group);
+        if (timelineScale) {
+          showEventDatesOnScale(
+            g,
+            xScale,
+            ev.date,
+            ev.endDate,
+            innerHeight,
+            color
+          );
+        } else {
+          showTooltip(tooltip, buildEventTooltipHtml(ev), event);
+        }
+      })
+      .on('mouseleave', function () {
+        fadeReset(g);
+        if (timelineScale) {
+          hideEventDatesOnScale(g);
+        } else {
+          hideTooltip(tooltip);
+        }
+      })
+      .on('mousemove', function (event: MouseEvent) {
+        if (!timelineScale) {
+          showTooltip(tooltip, buildEventTooltipHtml(ev), event);
+        }
+      })
+      .on('click', () => {
+        if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
+      });
+    setTagAttrs(evG, ev);
+
+    if (ev.endDate) {
+      const x2 = xScale(parseTimelineDate(ev.endDate));
+      const rectW = Math.max(x2 - x, 4);
+      // Estimate label width (~7px per char at 13px font) + padding
+      const estLabelWidth = ev.label.length * 7 + 16;
+      const labelFitsInside = rectW >= estLabelWidth;
+
+      let fill: string = shapeFill(palette, color, isDark, { solid });
+      let stroke: string = color;
+      if (ev.uncertain) {
+        // Create gradient for uncertain end - fades last 20%
+        const gradientId = `uncertain-ts-${ev.lineNumber}`;
+        const strokeGradientId = `uncertain-ts-s-${ev.lineNumber}`;
+        const defs = svg.select('defs').node() || svg.append('defs').node();
+        const defsEl = d3Selection.select(defs as Element);
+        defsEl
+          .append('linearGradient')
+          .attr('id', gradientId)
+          .attr('x1', '0%')
+          .attr('y1', '0%')
+          .attr('x2', '100%')
+          .attr('y2', '0%')
+          .selectAll('stop')
+          .data([
+            { offset: '0%', opacity: 1 },
+            { offset: '80%', opacity: 1 },
+            { offset: '100%', opacity: 0 },
+          ])
+          .enter()
+          .append('stop')
+          .attr('offset', (d) => d.offset)
+          .attr('stop-color', mix(color, bg, 30))
+          .attr('stop-opacity', (d) => d.opacity);
+        defsEl
+          .append('linearGradient')
+          .attr('id', strokeGradientId)
+          .attr('x1', '0%')
+          .attr('y1', '0%')
+          .attr('x2', '100%')
+          .attr('y2', '0%')
+          .selectAll('stop')
+          .data([
+            { offset: '0%', opacity: 1 },
+            { offset: '80%', opacity: 1 },
+            { offset: '100%', opacity: 0 },
+          ])
+          .enter()
+          .append('stop')
+          .attr('offset', (d) => d.offset)
+          .attr('stop-color', color)
+          .attr('stop-opacity', (d) => d.opacity);
+        fill = `url(#${gradientId})`;
+        stroke = `url(#${strokeGradientId})`;
+      }
+
+      evG
+        .append('rect')
+        .attr('x', x)
+        .attr('y', y - BAR_H / 2)
+        .attr('width', rectW)
+        .attr('height', BAR_H)
+        .attr('rx', 4)
+        .attr('fill', fill)
+        .attr('stroke', stroke)
+        .attr('stroke-width', 2);
+
+      if (labelFitsInside) {
+        // Text inside bar - use textColor for readability on muted fill
+        evG
+          .append('text')
+          .attr('x', x + 8)
+          .attr('y', y)
+          .attr('dy', '0.35em')
+          .attr('text-anchor', 'start')
+          .attr('fill', textColor)
+          .attr('font-size', '13px')
+          .text(ev.label);
+      } else {
+        // Text outside bar - check if it fits on left or must go right
+        const wouldFlipLeft = x + rectW > innerWidth * 0.6;
+        const labelFitsLeft = x - 6 - estLabelWidth > 0;
+        const flipLeft = wouldFlipLeft && labelFitsLeft;
+        evG
+          .append('text')
+          .attr('x', flipLeft ? x - 6 : x + rectW + 6)
+          .attr('y', y)
+          .attr('dy', '0.35em')
+          .attr('text-anchor', flipLeft ? 'end' : 'start')
+          .attr('fill', textColor)
+          .attr('font-size', '13px')
+          .text(ev.label);
+      }
+    } else {
+      // Point event (no end date) - render as circle with label
+      const estLabelWidth = ev.label.length * 7;
+      // Only flip left if past 60% AND label fits without going off-chart
+      const wouldFlipLeft = x > innerWidth * 0.6;
+      const labelFitsLeft = x - 10 - estLabelWidth > 0;
+      const flipLeft = wouldFlipLeft && labelFitsLeft;
+      evG
+        .append('circle')
+        .attr('cx', x)
+        .attr('cy', y)
+        .attr('r', 5)
+        .attr('fill', shapeFill(palette, color, isDark, { solid }))
+        .attr('stroke', color)
+        .attr('stroke-width', 2);
+      evG
+        .append('text')
+        .attr('x', flipLeft ? x - 10 : x + 10)
+        .attr('y', y)
+        .attr('dy', '0.35em')
+        .attr('text-anchor', flipLeft ? 'end' : 'start')
+        .attr('fill', textColor)
+        .attr('font-size', '12px')
+        .text(ev.label);
+    }
+  });
+}
+
+// ============================================================
+// Timeline — horizontal-grouped renderer (extracted from renderTimeline)
+// ============================================================
+
+function renderTimelineHorizontalGrouped(
+  container: HTMLDivElement,
+  parsed: ParsedVisualization,
+  palette: PaletteColors,
+  isDark: boolean,
+  setup: TimelineSetup,
+  hovers: TimelineHoverHelpers,
+  onClickItem: ((lineNumber: number) => void) | undefined,
+  _exportDims: D3ExportDimensions | undefined,
+  _swimlaneTagGroup: string | null | undefined,
+  _activeTagGroup: string | null | undefined,
+  _onTagStateChange:
+    | ((activeTagGroup: string | null, swimlaneTagGroup: string | null) => void)
+    | undefined,
+  _viewMode: boolean | undefined
+): void {
+  const {
+    width,
+    height,
+    tooltip,
+    solid,
+    textColor,
+    bgColor,
+    bg,
+    groupColorMap,
+    tagLanes,
+    eventColor,
+    minDate,
+    maxDate,
+    datePadding,
+    earliestStartDateStr,
+    latestEndDateStr,
+    tagLegendReserve,
+  } = setup;
+  const { fadeToGroup, fadeToEra, fadeToMarker, fadeReset, setTagAttrs } =
+    hovers;
+  const {
+    timelineEvents,
+    timelineGroups,
+    timelineEras,
+    timelineMarkers,
+    timelineScale,
+    timelineSwimlanes,
+  } = parsed;
+  const title = parsed.noTitle ? null : parsed.title;
+
+  const BAR_H = 22;
+  const GROUP_GAP = 12;
+
+  // === GROUPED: swim-lanes stacked vertically, events on own rows ===
+  let lanes: Lane[];
+
+  if (tagLanes) {
+    lanes = tagLanes;
+  } else {
+    const groupNames = timelineGroups.map((gr) => gr.name);
+    const ungroupedEvents = timelineEvents.filter(
+      (ev) => ev.group === null || !groupNames.includes(ev.group)
+    );
+    const laneNames =
+      ungroupedEvents.length > 0 ? [...groupNames, '(Other)'] : groupNames;
+    lanes = laneNames.map((name) => ({
+      name,
+      events: timelineEvents.filter((ev) =>
+        name === '(Other)'
+          ? ev.group === null || !groupNames.includes(ev.group)
+          : ev.group === name
+      ),
+    }));
+  }
+
+  const totalEventRows = lanes.reduce((s, l) => s + l.events.length, 0);
+  const scaleMargin = timelineScale ? 24 : 0;
+  // Per-feature header rows: era + marker each get their own row, reserved
+  // only when present (mirrors the gantt header stack).
+  const ERA_ROW_H = 22;
+  const MARKER_ROW_H = 22;
+  const eraReserve = timelineEras.length > 0 ? ERA_ROW_H : 0;
+  const markerReserve = timelineMarkers.length > 0 ? MARKER_ROW_H : 0;
+  const topScaleH = timelineScale ? 40 : 0;
+  // Calculate left margin based on longest group name (~7px per char + padding)
+  const maxGroupNameLen = Math.max(...lanes.map((l) => l.name.length));
+  const dynamicLeftMargin = Math.max(120, maxGroupNameLen * 7 + 30);
+  // Group-sorted doesn't need legend space (group names shown on left)
+  const baseTopMargin = title ? 50 : 20;
+  const margin = {
+    top:
+      baseTopMargin + topScaleH + eraReserve + markerReserve + tagLegendReserve,
+    right: 40,
+    bottom: 40 + scaleMargin,
+    left: dynamicLeftMargin,
+  };
+  // Y offsets for label rows (negative = above chart's y=0).
+  const markerLabelY = markerReserve ? -(topScaleH + MARKER_ROW_H / 2) : 0;
+  const eraLabelY = eraReserve
+    ? -(topScaleH + markerReserve + ERA_ROW_H / 2)
+    : 0;
+  const innerWidth = width - margin.left - margin.right;
+  const innerHeight = height - margin.top - margin.bottom;
+  const totalGaps = (lanes.length - 1) * GROUP_GAP;
+  const rowH = Math.min(28, (innerHeight - totalGaps) / totalEventRows);
+
+  const xScale = d3Scale
+    .scaleLinear()
+    .domain([minDate - datePadding, maxDate + datePadding])
+    .range([0, innerWidth]);
+
+  const svg = d3Selection
+    .select(container)
+    .append('svg')
+    .attr('width', width)
+    .attr('height', height)
+    .style('background', bgColor);
+
+  const g = svg
+    .append('g')
+    .attr('transform', `translate(${margin.left},${margin.top})`);
+
+  renderChartTitle(
+    svg,
+    title,
+    parsed.titleLineNumber,
+    width,
+    textColor,
+    onClickItem
+  );
+
+  renderEras(
+    g,
+    timelineEras,
+    xScale,
+    false,
+    innerWidth,
+    innerHeight,
+    (s, e) => fadeToEra(g, s, e),
+    () => fadeReset(g),
+    timelineScale,
+    tooltip,
+    palette,
+    eraReserve ? eraLabelY : undefined
+  );
+
+  renderMarkers(
+    g,
+    timelineMarkers,
+    xScale,
+    false,
+    innerWidth,
+    innerHeight,
+    (d) => fadeToMarker(g, d),
+    () => fadeReset(g),
+    timelineScale,
+    tooltip,
+    palette,
+    markerReserve ? markerLabelY : undefined
+  );
+
+  if (timelineScale) {
+    renderTimeScale(
+      g,
+      xScale,
+      false,
+      innerWidth,
+      innerHeight,
+      textColor,
+      minDate,
+      maxDate,
+      formatBoundaryLabel(earliestStartDateStr, latestEndDateStr),
+      formatBoundaryLabel(latestEndDateStr, earliestStartDateStr)
+    );
+  }
+
+  // Marker labels now live in their reserved row above the chart, so
+  // events can start at y=0 (chart top edge).
+  let curY = 0;
+
+  // Render swimlane backgrounds first (so they appear behind events)
+  // Extend into left margin to include group names
+  if (timelineSwimlanes || tagLanes) {
+    let swimY = 0;
+    lanes.forEach((lane, idx) => {
+      const laneSpan = lane.events.length * rowH;
+      // Alternate between light gray and transparent for visual separation
+      const fillColor = idx % 2 === 0 ? textColor : 'transparent';
+      g.append('rect')
+        .attr('class', 'tl-swimlane')
+        .attr('data-group', lane.name)
+        .attr('x', -margin.left)
+        .attr('y', swimY)
+        .attr('width', innerWidth + margin.left)
+        .attr('height', laneSpan + (idx < lanes.length - 1 ? GROUP_GAP : 0))
+        .attr('fill', fillColor)
+        .attr('opacity', 0.06);
+      swimY += laneSpan + GROUP_GAP;
+    });
+  }
+
+  for (const lane of lanes) {
+    const laneColor = groupColorMap.get(lane.name) ?? textColor;
+    const laneSpan = lane.events.length * rowH;
+
+    // Group label — left of lane, vertically centred
+    const group = timelineGroups.find((grp) => grp.name === lane.name);
+    const headerG = g
+      .append('g')
+      .attr('class', 'tl-lane-header')
+      .attr('data-group', lane.name)
+      .style('cursor', 'pointer')
+      .on('mouseenter', () => fadeToGroup(g, lane.name))
+      .on('mouseleave', () => fadeReset(g))
+      .on('click', () => {
+        if (onClickItem && group?.lineNumber) onClickItem(group.lineNumber);
+      });
+
+    headerG
+      .append('text')
+      .attr('x', -margin.left + 10)
+      .attr('y', curY + laneSpan / 2)
+      .attr('dy', '0.35em')
+      .attr('text-anchor', 'start')
+      .attr('fill', laneColor)
+      .attr('font-size', '12px')
+      .attr('font-weight', '600')
+      .text(lane.name);
+
+    lane.events.forEach((ev, i) => {
+      const y = curY + i * rowH + rowH / 2;
+      const x = xScale(parseTimelineDate(ev.date));
+
+      const evG = g
+        .append('g')
+        .attr('class', 'tl-event')
+        .attr('data-group', lane.name)
+        .attr('data-line-number', String(ev.lineNumber))
+        .attr('data-date', String(parseTimelineDate(ev.date)))
+        .attr(
+          'data-end-date',
+          ev.endDate ? String(parseTimelineDate(ev.endDate)) : null
+        )
+        .style('cursor', 'pointer')
+        .on('mouseenter', function (event: MouseEvent) {
+          fadeToGroup(g, lane.name);
+          if (timelineScale) {
+            showEventDatesOnScale(
+              g,
+              xScale,
+              ev.date,
+              ev.endDate,
+              innerHeight,
+              laneColor
+            );
+          } else {
+            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
+          }
+        })
+        .on('mouseleave', function () {
+          fadeReset(g);
+          if (timelineScale) {
+            hideEventDatesOnScale(g);
+          } else {
+            hideTooltip(tooltip);
+          }
+        })
+        .on('mousemove', function (event: MouseEvent) {
+          if (!timelineScale) {
+            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
           }
+        })
+        .on('click', () => {
+          if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
+        });
+      setTagAttrs(evG, ev);
 
-          evG
-            .append('rect')
-            .attr('x', axisX - 6)
-            .attr('y', y)
-            .attr('width', 12)
-            .attr('height', rectH)
-            .attr('rx', 4)
-            .attr('fill', fill)
-            .attr('stroke', stroke)
-            .attr('stroke-width', 2);
+      const evColor = eventColor(ev);
+
+      if (ev.endDate) {
+        const x2 = xScale(parseTimelineDate(ev.endDate));
+        const rectW = Math.max(x2 - x, 4);
+        // Estimate label width (~7px per char at 13px font) + padding
+        const estLabelWidth = ev.label.length * 7 + 16;
+        const labelFitsInside = rectW >= estLabelWidth;
+
+        let fill: string = shapeFill(palette, evColor, isDark, { solid });
+        let stroke: string = evColor;
+        if (ev.uncertain) {
+          // Create gradient for uncertain end - fades last 20%
+          const gradientId = `uncertain-${ev.lineNumber}`;
+          const strokeGradientId = `uncertain-s-${ev.lineNumber}`;
+          const defs = svg.select('defs').node() || svg.append('defs').node();
+          const defsEl = d3Selection.select(defs as Element);
+          defsEl
+            .append('linearGradient')
+            .attr('id', gradientId)
+            .attr('x1', '0%')
+            .attr('y1', '0%')
+            .attr('x2', '100%')
+            .attr('y2', '0%')
+            .selectAll('stop')
+            .data([
+              { offset: '0%', opacity: 1 },
+              { offset: '80%', opacity: 1 },
+              { offset: '100%', opacity: 0 },
+            ])
+            .enter()
+            .append('stop')
+            .attr('offset', (d) => d.offset)
+            .attr('stop-color', mix(evColor, bg, 30))
+            .attr('stop-opacity', (d) => d.opacity);
+          defsEl
+            .append('linearGradient')
+            .attr('id', strokeGradientId)
+            .attr('x1', '0%')
+            .attr('y1', '0%')
+            .attr('x2', '100%')
+            .attr('y2', '0%')
+            .selectAll('stop')
+            .data([
+              { offset: '0%', opacity: 1 },
+              { offset: '80%', opacity: 1 },
+              { offset: '100%', opacity: 0 },
+            ])
+            .enter()
+            .append('stop')
+            .attr('offset', (d) => d.offset)
+            .attr('stop-color', evColor)
+            .attr('stop-opacity', (d) => d.opacity);
+          fill = `url(#${gradientId})`;
+          stroke = `url(#${strokeGradientId})`;
+        }
+
+        evG
+          .append('rect')
+          .attr('x', x)
+          .attr('y', y - BAR_H / 2)
+          .attr('width', rectW)
+          .attr('height', BAR_H)
+          .attr('rx', 4)
+          .attr('fill', fill)
+          .attr('stroke', stroke)
+          .attr('stroke-width', 2);
+
+        if (labelFitsInside) {
+          // Text inside bar - use textColor for readability on muted fill
           evG
             .append('text')
-            .attr('x', axisX + 16)
-            .attr('y', y + rectH / 2)
+            .attr('x', x + 8)
+            .attr('y', y)
             .attr('dy', '0.35em')
+            .attr('text-anchor', 'start')
             .attr('fill', textColor)
-            .attr('font-size', '11px')
+            .attr('font-size', '13px')
             .text(ev.label);
         } else {
-          evG
-            .append('circle')
-            .attr('cx', axisX)
-            .attr('cy', y)
-            .attr('r', 4)
-            .attr('fill', shapeFill(palette, color, isDark, { solid }))
-            .attr('stroke', color)
-            .attr('stroke-width', 2);
+          // Text outside bar - check if it fits on left or must go right
+          const wouldFlipLeft = x + rectW > innerWidth * 0.6;
+          const labelFitsLeft = x - 6 - estLabelWidth > 0;
+          const flipLeft = wouldFlipLeft && labelFitsLeft;
           evG
             .append('text')
-            .attr('x', axisX + 16)
+            .attr('x', flipLeft ? x - 6 : x + rectW + 6)
             .attr('y', y)
             .attr('dy', '0.35em')
+            .attr('text-anchor', flipLeft ? 'end' : 'start')
             .attr('fill', textColor)
-            .attr('font-size', '11px')
+            .attr('font-size', '13px')
             .text(ev.label);
         }
-
-        // Date label to the left
+      } else {
+        // Point event (no end date) - render as circle with label
+        const estLabelWidth = ev.label.length * 7;
+        // Only flip left if past 60% AND label fits without colliding with group name area
+        const wouldFlipLeft = x > innerWidth * 0.6;
+        const labelFitsLeft = x - 10 - estLabelWidth > 0;
+        const flipLeft = wouldFlipLeft && labelFitsLeft;
+        evG
+          .append('circle')
+          .attr('cx', x)
+          .attr('cy', y)
+          .attr('r', 5)
+          .attr('fill', shapeFill(palette, evColor, isDark, { solid }))
+          .attr('stroke', evColor)
+          .attr('stroke-width', 2);
         evG
           .append('text')
-          .attr('x', axisX - 14)
-          .attr(
-            'y',
-            ev.endDate
-              ? yScale(parseTimelineDate(ev.date)) +
-                  Math.max(
-                    yScale(parseTimelineDate(ev.endDate)) -
-                      yScale(parseTimelineDate(ev.date)),
-                    4
-                  ) /
-                    2
-              : y
-          )
+          .attr('x', flipLeft ? x - 10 : x + 10)
+          .attr('y', y)
           .attr('dy', '0.35em')
-          .attr('text-anchor', 'end')
-          .attr('fill', mutedColor)
-          .attr('font-size', '10px')
-          .text(ev.date + (ev.endDate ? `→${ev.endDate}` : ''));
+          .attr('text-anchor', flipLeft ? 'end' : 'start')
+          .attr('fill', textColor)
+          .attr('font-size', '12px')
+          .text(ev.label);
       }
-    }
+    });
 
-    return; // vertical done
+    curY += laneSpan + GROUP_GAP;
   }
+}
 
-  // ================================================================
-  // HORIZONTAL orientation (default — time flows left→right)
-  // Each event gets its own row, stacked vertically.
-  // ================================================================
+// ============================================================
+// Timeline — vertical-orientation renderer (extracted from renderTimeline)
+// ============================================================
 
-  const BAR_H = 22; // range bar thickness (tall enough for text inside)
-  const GROUP_GAP = 12; // vertical gap between group swim-lanes
+function renderTimelineVertical(
+  container: HTMLDivElement,
+  parsed: ParsedVisualization,
+  palette: PaletteColors,
+  isDark: boolean,
+  setup: TimelineSetup,
+  hovers: TimelineHoverHelpers,
+  onClickItem: ((lineNumber: number) => void) | undefined,
+  exportDims: D3ExportDimensions | undefined,
+  _swimlaneTagGroup: string | null | undefined,
+  _activeTagGroup: string | null | undefined,
+  _onTagStateChange:
+    | ((activeTagGroup: string | null, swimlaneTagGroup: string | null) => void)
+    | undefined,
+  _viewMode: boolean | undefined
+): void {
+  const {
+    width,
+    height,
+    tooltip,
+    solid,
+    textColor,
+    mutedColor,
+    bgColor,
+    bg,
+    groupColorMap,
+    tagLanes,
+    eventColor,
+    minDate,
+    maxDate,
+    datePadding,
+    earliestStartDateStr,
+    latestEndDateStr,
+    tagLegendReserve,
+  } = setup;
+  const { fadeToGroup, fadeToEra, fadeToMarker, fadeReset, setTagAttrs } =
+    hovers;
+  const {
+    timelineEvents,
+    timelineGroups,
+    timelineEras,
+    timelineMarkers,
+    timelineSort,
+    timelineScale,
+    timelineSwimlanes,
+  } = parsed;
+  const title = parsed.noTitle ? null : parsed.title;
 
-  const useGroupedHorizontal =
+  const useGroupedVertical =
     tagLanes != null || (timelineSort === 'group' && timelineGroups.length > 0);
-  if (useGroupedHorizontal) {
-    // === GROUPED: swim-lanes stacked vertically, events on own rows ===
-    let lanes: Lane[];
+  if (useGroupedVertical) {
+    // === GROUPED: one column/lane per group, vertical ===
+    let laneNames: string[];
+    let laneEventsByName: Map<string, TimelineEvent[]>;
 
     if (tagLanes) {
-      lanes = tagLanes;
+      laneNames = tagLanes.map((l) => l.name);
+      laneEventsByName = new Map(tagLanes.map((l) => [l.name, l.events]));
     } else {
       const groupNames = timelineGroups.map((gr) => gr.name);
       const ungroupedEvents = timelineEvents.filter(
         (ev) => ev.group === null || !groupNames.includes(ev.group)
       );
-      const laneNames =
+      laneNames =
         ungroupedEvents.length > 0 ? [...groupNames, '(Other)'] : groupNames;
-      lanes = laneNames.map((name) => ({
-        name,
-        events: timelineEvents.filter((ev) =>
-          name === '(Other)'
-            ? ev.group === null || !groupNames.includes(ev.group)
-            : ev.group === name
-        ),
-      }));
+      laneEventsByName = new Map(
+        laneNames.map((name) => [
+          name,
+          timelineEvents.filter((ev) =>
+            name === '(Other)'
+              ? ev.group === null || !groupNames.includes(ev.group)
+              : ev.group === name
+          ),
+        ])
+      );
     }
 
-    const totalEventRows = lanes.reduce((s, l) => s + l.events.length, 0);
-    const scaleMargin = timelineScale ? 24 : 0;
-    // Per-feature header rows: era + marker each get their own row, reserved
-    // only when present (mirrors the gantt header stack).
-    const ERA_ROW_H = 22;
-    const MARKER_ROW_H = 22;
-    const eraReserve = timelineEras.length > 0 ? ERA_ROW_H : 0;
-    const markerReserve = timelineMarkers.length > 0 ? MARKER_ROW_H : 0;
-    const topScaleH = timelineScale ? 40 : 0;
-    // Calculate left margin based on longest group name (~7px per char + padding)
-    const maxGroupNameLen = Math.max(...lanes.map((l) => l.name.length));
-    const dynamicLeftMargin = Math.max(120, maxGroupNameLen * 7 + 30);
-    // Group-sorted doesn't need legend space (group names shown on left)
-    const baseTopMargin = title ? 50 : 20;
+    const laneCount = laneNames.length;
+    const scaleMargin = timelineScale ? 40 : 0;
+    const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
     const margin = {
-      top:
-        baseTopMargin +
-        topScaleH +
-        eraReserve +
-        markerReserve +
-        tagLegendReserve,
-      right: 40,
-      bottom: 40 + scaleMargin,
-      left: dynamicLeftMargin,
+      top: 104 + markerMargin + tagLegendReserve,
+      right: 40 + scaleMargin,
+      bottom: 40,
+      left: 60 + scaleMargin,
     };
-    // Y offsets for label rows (negative = above chart's y=0).
-    const markerLabelY = markerReserve ? -(topScaleH + MARKER_ROW_H / 2) : 0;
-    const eraLabelY = eraReserve
-      ? -(topScaleH + markerReserve + ERA_ROW_H / 2)
-      : 0;
     const innerWidth = width - margin.left - margin.right;
     const innerHeight = height - margin.top - margin.bottom;
-    const totalGaps = (lanes.length - 1) * GROUP_GAP;
-    const rowH = Math.min(28, (innerHeight - totalGaps) / totalEventRows);
+    const laneWidth = innerWidth / laneCount;
 
-    const xScale = d3Scale
+    const yScale = d3Scale
       .scaleLinear()
       .domain([minDate - datePadding, maxDate + datePadding])
-      .range([0, innerWidth]);
+      .range([0, innerHeight]);
 
     const svg = d3Selection
       .select(container)
       .append('svg')
-      .attr('width', width)
-      .attr('height', height)
+      .attr('viewBox', `0 0 ${width} ${height}`)
+      .attr('width', exportDims ? width : '100%')
+      .attr('preserveAspectRatio', 'xMidYMin meet')
       .style('background', bgColor);
 
     const g = svg
@@ -4432,38 +5054,36 @@ export function renderTimeline(
     renderEras(
       g,
       timelineEras,
-      xScale,
-      false,
+      yScale,
+      true,
       innerWidth,
       innerHeight,
       (s, e) => fadeToEra(g, s, e),
       () => fadeReset(g),
       timelineScale,
       tooltip,
-      palette,
-      eraReserve ? eraLabelY : undefined
+      palette
     );
 
     renderMarkers(
       g,
       timelineMarkers,
-      xScale,
-      false,
+      yScale,
+      true,
       innerWidth,
       innerHeight,
       (d) => fadeToMarker(g, d),
       () => fadeReset(g),
       timelineScale,
       tooltip,
-      palette,
-      markerReserve ? markerLabelY : undefined
+      palette
     );
 
     if (timelineScale) {
       renderTimeScale(
         g,
-        xScale,
-        false,
+        yScale,
+        true,
         innerWidth,
         innerHeight,
         textColor,
@@ -4474,67 +5094,63 @@ export function renderTimeline(
       );
     }
 
-    // Marker labels now live in their reserved row above the chart, so
-    // events can start at y=0 (chart top edge).
-    let curY = 0;
-
-    // Render swimlane backgrounds first (so they appear behind events)
-    // Extend into left margin to include group names
+    // Render swimlane backgrounds for vertical lanes
     if (timelineSwimlanes || tagLanes) {
-      let swimY = 0;
-      lanes.forEach((lane, idx) => {
-        const laneSpan = lane.events.length * rowH;
-        // Alternate between light gray and transparent for visual separation
-        const fillColor = idx % 2 === 0 ? textColor : 'transparent';
+      laneNames.forEach((laneName, laneIdx) => {
+        const laneX = laneIdx * laneWidth;
+        const fillColor = laneIdx % 2 === 0 ? textColor : 'transparent';
         g.append('rect')
           .attr('class', 'tl-swimlane')
-          .attr('data-group', lane.name)
-          .attr('x', -margin.left)
-          .attr('y', swimY)
-          .attr('width', innerWidth + margin.left)
-          .attr('height', laneSpan + (idx < lanes.length - 1 ? GROUP_GAP : 0))
+          .attr('data-group', laneName)
+          .attr('x', laneX)
+          .attr('y', 0)
+          .attr('width', laneWidth)
+          .attr('height', innerHeight)
           .attr('fill', fillColor)
           .attr('opacity', 0.06);
-        swimY += laneSpan + GROUP_GAP;
       });
     }
 
-    for (const lane of lanes) {
-      const laneColor = groupColorMap.get(lane.name) ?? textColor;
-      const laneSpan = lane.events.length * rowH;
+    laneNames.forEach((laneName, laneIdx) => {
+      const laneX = laneIdx * laneWidth;
+      const laneColor = groupColorMap.get(laneName) ?? textColor;
+      const laneCenter = laneX + laneWidth / 2;
 
-      // Group label — left of lane, vertically centred
-      const group = timelineGroups.find((grp) => grp.name === lane.name);
       const headerG = g
         .append('g')
         .attr('class', 'tl-lane-header')
-        .attr('data-group', lane.name)
+        .attr('data-group', laneName)
         .style('cursor', 'pointer')
-        .on('mouseenter', () => fadeToGroup(g, lane.name))
-        .on('mouseleave', () => fadeReset(g))
-        .on('click', () => {
-          if (onClickItem && group?.lineNumber) onClickItem(group.lineNumber);
-        });
+        .on('mouseenter', () => fadeToGroup(g, laneName))
+        .on('mouseleave', () => fadeReset(g));
 
       headerG
         .append('text')
-        .attr('x', -margin.left + 10)
-        .attr('y', curY + laneSpan / 2)
-        .attr('dy', '0.35em')
-        .attr('text-anchor', 'start')
+        .attr('x', laneCenter)
+        .attr('y', -15)
+        .attr('text-anchor', 'middle')
         .attr('fill', laneColor)
         .attr('font-size', '12px')
         .attr('font-weight', '600')
-        .text(lane.name);
+        .text(laneName);
+
+      g.append('line')
+        .attr('x1', laneCenter)
+        .attr('y1', 0)
+        .attr('x2', laneCenter)
+        .attr('y2', innerHeight)
+        .attr('stroke', mutedColor)
+        .attr('stroke-width', 1)
+        .attr('stroke-dasharray', '4,4');
 
-      lane.events.forEach((ev, i) => {
-        const y = curY + i * rowH + rowH / 2;
-        const x = xScale(parseTimelineDate(ev.date));
+      const laneEvents = laneEventsByName.get(laneName) ?? [];
 
+      for (const ev of laneEvents) {
+        const y = yScale(parseTimelineDate(ev.date));
         const evG = g
           .append('g')
           .attr('class', 'tl-event')
-          .attr('data-group', lane.name)
+          .attr('data-group', laneName)
           .attr('data-line-number', String(ev.lineNumber))
           .attr('data-date', String(parseTimelineDate(ev.date)))
           .attr(
@@ -4543,32 +5159,15 @@ export function renderTimeline(
           )
           .style('cursor', 'pointer')
           .on('mouseenter', function (event: MouseEvent) {
-            fadeToGroup(g, lane.name);
-            if (timelineScale) {
-              showEventDatesOnScale(
-                g,
-                xScale,
-                ev.date,
-                ev.endDate,
-                innerHeight,
-                laneColor
-              );
-            } else {
-              showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-            }
+            fadeToGroup(g, laneName);
+            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
           })
           .on('mouseleave', function () {
             fadeReset(g);
-            if (timelineScale) {
-              hideEventDatesOnScale(g);
-            } else {
-              hideTooltip(tooltip);
-            }
+            hideTooltip(tooltip);
           })
           .on('mousemove', function (event: MouseEvent) {
-            if (!timelineScale) {
-              showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-            }
+            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
           })
           .on('click', () => {
             if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
@@ -4578,18 +5177,14 @@ export function renderTimeline(
         const evColor = eventColor(ev);
 
         if (ev.endDate) {
-          const x2 = xScale(parseTimelineDate(ev.endDate));
-          const rectW = Math.max(x2 - x, 4);
-          // Estimate label width (~7px per char at 13px font) + padding
-          const estLabelWidth = ev.label.length * 7 + 16;
-          const labelFitsInside = rectW >= estLabelWidth;
+          const y2 = yScale(parseTimelineDate(ev.endDate));
+          const rectH = Math.max(y2 - y, 4);
 
           let fill: string = shapeFill(palette, evColor, isDark, { solid });
           let stroke: string = evColor;
           if (ev.uncertain) {
-            // Create gradient for uncertain end - fades last 20%
-            const gradientId = `uncertain-${ev.lineNumber}`;
-            const strokeGradientId = `uncertain-s-${ev.lineNumber}`;
+            const gradientId = `uncertain-vg-${ev.lineNumber}`;
+            const strokeGradientId = `uncertain-vg-s-${ev.lineNumber}`;
             const defs = svg.select('defs').node() || svg.append('defs').node();
             const defsEl = d3Selection.select(defs as Element);
             defsEl
@@ -4597,8 +5192,8 @@ export function renderTimeline(
               .attr('id', gradientId)
               .attr('x1', '0%')
               .attr('y1', '0%')
-              .attr('x2', '100%')
-              .attr('y2', '0%')
+              .attr('x2', '0%')
+              .attr('y2', '100%')
               .selectAll('stop')
               .data([
                 { offset: '0%', opacity: 1 },
@@ -4608,15 +5203,15 @@ export function renderTimeline(
               .enter()
               .append('stop')
               .attr('offset', (d) => d.offset)
-              .attr('stop-color', mix(evColor, bg, 30))
+              .attr('stop-color', mix(laneColor, bg, 30))
               .attr('stop-opacity', (d) => d.opacity);
             defsEl
               .append('linearGradient')
               .attr('id', strokeGradientId)
               .attr('x1', '0%')
               .attr('y1', '0%')
-              .attr('x2', '100%')
-              .attr('y2', '0%')
+              .attr('x2', '0%')
+              .attr('y2', '100%')
               .selectAll('stop')
               .data([
                 { offset: '0%', opacity: 1 },
@@ -4634,108 +5229,71 @@ export function renderTimeline(
 
           evG
             .append('rect')
-            .attr('x', x)
-            .attr('y', y - BAR_H / 2)
-            .attr('width', rectW)
-            .attr('height', BAR_H)
+            .attr('x', laneCenter - 6)
+            .attr('y', y)
+            .attr('width', 12)
+            .attr('height', rectH)
             .attr('rx', 4)
             .attr('fill', fill)
             .attr('stroke', stroke)
             .attr('stroke-width', 2);
-
-          if (labelFitsInside) {
-            // Text inside bar - use textColor for readability on muted fill
-            evG
-              .append('text')
-              .attr('x', x + 8)
-              .attr('y', y)
-              .attr('dy', '0.35em')
-              .attr('text-anchor', 'start')
-              .attr('fill', textColor)
-              .attr('font-size', '13px')
-              .text(ev.label);
-          } else {
-            // Text outside bar - check if it fits on left or must go right
-            const wouldFlipLeft = x + rectW > innerWidth * 0.6;
-            const labelFitsLeft = x - 6 - estLabelWidth > 0;
-            const flipLeft = wouldFlipLeft && labelFitsLeft;
-            evG
-              .append('text')
-              .attr('x', flipLeft ? x - 6 : x + rectW + 6)
-              .attr('y', y)
-              .attr('dy', '0.35em')
-              .attr('text-anchor', flipLeft ? 'end' : 'start')
-              .attr('fill', textColor)
-              .attr('font-size', '13px')
-              .text(ev.label);
-          }
+          evG
+            .append('text')
+            .attr('x', laneCenter + 14)
+            .attr('y', y + rectH / 2)
+            .attr('dy', '0.35em')
+            .attr('fill', textColor)
+            .attr('font-size', '10px')
+            .text(ev.label);
         } else {
-          // Point event (no end date) - render as circle with label
-          const estLabelWidth = ev.label.length * 7;
-          // Only flip left if past 60% AND label fits without colliding with group name area
-          const wouldFlipLeft = x > innerWidth * 0.6;
-          const labelFitsLeft = x - 10 - estLabelWidth > 0;
-          const flipLeft = wouldFlipLeft && labelFitsLeft;
           evG
             .append('circle')
-            .attr('cx', x)
+            .attr('cx', laneCenter)
             .attr('cy', y)
-            .attr('r', 5)
+            .attr('r', 4)
             .attr('fill', shapeFill(palette, evColor, isDark, { solid }))
             .attr('stroke', evColor)
             .attr('stroke-width', 2);
           evG
             .append('text')
-            .attr('x', flipLeft ? x - 10 : x + 10)
+            .attr('x', laneCenter + 10)
             .attr('y', y)
             .attr('dy', '0.35em')
-            .attr('text-anchor', flipLeft ? 'end' : 'start')
             .attr('fill', textColor)
-            .attr('font-size', '12px')
+            .attr('font-size', '10px')
             .text(ev.label);
         }
-      });
-
-      curY += laneSpan + GROUP_GAP;
-    }
+      }
+    });
   } else {
-    // === TIME SORT, horizontal: each event on its own row ===
-    const sorted = timelineEvents
-      .slice()
-      .sort((a, b) => parseTimelineDate(a.date) - parseTimelineDate(b.date));
-
-    const scaleMargin = timelineScale ? 24 : 0;
-    // Per-feature header rows: era + marker each get their own row, reserved
-    // only when present (mirrors the gantt header stack).
-    const ERA_ROW_H = 22;
-    const MARKER_ROW_H = 22;
-    const eraReserve = timelineEras.length > 0 ? ERA_ROW_H : 0;
-    const markerReserve = timelineMarkers.length > 0 ? MARKER_ROW_H : 0;
-    const topScaleH = timelineScale ? 40 : 0;
+    // === TIME SORT, vertical: single vertical axis ===
+    const scaleMargin = timelineScale ? 40 : 0;
+    const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
     const margin = {
-      top: 104 + topScaleH + eraReserve + markerReserve + tagLegendReserve,
-      right: 40,
-      bottom: 40 + scaleMargin,
-      left: 60,
+      top: 104 + markerMargin + tagLegendReserve,
+      right: 200,
+      bottom: 40,
+      left: 60 + scaleMargin,
     };
-    const markerLabelY = markerReserve ? -(topScaleH + MARKER_ROW_H / 2) : 0;
-    const eraLabelY = eraReserve
-      ? -(topScaleH + markerReserve + ERA_ROW_H / 2)
-      : 0;
     const innerWidth = width - margin.left - margin.right;
     const innerHeight = height - margin.top - margin.bottom;
-    const rowH = Math.min(28, innerHeight / sorted.length);
+    const axisX = 20;
 
-    const xScale = d3Scale
+    const yScale = d3Scale
       .scaleLinear()
       .domain([minDate - datePadding, maxDate + datePadding])
-      .range([0, innerWidth]);
+      .range([0, innerHeight]);
+
+    const sorted = timelineEvents
+      .slice()
+      .sort((a, b) => parseTimelineDate(a.date) - parseTimelineDate(b.date));
 
     const svg = d3Selection
       .select(container)
       .append('svg')
-      .attr('width', width)
-      .attr('height', height)
+      .attr('viewBox', `0 0 ${width} ${height}`)
+      .attr('width', exportDims ? width : '100%')
+      .attr('preserveAspectRatio', 'xMidYMin meet')
       .style('background', bgColor);
 
     const g = svg
@@ -4754,38 +5312,36 @@ export function renderTimeline(
     renderEras(
       g,
       timelineEras,
-      xScale,
-      false,
+      yScale,
+      true,
       innerWidth,
       innerHeight,
       (s, e) => fadeToEra(g, s, e),
       () => fadeReset(g),
       timelineScale,
       tooltip,
-      palette,
-      eraReserve ? eraLabelY : undefined
+      palette
     );
 
     renderMarkers(
       g,
       timelineMarkers,
-      xScale,
-      false,
+      yScale,
+      true,
       innerWidth,
       innerHeight,
       (d) => fadeToMarker(g, d),
       () => fadeReset(g),
       timelineScale,
       tooltip,
-      palette,
-      markerReserve ? markerLabelY : undefined
+      palette
     );
 
     if (timelineScale) {
       renderTimeScale(
         g,
-        xScale,
-        false,
+        yScale,
+        true,
         innerWidth,
         innerHeight,
         textColor,
@@ -4796,9 +5352,8 @@ export function renderTimeline(
       );
     }
 
-    // Group legend at top-left (pill style)
+    // Group legend (pill style)
     if (timelineGroups.length > 0) {
-      const legendY = timelineScale ? -75 : -55;
       renderTimelineGroupLegend(
         g,
         timelineGroups,
@@ -4806,17 +5361,23 @@ export function renderTimeline(
         textColor,
         palette,
         isDark,
-        legendY,
+        -55,
         (name) => fadeToGroup(g, name),
         () => fadeReset(g)
       );
     }
 
-    sorted.forEach((ev, i) => {
-      // Marker labels live in their reserved row above the chart, so the
-      // first event sits at the chart top edge.
-      const y = i * rowH + rowH / 2;
-      const x = xScale(parseTimelineDate(ev.date));
+    g.append('line')
+      .attr('x1', axisX)
+      .attr('y1', 0)
+      .attr('x2', axisX)
+      .attr('y2', innerHeight)
+      .attr('stroke', mutedColor)
+      .attr('stroke-width', 1)
+      .attr('stroke-dasharray', '4,4');
+
+    for (const ev of sorted) {
+      const y = yScale(parseTimelineDate(ev.date));
       const color = eventColor(ev);
 
       const evG = g
@@ -4832,31 +5393,14 @@ export function renderTimeline(
         .style('cursor', 'pointer')
         .on('mouseenter', function (event: MouseEvent) {
           if (ev.group && timelineGroups.length > 0) fadeToGroup(g, ev.group);
-          if (timelineScale) {
-            showEventDatesOnScale(
-              g,
-              xScale,
-              ev.date,
-              ev.endDate,
-              innerHeight,
-              color
-            );
-          } else {
-            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-          }
+          showTooltip(tooltip, buildEventTooltipHtml(ev), event);
         })
         .on('mouseleave', function () {
           fadeReset(g);
-          if (timelineScale) {
-            hideEventDatesOnScale(g);
-          } else {
-            hideTooltip(tooltip);
-          }
+          hideTooltip(tooltip);
         })
         .on('mousemove', function (event: MouseEvent) {
-          if (!timelineScale) {
-            showTooltip(tooltip, buildEventTooltipHtml(ev), event);
-          }
+          showTooltip(tooltip, buildEventTooltipHtml(ev), event);
         })
         .on('click', () => {
           if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
@@ -4864,18 +5408,14 @@ export function renderTimeline(
       setTagAttrs(evG, ev);
 
       if (ev.endDate) {
-        const x2 = xScale(parseTimelineDate(ev.endDate));
-        const rectW = Math.max(x2 - x, 4);
-        // Estimate label width (~7px per char at 13px font) + padding
-        const estLabelWidth = ev.label.length * 7 + 16;
-        const labelFitsInside = rectW >= estLabelWidth;
+        const y2 = yScale(parseTimelineDate(ev.endDate));
+        const rectH = Math.max(y2 - y, 4);
 
         let fill: string = shapeFill(palette, color, isDark, { solid });
         let stroke: string = color;
         if (ev.uncertain) {
-          // Create gradient for uncertain end - fades last 20%
-          const gradientId = `uncertain-ts-${ev.lineNumber}`;
-          const strokeGradientId = `uncertain-ts-s-${ev.lineNumber}`;
+          const gradientId = `uncertain-v-${ev.lineNumber}`;
+          const strokeGradientId = `uncertain-v-s-${ev.lineNumber}`;
           const defs = svg.select('defs').node() || svg.append('defs').node();
           const defsEl = d3Selection.select(defs as Element);
           defsEl
@@ -4883,8 +5423,8 @@ export function renderTimeline(
             .attr('id', gradientId)
             .attr('x1', '0%')
             .attr('y1', '0%')
-            .attr('x2', '100%')
-            .attr('y2', '0%')
+            .attr('x2', '0%')
+            .attr('y2', '100%')
             .selectAll('stop')
             .data([
               { offset: '0%', opacity: 1 },
@@ -4901,8 +5441,8 @@ export function renderTimeline(
             .attr('id', strokeGradientId)
             .attr('x1', '0%')
             .attr('y1', '0%')
-            .attr('x2', '100%')
-            .attr('y2', '0%')
+            .attr('x2', '0%')
+            .attr('y2', '100%')
             .selectAll('stop')
             .data([
               { offset: '0%', opacity: 1 },
@@ -4920,353 +5460,169 @@ export function renderTimeline(
 
         evG
           .append('rect')
-          .attr('x', x)
-          .attr('y', y - BAR_H / 2)
-          .attr('width', rectW)
-          .attr('height', BAR_H)
+          .attr('x', axisX - 6)
+          .attr('y', y)
+          .attr('width', 12)
+          .attr('height', rectH)
           .attr('rx', 4)
           .attr('fill', fill)
           .attr('stroke', stroke)
           .attr('stroke-width', 2);
-
-        if (labelFitsInside) {
-          // Text inside bar - use textColor for readability on muted fill
-          evG
-            .append('text')
-            .attr('x', x + 8)
-            .attr('y', y)
-            .attr('dy', '0.35em')
-            .attr('text-anchor', 'start')
-            .attr('fill', textColor)
-            .attr('font-size', '13px')
-            .text(ev.label);
-        } else {
-          // Text outside bar - check if it fits on left or must go right
-          const wouldFlipLeft = x + rectW > innerWidth * 0.6;
-          const labelFitsLeft = x - 6 - estLabelWidth > 0;
-          const flipLeft = wouldFlipLeft && labelFitsLeft;
-          evG
-            .append('text')
-            .attr('x', flipLeft ? x - 6 : x + rectW + 6)
-            .attr('y', y)
-            .attr('dy', '0.35em')
-            .attr('text-anchor', flipLeft ? 'end' : 'start')
-            .attr('fill', textColor)
-            .attr('font-size', '13px')
-            .text(ev.label);
-        }
+        evG
+          .append('text')
+          .attr('x', axisX + 16)
+          .attr('y', y + rectH / 2)
+          .attr('dy', '0.35em')
+          .attr('fill', textColor)
+          .attr('font-size', '11px')
+          .text(ev.label);
       } else {
-        // Point event (no end date) - render as circle with label
-        const estLabelWidth = ev.label.length * 7;
-        // Only flip left if past 60% AND label fits without going off-chart
-        const wouldFlipLeft = x > innerWidth * 0.6;
-        const labelFitsLeft = x - 10 - estLabelWidth > 0;
-        const flipLeft = wouldFlipLeft && labelFitsLeft;
         evG
           .append('circle')
-          .attr('cx', x)
+          .attr('cx', axisX)
           .attr('cy', y)
-          .attr('r', 5)
+          .attr('r', 4)
           .attr('fill', shapeFill(palette, color, isDark, { solid }))
           .attr('stroke', color)
           .attr('stroke-width', 2);
         evG
           .append('text')
-          .attr('x', flipLeft ? x - 10 : x + 10)
+          .attr('x', axisX + 16)
           .attr('y', y)
           .attr('dy', '0.35em')
-          .attr('text-anchor', flipLeft ? 'end' : 'start')
           .attr('fill', textColor)
-          .attr('font-size', '12px')
+          .attr('font-size', '11px')
           .text(ev.label);
       }
-    });
-  }
-
-  // ── Tag Legend (org-chart-style pills) ──
-  if (parsed.timelineTagGroups.length > 0) {
-    const LG_HEIGHT = TL_LEGEND_HEIGHT;
-    const LG_PILL_PAD = TL_LEGEND_PILL_PAD;
-    const LG_PILL_FONT_SIZE = TL_LEGEND_PILL_FONT_SIZE;
-    const LG_CAPSULE_PAD = TL_LEGEND_CAPSULE_PAD;
-    const LG_DOT_R = TL_LEGEND_DOT_R;
-    const LG_ENTRY_FONT_SIZE = TL_LEGEND_ENTRY_FONT_SIZE;
-    const LG_ENTRY_DOT_GAP = TL_LEGEND_ENTRY_DOT_GAP;
-    const LG_ENTRY_TRAIL = TL_LEGEND_ENTRY_TRAIL;
-    // LG_GROUP_GAP no longer needed — centralized legend handles spacing
-    const LG_ICON_W = 20; // swimlane icon area (icon + surrounding space) — local
-
-    const mainSvg = d3Selection.select(container).select<SVGSVGElement>('svg');
-    const mainG = mainSvg.select<SVGGElement>('g');
-    if (!mainSvg.empty() && !mainG.empty()) {
-      // Position legend at top, below title
-      const legendY = title ? 50 : 10;
-
-      // Pre-compute group widths (minified and expanded)
-      type LegendGroup = {
-        group: TagGroup;
-        minifiedWidth: number;
-        expandedWidth: number;
-      };
-      const legendGroups: LegendGroup[] = parsed.timelineTagGroups.map((g) => {
-        const pillW =
-          measureLegendText(g.name, LG_PILL_FONT_SIZE) + LG_PILL_PAD;
-        // Expanded: pill + icon (unless viewMode) + entries
-        const iconSpace = viewMode ? 8 : LG_ICON_W + 4;
-        let entryX = LG_CAPSULE_PAD + pillW + iconSpace;
-        for (const entry of g.entries) {
-          const textX = entryX + LG_DOT_R * 2 + LG_ENTRY_DOT_GAP;
-          entryX =
-            textX +
-            measureLegendText(entry.value, LG_ENTRY_FONT_SIZE) +
-            LG_ENTRY_TRAIL;
-        }
-        return {
-          group: g,
-          minifiedWidth: pillW,
-          expandedWidth: entryX + LG_CAPSULE_PAD,
-        };
-      });
-
-      // Two independent state axes: swimlane source + color source
-      let currentActiveGroup: string | null = activeTagGroup ?? null;
-      let currentSwimlaneGroup: string | null = swimlaneTagGroup ?? null;
-
-      /** Render the swimlane icon (3 horizontal bars of varying width) */
-      function drawSwimlaneIcon(
-        parent: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
-        x: number,
-        y: number,
-        isSwimActive: boolean
-      ) {
-        const iconG = parent
-          .append('g')
-          .attr('class', 'tl-swimlane-icon')
-          .attr('transform', `translate(${x}, ${y})`)
-          .style('cursor', 'pointer');
-
-        const barColor = isSwimActive ? palette.primary : palette.textMuted;
-        const barOpacity = isSwimActive ? 1 : 0.35;
-        const bars = [
-          { y: 0, w: 8 },
-          { y: 4, w: 12 },
-          { y: 8, w: 6 },
-        ];
-        for (const bar of bars) {
-          iconG
-            .append('rect')
-            .attr('x', 0)
-            .attr('y', bar.y)
-            .attr('width', bar.w)
-            .attr('height', 2)
-            .attr('rx', 1)
-            .attr('fill', barColor)
-            .attr('opacity', barOpacity);
-        }
-        return iconG;
-      }
-
-      /** Full re-render with updated swimlane state */
-      function relayout() {
-        renderTimeline(
-          container,
-          parsed,
-          palette,
-          isDark,
-          onClickItem,
-          exportDims,
-          currentActiveGroup,
-          currentSwimlaneGroup,
-          onTagStateChange,
-          viewMode
-        );
-      }
-
-      function drawLegend() {
-        // Remove previous legend
-        mainSvg.selectAll('.tl-tag-legend-group').remove();
-        mainSvg.selectAll('.tl-tag-legend-container').remove();
-
-        // Effective color source: explicit color group > swimlane group
-        const effectiveColorKey =
-          (currentActiveGroup ?? currentSwimlaneGroup)?.toLowerCase() ?? null;
-
-        // In view mode, only show the color-driving tag group (expanded, non-interactive).
-        // Skip the swimlane group if it's separate from the color group (lane headers already label it).
-        const visibleGroups = viewMode
-          ? legendGroups.filter(
-              (lg) =>
-                effectiveColorKey != null &&
-                lg.group.name.toLowerCase() === effectiveColorKey
-            )
-          : legendGroups;
-
-        if (visibleGroups.length === 0) return;
 
-        // Legend container for data-legend-active attribute
-        const legendContainer = mainSvg
-          .append('g')
-          .attr('class', 'tl-tag-legend-container');
-        if (currentActiveGroup) {
-          legendContainer.attr(
-            'data-legend-active',
-            currentActiveGroup.toLowerCase()
-          );
-        }
+      // Date label to the left
+      evG
+        .append('text')
+        .attr('x', axisX - 14)
+        .attr(
+          'y',
+          ev.endDate
+            ? yScale(parseTimelineDate(ev.date)) +
+                Math.max(
+                  yScale(parseTimelineDate(ev.endDate)) -
+                    yScale(parseTimelineDate(ev.date)),
+                  4
+                ) /
+                  2
+            : y
+        )
+        .attr('dy', '0.35em')
+        .attr('text-anchor', 'end')
+        .attr('fill', mutedColor)
+        .attr('font-size', '10px')
+        .text(ev.date + (ev.endDate ? `→${ev.endDate}` : ''));
+    }
+  }
+}
 
-        // Render tag groups via centralized legend system
-        const iconAddon = viewMode ? 0 : LG_ICON_W;
-        const centralGroups = visibleGroups.map((lg) => ({
-          name: lg.group.name,
-          entries: lg.group.entries.map((e) => ({
-            value: e.value,
-            color: e.color,
-          })),
-        }));
-
-        // Determine effective active group for centralized renderer
-        const centralActive = viewMode ? effectiveColorKey : currentActiveGroup;
-
-        const centralConfig: LegendConfig = {
-          groups: centralGroups,
-          position: { placement: 'top-center', titleRelation: 'below-title' },
-          mode: 'fixed',
-          capsulePillAddonWidth: iconAddon,
-        };
-        const centralState: LegendState = { activeGroup: centralActive };
-
-        const centralCallbacks: LegendCallbacks = viewMode
-          ? {}
-          : {
-              onGroupToggle: (groupName) => {
-                currentActiveGroup =
-                  currentActiveGroup === groupName.toLowerCase()
-                    ? null
-                    : groupName.toLowerCase();
-                drawLegend();
-                recolorEvents();
-                onTagStateChange?.(currentActiveGroup, currentSwimlaneGroup);
-              },
-              onEntryHover: (groupName, entryValue) => {
-                const tagKey = groupName.toLowerCase();
-                if (entryValue) {
-                  const tagVal = entryValue.toLowerCase();
-                  fadeToTagValue(mainG, tagKey, tagVal);
-                  mainSvg
-                    .selectAll<SVGGElement, unknown>('[data-legend-entry]')
-                    .each(function () {
-                      const el = d3Selection.select(this);
-                      const ev = el.attr('data-legend-entry');
-                      const eg =
-                        el.attr('data-tag-group') ??
-                        (el.node() as Element)
-                          ?.closest?.('[data-tag-group]')
-                          ?.getAttribute('data-tag-group');
-                      el.attr(
-                        'opacity',
-                        eg === tagKey && ev === tagVal ? 1 : FADE_OPACITY
-                      );
-                    });
-                } else {
-                  fadeReset(mainG);
-                  mainSvg
-                    .selectAll<SVGGElement, unknown>('[data-legend-entry]')
-                    .attr('opacity', 1);
-                }
-              },
-              onGroupRendered: (groupName, groupEl, isActive) => {
-                const groupKey = groupName.toLowerCase();
-                groupEl.attr('data-tag-group', groupKey);
-                if (isActive && !viewMode) {
-                  const isSwimActive =
-                    currentSwimlaneGroup != null &&
-                    currentSwimlaneGroup.toLowerCase() === groupKey;
-                  const pillWidth =
-                    measureLegendText(groupName, LG_PILL_FONT_SIZE) +
-                    LG_PILL_PAD;
-                  const pillXOff = LG_CAPSULE_PAD;
-                  const iconX = pillXOff + pillWidth + 5;
-                  const iconY = (LG_HEIGHT - 10) / 2;
-                  const iconEl = drawSwimlaneIcon(
-                    groupEl,
-                    iconX,
-                    iconY,
-                    isSwimActive
-                  );
-                  iconEl
-                    .attr('data-swimlane-toggle', groupKey)
-                    .on('click', (event: MouseEvent) => {
-                      event.stopPropagation();
-                      currentSwimlaneGroup =
-                        currentSwimlaneGroup === groupKey ? null : groupKey;
-                      onTagStateChange?.(
-                        currentActiveGroup,
-                        currentSwimlaneGroup
-                      );
-                      relayout();
-                    });
-                }
-              },
-            };
-
-        const legendInnerG = legendContainer
-          .append('g')
-          .attr('transform', `translate(0, ${legendY})`);
-        renderLegendD3(
-          legendInnerG,
-          centralConfig,
-          centralState,
-          palette,
-          isDark,
-          centralCallbacks,
-          width
-        );
-      }
+/**
+ * Renders a timeline chart into the given container using D3.
+ * Supports horizontal (default) and vertical orientation.
+ */
+export function renderTimeline(
+  container: HTMLDivElement,
+  parsed: ParsedVisualization,
+  palette: PaletteColors,
+  isDark: boolean,
+  onClickItem?: (lineNumber: number) => void,
+  exportDims?: D3ExportDimensions,
+  activeTagGroup?: string | null,
+  swimlaneTagGroup?: string | null,
+  onTagStateChange?: (
+    activeTagGroup: string | null,
+    swimlaneTagGroup: string | null
+  ) => void,
+  viewMode?: boolean,
+  exportMode?: boolean
+): void {
+  const setup = setupTimeline(
+    container,
+    parsed,
+    palette,
+    isDark,
+    exportDims,
+    activeTagGroup,
+    swimlaneTagGroup
+  );
+  if (!setup) return;
+  swimlaneTagGroup = setup.swimlaneTagGroup;
 
-      // Build a quick lineNumber→event lookup
-      const eventByLine = new Map<string, TimelineEvent>();
-      for (const ev of timelineEvents) {
-        eventByLine.set(String(ev.lineNumber), ev);
-      }
+  const { isVertical, tagLanes } = setup;
+  const hovers = makeTimelineHoverHelpers();
 
-      function recolorEvents() {
-        const colorTG = currentActiveGroup ?? swimlaneTagGroup ?? null;
-        mainG.selectAll<SVGGElement, unknown>('.tl-event').each(function () {
-          const el = d3Selection.select(this);
-          const lineNum = el.attr('data-line-number');
-          const ev = lineNum ? eventByLine.get(lineNum) : undefined;
-          if (!ev) return;
-
-          let color: string;
-          if (colorTG) {
-            const tagColor = resolveTagColor(
-              ev.metadata,
-              parsed.timelineTagGroups,
-              colorTG
-            );
-            color =
-              tagColor ??
-              (ev.group && groupColorMap.has(ev.group)
-                ? groupColorMap.get(ev.group)!
-                : textColor);
-          } else {
-            color =
-              ev.group && groupColorMap.has(ev.group)
-                ? groupColorMap.get(ev.group)!
-                : textColor;
-          }
-          el.selectAll('rect')
-            .attr('fill', shapeFill(palette, color, isDark, { solid }))
-            .attr('stroke', color);
-          el.selectAll('circle:not(.tl-event-point-outline)')
-            .attr('fill', shapeFill(palette, color, isDark, { solid }))
-            .attr('stroke', color);
-        });
-      }
+  if (isVertical) {
+    renderTimelineVertical(
+      container,
+      parsed,
+      palette,
+      isDark,
+      setup,
+      hovers,
+      onClickItem,
+      exportDims,
+      swimlaneTagGroup,
+      activeTagGroup,
+      onTagStateChange,
+      viewMode
+    );
+    return;
+  }
 
-      drawLegend();
-    }
+  const useGroupedHorizontal =
+    tagLanes != null ||
+    (parsed.timelineSort === 'group' && parsed.timelineGroups.length > 0);
+  if (useGroupedHorizontal) {
+    renderTimelineHorizontalGrouped(
+      container,
+      parsed,
+      palette,
+      isDark,
+      setup,
+      hovers,
+      onClickItem,
+      exportDims,
+      swimlaneTagGroup,
+      activeTagGroup,
+      onTagStateChange,
+      viewMode
+    );
+  } else {
+    renderTimelineHorizontalTimeSort(
+      container,
+      parsed,
+      palette,
+      isDark,
+      setup,
+      hovers,
+      onClickItem,
+      exportDims,
+      swimlaneTagGroup,
+      activeTagGroup,
+      onTagStateChange,
+      viewMode
+    );
   }
+
+  renderTimelineTagLegendOverlay(
+    container,
+    parsed,
+    palette,
+    isDark,
+    setup,
+    hovers,
+    onClickItem,
+    exportDims,
+    swimlaneTagGroup,
+    activeTagGroup,
+    onTagStateChange,
+    viewMode,
+    exportMode
+  );
 }
 
 // ============================================================
@@ -5580,7 +5936,7 @@ export function renderVenn(
   container: HTMLDivElement,
   parsed: ParsedVisualization,
   palette: PaletteColors,
-  isDark: boolean,
+  _isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
   exportDims?: D3ExportDimensions
 ): void {
@@ -5955,7 +6311,7 @@ export function renderVenn(
   const gcx = circles.reduce((s, c) => s + c.x, 0) / n;
   const gcy = circles.reduce((s, c) => s + c.y, 0) / n;
 
-  function exclusiveHSpan(px: number, py: number, ci: number): number {
+  function exclusiveHSpan(_px: number, py: number, ci: number): number {
     const dy = py - circles[ci].y;
     const halfChord = Math.sqrt(
       Math.max(0, circles[ci].r * circles[ci].r - dy * dy)
@@ -7178,8 +7534,10 @@ export async function renderForExport(
     c4System?: string;
     c4Container?: string;
     tagGroup?: string;
+    exportMode?: boolean;
   }
 ): Promise<string> {
+  const exportMode = options?.exportMode ?? false;
   // Flowchart and org chart use their own parser pipelines — intercept before parseVisualization()
   const { parseDgmoChartType } = await import('./dgmo-router');
   const detectedType = parseDgmoChartType(content);
@@ -7233,7 +7591,9 @@ export async function renderForExport(
       undefined,
       { width: exportWidth, height: exportHeight },
       activeTagGroup,
-      hiddenAttributes
+      hiddenAttributes,
+      undefined,
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7287,7 +7647,8 @@ export async function renderForExport(
       undefined,
       { width: exportWidth, height: exportHeight },
       activeTagGroup,
-      hiddenAttributes
+      hiddenAttributes,
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7316,6 +7677,7 @@ export async function renderForExport(
       collapsedLanes: viewState?.cl ? new Set(viewState.cl) : undefined,
       collapsedColumns: viewState?.cc ? new Set(viewState.cc) : undefined,
       compactMeta: viewState?.cm,
+      exportMode,
     });
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7343,7 +7705,9 @@ export async function renderForExport(
       effectivePalette,
       theme === 'dark',
       undefined,
-      { width: exportWidth, height: exportHeight }
+      { width: exportWidth, height: exportHeight },
+      undefined,
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7377,7 +7741,8 @@ export async function renderForExport(
         erParsed.options['active-tag'],
         viewState?.tag ?? options?.tagGroup
       ),
-      viewState?.sem
+      viewState?.sem,
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7397,11 +7762,10 @@ export async function renderForExport(
       }
     }
 
-    const { layoutBoxesAndLines } = await import('./boxes-and-lines/layout');
     const { renderBoxesAndLinesForExport } =
       await import('./boxes-and-lines/renderer');
-
-    const blLayout = layoutBoxesAndLines(blParsed);
+    const { layoutBoxesAndLines } = await import('./boxes-and-lines/layout');
+    const blLayout = await layoutBoxesAndLines(blParsed);
     const PADDING = 20;
     const titleOffset = blParsed.title ? 40 : 0;
     const exportWidth = blLayout.width + PADDING * 2;
@@ -7418,6 +7782,7 @@ export async function renderForExport(
         exportDims: { width: exportWidth, height: exportHeight },
         activeTagGroup: viewState?.tag ?? options?.tagGroup,
         hiddenTagValues: blHiddenTagValues,
+        exportMode,
       }
     );
     return finalizeSvgExport(container, theme, effectivePalette);
@@ -7477,7 +7842,7 @@ export async function renderForExport(
       undefined,
       hideDescriptions,
       colorByDepth ? null : activeTagGroup,
-      colorByDepth ? { colorByDepth: true } : undefined
+      colorByDepth ? { colorByDepth: true, exportMode } : { exportMode }
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7579,7 +7944,8 @@ export async function renderForExport(
         c4Parsed.tagGroups,
         c4Parsed.options['active-tag'],
         viewState?.tag ?? options?.tagGroup
-      )
+      ),
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7746,6 +8112,7 @@ export async function renderForExport(
           resolved.options.activeTag ?? undefined,
           viewState?.tag ?? options?.tagGroup
         ),
+        exportMode,
       },
       { width: EXPORT_W, height: EXPORT_H }
     );
@@ -7793,7 +8160,8 @@ export async function renderForExport(
       effectivePalette,
       theme === 'dark',
       { width: RADAR_EXPORT_W, height: RADAR_EXPORT_H },
-      viewState
+      viewState,
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7820,6 +8188,7 @@ export async function renderForExport(
     );
     renderJourneyMap(container, jmParsed, effectivePalette, theme === 'dark', {
       exportDims: { width: jmLayout.totalWidth, height: jmLayout.totalHeight },
+      exportMode,
     });
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7839,7 +8208,8 @@ export async function renderForExport(
       effectivePalette,
       theme === 'dark',
       { width: EXPORT_WIDTH, height: EXPORT_HEIGHT },
-      viewState
+      viewState,
+      exportMode
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }
@@ -7978,7 +8348,10 @@ export async function renderForExport(
         undefined,
         viewState?.tag ?? options?.tagGroup
       ),
-      viewState?.swim
+      viewState?.swim,
+      undefined,
+      undefined,
+      exportMode
     );
   } else if (parsed.type === 'venn') {
     renderVenn(container, parsed, effectivePalette, isDark, undefined, dims);