@datagrok/bio 2.27.2 → 2.27.4

package/src/utils/annotations/numbering-ui.ts

@@ -7,99 +7,48 @@ import {TAGS as bioTAGS, ALIGNMENT, ALPHABET, NOTATION} from '@datagrok-librarie
 import {
   SeqAnnotation, SeqAnnotationHit, AnnotationCategory,
 } from '@datagrok-libraries/bio/src/utils/macromolecule/annotations';
-import {NumberingScheme} from '@datagrok-libraries/bio/src/utils/macromolecule/numbering-schemes';
 import {
   setColumnAnnotations, getColumnAnnotations,
   getOrCreateAnnotationColumn, getRowAnnotations, setRowAnnotations, mergeRowHits,
 } from './annotation-manager';
-import {_package} from '../../package';
-import type {NumberingResult, Scheme} from '../antibody-numbering (WIP)';
-import {VdRegionsViewer} from '../../viewers/vd-regions-viewer';
-import { VdRegion, VdRegionType } from '@datagrok-libraries/bio/src/viewers/vd-regions';
-
-const BUILTIN_ENGINE_KEY = '__builtin__';
-const BUILTIN_ENGINE_LABEL = 'Built-in (TypeScript)';
-
-/** An engine entry: either a dynamically discovered DG.Func or the built-in TS engine. */
+/** An engine entry — a dynamically discovered DG.Func with meta.role: 'antibodyNumbering'. */
 interface NumberingEngine {
-  /** Display label for the dropdown */
   label: string;
-  /** Unique key — nqName for DG.Func engines, BUILTIN_ENGINE_KEY for built-in */
+  /** Unique key — `${package}:${name}`. */
   key: string;
-  /** The DG.Func to call, or null for the built-in engine */
-  func: DG.Func | null;
+  func: DG.Func;
 }
 
-/** Discovers all registered antibody numbering engines + the built-in TS engine.
- *  Dynamic engines (meta.role = 'antibodyNumbering') come first; built-in is last. */
+/** Discovers all registered antibody numbering engines (functions with
+ *  meta.role = 'antibodyNumbering'). Built-in engines: Bio package ships an
+ *  immunum-WASM-based engine; other packages (Proteomics etc.) can register
+ *  AntPack/ANARCI/etc. by adding their own meta.role function. */
 function discoverEngines(): NumberingEngine[] {
   const engines: NumberingEngine[] = [];
-
   const funcs = DG.Func.find({meta: {role: 'antibodyNumbering'}});
   if (funcs.length === 0) {
-    grok.shell.error('No antibody numbering engines found. Make sure that Proteomics plugin is installed and up to date.');
-    throw new Error('No external antibody numbering engines found. Make sure that Proteomics plugin is installed and up to date.');
+    grok.shell.error('No antibody numbering engines found. Make sure the Bio package is up to date.');
+    throw new Error('No antibody numbering engines found.');
   }
   for (const f of funcs) {
     const pkgName = f.package?.name ?? '';
-    const label = f.friendlyName || f.name;
     engines.push({
-      label: label,
+      label: f.friendlyName || f.name,
       key: pkgName ? `${pkgName}:${f.name}` : f.name,
       func: f,
     });
   }
-
-  // Built-in TS engine is always last
-  engines.push({label: BUILTIN_ENGINE_LABEL, key: BUILTIN_ENGINE_KEY, func: null});
   return engines;
 }
 
-/** Converts TS NumberingResult[] to a DG.DataFrame matching the expected output shape.
- *  Columns: position_names, chain_type, annotations_json, numbering_detail, numbering_map. */
-export function numberingResultsToDataFrame(results: NumberingResult[]): DG.DataFrame {
-  const n = results.length;
-  const posNames = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'position_names', n);
-  const chainTypes = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'chain_type', n);
-  const annotJson = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'annotations_json', n);
-  const numDetail = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_detail', n);
-  const numMap = DG.Column.fromType(DG.COLUMN_TYPE.STRING, 'numbering_map', n);
-
-  for (let i = 0; i < n; i++) {
-    const r = results[i];
-    if (r.error && r.percentIdentity < 0.3) {
-      posNames.set(i, '');
-      chainTypes.set(i, '');
-      annotJson.set(i, '[]');
-      numDetail.set(i, '');
-      numMap.set(i, '');
-    } else {
-      posNames.set(i, r.positionNames);
-      chainTypes.set(i, r.chainType);
-      annotJson.set(i, JSON.stringify(r.annotations));
-      numDetail.set(i, JSON.stringify(r.numberingDetail));
-      numMap.set(i, JSON.stringify(r.numberingMap));
-    }
-  }
-
-  return DG.DataFrame.fromColumns([posNames, chainTypes, annotJson, numDetail, numMap]);
-}
-
-/** Runs the built-in TS numbering engine on all rows of a sequence column. */
-async function runBuiltinNumbering(
-  seqCol: DG.Column<string>, schemeName: string,
-): Promise<DG.DataFrame> {
-  const {numberSequences, extractSequence} = await import('../antibody-numbering (WIP)');
-  const scheme = schemeName.toLowerCase() as Scheme;
-
-  const sequences: string[] = [];
-  for (let i = 0; i < seqCol.length; i++) {
-    const raw = seqCol.get(i);
-    sequences.push(extractSequence(raw ?? ''));
-  }
-
-  const results = numberSequences(sequences, scheme);
-  return numberingResultsToDataFrame(results);
+/** Reads the `scheme` parameter's declared choices off an engine function.
+ *  Engines advertise which schemes they support via the `choices` option of
+ *  their `scheme: string` parameter; if the function has none we fall back to
+ *  a single generic IMGT option so the dropdown is never empty. */
+function getEngineSchemes(engine: NumberingEngine): string[] {
+  const schemeInput = engine.func.inputs.find((p) => p.name.toLowerCase() === 'scheme');
+  const choices = schemeInput?.choices ?? [];
+  return choices.length > 0 ? choices.slice() : ['imgt'];
 }
 
 export function showNumberingSchemeDialog(): void {
@@ -117,45 +66,40 @@ export function showNumberingSchemeDialog(): void {
 
   const engines = discoverEngines();
   const engineLabels = engines.map((e) => e.label);
-  const schemeChoices = Object.values(NumberingScheme);
 
   const tableInput = ui.input.table('Table', {value: df});
   const seqInput = ui.input.column('Sequence', {
     table: df, value: seqCols[0],
     filter: (col: DG.Column) => col.semType === DG.SEMTYPE.MACROMOLECULE,
   });
-  const schemeInput = ui.input.choice('Scheme', {value: NumberingScheme.IMGT, items: schemeChoices});
   const engineInput = ui.input.choice('Engine', {
     value: engineLabels[0], items: engineLabels,
   });
-  // const populateRegions = ui.input.bool('Populate FR/CDR regions', {value: true});
-  // const openVdRegions = ui.input.bool('Open VD Regions viewer', {value: true});
+  const initialSchemes = getEngineSchemes(engines[0]);
+  const schemeInput = ui.input.choice('Scheme', {value: initialSchemes[0], items: initialSchemes});
+
+  // Switch the scheme list when the user picks a different engine — each engine
+  // advertises its own set via the `scheme` parameter's `choices`.
+  engineInput.onChanged.subscribe(() => {
+    const selected = engines.find((e) => e.label === engineInput.value);
+    if (!selected) return;
+    const schemes = getEngineSchemes(selected);
+    const prev = schemeInput.value;
+    schemeInput.items = schemes;
+    schemeInput.value = schemes.includes(prev ?? '') ? prev : schemes[0];
+  });
 
   const dialog = ui.dialog({title: 'Apply Antibody Numbering'})
-    .add(ui.inputs([tableInput, seqInput, schemeInput, engineInput]))
+    .add(ui.inputs([tableInput, seqInput, engineInput, schemeInput]))
     .onOK(async () => {
       const seqCol = seqInput.value!;
       const schemeName = schemeInput.value!;
       const selectedLabel = engineInput.value!;
-      const engine = engines.find((e) => e.label === selectedLabel) ?? engines[engines.length - 1];
+      const engine = engines.find((e) => e.label === selectedLabel) ?? engines[0];
       const pi = DG.TaskBarProgressIndicator.create(`Applying ${schemeName} numbering...`);
       try {
-        let result: DG.DataFrame;
-        if (engine.func)
-          result = await engine.func.apply({df: df, seqCol: seqCol, scheme: schemeName.toLowerCase()});
-        else
-          result = await runBuiltinNumbering(seqCol, schemeName);
-
+        const result: DG.DataFrame = await engine.func.apply({df: df, seqCol: seqCol, scheme: schemeName});
         applyNumberingResults(df, seqCol, result, schemeName, true, engine.label);
-
-        // // Open VD Regions viewer
-        // if (openVdRegions.value && grok.shell.tv) {
-        //   try {
-        //     await grok.shell.tv.dataFrame.plot.fromType('VdRegions', {});
-        //   } catch (err) {
-        //     console.warn('Could not open VD Regions viewer:', err);
-        //   }
-        // }
       } catch (err: any) {
         grok.shell.error(`Numbering failed: ${err.message ?? err}`);
         console.error(err);

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

@@ -0,0 +1,45 @@
+import type {
+  ImmunumNumberingRow, ImmunumWorkerRequest, ImmunumWorkerResponse,
+} from './types';
+
+/** Short-lived worker: we spin it up per call and tear it down immediately
+ *  after. Numbering is a one-shot batch operation — keeping the worker alive
+ *  would pin the immunum WASM instance (≈700 KB) in memory indefinitely. */
+function spawnWorker(): Worker {
+  return new Worker(new URL('./immunum.worker', import.meta.url));
+}
+
+function callOnce(worker: Worker, req: ImmunumWorkerRequest): Promise<ImmunumWorkerResponse> {
+  return new Promise((resolve, reject) => {
+    const ch = new MessageChannel();
+    ch.port1.onmessage = ({data}) => {
+      ch.port1.close();
+      resolve(data as ImmunumWorkerResponse);
+    };
+    ch.port1.onmessageerror = (err) => {
+      ch.port1.close();
+      reject(err);
+    };
+    worker.postMessage({req}, [ch.port2]);
+  });
+}
+
+/** Runs immunum numbering on a batch of sequences inside a web worker. Spawns a
+ *  fresh worker for this call and terminates it before returning so the WASM
+ *  instance is freed. Throws on WASM/init errors; individual per-row errors
+ *  are attached to each row's `error` field. */
+export async function numberSequencesWithImmunum(
+  sequences: string[],
+  scheme: string,
+  chains?: string[],
+  minConfidence?: number | null,
+): Promise<ImmunumNumberingRow[]> {
+  const worker = spawnWorker();
+  try {
+    const resp = await callOnce(worker, {op: 'number', sequences, scheme, chains, minConfidence});
+    if (!resp.ok) throw new Error(resp.error);
+    return resp.rows ?? [];
+  } finally {
+    worker.terminate();
+  }
+}

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);
+  }
+});