@diagrammo/dgmo 0.4.4 → 0.5.1

package/src/d3.ts

@@ -65,13 +65,14 @@ export interface ArcNodeGroup {
   lineNumber: number;
 }
 
-export type TimelineSort = 'time' | 'group';
+export type TimelineSort = 'time' | 'group' | 'tag';
 
 export interface TimelineEvent {
   date: string;
   endDate: string | null;
   label: string;
   group: string | null;
+  metadata: Record<string, string>;
   lineNumber: number;
   uncertain?: boolean;
 }
@@ -153,7 +154,9 @@ export interface ParsedD3 {
   timelineGroups: TimelineGroup[];
   timelineEras: TimelineEra[];
   timelineMarkers: TimelineMarker[];
+  timelineTagGroups: TagGroup[];
   timelineSort: TimelineSort;
+  timelineDefaultSwimlaneTG?: string;
   timelineScale: boolean;
   timelineSwimlanes: boolean;
   vennSets: VennSet[];
@@ -178,9 +181,12 @@ export interface ParsedD3 {
 import { resolveColor } from './colors';
 import type { PaletteColors } from './palettes';
 import { getSeriesColors } from './palettes';
+import { mix } from './palettes/color-utils';
 import type { DgmoError } from './diagnostics';
 import { makeDgmoError, formatDgmoError, suggest } from './diagnostics';
-import { collectIndentedValues } from './utils/parsing';
+import { collectIndentedValues, extractColor, parsePipeMetadata } from './utils/parsing';
+import { matchTagBlockHeading, validateTagValues, resolveTagColor } from './utils/tag-groups';
+import type { TagGroup } from './utils/tag-groups';
 
 // ============================================================
 // Shared Rendering Helpers
@@ -342,6 +348,7 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
     timelineGroups: [],
     timelineEras: [],
     timelineMarkers: [],
+    timelineTagGroups: [],
     timelineSort: 'time',
     timelineScale: true,
     timelineSwimlanes: false,
@@ -379,28 +386,74 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
   const freeformLines: string[] = [];
   let currentArcGroup: string | null = null;
   let currentTimelineGroup: string | null = null;
+  let currentTimelineTagGroup: TagGroup | null = null;
+  const timelineAliasMap = new Map<string, string>();
 
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
+    const rawLine = lines[i];
+    const line = rawLine.trim();
+    const indent = rawLine.length - rawLine.trimStart().length;
     const lineNumber = i + 1;
 
     // Skip empty lines
     if (!line) continue;
 
-    // ## Section headers for arc diagram node grouping (before # comment check)
-    const sectionMatch = line.match(/^#{2,}\s+(.+?)(?:\s*\(([^)]+)\))?\s*$/);
-    if (sectionMatch) {
+    // Timeline tag group heading: `tag: Name [alias X]`
+    if (result.type === 'timeline' && indent === 0) {
+      const tagBlockMatch = matchTagBlockHeading(line);
+      if (tagBlockMatch) {
+        if (tagBlockMatch.deprecated) {
+          result.diagnostics.push(makeDgmoError(lineNumber,
+            `'## ${tagBlockMatch.name}' is deprecated for tag groups — use 'tag: ${tagBlockMatch.name}' instead`, 'warning'));
+        }
+        currentTimelineTagGroup = {
+          name: tagBlockMatch.name,
+          alias: tagBlockMatch.alias,
+          entries: [],
+          lineNumber,
+        };
+        if (tagBlockMatch.alias) {
+          timelineAliasMap.set(tagBlockMatch.alias.toLowerCase(), tagBlockMatch.name.toLowerCase());
+        }
+        result.timelineTagGroups.push(currentTimelineTagGroup);
+        continue;
+      }
+    }
+
+    // Timeline tag group entries (indented under tag: heading)
+    if (currentTimelineTagGroup && indent > 0) {
+      const trimmedEntry = line;
+      const isDefault = /\bdefault\s*$/.test(trimmedEntry);
+      const entryText = isDefault
+        ? trimmedEntry.replace(/\s+default\s*$/, '').trim()
+        : trimmedEntry;
+      const { label, color } = extractColor(entryText, palette);
+      if (color) {
+        if (isDefault) currentTimelineTagGroup.defaultValue = label;
+        currentTimelineTagGroup.entries.push({ value: label, color, lineNumber });
+        continue;
+      }
+    }
+
+    // End tag group on non-indented line
+    if (currentTimelineTagGroup && indent === 0) {
+      currentTimelineTagGroup = null;
+    }
+
+    // [Group] container headers for arc diagram node grouping and timeline eras
+    const groupMatch = line.match(/^\[(.+?)\](?:\s*\(([^)]+)\))?\s*$/);
+    if (groupMatch) {
       if (result.type === 'arc') {
-        const name = sectionMatch[1].trim();
-        const color = sectionMatch[2]
-          ? resolveColor(sectionMatch[2].trim(), palette)
+        const name = groupMatch[1].trim();
+        const color = groupMatch[2]
+          ? resolveColor(groupMatch[2].trim(), palette)
           : null;
         result.arcNodeGroups.push({ name, nodes: [], color, lineNumber });
         currentArcGroup = name;
       } else if (result.type === 'timeline') {
-        const name = sectionMatch[1].trim();
-        const color = sectionMatch[2]
-          ? resolveColor(sectionMatch[2].trim(), palette)
+        const name = groupMatch[1].trim();
+        const color = groupMatch[2]
+          ? resolveColor(groupMatch[2].trim(), palette)
           : null;
         result.timelineGroups.push({ name, color, lineNumber });
         currentTimelineGroup = name;
@@ -408,6 +461,19 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
       continue;
     }
 
+    // Reject legacy ## group syntax
+    if (/^#{2,}\s+/.test(line) && (result.type === 'arc' || result.type === 'timeline')) {
+      const name = line.replace(/^#{2,}\s+/, '').replace(/\s*\([^)]*\)\s*$/, '').trim();
+      result.diagnostics.push(makeDgmoError(lineNumber, `'## ${name}' is no longer supported. Use '[${name}]' instead`, 'warning'));
+      continue;
+    }
+
+    // Clear group context on un-indented lines (except [Group] already handled above)
+    if (indent === 0) {
+      currentArcGroup = null;
+      currentTimelineGroup = null;
+    }
+
     // Skip comments
     if (line.startsWith('//')) {
       continue;
@@ -498,11 +564,16 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
         const amount = parseFloat(durationMatch[2]);
         const unit = durationMatch[3] as 'd' | 'w' | 'm' | 'y';
         const endDate = addDurationToDate(startDate, amount, unit);
+        const segments = durationMatch[5].split('|');
+        const metadata = segments.length > 1
+          ? parsePipeMetadata(['', ...segments.slice(1)], timelineAliasMap)
+          : {};
         result.timelineEvents.push({
           date: startDate,
           endDate,
-          label: durationMatch[5].trim(),
+          label: segments[0].trim(),
           group: currentTimelineGroup,
+          metadata,
           lineNumber,
           uncertain,
         });
@@ -514,11 +585,16 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
         /^(\d{4}(?:-\d{2})?(?:-\d{2})?)\s*->\s*(\d{4}(?:-\d{2})?(?:-\d{2})?)(\?)?\s*:\s*(.+)$/
       );
       if (rangeMatch) {
+        const segments = rangeMatch[4].split('|');
+        const metadata = segments.length > 1
+          ? parsePipeMetadata(['', ...segments.slice(1)], timelineAliasMap)
+          : {};
         result.timelineEvents.push({
           date: rangeMatch[1],
           endDate: rangeMatch[2],
-          label: rangeMatch[4].trim(),
+          label: segments[0].trim(),
           group: currentTimelineGroup,
+          metadata,
           lineNumber,
           uncertain: rangeMatch[3] === '?',
         });
@@ -530,11 +606,16 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
         /^(\d{4}(?:-\d{2})?(?:-\d{2})?)\s*:\s*(.+)$/
       );
       if (pointMatch) {
+        const segments = pointMatch[2].split('|');
+        const metadata = segments.length > 1
+          ? parsePipeMetadata(['', ...segments.slice(1)], timelineAliasMap)
+          : {};
         result.timelineEvents.push({
           date: pointMatch[1],
           endDate: null,
-          label: pointMatch[2].trim(),
+          label: segments[0].trim(),
           group: currentTimelineGroup,
+          metadata,
           lineNumber,
         });
         continue;
@@ -735,10 +816,19 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
       if (key === 'sort') {
         const v = line
           .substring(colonIndex + 1)
-          .trim()
-          .toLowerCase();
-        if (v === 'time' || v === 'group') {
-          result.timelineSort = v;
+          .trim();
+        const vLower = v.toLowerCase();
+        if (vLower === 'time' || vLower === 'group') {
+          result.timelineSort = vLower;
+        } else if (vLower === 'tag' || vLower.startsWith('tag:')) {
+          result.timelineSort = 'tag';
+          if (vLower.startsWith('tag:')) {
+            // Extract group name (preserving original case for display)
+            const groupRef = v.substring(4).trim();
+            if (groupRef) {
+              result.timelineDefaultSwimlaneTG = groupRef;
+            }
+          }
         }
         continue;
       }
@@ -914,7 +1004,7 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
     // Validate arc ordering vs groups
     if (result.arcNodeGroups.length > 0) {
       if (result.arcOrder === 'name' || result.arcOrder === 'degree') {
-        warn(1, `Cannot use "order: ${result.arcOrder}" with ## section headers. Use "order: group" or remove section headers.`);
+        warn(1, `Cannot use "order: ${result.arcOrder}" with [Group] headers. Use "order: group" or remove group headers.`);
         result.arcOrder = 'group';
       }
       if (result.arcOrder === 'appearance') {
@@ -928,6 +1018,48 @@ export function parseD3(content: string, palette?: PaletteColors): ParsedD3 {
     if (result.timelineEvents.length === 0) {
       warn(1, 'No events found. Add events as "YYYY: description" or "YYYY->YYYY: description"');
     }
+    // Validate tag values and inject defaults
+    if (result.timelineTagGroups.length > 0) {
+      validateTagValues(
+        result.timelineEvents,
+        result.timelineTagGroups,
+        (line, msg) => result.diagnostics.push(makeDgmoError(line, msg, 'warning')),
+        suggest,
+      );
+      for (const group of result.timelineTagGroups) {
+        if (!group.defaultValue) continue;
+        const key = group.name.toLowerCase();
+        for (const event of result.timelineEvents) {
+          if (!event.metadata[key]) {
+            event.metadata[key] = group.defaultValue;
+          }
+        }
+      }
+    }
+
+    // Resolve sort: tag default swimlane group
+    if (result.timelineSort === 'tag') {
+      if (result.timelineTagGroups.length === 0) {
+        warn(1, '"sort: tag" requires at least one tag group definition');
+        result.timelineSort = 'time';
+      } else if (result.timelineDefaultSwimlaneTG) {
+        // Resolve alias → full group name
+        const ref = result.timelineDefaultSwimlaneTG.toLowerCase();
+        const match = result.timelineTagGroups.find(
+          (g) => g.name.toLowerCase() === ref || g.alias?.toLowerCase() === ref
+        );
+        if (match) {
+          result.timelineDefaultSwimlaneTG = match.name;
+        } else {
+          warn(1, `"sort: tag:${result.timelineDefaultSwimlaneTG}" — no tag group matches "${result.timelineDefaultSwimlaneTG}"`);
+          result.timelineDefaultSwimlaneTG = result.timelineTagGroups[0].name;
+        }
+      } else {
+        // Default to first tag group
+        result.timelineDefaultSwimlaneTG = result.timelineTagGroups[0].name;
+      }
+    }
+
     return result;
   }
 
@@ -2682,7 +2814,10 @@ export function renderTimeline(
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
-  exportDims?: D3ExportDimensions
+  exportDims?: D3ExportDimensions,
+  activeTagGroup?: string | null,
+  swimlaneTagGroup?: string | null,
+  onTagStateChange?: (activeTagGroup: string | null, swimlaneTagGroup: string | null) => void
 ): void {
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
 
@@ -2699,6 +2834,11 @@ export function renderTimeline(
   } = parsed;
   if (timelineEvents.length === 0) return;
 
+  // When sort: tag is set and no explicit swimlane param, use the default
+  if (swimlaneTagGroup == null && timelineSort === 'tag' && parsed.timelineDefaultSwimlaneTG) {
+    swimlaneTagGroup = parsed.timelineDefaultSwimlaneTG;
+  }
+
   const tooltip = createTooltip(container, palette, isDark);
 
   const width = exportDims?.width ?? container.clientWidth;
@@ -2719,7 +2859,63 @@ export function renderTimeline(
     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();
+    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) {
+        const val = ev.metadata[tagKey];
+        if (val) {
+          const list = buckets.get(val) ?? [];
+          list.push(ev);
+          buckets.set(val, list);
+        } else {
+          otherEvents.push(ev);
+        }
+      }
+
+      // 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))
+        );
+        return aMin - bMin;
+      });
+
+      tagLanes = laneEntries.map(([name, events]) => ({ name, events }));
+      if (otherEvents.length > 0) {
+        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;
+
   function eventColor(ev: TimelineEvent): string {
+    // Tag color takes priority when a tag group is active
+    if (effectiveColorTG) {
+      const tagColor = resolveTagColor(ev.metadata, parsed.timelineTagGroups, effectiveColorTG);
+      if (tagColor) return tagColor;
+    }
     if (ev.group && groupColorMap.has(ev.group)) {
       return groupColorMap.get(ev.group)!;
     }
@@ -2811,29 +3007,87 @@ export function renderTimeline(
     g: d3Selection.Selection<SVGGElement, unknown, null, undefined>
   ) {
     g.selectAll<SVGGElement, unknown>(
-      '.tl-event, .tl-legend-item, .tl-lane-header, .tl-marker'
+      '.tl-event, .tl-legend-item, .tl-lane-header, .tl-marker, .tl-tag-legend-entry'
     ).attr('opacity', 1);
     g.selectAll<SVGGElement, unknown>('.tl-era').attr('opacity', 1);
   }
 
+  function fadeToTagValue(
+    g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    tagKey: string,
+    tagValue: string
+  ) {
+    const attrName = `data-tag-${tagKey}`;
+    g.selectAll<SVGGElement, unknown>('.tl-event').each(function () {
+      const el = d3Selection.select(this);
+      const val = el.attr(attrName);
+      el.attr('opacity', val === tagValue ? 1 : FADE_OPACITY);
+    });
+    g.selectAll<SVGGElement, unknown>('.tl-legend-item, .tl-lane-header').attr(
+      'opacity', FADE_OPACITY
+    );
+    g.selectAll<SVGGElement, unknown>('.tl-marker').attr('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
+      const entryGroup = el.attr('data-tag-group');
+      el.attr('opacity', entryGroup === tagKey && entryValue === tagValue ? 1 : FADE_OPACITY);
+    });
+  }
+
+  /** Attach data-tag-* attributes on an event group element */
+  function setTagAttrs(
+    evG: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+    ev: TimelineEvent
+  ) {
+    for (const [key, value] of Object.entries(ev.metadata)) {
+      evG.attr(`data-tag-${key}`, value.toLowerCase());
+    }
+  }
+
+  // Reserve space for tag legend between title and chart content
+  const tagLegendReserve = parsed.timelineTagGroups.length > 0 ? 36 : 0;
+
   // ================================================================
   // VERTICAL orientation (time flows top→bottom)
   // ================================================================
   if (isVertical) {
-    if (timelineSort === 'group' && timelineGroups.length > 0) {
+    const useGroupedVertical = tagLanes != null ||
+      (timelineSort === 'group' && timelineGroups.length > 0);
+    if (useGroupedVertical) {
       // === GROUPED: one column/lane per group, vertical ===
-      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;
+      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
+            ),
+          ])
+        );
+      }
 
       const laneCount = laneNames.length;
       const scaleMargin = timelineScale ? 40 : 0;
       const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
       const margin = {
-        top: 104 + markerMargin,
+        top: 104 + markerMargin + tagLegendReserve,
         right: 40 + scaleMargin,
         bottom: 40,
         left: 60 + scaleMargin,
@@ -2901,6 +3155,23 @@ export function renderTimeline(
         );
       }
 
+      // 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);
+        });
+      }
+
       laneNames.forEach((laneName, laneIdx) => {
         const laneX = laneIdx * laneWidth;
         const laneColor = groupColorMap.get(laneName) ?? textColor;
@@ -2933,11 +3204,7 @@ export function renderTimeline(
           .attr('stroke-width', 1)
           .attr('stroke-dasharray', '4,4');
 
-        const laneEvents = timelineEvents.filter((ev) =>
-          laneName === '(Other)'
-            ? ev.group === null || !groupNames.includes(ev.group)
-            : ev.group === laneName
-        );
+        const laneEvents = laneEventsByName.get(laneName) ?? [];
 
         for (const ev of laneEvents) {
           const y = yScale(parseTimelineDate(ev.date));
@@ -2966,12 +3233,15 @@ export function renderTimeline(
             .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 = laneColor;
+            let fill: string = evColor;
             if (ev.uncertain) {
               const gradientId = `uncertain-vg-${ev.lineNumber}`;
               const defs =
@@ -3020,7 +3290,7 @@ export function renderTimeline(
               .attr('cx', laneCenter)
               .attr('cy', y)
               .attr('r', 4)
-              .attr('fill', laneColor)
+              .attr('fill', evColor)
               .attr('stroke', bgColor)
               .attr('stroke-width', 1.5);
             evG
@@ -3039,7 +3309,7 @@ export function renderTimeline(
       const scaleMargin = timelineScale ? 40 : 0;
       const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
       const margin = {
-        top: 104 + markerMargin,
+        top: 104 + markerMargin + tagLegendReserve,
         right: 200,
         bottom: 40,
         left: 60 + scaleMargin,
@@ -3183,6 +3453,7 @@ export function renderTimeline(
           .on('click', () => {
             if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
           });
+        setTagAttrs(evG, ev);
 
         if (ev.endDate) {
           const y2 = yScale(parseTimelineDate(ev.endDate));
@@ -3285,24 +3556,30 @@ export function renderTimeline(
   const BAR_H = 22; // range bar thickness (tall enough for text inside)
   const GROUP_GAP = 12; // vertical gap between group swim-lanes
 
-  if (timelineSort === 'group' && timelineGroups.length > 0) {
+  const useGroupedHorizontal = tagLanes != null ||
+    (timelineSort === 'group' && timelineGroups.length > 0);
+  if (useGroupedHorizontal) {
     // === GROUPED: swim-lanes stacked vertically, events on own rows ===
-    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;
-
-    // Build lane data
-    const lanes = laneNames.map((name) => ({
-      name,
-      events: timelineEvents.filter((ev) =>
-        name === '(Other)'
-          ? ev.group === null || !groupNames.includes(ev.group)
-          : ev.group === name
-      ),
-    }));
+    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;
@@ -3313,7 +3590,7 @@ export function renderTimeline(
     // Group-sorted doesn't need legend space (group names shown on left)
     const baseTopMargin = title ? 50 : 20;
     const margin = {
-      top: baseTopMargin + (timelineScale ? 40 : 0) + markerMargin,
+      top: baseTopMargin + (timelineScale ? 40 : 0) + markerMargin + tagLegendReserve,
       right: 40,
       bottom: 40 + scaleMargin,
       left: dynamicLeftMargin,
@@ -3387,7 +3664,7 @@ export function renderTimeline(
 
     // Render swimlane backgrounds first (so they appear behind events)
     // Extend into left margin to include group names
-    if (timelineSwimlanes) {
+    if (timelineSwimlanes || tagLanes) {
       let swimY = markerMargin;
       lanes.forEach((lane, idx) => {
         const laneSpan = lane.events.length * rowH;
@@ -3480,6 +3757,9 @@ export function renderTimeline(
           .on('click', () => {
             if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
           });
+        setTagAttrs(evG, ev);
+
+        const evColor = eventColor(ev);
 
         if (ev.endDate) {
           const x2 = xScale(parseTimelineDate(ev.endDate));
@@ -3488,7 +3768,7 @@ export function renderTimeline(
           const estLabelWidth = ev.label.length * 7 + 16;
           const labelFitsInside = rectW >= estLabelWidth;
 
-          let fill: string = laneColor;
+          let fill: string = evColor;
           if (ev.uncertain) {
             // Create gradient for uncertain end - fades last 20%
             const gradientId = `uncertain-${ev.lineNumber}`;
@@ -3510,7 +3790,7 @@ export function renderTimeline(
               .enter()
               .append('stop')
               .attr('offset', (d) => d.offset)
-              .attr('stop-color', laneColor)
+              .attr('stop-color', evColor)
               .attr('stop-opacity', (d) => d.opacity);
             fill = `url(#${gradientId})`;
           }
@@ -3563,7 +3843,7 @@ export function renderTimeline(
             .attr('cx', x)
             .attr('cy', y)
             .attr('r', 5)
-            .attr('fill', laneColor)
+            .attr('fill', evColor)
             .attr('stroke', bgColor)
             .attr('stroke-width', 1.5);
           evG
@@ -3589,7 +3869,7 @@ export function renderTimeline(
     const scaleMargin = timelineScale ? 24 : 0;
     const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
     const margin = {
-      top: 104 + (timelineScale ? 40 : 0) + markerMargin,
+      top: 104 + (timelineScale ? 40 : 0) + markerMargin + tagLegendReserve,
       right: 40,
       bottom: 40 + scaleMargin,
       left: 60,
@@ -3739,6 +4019,7 @@ export function renderTimeline(
         .on('click', () => {
           if (onClickItem && ev.lineNumber) onClickItem(ev.lineNumber);
         });
+      setTagAttrs(evG, ev);
 
       if (ev.endDate) {
         const x2 = xScale(parseTimelineDate(ev.endDate));
@@ -3837,6 +4118,283 @@ export function renderTimeline(
       }
     });
   }
+
+  // ── Tag Legend (org-chart-style pills) ──
+  if (parsed.timelineTagGroups.length > 0) {
+    const LG_HEIGHT = 28;
+    const LG_PILL_PAD = 16;
+    const LG_PILL_FONT_SIZE = 11;
+    const LG_PILL_FONT_W = LG_PILL_FONT_SIZE * 0.6;
+    const LG_CAPSULE_PAD = 4;
+    const LG_DOT_R = 4;
+    const LG_ENTRY_FONT_SIZE = 10;
+    const LG_ENTRY_FONT_W = LG_ENTRY_FONT_SIZE * 0.6;
+    const LG_ENTRY_DOT_GAP = 4;
+    const LG_ENTRY_TRAIL = 8;
+    const LG_GROUP_GAP = 12;
+    const LG_ICON_W = 20; // swimlane icon area (icon + surrounding space)
+
+    const mainSvg = d3Selection.select(container).select<SVGSVGElement>('svg');
+    const mainG = mainSvg.select<SVGGElement>('g');
+    if (!mainSvg.empty() && !mainG.empty()) {
+      const legendY = title ? 50 : 10;
+
+      const groupBg = isDark
+        ? mix(palette.surface, palette.bg, 50)
+        : mix(palette.surface, palette.bg, 30);
+
+      // Pre-compute group widths (minified and expanded)
+      type LegendGroup = {
+        group: TagGroup;
+        minifiedWidth: number;
+        expandedWidth: number;
+      };
+      const legendGroups: LegendGroup[] = parsed.timelineTagGroups.map((g) => {
+        const pillW = g.name.length * LG_PILL_FONT_W + LG_PILL_PAD;
+        // Expanded: pill + icon + entries
+        let entryX = LG_CAPSULE_PAD + pillW + LG_ICON_W + 4;
+        for (const entry of g.entries) {
+          const textX = entryX + LG_DOT_R * 2 + LG_ENTRY_DOT_GAP;
+          entryX = textX + entry.value.length * LG_ENTRY_FONT_W + 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
+        );
+      }
+
+      function drawLegend() {
+        // Remove previous legend
+        mainSvg.selectAll('.tl-tag-legend-group').remove();
+
+        // Compute total width and center horizontally in SVG
+        const totalW = legendGroups.reduce((s, lg) => {
+          const isActive = currentActiveGroup != null &&
+            lg.group.name.toLowerCase() === currentActiveGroup.toLowerCase();
+          return s + (isActive ? lg.expandedWidth : lg.minifiedWidth);
+        }, 0) + (legendGroups.length - 1) * LG_GROUP_GAP;
+
+        let cx = (width - totalW) / 2;
+
+        for (const lg of legendGroups) {
+          const groupKey = lg.group.name.toLowerCase();
+          const isActive = currentActiveGroup != null &&
+            currentActiveGroup.toLowerCase() === groupKey;
+          const isSwimActive = currentSwimlaneGroup != null &&
+            currentSwimlaneGroup.toLowerCase() === groupKey;
+
+          const pillLabel = lg.group.name;
+          const pillWidth = pillLabel.length * LG_PILL_FONT_W + LG_PILL_PAD;
+
+          const gEl = mainSvg
+            .append('g')
+            .attr('transform', `translate(${cx}, ${legendY})`)
+            .attr('class', 'tl-tag-legend-group tl-tag-legend-entry')
+            .attr('data-legend-group', groupKey)
+            .attr('data-tag-group', groupKey)
+            .attr('data-legend-entry', '__group__')
+            .style('cursor', 'pointer')
+            .on('click', () => {
+              currentActiveGroup = currentActiveGroup === groupKey ? null : groupKey;
+              drawLegend();
+              recolorEvents();
+              onTagStateChange?.(currentActiveGroup, currentSwimlaneGroup);
+            });
+
+          // Outer capsule background (active only)
+          if (isActive) {
+            gEl.append('rect')
+              .attr('width', lg.expandedWidth)
+              .attr('height', LG_HEIGHT)
+              .attr('rx', LG_HEIGHT / 2)
+              .attr('fill', groupBg);
+          }
+
+          const pillXOff = isActive ? LG_CAPSULE_PAD : 0;
+          const pillYOff = isActive ? LG_CAPSULE_PAD : 0;
+          const pillH = LG_HEIGHT - (isActive ? LG_CAPSULE_PAD * 2 : 0);
+
+          // Pill background
+          gEl.append('rect')
+            .attr('x', pillXOff)
+            .attr('y', pillYOff)
+            .attr('width', pillWidth)
+            .attr('height', pillH)
+            .attr('rx', pillH / 2)
+            .attr('fill', isActive ? palette.bg : groupBg);
+
+          // Active pill border
+          if (isActive) {
+            gEl.append('rect')
+              .attr('x', pillXOff)
+              .attr('y', pillYOff)
+              .attr('width', pillWidth)
+              .attr('height', pillH)
+              .attr('rx', pillH / 2)
+              .attr('fill', 'none')
+              .attr('stroke', mix(palette.textMuted, palette.bg, 50))
+              .attr('stroke-width', 0.75);
+          }
+
+          // Pill text
+          gEl.append('text')
+            .attr('x', pillXOff + pillWidth / 2)
+            .attr('y', LG_HEIGHT / 2 + LG_PILL_FONT_SIZE / 2 - 2)
+            .attr('font-size', LG_PILL_FONT_SIZE)
+            .attr('font-weight', '500')
+            .attr('font-family', FONT_FAMILY)
+            .attr('fill', isActive ? palette.text : palette.textMuted)
+            .attr('text-anchor', 'middle')
+            .text(pillLabel);
+
+          // Entries + swimlane icon inside capsule (active only)
+          if (isActive) {
+            // Swimlane icon right after the pill label, with breathing room
+            const iconX = pillXOff + pillWidth + 5;
+            const iconY = (LG_HEIGHT - 10) / 2; // vertically centered
+            const iconEl = drawSwimlaneIcon(gEl, iconX, iconY, isSwimActive);
+            iconEl
+              .attr('data-swimlane-toggle', groupKey)
+              .on('click', (event: MouseEvent) => {
+                event.stopPropagation();
+                currentSwimlaneGroup = currentSwimlaneGroup === groupKey ? null : groupKey;
+                onTagStateChange?.(currentActiveGroup, currentSwimlaneGroup);
+                relayout();
+              });
+
+            let entryX = pillXOff + pillWidth + LG_ICON_W + 4;
+            for (const entry of lg.group.entries) {
+              const tagKey = lg.group.name.toLowerCase();
+              const tagVal = entry.value.toLowerCase();
+
+              const entryG = gEl.append('g')
+                .attr('class', 'tl-tag-legend-entry')
+                .attr('data-tag-group', tagKey)
+                .attr('data-legend-entry', tagVal)
+                .style('cursor', 'pointer')
+                .on('mouseenter', (event: MouseEvent) => {
+                  event.stopPropagation();
+                  fadeToTagValue(mainG, tagKey, tagVal);
+                  // Also fade legend entries on the SVG level
+                  mainSvg.selectAll<SVGGElement, unknown>('.tl-tag-legend-entry').each(function () {
+                    const el = d3Selection.select(this);
+                    const ev = el.attr('data-legend-entry');
+                    if (ev === '__group__') return;
+                    const eg = el.attr('data-tag-group');
+                    el.attr('opacity', eg === tagKey && ev === tagVal ? 1 : FADE_OPACITY);
+                  });
+                })
+                .on('mouseleave', (event: MouseEvent) => {
+                  event.stopPropagation();
+                  fadeReset(mainG);
+                  mainSvg.selectAll<SVGGElement, unknown>('.tl-tag-legend-entry')
+                    .attr('opacity', 1);
+                })
+                .on('click', (event: MouseEvent) => {
+                  event.stopPropagation(); // don't toggle group
+                });
+
+              entryG.append('circle')
+                .attr('cx', entryX + LG_DOT_R)
+                .attr('cy', LG_HEIGHT / 2)
+                .attr('r', LG_DOT_R)
+                .attr('fill', entry.color);
+
+              const textX = entryX + LG_DOT_R * 2 + LG_ENTRY_DOT_GAP;
+              entryG.append('text')
+                .attr('x', textX)
+                .attr('y', LG_HEIGHT / 2 + LG_ENTRY_FONT_SIZE / 2 - 1)
+                .attr('font-size', LG_ENTRY_FONT_SIZE)
+                .attr('font-family', FONT_FAMILY)
+                .attr('fill', palette.textMuted)
+                .text(entry.value);
+
+              entryX = textX + entry.value.length * LG_ENTRY_FONT_W + LG_ENTRY_TRAIL;
+            }
+          }
+
+          cx += (isActive ? lg.expandedWidth : lg.minifiedWidth) + LG_GROUP_GAP;
+        }
+      }
+
+      // Build a quick lineNumber→event lookup
+      const eventByLine = new Map<string, TimelineEvent>();
+      for (const ev of timelineEvents) {
+        eventByLine.set(String(ev.lineNumber), ev);
+      }
+
+      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', color);
+          el.selectAll('circle:not(.tl-event-point-outline)').attr('fill', color);
+        });
+      }
+
+      drawLegend();
+    }
+  }
 }
 
 // ============================================================
@@ -5158,6 +5716,7 @@ export async function renderD3ForExport(
     collapsedNodes?: Set<string>;
     activeTagGroup?: string | null;
     hiddenAttributes?: Set<string>;
+    swimlaneTagGroup?: string | null;
   },
   options?: { branding?: boolean; c4Level?: 'context' | 'containers' | 'components' | 'deployment'; c4System?: string; c4Container?: string; scenario?: string }
 ): Promise<string> {
@@ -5463,7 +6022,8 @@ export async function renderD3ForExport(
   } else if (parsed.type === 'arc') {
     renderArcDiagram(container, parsed, effectivePalette, isDark, undefined, dims);
   } else if (parsed.type === 'timeline') {
-    renderTimeline(container, parsed, effectivePalette, isDark, undefined, dims);
+    renderTimeline(container, parsed, effectivePalette, isDark, undefined, dims,
+      orgExportState?.activeTagGroup, orgExportState?.swimlaneTagGroup);
   } else if (parsed.type === 'venn') {
     renderVenn(container, parsed, effectivePalette, isDark, undefined, dims);
   } else if (parsed.type === 'quadrant') {