feat: add XY plot swimlanes with EKG waveforms and cursor value display

- Add TimeGraphXYComponent for rendering line plots within rows
- Add XY series model (TimeGraphXYPoint, TimeGraphXYSeries) to row model
- Render XY plots only on empty rows (no states)
- Rich cursor shows interpolated XY value on hover with tooltip
- Example: two EKG-style swimlanes (Heart Rate, Respiration)

Author: MatthewKhouzam

example/src/test-data-provider.ts

@@ -186,6 +186,8 @@ export class TestDataProvider {
         timeGraphEntries.model.entries.forEach(entry => {
             rowIds.push(entry.id);
         });
+        // Add XY plot row IDs
+        rowIds.push(-100, -101);
         return rowIds;
     }
 
@@ -292,6 +294,13 @@ export class TestDataProvider {
             });
         });
 
+        // Generate XY plot rows with fixed-time EKG-style data
+        const xyRows: TimelineChart.TimeGraphRowModel[] = [
+            this.createXYRow(-100, 'Heart Rate (EKG)', range, (t) => this.ekgWaveform(t)),
+            this.createXYRow(-101, 'Respiration (EKG)', range, (t) => this.ekgWaveform(t * 0.4 + 0.1))
+        ];
+        rows.push(...xyRows);
+
         return {
             id: "",
             arrows,
@@ -300,4 +309,63 @@ export class TestDataProvider {
             totalLength: this.totalLength
         };
     }
+
+    private createXYRow(id: number, name: string, range: TimelineChart.TimeGraphRange, fn: (t: number) => number): TimelineChart.TimeGraphRowModel {
+        // Generate points with fixed time positions spanning the full trace.
+        // Only emit points that fall within the requested range (with small buffer).
+        const totalLen = Number(this.totalLength);
+        const rangeStart = Number(range.start);
+        const rangeEnd = Number(range.end);
+        const rangeLen = rangeEnd - rangeStart;
+
+        // Use enough points to get ~1 point per 2 pixels at current resolution
+        const numPoints = Math.max(200, Math.min(2000, Math.round(rangeLen / (totalLen / 2000))));
+        const step = rangeLen / (numPoints - 1);
+
+        const points: TimelineChart.TimeGraphXYPoint[] = [];
+        for (let i = 0; i < numPoints; i++) {
+            const timeNum = rangeStart + i * step;
+            const t = timeNum / totalLen; // normalized position in full trace
+            const time = BigInt(Math.round(timeNum));
+            points.push({ time, value: Math.max(0, Math.min(1, fn(t))) });
+        }
+        return {
+            id,
+            name,
+            range: { start: range.start, end: range.end },
+            states: [],
+            annotations: [],
+            xySeries: [{ id: `xy_${id}`, label: name, color: id === -100 ? 0x22cc44 : 0x44aaff, points }],
+            prevPossibleState: range.start,
+            nextPossibleState: range.end
+        };
+    }
+
+    /** EKG-style waveform: flat baseline with periodic sharp QRS-like spikes */
+    private ekgWaveform(t: number): number {
+        // Repeat every cycle; ~20 beats across the full trace
+        const cycles = 20;
+        const phase = (t * cycles) % 1;
+
+        // P wave (small bump)
+        if (phase > 0.1 && phase < 0.2) {
+            const p = (phase - 0.1) / 0.1;
+            return 0.5 + 0.08 * Math.sin(p * Math.PI);
+        }
+        // QRS complex (sharp spike)
+        if (phase > 0.25 && phase < 0.45) {
+            const q = (phase - 0.25) / 0.2;
+            if (q < 0.2) return 0.5 - 0.1 * (q / 0.2); // Q dip
+            if (q < 0.5) return 0.5 - 0.1 + 0.9 * ((q - 0.2) / 0.3); // R spike up
+            if (q < 0.7) return 0.5 + 0.8 - 1.0 * ((q - 0.5) / 0.2); // R spike down
+            return 0.5 - 0.2 + 0.2 * ((q - 0.7) / 0.3); // S recovery
+        }
+        // T wave (broad bump)
+        if (phase > 0.55 && phase < 0.75) {
+            const tw = (phase - 0.55) / 0.2;
+            return 0.5 + 0.12 * Math.sin(tw * Math.PI);
+        }
+        // Baseline
+        return 0.5;
+    }
 }

timeline-chart/src/components/time-graph-row.ts

@@ -2,6 +2,7 @@ import { TimeGraphComponent, TimeGraphElementPosition, TimeGraphParentComponent,
 import { TimelineChart } from "../time-graph-model";
 import { TimeGraphStateComponent } from "./time-graph-state";
 import { TimeGraphAnnotationComponent } from "./time-graph-annotation";
+import { TimeGraphXYComponent } from "./time-graph-xy";
 
 export interface TimeGraphRowStyle {
     backgroundColor?: number
@@ -16,6 +17,7 @@ export class TimeGraphRow extends TimeGraphComponent<TimelineChart.TimeGraphRowM
     protected _providedModel: { range: TimelineChart.TimeGraphRange, resolution: number, filterExpressionsMap?: {[key: number]: string[]} } | undefined;
     protected _rowStateComponents: Map<string, TimeGraphStateComponent> = new Map();
     protected _rowAnnotationComponents: Map<string, TimeGraphAnnotationComponent> = new Map();
+    protected _rowXYComponents: Map<string, TimeGraphXYComponent> = new Map();
 
     constructor(
         id: string,
@@ -96,6 +98,16 @@ export class TimeGraphRow extends TimeGraphComponent<TimelineChart.TimeGraphRowM
         return this._rowAnnotationComponents.get(id);
     }
 
+    addXYSeries(xyComponent: TimeGraphXYComponent) {
+        this._rowXYComponents.set(xyComponent.id, xyComponent);
+        this.addChild(xyComponent);
+    }
+
+    removeXYSeries(xyComponent: TimeGraphXYComponent) {
+        this._rowXYComponents.delete(xyComponent.id);
+        this.removeChild(xyComponent);
+    }
+
     get style() {
         return this._style;
     }

timeline-chart/src/components/time-graph-xy.ts

@@ -0,0 +1,47 @@
+import { TimeGraphComponent } from "./time-graph-component";
+import { TimelineChart } from "../time-graph-model";
+
+export interface TimeGraphXYStyle {
+    color?: number
+    opacity?: number
+    thickness?: number
+}
+
+export class TimeGraphXYComponent extends TimeGraphComponent<TimelineChart.TimeGraphXYSeries> {
+
+    constructor(
+        id: string,
+        model: TimelineChart.TimeGraphXYSeries,
+        protected _xCoordinates: number[],
+        protected _rowHeight: number,
+        protected _rowY: number,
+        protected _style: TimeGraphXYStyle = {}
+    ) {
+        super(id, undefined, model);
+    }
+
+    render() {
+        const color = this._style.color ?? this._model.color ?? 0x0000ff;
+        const opacity = this._style.opacity ?? 1;
+        const thickness = this._style.thickness ?? 1.5;
+        const points = this._model.points;
+
+        if (points.length < 2 || this._xCoordinates.length !== points.length) {
+            return;
+        }
+
+        this._displayObject.lineStyle(thickness, color, opacity);
+
+        const padding = 2;
+        const drawHeight = this._rowHeight - padding * 2;
+
+        // moveTo first point
+        const y0 = this._rowY + padding + drawHeight * (1 - points[0].value);
+        this._displayObject.moveTo(this._xCoordinates[0], y0);
+
+        for (let i = 1; i < points.length; i++) {
+            const y = this._rowY + padding + drawHeight * (1 - points[i].value);
+            this._displayObject.lineTo(this._xCoordinates[i], y);
+        }
+    }
+}

timeline-chart/src/layer/time-graph-chart-rich-cursor.ts

@@ -3,6 +3,7 @@ import * as PIXI from "pixi.js-legacy";
 import { TimeGraphChartLayer } from "./time-graph-chart-layer";
 import { TimeGraphRowController } from "../time-graph-row-controller";
 import { TimeGraphChart } from "./time-graph-chart";
+import { TimelineChart } from "../time-graph-model";
 import { BIMath } from "../bigint-utils";
 
 export class TimeGraphChartRichCursor extends TimeGraphChartLayer {
@@ -88,6 +89,57 @@ export class TimeGraphChartRichCursor extends TimeGraphChartLayer {
                 this.drawTooltip(mouseX, centerY, label);
             }
         });
+
+        // Draw XY value indicators on rows with xySeries
+        const rowComponents: Map<number, any> = (this.chartLayer as any).rowComponents;
+        rowComponents.forEach((rowComponent) => {
+            const model: TimelineChart.TimeGraphRowModel | undefined = rowComponent.model;
+            if (!model?.xySeries?.length) return;
+
+            const y = rowComponent.position.y - this.rowController.verticalOffset;
+            if (y + rowHeight < 0 || y > height) return;
+
+            const padding = 2;
+            const drawHeight = rowHeight - padding * 2;
+
+            model.xySeries.forEach((series: TimelineChart.TimeGraphXYSeries) => {
+                const value = this.interpolateXY(series.points, timestamp);
+                if (value === undefined) return;
+
+                const dotY = y + padding + drawHeight * (1 - value);
+                const color = series.color ?? 0x0000ff;
+
+                this.graphics.beginFill(color, 1);
+                this.graphics.drawCircle(mouseX, dotY, 4);
+                this.graphics.endFill();
+                this.graphics.lineStyle(1, 0xffffff, 0.8);
+                this.graphics.drawCircle(mouseX, dotY, 4);
+                this.graphics.lineStyle(0);
+
+                const label = `${series.label ?? 'XY'}: ${value.toFixed(2)}`;
+                this.drawTooltip(mouseX, dotY, label);
+            });
+        });
+    }
+
+    /** Linearly interpolate the XY series value at the given timestamp */
+    private interpolateXY(points: TimelineChart.TimeGraphXYPoint[], timestamp: bigint): number | undefined {
+        if (points.length === 0) return undefined;
+        if (timestamp <= points[0].time) return points[0].value;
+        if (timestamp >= points[points.length - 1].time) return points[points.length - 1].value;
+
+        // Binary search for the bracketing interval
+        let lo = 0, hi = points.length - 1;
+        while (hi - lo > 1) {
+            const mid = (lo + hi) >> 1;
+            if (points[mid].time <= timestamp) lo = mid;
+            else hi = mid;
+        }
+        const p0 = points[lo], p1 = points[hi];
+        const dt = Number(p1.time - p0.time);
+        if (dt === 0) return p0.value;
+        const t = Number(timestamp - p0.time) / dt;
+        return p0.value + t * (p1.value - p0.value);
     }
 
     private removeTooltips() {

timeline-chart/src/layer/time-graph-chart.ts

@@ -4,6 +4,7 @@ import { TimeGraphComponent } from "../components/time-graph-component";
 import { TimeGraphRectangle } from "../components/time-graph-rectangle";
 import { TimeGraphRow, TimeGraphRowStyle } from "../components/time-graph-row";
 import { TimeGraphStateComponent, TimeGraphStateStyle } from "../components/time-graph-state";
+import { TimeGraphXYComponent } from "../components/time-graph-xy";
 import { TimelineChart } from "../time-graph-model";
 import { TimeGraphRowController } from "../time-graph-row-controller";
 import { TimeGraphChartLayer } from "./time-graph-chart-layer";
@@ -788,6 +789,20 @@ export class TimeGraphChart extends TimeGraphChartLayer {
                 rowComponent.addAnnotation(el);
             }
         });
+        if (row.xySeries && row.states.length === 0) {
+            row.xySeries.forEach((series: TimelineChart.TimeGraphXYSeries) => {
+                const xCoords = series.points.map(p => this.getWorldPixel(p.time));
+                const xy = new TimeGraphXYComponent(
+                    series.id,
+                    series,
+                    xCoords,
+                    rowComponent.height,
+                    rowComponent.position.y,
+                    { color: series.color }
+                );
+                rowComponent.addXYSeries(xy);
+            });
+        }
         rowComponent.providedModel = providedModel;
     }
 

timeline-chart/src/time-graph-model.ts

@@ -19,6 +19,8 @@ export namespace TimelineChart {
         range: TimeGraphRange
         states: TimeGraphState[]
         annotations: TimeGraphAnnotation[]
+        /** Optional XY series to render as line plots within this row (values normalized 0-1) */
+        xySeries?: TimeGraphXYSeries[]
         selected?: boolean
         readonly data?: { [key: string]: any }
         prevPossibleState: bigint
@@ -56,4 +58,17 @@ export namespace TimelineChart {
         selected?: boolean
         readonly data?: { [key: string]: any }
     }
+
+    export interface TimeGraphXYPoint {
+        readonly time: bigint
+        /** Normalized value between 0 and 1 */
+        readonly value: number
+    }
+
+    export interface TimeGraphXYSeries {
+        readonly id: string
+        readonly label?: string
+        readonly color?: number
+        readonly points: TimeGraphXYPoint[]
+    }
 }