@datagrok/bio 2.25.17 → 2.26.1

package/src/utils/antibody-numbering (WIP)/types.ts

@@ -0,0 +1,69 @@
+/** Supported numbering schemes */
+export type Scheme = 'imgt' | 'kabat' | 'chothia' | 'aho';
+
+/** Antibody chain types */
+export type ChainType = 'H' | 'K' | 'L';
+
+/** Human-readable chain group */
+export type ChainGroup = 'Heavy' | 'Light';
+
+/** A single numbered position with its amino acid */
+export interface NumberingEntry {
+  /** Position code (e.g. "1", "27A", "111A") */
+  position: string;
+  /** Single-letter amino acid at this position */
+  aa: string;
+}
+
+/** Region annotation for a numbered antibody */
+export interface RegionAnnotation {
+  id: string;
+  name: string;
+  description: string;
+  start: string;
+  end: string;
+  visualType: 'region';
+  category: 'structure';
+  sourceScheme: string;
+  autoGenerated: boolean;
+}
+
+/** Result of numbering a single antibody sequence */
+export interface NumberingResult {
+  /** Comma-separated position names for each numbered residue */
+  positionNames: string;
+  /** Chain type: 'Heavy' or 'Light' */
+  chainType: ChainGroup;
+  /** Chain type code: 'H', 'K', or 'L' */
+  chainTypeCode: ChainType | '';
+  /** Region annotations as structured objects */
+  annotations: RegionAnnotation[];
+  /** Detailed numbering: position -> amino acid */
+  numberingDetail: NumberingEntry[];
+  /** Map from position code to character index in the original sequence */
+  numberingMap: Record<string, number>;
+  /** Percent identity of the alignment (0-1) */
+  percentIdentity: number;
+  /** Error message if numbering failed, empty string otherwise */
+  error: string;
+  /**
+   * Full numbering array aligned to input sequence.
+   * Each element is a position code or '-' for residues outside the variable region.
+   */
+  numbering: string[];
+}
+
+/** Consensus profile: for each position, which amino acids are expected */
+export type ConsensusProfile = Map<number, string[]>;
+
+/** Internal alignment result */
+export interface AlignmentResult {
+  /** Position code for each residue in the input, or '-' */
+  numbering: string[];
+  /** Percent identity */
+  percentIdentity: number;
+  /** Detected chain type */
+  chainType: ChainType;
+  /** Error message or empty string */
+  error: string;
+}

package/src/utils/context-menu.ts

@@ -1,13 +1,14 @@
 /* eslint-disable max-len */
 import * as grok from 'datagrok-api/grok';
 import * as DG from 'datagrok-api/dg';
-import * as ui from 'datagrok-api/ui';
 
 import {ALPHABET, NOTATION} from '@datagrok-libraries/bio/src/utils/macromolecule';
 import {ISeqHelper} from '@datagrok-libraries/bio/src/utils/seq-helper';
 
 import {_package} from '../package';
-import {TAGS as bioTags} from '@datagrok-libraries/bio/src/utils/macromolecule';
+import {AnnotationRenderer} from '@datagrok-libraries/bio/src/utils/cell-renderer-annotations';
+import {getColumnAnnotations} from './annotations/annotation-manager';
+import {AnnotationCategory} from '@datagrok-libraries/bio/src/utils/macromolecule/annotations';
 
 
 export function addCopyMenuUI(cell: DG.Cell, menu: DG.Menu, seqHelper: ISeqHelper): void {
@@ -30,4 +31,43 @@ export function addCopyMenuUI(cell: DG.Cell, menu: DG.Menu, seqHelper: ISeqHelpe
         grok.shell.info(`Value of notation '${tgtNotation}' copied to clipboard`);
       }
     });
+
+  // Annotation context menu items
+  const srcCol = cell.column;
+  const annotations = getColumnAnnotations(srcCol);
+  if (annotations.length > 0) {
+    const annotRenderer = new AnnotationRenderer(srcCol);
+    if (annotRenderer.hasAnnotations()) {
+      // Add annotation info submenu
+      const structAnnots = annotations.filter((a) => a.category === AnnotationCategory.Structure);
+      if (structAnnots.length > 0) {
+        const annotMenu = menu.group('Annotations');
+
+        // Extract region actions (uses per-row data for unaligned sequences)
+        for (const annot of structAnnots) {
+          if (annot.start && annot.end) {
+            annotMenu.item(`Extract ${annot.name} as Column`, () => {
+              import('./annotations/annotation-actions').then((m) => {
+                try {
+                  m.extractAnnotatedRegion(srcCol.dataFrame, srcCol, annot.name, seqHelper);
+                } catch (err: any) {
+                  grok.shell.error(`Failed to extract region: ${err.message ?? err}`);
+                }
+              });
+            });
+          }
+        }
+
+        // Filter by liability hits
+        const liabAnnots = annotations.filter((a) => a.category === AnnotationCategory.Liability);
+        if (liabAnnots.length > 0) {
+          annotMenu.item('Filter: Rows with Liability Hits', () => {
+            import('./annotations/annotation-actions').then((m) => {
+              m.filterByLiabilityHits(srcCol.dataFrame, srcCol);
+            });
+          });
+        }
+      }
+    }
+  }
 }

package/src/utils/get-region-func-editor.ts

@@ -140,8 +140,24 @@ export class GetRegionFuncEditor {
 
   private updateRegionItems(): void {
     const seqCol = this.inputs.sequence.value;
-    const regionsTagTxt: string | null = seqCol ? seqCol.getTag(bioTAGS.regions) : null;
-    const regionList: SeqRegion[] | null = regionsTagTxt ? JSON.parse(regionsTagTxt) : null;
+    // Read from .annotations first (new system), fall back to .regions (legacy)
+    let regionList: SeqRegion[] | null = null;
+    const annotationsTag: string | null = seqCol ? seqCol.getTag(bioTAGS.annotations) : null;
+    if (annotationsTag) {
+      try {
+        const annotations = JSON.parse(annotationsTag);
+        const structAnnots = annotations.filter((a: any) => a.category === 'structure' && a.start && a.end);
+        if (structAnnots.length > 0) {
+          regionList = structAnnots.map((a: any) => ({
+            name: a.name, description: a.description ?? '', start: a.start, end: a.end,
+          }));
+        }
+      } catch { /* ignore parse errors */ }
+    }
+    if (!regionList) {
+      const regionsTagTxt: string | null = seqCol ? seqCol.getTag(bioTAGS.regions) : null;
+      regionList = regionsTagTxt ? JSON.parse(regionsTagTxt) : null;
+    }
 
     const regionSE = (this.inputs.region.input as HTMLSelectElement);
     for (let i = regionSE.options.length - 1; i >= 0; --i) regionSE.options.remove(i);

package/src/utils/get-region.ts

@@ -2,36 +2,127 @@ import * as grok from 'datagrok-api/grok';
 import * as ui from 'datagrok-api/ui';
 import * as DG from 'datagrok-api/dg';
 
+import {TAGS as bioTAGS} from '@datagrok-libraries/bio/src/utils/macromolecule';
+import {
+  SeqAnnotation, SeqAnnotationHit, AnnotationCategory,
+} from '@datagrok-libraries/bio/src/utils/macromolecule/annotations';
+import {getAnnotationColumnName, cacheAllRowAnnotations} from './annotations/annotation-manager';
 import {_package} from '../package';
 
 export function getRegionUI(col: DG.Column<string>): void {
+  showGetRegionDialog(col);
+}
+
+/** Shows the Get Region dialog for the given column.
+ *  When the user confirms, the region column is extracted, added to the dataframe, and
+ *  {@link onRegionCreated} is called with it (if provided).
+ *  Returns the dialog instance for further control. */
+export function showGetRegionDialog(
+  col: DG.Column<string>,
+  onRegionCreated?: (regCol: DG.Column<string>) => void,
+): DG.Dialog {
   const sh = _package.seqHelper.getSeqHandler(col);
 
   const nameInput = ui.input.string('Name', {value: ''});
   const startPositionInput = ui.input.choice('Start Position', {value: sh.posList[0], items: sh.posList,
-    onValueChanged: () => { /* TODO: update name placeholder with getDefaultName() */ }});
-  const endPositionInput = ui.input.choice('End Position', {value: sh.posList[sh.posList.length], items: sh.posList,
-    onValueChanged: () => { /* TODO: update name placeholder with getDefaultName() */ }});
+    onValueChanged: () => updateNamePlaceholder()});
+  const endPositionInput = ui.input.choice('End Position', {value: sh.posList[sh.posList.length - 1], items: sh.posList,
+    onValueChanged: () => updateNamePlaceholder()});
+
+  let selectedRegionName: string | null = null;
 
   const getDefaultName = (): string => {
-    return `${col.name}:${startPositionInput.value}-${endPositionInput.value}`;
+    return selectedRegionName
+      ? `${col.name}(${selectedRegionName}): ${startPositionInput.value}-${endPositionInput.value}`
+      : `${col.name}:${startPositionInput.value}-${endPositionInput.value}`;
   };
 
-  ui.dialog({title: 'Get Region'}).add(ui.inputs([
-    nameInput,
-    startPositionInput,
-    endPositionInput,
-  ])).onOK(() => {
-    const pi = DG.TaskBarProgressIndicator.create('Getting region...');
+  const updateNamePlaceholder = (): void => {
+    if (!nameInput.value)
+      nameInput.input.setAttribute('placeholder', getDefaultName());
+  };
+  updateNamePlaceholder();
+
+  // Build region presets from annotations (new system) or .regions tag (legacy)
+  const regionInput = _buildRegionPresetsInput(col, startPositionInput, endPositionInput, (regionName) => {
+    selectedRegionName = regionName;
+    updateNamePlaceholder();
+  });
+
+  const inputsList: DG.InputBase[] = [];
+  if (regionInput) inputsList.push(regionInput);
+  inputsList.push(nameInput, startPositionInput, endPositionInput);
+
+  const dlg = ui.dialog({title: 'Get Region'}).add(ui.inputs(inputsList))
+    .onOK(() => {
+      const pi = DG.TaskBarProgressIndicator.create('Getting region...');
+      try {
+        const name: string = nameInput.value || getDefaultName();
+        const regCol = getRegionDo(col, startPositionInput.value, endPositionInput.value, name);
+        col.dataFrame.columns.add(regCol);
+        regCol.setTag(DG.TAGS.CELL_RENDERER, 'sequence');
+        onRegionCreated?.(regCol);
+      } catch (err: any) {
+        grok.shell.error(err.toString());
+      } finally { pi.close(); }
+    });
+  dlg.show();
+  return dlg;
+}
+
+/** Builds a Region preset dropdown from column annotations / legacy .regions tag.
+ *  Returns null if the column has no annotated regions. */
+function _buildRegionPresetsInput(
+  col: DG.Column<string>,
+  startInput: DG.InputBase<string | null>,
+  endInput: DG.InputBase<string | null>,
+  onRegionSelected?: (regionName: string | null) => void,
+): DG.InputBase | null {
+  type RegionPreset = { name: string, start: string, end: string };
+  let regionList: RegionPreset[] | null = null;
+
+  // New annotation system
+  const annotationsTag: string | null = col.getTag(bioTAGS.annotations);
+  if (annotationsTag) {
     try {
-      const name: string = nameInput.value ?? getDefaultName();
-      const regCol = getRegionDo(col, name, startPositionInput.value, endPositionInput.value);
-      col.dataFrame.columns.add(regCol);
-      regCol.setTag(DG.TAGS.CELL_RENDERER, 'sequence');
-    } catch (err: any) {
-      grok.shell.error(err.toString());
-    } finally { pi.close(); }
+      const annotations = JSON.parse(annotationsTag);
+      const structAnnots = annotations.filter(
+        (a: any) => a.category === AnnotationCategory.Structure && a.start && a.end);
+      if (structAnnots.length > 0) {
+        regionList = structAnnots.map((a: any) => ({
+          name: a.name, start: a.start, end: a.end,
+        }));
+      }
+    } catch { /* ignore parse errors */ }
+  }
+
+  // Legacy .regions tag
+  if (!regionList) {
+    const regionsTagTxt: string | null = col.getTag(bioTAGS.regions);
+    if (regionsTagTxt) {
+      try { regionList = JSON.parse(regionsTagTxt); } catch { /* ignore */ }
+    }
+  }
+
+  if (!regionList || regionList.length === 0) return null;
+
+  const items = ['', ...regionList.map((r) => `${r.name}: ${r.start}-${r.end}`)];
+  const regionInput = ui.input.choice('Region', {
+    value: '', items: items,
+    onValueChanged: (value: string) => {
+      if (!value) {
+        onRegionSelected?.(null);
+        return;
+      }
+      const preset = regionList!.find((r) => `${r.name}: ${r.start}-${r.end}` === value);
+      if (preset) {
+        startInput.value = preset.start;
+        endInput.value = preset.end;
+        onRegionSelected?.(preset.name);
+      }
+    },
   });
+  return regionInput;
 }
 
 /** {@link startPosName} and {@link endPosName} are according positionNames tag (or default ['1', '2',...]) */
@@ -57,6 +148,65 @@ export function getRegionDo(
 
   const regColName: string = !!name ? name : `${col.name}: (${startPosName ?? ''}-${endPosName ?? ''})`;
 
+  // Try per-row extraction for unaligned data: find a matching structure annotation with per-row spans
+  const perRowCol = _tryPerRowExtraction(col, sh, startPosName, endPosName, regColName);
+  if (perRowCol) return perRowCol;
+
+  // Fall back to column-level extraction (aligned/MSA data)
   const regCol = sh.getRegion(startPosIdx, endPosIdx, regColName);
   return regCol;
 }
+
+/** Attempts per-row region extraction using the companion annotation column.
+ *  Returns null if no per-row data is available for the given start/end. */
+function _tryPerRowExtraction(
+  col: DG.Column<string>,
+  sh: ReturnType<typeof _package.seqHelper.getSeqHandler>,
+  startPosName: string | null,
+  endPosName: string | null,
+  regColName: string,
+): DG.Column<string> | null {
+  if (!startPosName || !endPosName || !col.dataFrame) return null;
+
+  // Find matching structure annotation
+  const annotTag = col.getTag(bioTAGS.annotations);
+  if (!annotTag) return null;
+
+  let annotations: SeqAnnotation[];
+  try { annotations = JSON.parse(annotTag); } catch { return null; }
+
+  const annot = annotations.find((a) =>
+    a.category === AnnotationCategory.Structure && a.start === startPosName && a.end === endPosName);
+  if (!annot) return null;
+
+  // Check for companion annotation column with per-row region spans
+  const annotColName = getAnnotationColumnName(col.name);
+  let annotCol: DG.Column<string> | null = null;
+  try { annotCol = col.dataFrame.columns.byName(annotColName) as DG.Column<string>; } catch { return null; }
+  if (!annotCol) return null;
+
+  const allRowData = cacheAllRowAnnotations(annotCol);
+  const hasPerRowRegions = allRowData.some((rd) =>
+    rd?.some((h: SeqAnnotationHit) => h.annotationId === annot.id && h.endPositionIndex != null));
+  if (!hasPerRowRegions) return null;
+
+  // Extract per-row using row-specific character indices
+  const df = col.dataFrame;
+  const regCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, regColName, df.rowCount);
+  for (let i = 0; i < df.rowCount; i++) {
+    const rowHits = allRowData[i];
+    const regionHit = rowHits?.find((h: SeqAnnotationHit) =>
+      h.annotationId === annot.id && h.endPositionIndex != null);
+    if (regionHit) {
+      const splitted = sh.getSplitted(i);
+      const parts: string[] = [];
+      for (let p = regionHit.positionIndex; p <= regionHit.endPositionIndex!; p++) {
+        if (p < splitted.length)
+          parts.push(splitted.getOriginal(p));
+      }
+      regCol.set(i, parts.join(sh.separator || ''));
+    } else
+      regCol.set(i, '');
+  }
+  return regCol;
+}

package/src/utils/sequence-column-input.ts

@@ -0,0 +1,57 @@
+import * as grok from 'datagrok-api/grok';
+import * as ui from 'datagrok-api/ui';
+import * as DG from 'datagrok-api/dg';
+
+import {showGetRegionDialog} from './get-region';
+import {ISequenceColumnInput} from '@datagrok-libraries/bio/src/utils/sequence-column-input';
+
+/** A column input that filters to macromolecule columns and provides a
+ *  "get region" button so users can extract a sub-region and use it instead. */
+export class SequenceColumnInput implements ISequenceColumnInput {
+  private readonly colInput: DG.InputBase<DG.Column | null>;
+
+  private constructor(
+    name: string,
+    options: ui.input.IColumnInputInitOptions<DG.Column>,
+  ) {
+    const filter = options.filter;
+    this.colInput = ui.input.column(name, {
+      ...options,
+      filter: (col: DG.Column) => {
+        if (col.semType !== DG.SEMTYPE.MACROMOLECULE) return false;
+        return filter ? filter(col) : true;
+      },
+    });
+
+    const regionIcon = ui.iconFA('cut', () => this.onRegionIconClick(), 'Extract a region from the sequence');
+    this.colInput.addOptions(regionIcon);
+  }
+
+  /** Creates a new SequenceColumnInput.
+   *  @param name - Caption for the input.
+   *  @param options - Same options as {@link ui.input.column}, table is required.
+   *    The `filter` option is extended to always require semType === Macromolecule. */
+  static create(
+    name: string,
+    options: ui.input.IColumnInputInitOptions<DG.Column>,
+  ): SequenceColumnInput {
+    return new SequenceColumnInput(name, options);
+  }
+
+  get root(): HTMLElement { return this.colInput.root; }
+  get value(): DG.Column | null { return this.colInput.value; }
+  set value(col: DG.Column | null) { this.colInput.value = col; }
+  get inputBase(): DG.InputBase<DG.Column | null> { return this.colInput; }
+
+  private onRegionIconClick(): void {
+    const col = this.colInput.value;
+    if (!col) {
+      grok.shell.warning('Select a macromolecule column first.');
+      return;
+    }
+
+    showGetRegionDialog(col, (regCol) => {
+      this.colInput.value = regCol;
+    });
+  }
+}

package/src/viewers/vd-regions-viewer.ts

@@ -322,6 +322,8 @@ export class VdRegionsViewer extends DG.JsViewer implements IVdRegionsViewer {
       for (const chain of this.chains) {
         const region: VdRegion | undefined = regionsFiltered
           .find((r) => r.order == orderList[orderI] && r.chain == chain);
+        if (!region)
+          continue;
         logoPromiseList.push((async (): Promise<[number, string, WebLogoViewer]> => {
           const wl: WebLogoViewer = await this.dataFrame.plot.fromType('WebLogo', {
             sequenceColumnName: region!.sequenceColumnName,

package/src/widgets/representations.ts

@@ -8,7 +8,9 @@ import {TAGS as mmcrTAGS} from '@datagrok-libraries/bio/src/utils/cell-renderer'
 import {MmcrTemps, rendererSettingsChangedState} from '@datagrok-libraries/bio/src/utils/cell-renderer-consts';
 
 import {_package} from '../package';
-import {NOTATION} from '@datagrok-libraries/bio/src/utils/macromolecule';
+import {NOTATION, TAGS as bioTAGS} from '@datagrok-libraries/bio/src/utils/macromolecule';
+import {getColumnAnnotations, clearAnnotations} from '../utils/annotations/annotation-manager';
+import {AnnotationCategory} from '@datagrok-libraries/bio/src/utils/macromolecule/annotations';
 
 /**
  * @export
@@ -142,5 +144,54 @@ export function getMacromoleculeColumnPropertyPanel(col: DG.Column): DG.Widget {
 
 
   const sequenceConfigInputs = ui.inputs(inputsArray);
-  return new DG.Widget(sequenceConfigInputs);
+
+  // --- Annotations section ---
+  const annotations = getColumnAnnotations(col);
+  const annotationsDiv = ui.divV([]);
+
+  if (annotations.length > 0) {
+    const scheme = col.getTag(bioTAGS.numberingScheme);
+    const structAnnots = annotations.filter((a) => a.category === AnnotationCategory.Structure);
+    const liabAnnots = annotations.filter((a) => a.category === AnnotationCategory.Liability);
+
+    if (scheme)
+      annotationsDiv.append(ui.divText(`Numbering: ${scheme}`, {style: {fontSize: '12px', marginBottom: '4px'}}));
+
+    if (structAnnots.length > 0) {
+      const regionNames = structAnnots.map((a) => a.name).join(', ');
+      annotationsDiv.append(ui.divText(`Regions: ${regionNames}`, {style: {fontSize: '12px', marginBottom: '4px'}}));
+    }
+
+    if (liabAnnots.length > 0) {
+      const totalHits = liabAnnots.reduce((sum, a) => {
+        const match = a.description?.match(/\((\d+) hits\)/);
+        return sum + (match ? parseInt(match[1]) : 0);
+      }, 0);
+      annotationsDiv.append(ui.divText(`Liabilities: ${liabAnnots.length} rules (${totalHits} hits)`, {style: {fontSize: '12px', marginBottom: '4px'}}));
+    }
+
+    const manageBtn = ui.button('Manage', () => {
+      import('../utils/annotations/annotation-manager-ui').then((m) => m.showAnnotationManagerDialog());
+    });
+    const clearBtn = ui.button('Clear All', () => {
+      clearAnnotations(col.dataFrame, col);
+      col.dataFrame.fireValuesChanged();
+    });
+    annotationsDiv.append(ui.divH([manageBtn, clearBtn], {style: {gap: '4px', marginTop: '4px'}}));
+  } else {
+    annotationsDiv.append(ui.divText('No annotations', {style: {fontSize: '12px', color: '#888'}}));
+    const scanBtn = ui.button('Scan Liabilities', () => {
+      import('../utils/annotations/liability-scanner-ui').then((m) => m.showLiabilityScannerDialog());
+    });
+    const numberBtn = ui.button('Apply Numbering', () => {
+      import('../utils/annotations/numbering-ui').then((m) => m.showNumberingSchemeDialog());
+    });
+    annotationsDiv.append(ui.divH([scanBtn, numberBtn], {style: {gap: '4px', marginTop: '4px'}}));
+  }
+
+  const acc = ui.accordion();
+  acc.addPane('Renderer Settings', () => sequenceConfigInputs);
+  acc.addPane('Annotations', () => annotationsDiv);
+
+  return new DG.Widget(acc.root);
 }

package/src/widgets/sequence-scrolling-widget.ts

@@ -10,6 +10,7 @@ import * as ui from 'datagrok-api/ui';
 import {ConservationTrack, MSAHeaderTrack, MSAScrollingHeader, WebLogoTrack} from '@datagrok-libraries/bio/src/utils/sequence-position-scroller';
 import {MonomerPlacer} from '@datagrok-libraries/bio/src/utils/cell-renderer-monomer-placer';
 import {ALPHABET, TAGS as bioTAGS} from '@datagrok-libraries/bio/src/utils/macromolecule';
+import {AnnotationTrack} from '@datagrok-libraries/bio/src/utils/annotation-track';
 import {_package} from '../package';
 import {ISeqHandler} from '@datagrok-libraries/bio/src/utils/macromolecule/seq-handler';
 import * as rxjs from 'rxjs';
@@ -399,16 +400,20 @@ export function handleSequenceHeaderRendering() {
 
         // Do not Skip if sequences are too short, rather, just don't render the tracks by default
 
+        // Annotation track adds 24px (20px track + 4px gap) when structure annotations exist
+        const hasAnnotations = !!seqCol.getTag(bioTAGS.annotations);
+        const annotationSpace = hasAnnotations ? 24 : 0; // ANNOTATION_TRACK_HEIGHT(20) + TRACK_GAP(4)
+
         const STRICT_THRESHOLDS = {
           WITH_TITLE: 58, // BASE + TITLE_HEIGHT(16) + TRACK_GAP(4)
-          WITH_WEBLOGO: 107, // WITH_TITLE + DEFAULT_TRACK_HEIGHT(45) + TRACK_GAP(4)
-          WITH_BOTH: 156 // WITH_WEBLOGO + DEFAULT_TRACK_HEIGHT(45) + TRACK_GAP(4)
+          WITH_WEBLOGO: 107 + annotationSpace, // WITH_TITLE + DEFAULT_TRACK_HEIGHT(45) + TRACK_GAP(4) + annotation
+          WITH_BOTH: 156 + annotationSpace, // WITH_WEBLOGO + DEFAULT_TRACK_HEIGHT(45) + TRACK_GAP(4) + annotation
         };
 
         let initialHeaderHeight: number;
         if (seqCol.length > 100_000 || maxSeqLen < 50) {
-          // Single sequence: just dotted cells
-          initialHeaderHeight = STRICT_THRESHOLDS.WITH_TITLE;
+          // Single sequence: just dotted cells (+ annotation track if present)
+          initialHeaderHeight = STRICT_THRESHOLDS.WITH_TITLE + annotationSpace;
         } else {
           if (seqCol.length > 50_000)
             initialHeaderHeight = STRICT_THRESHOLDS.WITH_WEBLOGO;
@@ -442,18 +447,11 @@ export function handleSequenceHeaderRendering() {
         const initializeHeaders = (monomerLib: IMonomerLib) => {
           const tracks: { id: string, track: MSAHeaderTrack, priority: number }[] = [];
 
-          // Create lazy tracks only for MSA sequences
-
-          // OPTIMIZED: Pass seqHandler directly instead of column/splitter
-          const conservationTrack = new LazyConservationTrack(
-            sh,
-            maxSeqLen,
-            45, // DEFAULT_TRACK_HEIGHT
-            'default',
-            'Conservation'
-          );
-          conservationTrackRef = conservationTrack; // Store reference
-          tracks.push({id: 'conservation', track: conservationTrack, priority: 1});
+          // Priority ordering: annotations (0) → weblogo (1) → conservation (2)
+          // Annotation track is primary when annotation data exists
+          const annotationTrack = new AnnotationTrack(seqCol, 'Annotations');
+          if (annotationTrack.hasRegions())
+            tracks.push({id: 'annotations', track: annotationTrack, priority: 0});
 
           // OPTIMIZED: Pass seqHandler directly
           const webLogoTrack = new LazyWebLogoTrack(
@@ -470,7 +468,18 @@ export function handleSequenceHeaderRendering() {
           }
 
           webLogoTrack.setupDefaultTooltip();
-          tracks.push({id: 'weblogo', track: webLogoTrack, priority: 2});
+          tracks.push({id: 'weblogo', track: webLogoTrack, priority: 1});
+
+          // OPTIMIZED: Pass seqHandler directly instead of column/splitter
+          const conservationTrack = new LazyConservationTrack(
+            sh,
+            maxSeqLen,
+            45, // DEFAULT_TRACK_HEIGHT
+            'default',
+            'Conservation'
+          );
+          conservationTrackRef = conservationTrack; // Store reference
+          tracks.push({id: 'conservation', track: conservationTrack, priority: 2});
 
           // Create the scrolling header
           const scroller = new MSAScrollingHeader({
@@ -503,7 +512,8 @@ export function handleSequenceHeaderRendering() {
 
           scroller.setupTooltipHandling();
 
-          // Add tracks to scroller
+          // Add tracks to scroller sorted by priority (annotations first, then weblogo, then conservation)
+          tracks.sort((a, b) => a.priority - b.priority);
           tracks.forEach(({id, track}) => {
             scroller.addTrack(id, track);
           });