react-msaview 4.6.0 → 4.8.1

package/src/rowCoordinateCalculations.test.ts

@@ -1,12 +1,14 @@
 import { expect, test } from 'vitest'
 
 import {
-  globalCoordToRowSpecificCoord,
-  mouseOverCoordToGapRemovedCoord,
-  mouseOverCoordToGlobalCoord,
+  globalColToSeqPos,
+  globalColToVisibleCol,
+  visibleColToGlobalCol,
+  visibleColToSeqPos,
 } from './rowCoordinateCalculations'
 
-test('with blanks at positions [2, 5, 8]', () => {
+// Tests for visibleColToGlobalCol (visible → global)
+test('visibleColToGlobalCol with blanks at positions [2, 5, 8]', () => {
   const blanks = [2, 5, 8]
   ;(
     [
@@ -20,11 +22,11 @@ test('with blanks at positions [2, 5, 8]', () => {
       [7, 10],
     ] as const
   ).forEach(r => {
-    expect(mouseOverCoordToGlobalCoord(blanks, r[0])).toBe(r[1])
+    expect(visibleColToGlobalCol(blanks, r[0])).toBe(r[1])
   })
 })
 
-test('with no blanks', () => {
+test('visibleColToGlobalCol with no blanks', () => {
   const blanks: number[] = []
   ;(
     [
@@ -34,11 +36,11 @@ test('with no blanks', () => {
       [10, 10],
     ] as const
   ).forEach(r => {
-    expect(mouseOverCoordToGlobalCoord(blanks, r[0])).toBe(r[1])
+    expect(visibleColToGlobalCol(blanks, r[0])).toBe(r[1])
   })
 })
 
-test('with consecutive blanks', () => {
+test('visibleColToGlobalCol with consecutive blanks', () => {
   const blanks = [2, 3, 4, 7, 8]
   ;(
     [
@@ -50,11 +52,11 @@ test('with consecutive blanks', () => {
       [5, 10],
     ] as const
   ).forEach(r => {
-    expect(mouseOverCoordToGlobalCoord(blanks, r[0])).toBe(r[1])
+    expect(visibleColToGlobalCol(blanks, r[0])).toBe(r[1])
   })
 })
 
-test('with blanks at the beginning', () => {
+test('visibleColToGlobalCol with blanks at the beginning', () => {
   const blanks = [1, 2, 5]
   ;(
     [
@@ -65,11 +67,11 @@ test('with blanks at the beginning', () => {
       [4, 7],
     ] as const
   ).forEach(r => {
-    expect(mouseOverCoordToGlobalCoord(blanks, r[0])).toBe(r[1])
+    expect(visibleColToGlobalCol(blanks, r[0])).toBe(r[1])
   })
 })
 
-test('with position exceeding blanks array', () => {
+test('visibleColToGlobalCol with position exceeding blanks array', () => {
   const blanks = [2, 5]
   ;(
     [
@@ -81,89 +83,180 @@ test('with position exceeding blanks array', () => {
       [10, 12], // Far beyond blanks array
     ] as const
   ).forEach(r => {
-    expect(mouseOverCoordToGlobalCoord(blanks, r[0])).toBe(r[1])
+    expect(visibleColToGlobalCol(blanks, r[0])).toBe(r[1])
   })
 })
 
-test('with gaps in sequence', () => {
+// Tests for globalColToVisibleCol (global → visible)
+test('globalColToVisibleCol with blanks at positions [2, 5, 8]', () => {
+  const blanks = [2, 5, 8]
+  // Inverse of visibleColToGlobalCol
+  expect(globalColToVisibleCol(blanks, 0)).toBe(0)
+  expect(globalColToVisibleCol(blanks, 1)).toBe(1)
+  expect(globalColToVisibleCol(blanks, 2)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 3)).toBe(2)
+  expect(globalColToVisibleCol(blanks, 4)).toBe(3)
+  expect(globalColToVisibleCol(blanks, 5)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 6)).toBe(4)
+  expect(globalColToVisibleCol(blanks, 7)).toBe(5)
+  expect(globalColToVisibleCol(blanks, 8)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 9)).toBe(6)
+  expect(globalColToVisibleCol(blanks, 10)).toBe(7)
+})
+
+test('globalColToVisibleCol with no blanks', () => {
+  const blanks: number[] = []
+  expect(globalColToVisibleCol(blanks, 0)).toBe(0)
+  expect(globalColToVisibleCol(blanks, 5)).toBe(5)
+  expect(globalColToVisibleCol(blanks, 10)).toBe(10)
+})
+
+test('globalColToVisibleCol with consecutive blanks', () => {
+  const blanks = [2, 3, 4, 7, 8]
+  expect(globalColToVisibleCol(blanks, 0)).toBe(0)
+  expect(globalColToVisibleCol(blanks, 1)).toBe(1)
+  expect(globalColToVisibleCol(blanks, 2)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 3)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 4)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 5)).toBe(2)
+  expect(globalColToVisibleCol(blanks, 6)).toBe(3)
+  expect(globalColToVisibleCol(blanks, 7)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 8)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 9)).toBe(4)
+  expect(globalColToVisibleCol(blanks, 10)).toBe(5)
+})
+
+// Tests for globalColToSeqPos (global column → sequence position)
+test('globalColToSeqPos with gaps in sequence', () => {
   const sequence = 'AC-GT-A'
-  expect(globalCoordToRowSpecificCoord(sequence, 0)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 1)).toBe(1)
-  expect(globalCoordToRowSpecificCoord(sequence, 2)).toBe(2)
+  expect(globalColToSeqPos(sequence, 0)).toBe(0)
+  expect(globalColToSeqPos(sequence, 1)).toBe(1)
+  expect(globalColToSeqPos(sequence, 2)).toBe(2)
   // Position 2 is a gap, so count before it is 2
-  expect(globalCoordToRowSpecificCoord(sequence, 3)).toBe(2)
-  expect(globalCoordToRowSpecificCoord(sequence, 4)).toBe(3)
-  expect(globalCoordToRowSpecificCoord(sequence, 5)).toBe(4)
+  expect(globalColToSeqPos(sequence, 3)).toBe(2)
+  expect(globalColToSeqPos(sequence, 4)).toBe(3)
+  expect(globalColToSeqPos(sequence, 5)).toBe(4)
   // Position 5 is a gap, so count before it is 4
-  expect(globalCoordToRowSpecificCoord(sequence, 6)).toBe(4)
+  expect(globalColToSeqPos(sequence, 6)).toBe(4)
 })
 
-test('with mixed gap characters (- and .)', () => {
+test('globalColToSeqPos with mixed gap characters (- and .)', () => {
   const sequence = 'AC.GT-A'
-  expect(globalCoordToRowSpecificCoord(sequence, 0)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 1)).toBe(1)
+  expect(globalColToSeqPos(sequence, 0)).toBe(0)
+  expect(globalColToSeqPos(sequence, 1)).toBe(1)
   // Position 2 is a gap (.), so count before it is 2
-  expect(globalCoordToRowSpecificCoord(sequence, 2)).toBe(2)
-  expect(globalCoordToRowSpecificCoord(sequence, 3)).toBe(2)
-  expect(globalCoordToRowSpecificCoord(sequence, 4)).toBe(3)
+  expect(globalColToSeqPos(sequence, 2)).toBe(2)
+  expect(globalColToSeqPos(sequence, 3)).toBe(2)
+  expect(globalColToSeqPos(sequence, 4)).toBe(3)
   // Position 5 is a gap (-), so count before it is 4
-  expect(globalCoordToRowSpecificCoord(sequence, 5)).toBe(4)
-  expect(globalCoordToRowSpecificCoord(sequence, 6)).toBe(4)
+  expect(globalColToSeqPos(sequence, 5)).toBe(4)
+  expect(globalColToSeqPos(sequence, 6)).toBe(4)
 })
 
-test('with no gaps in sequence', () => {
+test('globalColToSeqPos with no gaps in sequence', () => {
   const sequence = 'ACGTA'
-  expect(globalCoordToRowSpecificCoord(sequence, 0)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 1)).toBe(1)
-  expect(globalCoordToRowSpecificCoord(sequence, 2)).toBe(2)
-  expect(globalCoordToRowSpecificCoord(sequence, 3)).toBe(3)
-  expect(globalCoordToRowSpecificCoord(sequence, 4)).toBe(4)
+  expect(globalColToSeqPos(sequence, 0)).toBe(0)
+  expect(globalColToSeqPos(sequence, 1)).toBe(1)
+  expect(globalColToSeqPos(sequence, 2)).toBe(2)
+  expect(globalColToSeqPos(sequence, 3)).toBe(3)
+  expect(globalColToSeqPos(sequence, 4)).toBe(4)
 })
 
-test('with all gaps in sequence', () => {
+test('globalColToSeqPos with all gaps in sequence', () => {
   const sequence = '-----'
-  expect(globalCoordToRowSpecificCoord(sequence, 0)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 1)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 2)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 3)).toBe(0)
-  expect(globalCoordToRowSpecificCoord(sequence, 4)).toBe(0)
+  expect(globalColToSeqPos(sequence, 0)).toBe(0)
+  expect(globalColToSeqPos(sequence, 1)).toBe(0)
+  expect(globalColToSeqPos(sequence, 2)).toBe(0)
+  expect(globalColToSeqPos(sequence, 3)).toBe(0)
+  expect(globalColToSeqPos(sequence, 4)).toBe(0)
 })
 
-test('with position exceeding sequence length', () => {
+test('globalColToSeqPos with position exceeding sequence length', () => {
   const sequence = 'AC-GT'
-  expect(globalCoordToRowSpecificCoord(sequence, 10)).toBe(4)
+  expect(globalColToSeqPos(sequence, 10)).toBe(4)
 })
 
-test('mouseOverCoordToGapRemovedCoord', () => {
+// Tests for visibleColToSeqPos (visible column → sequence position)
+test('visibleColToSeqPos returns sequence position or undefined for gaps', () => {
   const seq = 'AC--GT--CT'
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 0, blanks: [] }),
-  ).toBe(0)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 1, blanks: [] }),
-  ).toBe(1)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 2, blanks: [] }),
-  ).toBe(undefined)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 3, blanks: [] }),
-  ).toBe(undefined)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 4, blanks: [] }),
-  ).toBe(2)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 5, blanks: [] }),
-  ).toBe(3)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 6, blanks: [] }),
-  ).toBe(undefined)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 7, blanks: [] }),
-  ).toBe(undefined)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 8, blanks: [] }),
-  ).toBe(4)
-  expect(
-    mouseOverCoordToGapRemovedCoord({ seq, position: 9, blanks: [] }),
-  ).toBe(5)
+  expect(visibleColToSeqPos({ seq, visibleCol: 0, blanks: [] })).toBe(0)
+  expect(visibleColToSeqPos({ seq, visibleCol: 1, blanks: [] })).toBe(1)
+  expect(visibleColToSeqPos({ seq, visibleCol: 2, blanks: [] })).toBe(undefined)
+  expect(visibleColToSeqPos({ seq, visibleCol: 3, blanks: [] })).toBe(undefined)
+  expect(visibleColToSeqPos({ seq, visibleCol: 4, blanks: [] })).toBe(2)
+  expect(visibleColToSeqPos({ seq, visibleCol: 5, blanks: [] })).toBe(3)
+  expect(visibleColToSeqPos({ seq, visibleCol: 6, blanks: [] })).toBe(undefined)
+  expect(visibleColToSeqPos({ seq, visibleCol: 7, blanks: [] })).toBe(undefined)
+  expect(visibleColToSeqPos({ seq, visibleCol: 8, blanks: [] })).toBe(4)
+  expect(visibleColToSeqPos({ seq, visibleCol: 9, blanks: [] })).toBe(5)
+})
+
+// Round-trip tests: visible → global → visible should be identity for valid columns
+test('round-trip: visibleColToGlobalCol and globalColToVisibleCol are inverses', () => {
+  const blanks = [2, 5, 8]
+  // For each visible column, going to global and back should return the same value
+  for (let visibleCol = 0; visibleCol < 10; visibleCol++) {
+    const globalCol = visibleColToGlobalCol(blanks, visibleCol)
+    const backToVisible = globalColToVisibleCol(blanks, globalCol)
+    expect(backToVisible).toBe(visibleCol)
+  }
+})
+
+test('round-trip: globalColToVisibleCol and visibleColToGlobalCol for non-hidden columns', () => {
+  const blanks = [2, 5, 8]
+  // For each global column that is NOT hidden, going to visible and back should return the same value
+  for (let globalCol = 0; globalCol < 15; globalCol++) {
+    const visibleCol = globalColToVisibleCol(blanks, globalCol)
+    if (visibleCol !== undefined) {
+      const backToGlobal = visibleColToGlobalCol(blanks, visibleCol)
+      expect(backToGlobal).toBe(globalCol)
+    }
+  }
+})
+
+// Edge case: blanks at position 0
+test('globalColToVisibleCol with blank at position 0', () => {
+  const blanks = [0, 1, 5]
+  expect(globalColToVisibleCol(blanks, 0)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 1)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 2)).toBe(0) // First visible column
+  expect(globalColToVisibleCol(blanks, 3)).toBe(1)
+  expect(globalColToVisibleCol(blanks, 4)).toBe(2)
+  expect(globalColToVisibleCol(blanks, 5)).toBe(undefined) // Hidden
+  expect(globalColToVisibleCol(blanks, 6)).toBe(3)
+})
+
+test('visibleColToGlobalCol with blank at position 0', () => {
+  const blanks = [0, 1, 5]
+  expect(visibleColToGlobalCol(blanks, 0)).toBe(2) // Skips 0, 1
+  expect(visibleColToGlobalCol(blanks, 1)).toBe(3)
+  expect(visibleColToGlobalCol(blanks, 2)).toBe(4)
+  expect(visibleColToGlobalCol(blanks, 3)).toBe(6) // Skips 5
+})
+
+// Edge case: all columns before a position are blanks
+test('globalColToVisibleCol with many leading blanks', () => {
+  const blanks = [0, 1, 2, 3, 4]
+  expect(globalColToVisibleCol(blanks, 0)).toBe(undefined)
+  expect(globalColToVisibleCol(blanks, 4)).toBe(undefined)
+  expect(globalColToVisibleCol(blanks, 5)).toBe(0) // First visible
+  expect(globalColToVisibleCol(blanks, 6)).toBe(1)
+  expect(globalColToVisibleCol(blanks, 10)).toBe(5)
+})
+
+// Test visibleColToSeqPos with blanks (combined gap hiding and row gaps)
+test('visibleColToSeqPos with both blanks and row gaps', () => {
+  // Sequence: A-C-G (global cols 0,1,2,3,4)
+  // If blanks = [1, 3], visible sequence becomes: A C G (visible cols 0,1,2)
+  const seq = 'A-C-G'
+  const blanks = [1, 3]
+
+  // Visible col 0 → global col 0 → 'A' → seqPos 0
+  expect(visibleColToSeqPos({ seq, visibleCol: 0, blanks })).toBe(0)
+
+  // Visible col 1 → global col 2 → 'C' → seqPos 1
+  expect(visibleColToSeqPos({ seq, visibleCol: 1, blanks })).toBe(1)
+
+  // Visible col 2 → global col 4 → 'G' → seqPos 2
+  expect(visibleColToSeqPos({ seq, visibleCol: 2, blanks })).toBe(2)
 })

package/src/rowCoordinateCalculations.ts

@@ -1,101 +1,176 @@
 import { isBlank } from './util'
 
-export function mouseOverCoordToGlobalCoord(
-  blanks: number[],
-  position: number,
-) {
-  let mousePosition = 0 // Current position in mouse coordinates
-  let blankArrayIndex = 0 // Current index in the blanks array
-  let globalPosition = 0 // Position in global coordinates (return value)
+/**
+ * MSA Coordinate Systems:
+ *
+ * 1. **Global Column (globalCol)**: The column index in the full, unfiltered MSA.
+ *    Range: 0 to (MSA width - 1)
+ *    This is the "true" column position before any gap-hiding is applied.
+ *
+ * 2. **Visible Column (visibleCol)**: The column index after hiding gappy columns.
+ *    Range: 0 to (numColumns - 1) where numColumns = MSA width - blanks.length
+ *    This is what the user sees on screen when "Hide columns w/ N% gaps" is enabled.
+ *    When gap hiding is disabled, visibleCol === globalCol.
+ *
+ * 3. **Sequence Position (seqPos)**: The position within a specific row's ungapped sequence.
+ *    Range: 0 to (ungapped sequence length - 1)
+ *    This counts only non-gap characters ('-' and '.' are gaps).
+ *    Each row can have different seqPos values for the same globalCol due to gaps.
+ */
+
+/**
+ * Convert a visible column index to a global column index.
+ * This is used when translating mouse/screen coordinates to MSA coordinates.
+ *
+ * @param blanks - Sorted array of global column indices that are hidden
+ * @param visibleCol - The visible column index (what the user sees on screen)
+ * @returns The corresponding global column index in the full MSA
+ */
+export function visibleColToGlobalCol(blanks: number[], visibleCol: number) {
+  let currentVisibleCol = 0
+  let blankArrayIndex = 0
+  let globalCol = 0
   const blanksLen = blanks.length
 
-  // Iterate until we reach the target mouse position
-  while (mousePosition < position) {
-    // Skip any blank positions in the sequence
-    // Check if the next position (globalPosition + 1) is blank by comparing
-    // blanks[blankArrayIndex] - 1 with current globalPosition
+  // Skip any leading blank columns (blanks at the very beginning)
+  while (blankArrayIndex < blanksLen && blanks[blankArrayIndex] === globalCol) {
+    blankArrayIndex++
+    globalCol++
+  }
+
+  while (currentVisibleCol < visibleCol) {
+    currentVisibleCol++
+    globalCol++
+
+    // Skip any blank columns after incrementing
     while (
       blankArrayIndex < blanksLen &&
-      blanks[blankArrayIndex]! - 1 === globalPosition
+      blanks[blankArrayIndex] === globalCol
     ) {
       blankArrayIndex++
-      globalPosition++
+      globalCol++
     }
-
-    // Move to next position
-    mousePosition++
-    globalPosition++
   }
 
-  return globalPosition
+  return globalCol
 }
 
-export function globalCoordToRowSpecificCoord(seq: string, position: number) {
-  // Initialize counter for non-gap characters
-  let nonGapCount = 0
-  // Initialize position counter
-  let currentPosition = 0
-  const sequenceLength = seq.length
-
-  // Iterate until we reach the target position or end of sequence
-  while (currentPosition < position && currentPosition < sequenceLength) {
-    // If current character is not a gap, increment the non-gap counter
-    if (!isBlank(seq[currentPosition])) {
-      nonGapCount++
+/**
+ * Convert a global column index to a visible column index.
+ * This is the inverse of visibleColToGlobalCol.
+ *
+ * @param blanks - Sorted array of global column indices that are hidden
+ * @param globalCol - The global column index in the full MSA
+ * @returns The visible column index, or undefined if the column is hidden
+ */
+export function globalColToVisibleCol(
+  blanks: number[],
+  globalCol: number,
+): number | undefined {
+  // Check if this column is hidden
+  // Use binary search since blanks is sorted
+  let left = 0
+  let right = blanks.length - 1
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2)
+    if (blanks[mid] === globalCol) {
+      return undefined // Column is hidden
+    }
+    if (blanks[mid]! < globalCol) {
+      left = mid + 1
+    } else {
+      right = mid - 1
     }
-    currentPosition++
   }
 
-  return nonGapCount
+  // Count blanks before this column (left is now the insertion point)
+  const blanksBefore = left
+  return globalCol - blanksBefore
 }
 
-export function mouseOverCoordToGapRemovedRowCoord({
-  rowName,
-  position,
-  rowMap,
-  blanks,
-}: {
-  rowName: string
-  position: number
-  rowMap: Map<string, string>
-  blanks: number[]
-}) {
-  const seq = rowMap.get(rowName)
-  return seq !== undefined
-    ? mouseOverCoordToGapRemovedCoord({
-        seq,
-        position,
-        blanks,
-      })
-    : undefined
+/**
+ * Convert a global column index to a row-specific sequence position.
+ * This counts non-gap characters up to the given global column.
+ *
+ * @param seq - The row's sequence string (including gaps)
+ * @param globalCol - The global column index
+ * @returns The sequence position (count of non-gap characters before this column)
+ */
+export function globalColToSeqPos(seq: string, globalCol: number) {
+  let seqPos = 0
+  let currentCol = 0
+  const seqLen = seq.length
+
+  while (currentCol < globalCol && currentCol < seqLen) {
+    if (!isBlank(seq[currentCol])) {
+      seqPos++
+    }
+    currentCol++
+  }
+
+  return seqPos
 }
 
-export function mouseOverCoordToGapRemovedCoord({
+/**
+ * Convert a visible column to a row-specific sequence position.
+ * Returns undefined if the position is a gap in the sequence.
+ *
+ * @param seq - The row's sequence string (including gaps)
+ * @param blanks - Sorted array of global column indices that are hidden
+ * @param visibleCol - The visible column index
+ * @returns The sequence position, or undefined if it's a gap
+ */
+export function visibleColToSeqPos({
   seq,
   blanks,
-  position,
+  visibleCol,
 }: {
   seq: string
   blanks: number[]
-  position: number
+  visibleCol: number
 }) {
-  // First convert the mouse position to global coordinates
-  const globalPos = mouseOverCoordToGlobalCoord(blanks, position)
+  // First convert the visible column to global column
+  const globalCol = visibleColToGlobalCol(blanks, visibleCol)
   const seqLen = seq.length
 
   // Check if the position in the sequence is a gap
-  if (globalPos < seqLen && isBlank(seq[globalPos])) {
+  if (globalCol < seqLen && isBlank(seq[globalCol])) {
     return undefined
   }
 
   // Count non-gap characters up to the global position
-  let nonGapCount = 0
-  for (let i = 0; i < globalPos && i < seqLen; i++) {
+  let seqPos = 0
+  for (let i = 0; i < globalCol && i < seqLen; i++) {
     if (!isBlank(seq[i])) {
-      nonGapCount++
+      seqPos++
     }
   }
 
-  // If we're at a valid position, return the count of non-gap characters
-  return globalPos < seqLen ? nonGapCount : undefined
+  return globalCol < seqLen ? seqPos : undefined
+}
+
+/**
+ * Convert a visible column to a row-specific sequence position, with row lookup.
+ *
+ * @param rowName - The name of the row
+ * @param visibleCol - The visible column index
+ * @param rowMap - Map from row name to sequence string
+ * @param blanks - Sorted array of global column indices that are hidden
+ * @returns The sequence position, or undefined if row not found or position is a gap
+ */
+export function visibleColToSeqPosForRow({
+  rowName,
+  visibleCol,
+  rowMap,
+  blanks,
+}: {
+  rowName: string
+  visibleCol: number
+  rowMap: Map<string, string>
+  blanks: number[]
+}) {
+  const seq = rowMap.get(rowName)
+  return seq !== undefined
+    ? visibleColToSeqPos({ seq, visibleCol, blanks })
+    : undefined
 }

package/src/seqPosToGlobalCol.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'vitest'
+
+import { seqPosToGlobalCol } from './seqPosToGlobalCol'
+
+describe('seqPosToGlobalCol', () => {
+  test('converts sequence position to global column with no gaps', () => {
+    const row = 'ATGCATGC'
+    expect(seqPosToGlobalCol({ row, seqPos: 0 })).toBe(0)
+    expect(seqPosToGlobalCol({ row, seqPos: 3 })).toBe(3)
+    expect(seqPosToGlobalCol({ row, seqPos: 7 })).toBe(7)
+    expect(seqPosToGlobalCol({ row, seqPos: 8 })).toBe(8) // Past end
+  })
+
+  test('converts sequence position to global column with gaps', () => {
+    const row = 'A-TG-CA-TGC'
+    // Global: A(0) -(1) T(2) G(3) -(4) C(5) A(6) -(7) T(8) G(9) C(10)
+    // SeqPos: A(0)      T(1) G(2)      C(3) A(4)      T(5) G(6) C(7)
+
+    expect(seqPosToGlobalCol({ row, seqPos: 0 })).toBe(0) // A
+    expect(seqPosToGlobalCol({ row, seqPos: 1 })).toBe(2) // T
+    expect(seqPosToGlobalCol({ row, seqPos: 2 })).toBe(3) // G
+    expect(seqPosToGlobalCol({ row, seqPos: 3 })).toBe(5) // C
+    expect(seqPosToGlobalCol({ row, seqPos: 4 })).toBe(6) // A
+    expect(seqPosToGlobalCol({ row, seqPos: 5 })).toBe(8) // T
+    expect(seqPosToGlobalCol({ row, seqPos: 6 })).toBe(9) // G
+    expect(seqPosToGlobalCol({ row, seqPos: 7 })).toBe(10) // C
+    expect(seqPosToGlobalCol({ row, seqPos: 8 })).toBe(11) // Past end
+  })
+
+  test('handles empty row', () => {
+    expect(seqPosToGlobalCol({ row: '', seqPos: 0 })).toBe(0)
+  })
+
+  test('handles row with only gaps', () => {
+    const row = '---..--'
+    expect(seqPosToGlobalCol({ row, seqPos: 0 })).toBe(0)
+    expect(seqPosToGlobalCol({ row, seqPos: 1 })).toBe(7) // Past end
+  })
+
+  test('handles mixed gap characters (- and .)', () => {
+    const row = 'A-.G-C.'
+    // Global: A(0) -(1) .(2) G(3) -(4) C(5) .(6)
+    // SeqPos: A(0)           G(1)      C(2)
+
+    expect(seqPosToGlobalCol({ row, seqPos: 0 })).toBe(0) // A
+    expect(seqPosToGlobalCol({ row, seqPos: 1 })).toBe(3) // G
+    expect(seqPosToGlobalCol({ row, seqPos: 2 })).toBe(5) // C
+    expect(seqPosToGlobalCol({ row, seqPos: 3 })).toBe(7) // Past end
+  })
+
+  test('handles leading gaps', () => {
+    const row = '--ACG'
+    // Global: -(0) -(1) A(2) C(3) G(4)
+    // SeqPos:           A(0) C(1) G(2)
+
+    expect(seqPosToGlobalCol({ row, seqPos: 0 })).toBe(2) // A
+    expect(seqPosToGlobalCol({ row, seqPos: 1 })).toBe(3) // C
+    expect(seqPosToGlobalCol({ row, seqPos: 2 })).toBe(4) // G
+  })
+
+  test('handles trailing gaps', () => {
+    const row = 'ACG--'
+    // Global: A(0) C(1) G(2) -(3) -(4)
+    // SeqPos: A(0) C(1) G(2)
+
+    expect(seqPosToGlobalCol({ row, seqPos: 0 })).toBe(0) // A
+    expect(seqPosToGlobalCol({ row, seqPos: 1 })).toBe(1) // C
+    expect(seqPosToGlobalCol({ row, seqPos: 2 })).toBe(2) // G
+    expect(seqPosToGlobalCol({ row, seqPos: 3 })).toBe(5) // Past end
+  })
+})

package/src/seqPosToGlobalCol.ts

@@ -0,0 +1,40 @@
+import { isBlank } from './util'
+
+/**
+ * Convert a sequence position (ungapped, 0-based) to a global column index.
+ * This finds the global column that contains the Nth non-gap character.
+ *
+ * @param row - The row's sequence string (including gaps)
+ * @param seqPos - The sequence position (0-based count of non-gap characters)
+ * @returns The global column index containing the seqPos-th non-gap character
+ *
+ * @example
+ * // Row: "A-TG-C" (A at 0, T at 2, G at 3, C at 5)
+ * seqPosToGlobalCol({ row: "A-TG-C", seqPos: 0 }) // → 0 (A)
+ * seqPosToGlobalCol({ row: "A-TG-C", seqPos: 1 }) // → 2 (T)
+ * seqPosToGlobalCol({ row: "A-TG-C", seqPos: 2 }) // → 3 (G)
+ * seqPosToGlobalCol({ row: "A-TG-C", seqPos: 3 }) // → 5 (C)
+ */
+export function seqPosToGlobalCol({
+  row,
+  seqPos,
+}: {
+  row: string
+  seqPos: number
+}) {
+  let nonGapCount = 0
+  let globalCol = 0
+  // Find the seqPos-th non-gap character
+  while (globalCol < row.length) {
+    if (!isBlank(row[globalCol])) {
+      if (nonGapCount === seqPos) {
+        return globalCol
+      }
+      nonGapCount++
+    }
+    globalCol++
+  }
+  // If seqPos is 0 and we didn't find any non-gap character, return 0
+  // Otherwise return globalCol (which is row.length at this point)
+  return seqPos === 0 ? 0 : globalCol
+}