@datagrok/bio 2.27.2 → 2.27.3

package/src/utils/antibody-numbering/immunum-glue.js

@@ -0,0 +1,275 @@
+/* eslint-disable */
+// @ts-nocheck
+//
+// Browser/worker-friendly port of node_modules/immunum/immunum.js (v1.1.0).
+// The upstream file uses require('fs').readFileSync to load the WASM at top
+// level, which breaks in the browser. This file is byte-identical up to the
+// wasm-bindgen glue; the only change is that the WASM bytes are supplied via
+// an explicit initImmunum() call instead of being read from disk at import
+// time. See README.md in the immunum package for the upstream source.
+
+let wasm = null;
+
+export class Annotator {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        AnnotatorFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_annotator_free(ptr, 0);
+    }
+    constructor(chains, scheme, min_confidence) {
+        const ptr0 = passArrayJsValueToWasm0(chains, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(scheme, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.annotator_new(ptr0, len0, ptr1, len1,
+            isLikeNone(min_confidence) ? 0x100000001 : Math.fround(min_confidence));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
+        AnnotatorFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    number(sequence) {
+        const ptr0 = passStringToWasm0(sequence, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        return wasm.annotator_number(this.__wbg_ptr, ptr0, len0);
+    }
+    segment(sequence) {
+        const ptr0 = passStringToWasm0(sequence, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        return wasm.annotator_segment(this.__wbg_ptr, ptr0, len0);
+    }
+}
+if (typeof Symbol !== 'undefined' && Symbol.dispose) Annotator.prototype[Symbol.dispose] = Annotator.prototype.free;
+
+const AnnotatorFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? {register: () => {}, unregister: () => {}}
+    : new FinalizationRegistry((ptr) => wasm.__wbg_annotator_free(ptr >>> 0, 1));
+
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_debug_string_5398f5bb970e0daa: function(arg0, arg1) {
+            const ret = debugString(arg1);
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_string_get_395e606bd0ee4427: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            const ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_6ddd609b62940d55: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_new_49d5571bd3f0c4d4: function() {
+            return new Map();
+        },
+        __wbg_new_ab79df5bd7c26067: function() {
+            return new Object();
+        },
+        __wbg_set_7eaa4f96924fd6b3: function() {
+            return handleError(function(arg0, arg1, arg2) {
+                return Reflect.set(arg0, arg1, arg2);
+            }, arguments);
+        },
+        __wbg_set_bf7251625df30a02: function(arg0, arg1, arg2) {
+            return arg0.set(arg1, arg2);
+        },
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            return arg0;
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            return getStringFromWasm0(arg0, arg1);
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        './immunum_bg.js': import0,
+    };
+}
+
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function debugString(val) {
+    const type = typeof val;
+    if (type == 'number' || type == 'boolean' || val == null) return `${val}`;
+    if (type == 'string') return `"${val}"`;
+    if (type == 'symbol') {
+        const description = val.description;
+        return description == null ? 'Symbol' : `Symbol(${description})`;
+    }
+    if (type == 'function') {
+        const name = val.name;
+        return (typeof name == 'string' && name.length > 0) ? `Function(${name})` : 'Function';
+    }
+    if (Array.isArray(val)) {
+        const length = val.length;
+        let debug = '[';
+        if (length > 0) debug += debugString(val[0]);
+        for (let i = 1; i < length; i++) debug += ', ' + debugString(val[i]);
+        debug += ']';
+        return debug;
+    }
+    const builtInMatches = /\[object ([^\]]+)\]/.exec(toString.call(val));
+    let className;
+    if (builtInMatches && builtInMatches.length > 1) {
+        className = builtInMatches[1];
+    } else {
+        return toString.call(val);
+    }
+    if (className == 'Object') {
+        try {
+            return 'Object(' + JSON.stringify(val) + ')';
+        } catch (_) {
+            return 'Object';
+        }
+    }
+    if (val instanceof Error) return `${val.name}: ${val.message}\n${val.stack}`;
+    return className;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null ||
+        cachedDataViewMemory0.buffer.detached === true ||
+        (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0)
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passArrayJsValueToWasm0(array, malloc) {
+    const ptr = malloc(array.length * 4, 4) >>> 0;
+    for (let i = 0; i < array.length; i++) {
+        const add = addToExternrefTable0(array[i]);
+        getDataViewMemory0().setUint32(ptr + 4 * i, add, true);
+    }
+    WASM_VECTOR_LEN = array.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) arg = arg.slice(offset);
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+const cachedTextDecoder = new TextDecoder('utf-8', {ignoreBOM: true, fatal: true});
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function(arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {read: arg.length, written: buf.length};
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+/** Instantiate the immunum WASM module from raw bytes or an ArrayBuffer.
+ *  Must be called once before constructing any Annotator. Safe to call multiple
+ *  times — subsequent calls are no-ops. */
+export async function initImmunum(wasmSource) {
+    if (wasm) return;
+    const imports = __wbg_get_imports();
+    let inst;
+    if (wasmSource instanceof WebAssembly.Module) {
+        inst = await WebAssembly.instantiate(wasmSource, imports);
+    } else {
+        const result = await WebAssembly.instantiate(wasmSource, imports);
+        inst = result.instance;
+    }
+    wasm = inst.exports;
+    wasm.__wbindgen_start();
+}
+
+export function isImmunumReady() {
+    return wasm !== null;
+}

package/src/utils/antibody-numbering/immunum.worker.ts

@@ -0,0 +1,159 @@
+// @ts-ignore -- file-loader emits the .wasm file to the package's dist/ dir.
+// The returned string is the path relative to the emitted bundle; we take only
+// the basename because the worker already lives in the same dist/ directory.
+import wasmEmittedPath from 'immunum/immunum_bg.wasm';
+// @ts-ignore -- plain JS port of immunum.js
+import {Annotator, initImmunum} from './immunum-glue.js';
+
+import type {ImmunumNumberingRow, ImmunumWorkerRequest, ImmunumWorkerResponse} from './types';
+
+const ctx: Worker = self as any;
+
+const DEFAULT_CHAINS = ['H', 'K', 'L'];
+let _annotatorCache: {key: string; annotator: any} | null = null;
+let _initPromise: Promise<void> | null = null;
+
+function resolveWasmUrl(): string {
+  // Worker script URL (e.g. http://host/packages/Bio/dist/NNN.js) is the right
+  // base — the wasm sits in the same dist/ folder. Stripping off any path
+  // prefix from file-loader's output (which may include a publicPath like
+  // 'dist/') keeps us at the basename regardless of how webpack resolved it.
+  const path = wasmEmittedPath as unknown as string;
+  const basename = path.substring(path.lastIndexOf('/') + 1);
+  return new URL(basename, self.location.href).toString();
+}
+
+async function ensureInit(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const wasmUrl = resolveWasmUrl();
+      const resp = await fetch(wasmUrl);
+      if (!resp.ok) throw new Error(`Failed to fetch immunum WASM from ${wasmUrl} (HTTP ${resp.status})`);
+      const bytes = await resp.arrayBuffer();
+      await initImmunum(bytes);
+    })();
+  }
+  return _initPromise;
+}
+
+function getAnnotator(chains: string[], scheme: string, minConfidence: number | null): any {
+  const key = `${scheme}|${chains.join(',')}|${minConfidence ?? 'null'}`;
+  if (_annotatorCache && _annotatorCache.key === key) return _annotatorCache.annotator;
+  if (_annotatorCache) {
+    try { _annotatorCache.annotator.free(); } catch { /* ignore */ }
+  }
+  const annotator = new Annotator(chains, scheme, minConfidence ?? undefined);
+  _annotatorCache = {key, annotator};
+  return annotator;
+}
+
+const VALID_AA = new Set('ACDEFGHIKLMNPQRSTVWY');
+
+/** Normalizes a raw input cell to a single-letter AA sequence: strips gaps, whitespace,
+ *  non-standard characters, and uppercases. Matches the Python `extract_sequence` helper
+ *  used by the antpack reference script so downstream char-index maps line up. */
+function extractSequence(raw: string | null | undefined): string {
+  if (!raw || typeof raw !== 'string') return '';
+  let out = '';
+  const s = raw.trim();
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i].toUpperCase();
+    if (VALID_AA.has(ch)) out += ch;
+  }
+  return out;
+}
+
+function chainToGroup(chain: string | null): string {
+  if (!chain) return '';
+  if (chain === 'H') return 'Heavy';
+  if (chain === 'K' || chain === 'L') return 'Light';
+  return '';
+}
+
+function numberOne(annotator: any, rawSeq: string): ImmunumNumberingRow {
+  const seq = extractSequence(rawSeq);
+  if (!seq || seq.length < 10) {
+    return {
+      positionNames: '',
+      chainType: '',
+      chainCode: '',
+      numberingDetail: [],
+      numberingMap: {},
+      confidence: 0,
+      error: seq ? 'sequence too short' : 'empty sequence',
+    };
+  }
+
+  let result;
+  try {
+    result = annotator.number(seq);
+  } catch (e: any) {
+    return {
+      positionNames: '', chainType: '', chainCode: '',
+      numberingDetail: [], numberingMap: {}, confidence: 0,
+      error: (e && e.message) || String(e),
+    };
+  }
+
+  if (!result || result.error || !result.numbering) {
+    return {
+      positionNames: '', chainType: '', chainCode: '',
+      numberingDetail: [], numberingMap: {}, confidence: result?.confidence ?? 0,
+      error: result?.error ?? 'no alignment',
+    };
+  }
+
+  // numbering is a Map<posCode, residue>; iterate in insertion (IMGT) order.
+  // Each entry corresponds to a single residue at consecutive input indices
+  // starting at query_start (immunum semantics).
+  const posNames: string[] = [];
+  const numberingDetail: {position: string; aa: string}[] = [];
+  const numberingMap: Record<string, number> = {};
+
+  let charIdx = (result.query_start ?? 0) | 0;
+  const numbering: Map<string, string> = result.numbering;
+  for (const [posCode, residue] of numbering.entries()) {
+    posNames.push(posCode);
+    numberingDetail.push({position: posCode, aa: residue});
+    numberingMap[posCode] = charIdx;
+    charIdx++;
+  }
+
+  return {
+    positionNames: posNames.join(', '),
+    chainType: chainToGroup(result.chain),
+    chainCode: result.chain ?? '',
+    numberingDetail,
+    numberingMap,
+    confidence: result.confidence ?? 0,
+    error: '',
+  };
+}
+
+ctx.addEventListener('message', async (e: MessageEvent) => {
+  const req: ImmunumWorkerRequest = e.data.req;
+  const port: MessagePort = e.ports[0];
+
+  try {
+    await ensureInit();
+
+    if (req.op === 'init') {
+      port.postMessage({ok: true} satisfies ImmunumWorkerResponse);
+      return;
+    }
+
+    if (req.op === 'number') {
+      const chains = req.chains && req.chains.length > 0 ? req.chains : DEFAULT_CHAINS;
+      const annotator = getAnnotator(chains, req.scheme, req.minConfidence ?? null);
+      const rows: ImmunumNumberingRow[] = new Array(req.sequences.length);
+      for (let i = 0; i < req.sequences.length; i++)
+        rows[i] = numberOne(annotator, req.sequences[i]);
+      port.postMessage({ok: true, rows} satisfies ImmunumWorkerResponse);
+      return;
+    }
+
+    port.postMessage({ok: false, error: `Unknown op: ${(req as any).op}`} satisfies ImmunumWorkerResponse);
+  } catch (err: any) {
+    port.postMessage({ok: false, error: (err && err.message) || String(err)} satisfies ImmunumWorkerResponse);
+  }
+});

package/src/utils/antibody-numbering/number-antibody.ts

@@ -0,0 +1,105 @@
+import * as DG from 'datagrok-api/dg';
+
+import {
+  NumberingScheme, ChainType, SCHEME_REGIONS,
+} from '@datagrok-libraries/bio/src/utils/macromolecule/numbering-schemes';
+
+import {numberSequencesWithImmunum} from './immunum-client';
+
+/** Normalizes an incoming scheme string to the immunum library's accepted values.
+ *  The engine only supports 'imgt' and 'kabat'; the dialog's scheme dropdown is
+ *  populated from the `choices` option on this function's `scheme` parameter, so
+ *  in practice only those two values reach here. */
+function toImmunumScheme(scheme: string): 'imgt' | 'kabat' {
+  return (scheme || '').toLowerCase() === 'kabat' ? 'kabat' : 'imgt';
+}
+
+/** Converts the scheme string to the enum value used by the region-table lookup. */
+function toSchemeEnum(scheme: string): NumberingScheme {
+  return (scheme || '').toLowerCase() === 'kabat' ? NumberingScheme.Kabat : NumberingScheme.IMGT;
+}
+
+/** Immunum returns 'Heavy' / 'Light' but region tables key on Heavy / Light_Kappa
+ *  / Light_Lambda. Use chain code to disambiguate: K → Light_Kappa, L → Light_Lambda.
+ *  Unknown chains fall back to Heavy so the dialog still gets *some* region set. */
+function toRegionChainKey(chainGroup: string, chainCode: string): ChainType {
+  if (chainGroup === 'Light')
+    return chainCode === 'L' ? ChainType.Light_Lambda : ChainType.Light_Kappa;
+  return ChainType.Heavy;
+}
+
+/** Builds a row's region-annotation JSON matching the antpack script output:
+ *  each entry has id/name/description/start/end/visualType/category/sourceScheme.
+ *  The `start` and `end` are **scheme-position codes** (strings), not character
+ *  indices — the dialog resolves them to chars via numbering_map. */
+function buildRegionAnnotations(
+  schemeLabel: string, chainGroup: string, chainCode: string,
+): any[] {
+  if (!chainGroup) return [];
+  const schemeEnum = toSchemeEnum(schemeLabel);
+  const regions = SCHEME_REGIONS[schemeEnum];
+  const chainKey = toRegionChainKey(chainGroup, chainCode);
+  const regionDefs = regions?.[chainKey];
+  if (!regionDefs) return [];
+  const schemeLower = schemeLabel.toLowerCase();
+  return regionDefs.map((r) => ({
+    id: `${schemeLower}-${chainGroup}-${r.name}`.toLowerCase(),
+    name: r.name,
+    description: `${r.name} (${schemeLabel.toUpperCase()} ${r.startPosition}-${r.endPosition})`,
+    start: r.startPosition,
+    end: r.endPosition,
+    visualType: 'region',
+    category: 'structure',
+    sourceScheme: schemeLabel.toUpperCase(),
+    autoGenerated: true,
+  }));
+}
+
+/** Runs immunum numbering on a sequence column and returns a DataFrame matching
+ *  the shape expected by `numbering-ui.ts` (same columns as the antpack Python
+ *  script `number_antibody.py`):
+ *  - `position_names`      — comma-separated list of numbered position codes
+ *  - `chain_type`          — 'Heavy' | 'Light' | ''
+ *  - `annotations_json`    — JSON array of FR/CDR region definitions
+ *  - `numbering_detail`    — JSON array of {position, aa} per numbered residue
+ *  - `numbering_map`       — JSON object mapping position code → char index
+ *
+ *  The numbering runs in a web worker (see `immunum.worker.ts`) so the main
+ *  thread stays responsive even for large columns. */
+export async function numberAntibodyColumn(
+  seqCol: DG.Column<string>,
+  scheme: string,
+): Promise<DG.DataFrame> {
+  const n = seqCol.length;
+  const sequences: string[] = new Array(n);
+  for (let i = 0; i < n; i++)
+    sequences[i] = seqCol.get(i) ?? '';
+
+  const immunumScheme = toImmunumScheme(scheme);
+  const rows = await numberSequencesWithImmunum(sequences, immunumScheme);
+
+  const posCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'position_names', n);
+  const chainCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'chain_type', n);
+  const annotCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'annotations_json', n);
+  const detailCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_detail', n);
+  const mapCol = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_map', n);
+
+  for (let i = 0; i < n; i++) {
+    const r = rows[i];
+    if (!r || r.error || !r.positionNames) {
+      posCol.set(i, '');
+      chainCol.set(i, '');
+      annotCol.set(i, '[]');
+      detailCol.set(i, '');
+      mapCol.set(i, '');
+      continue;
+    }
+    posCol.set(i, r.positionNames);
+    chainCol.set(i, r.chainType);
+    annotCol.set(i, JSON.stringify(buildRegionAnnotations(scheme, r.chainType, r.chainCode)));
+    detailCol.set(i, JSON.stringify(r.numberingDetail));
+    mapCol.set(i, JSON.stringify(r.numberingMap));
+  }
+
+  return DG.DataFrame.fromColumns([posCol, chainCol, annotCol, detailCol, mapCol]);
+}

package/src/utils/antibody-numbering/types.ts

@@ -0,0 +1,48 @@
+/** Position → amino-acid entry in the numbering detail JSON. */
+export interface ImmunumNumberingEntry {
+  /** Position code (e.g. "1", "27A"). */
+  position: string;
+  /** Single-letter residue at this position. */
+  aa: string;
+}
+
+/** Per-row numbering result produced by the immunum worker. */
+export interface ImmunumNumberingRow {
+  /** Comma-separated position codes in scheme order. Empty string on failure. */
+  positionNames: string;
+  /** 'Heavy' / 'Light' / '' — UI-facing chain group. */
+  chainType: string;
+  /** Immunum chain code: H, K, L, A, B, G, D, or ''. */
+  chainCode: string;
+  /** Ordered list of {position, aa} entries for the aligned region. */
+  numberingDetail: ImmunumNumberingEntry[];
+  /** Map from position code → character index in the extracted (gap-free) sequence. */
+  numberingMap: Record<string, number>;
+  /** Alignment confidence in [0, 1]. */
+  confidence: number;
+  /** Error message, empty string on success. */
+  error: string;
+}
+
+export type ImmunumWorkerRequest =
+  | {op: 'init'}
+  | {
+      op: 'number';
+      sequences: string[];
+      /** Immunum scheme: 'imgt' or 'kabat'. */
+      scheme: string;
+      /** Case-insensitive chain codes (e.g. ['H', 'K', 'L']). Defaults to H/K/L. */
+      chains?: string[];
+      /** Minimum confidence in [0, 1]; null/undefined → library default (0.5). */
+      minConfidence?: number | null;
+    };
+
+export type ImmunumWorkerResponse =
+  | {ok: true; rows?: ImmunumNumberingRow[]}
+  | {ok: false; error: string};
+
+/** Supported schemes by immunum. Chothia/AHo are not supported — the UI engine
+ *  dropdown lists all schemes globally so the immunum path falls back for the
+ *  unsupported ones by returning empty rows with errors. */
+export const IMMUNUM_SCHEMES = ['imgt', 'kabat'] as const;
+export type ImmunumScheme = typeof IMMUNUM_SCHEMES[number];