@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/formatGuessers.js

@@ -0,0 +1,69 @@
+import { matchFormat, resolveIndexType, trackTypeForAdapter, } from '@jbrowse/add-track-core';
+import { getFileName } from './getFileName.js';
+import { addAdapterGuesser, addTrackTypeGuesser, makeIndex } from './tracks.js';
+/**
+ * The adapter config one format-table entry describes: the data file under the
+ * field that format's adapter reads it from, plus wherever that adapter expects
+ * its index — nested under `index` for BAM and the tabix formats, a top-level
+ * sidecar field for CRAM and FASTA.
+ *
+ * `index` is the location the caller was handed (the "index file" field of the
+ * add-track form); every sidecar the caller did not name is derived from the
+ * data file's own location.
+ */
+export function adapterConfigFromSpec(spec, file, index) {
+    switch (spec.kind) {
+        case 'single':
+        case 'anchors':
+            return { type: spec.adapterType, [spec.locField]: file };
+        case 'indexed':
+            return {
+                type: spec.adapterType,
+                [spec.locField]: file,
+                index: {
+                    location: index ?? makeIndex(file, spec.suffix),
+                    indexType: resolveIndexType(index && getFileName(index), spec.indexType),
+                },
+            };
+        case 'sidecar':
+            return {
+                type: spec.adapterType,
+                [spec.locField]: file,
+                ...Object.fromEntries(spec.sidecars.map(s => [
+                    s.field,
+                    s.fromIndex && index ? index : makeIndex(file, s.suffix),
+                ])),
+            };
+        case 'unsupported':
+            return undefined;
+    }
+}
+/**
+ * Guess every format `@jbrowse/add-track-core`'s table describes — the same
+ * table `@jbrowse/cli`'s `add-track` reads, so a file resolves to the same
+ * adapter config in the app and on the command line.
+ *
+ * Whether a build can open a format is decided by `hasAdapterType`, not by the
+ * table: guessing `BamAdapter` in a build with no alignments plugin writes a
+ * track config that fails at render. A plugin therefore registers its adapters
+ * and nothing else — there is no format list to keep in step. ADR-077.
+ *
+ * `CorePlugin` installs this first, so any `addAdapterGuesser` a plugin
+ * registers is later in the chain and wins over the table. That is how a format
+ * the table cannot express is added, and how a third-party plugin claims one.
+ */
+// #region installFormatGuessers
+export function installFormatGuessers(pluginManager) {
+    addAdapterGuesser(pluginManager, (file, index, adapterHint) => {
+        const spec = matchFormat(getFileName(file), adapterHint)?.spec;
+        return spec &&
+            'adapterType' in spec &&
+            pluginManager.hasAdapterType(spec.adapterType)
+            ? adapterConfigFromSpec(spec, file, index)
+            : undefined;
+    });
+    addTrackTypeGuesser(pluginManager, (adapterName, file) => pluginManager.hasAdapterType(adapterName)
+        ? trackTypeForAdapter(adapterName, file && getFileName(file))
+        : undefined);
+}
+// #endregion

package/esm/util/formatRelativeTime.d.ts

@@ -0,0 +1 @@
+export declare function formatRelativeTime(date: Date | number, now?: number): string;

package/esm/util/formatRelativeTime.js

@@ -0,0 +1,25 @@
+const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+const DIVISIONS = [
+    { amount: 60, unit: 'seconds' },
+    { amount: 60, unit: 'minutes' },
+    { amount: 24, unit: 'hours' },
+    { amount: 7, unit: 'days' },
+    { amount: 4.34524, unit: 'weeks' },
+    { amount: 12, unit: 'months' },
+    { amount: Number.POSITIVE_INFINITY, unit: 'years' },
+];
+// Relative time like "5 minutes ago" / "yesterday" / "in 3 days". Replaces
+// date-fns formatDistanceToNow({ addSuffix: true }) with the built-in Intl API
+// so date-fns stays out of the bundle.
+export function formatRelativeTime(date, now = Date.now()) {
+    let duration = (Number(date) - now) / 1000;
+    let result = rtf.format(Math.round(duration), 'years');
+    for (const { amount, unit } of DIVISIONS) {
+        if (Math.abs(duration) < amount) {
+            result = rtf.format(Math.round(duration), unit);
+            break;
+        }
+        duration /= amount;
+    }
+    return result;
+}

package/esm/util/frameCoalescer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One animation frame's worth of scheduling, with the cancel attached.
+ *
+ * The shape every high-frequency input handler ends up in: the event handler
+ * only accumulates — a wheel delta, a scroll offset, a pointer sample — and one
+ * `requestAnimationFrame` per frame does the model write, so a burst of events
+ * (fast trackpad, inertial scroll, coalesced pointer batches) collapses to one
+ * update per frame instead of thrashing the views once per event.
+ *
+ * It exists for the second half of that, not the first. A pending frame holds a
+ * closure over a view that a tab-close, a track-hide or a route change can
+ * detach before it runs, and then the flush writes to a destroyed MST node,
+ * which throws. Every one of these handlers has to cancel on dispose, and the
+ * cancel is the half that is invisible when missing — `useDotplotInteraction`
+ * had `scheduled = false` bookkeeping and no `cancelAnimationFrame` for as long
+ * as it existed, because nothing about the scheduling side looks incomplete.
+ * Here the disposer is the object's own method.
+ *
+ * **First scheduler of a frame wins.** Later `schedule` calls before the frame
+ * runs are no-ops rather than replacing the callback, which is what a caller
+ * accumulating into its own state wants: the deltas are already in that state,
+ * and the flush reads them when it runs. A caller wanting last-write-wins over
+ * a *value* wants `useRafCommit` instead.
+ */
+export interface FrameCoalescer {
+    schedule: (flush: (now: number) => void) => void;
+    cancel: () => void;
+    readonly pending: boolean;
+}
+export declare function createFrameCoalescer(): FrameCoalescer;

package/esm/util/frameCoalescer.js

@@ -0,0 +1,22 @@
+export function createFrameCoalescer() {
+    let id = null;
+    return {
+        schedule(flush) {
+            id ??= requestAnimationFrame(now => {
+                // cleared before the flush, so a flush that schedules again (a spring,
+                // a momentum tail) gets the next frame rather than being swallowed
+                id = null;
+                flush(now);
+            });
+        },
+        cancel() {
+            if (id !== null) {
+                cancelAnimationFrame(id);
+                id = null;
+            }
+        },
+        get pending() {
+            return id !== null;
+        },
+    };
+}

package/esm/util/freezeDeep.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Freeze `value` and everything reachable from it, in place, and return it.
+ *
+ * For a value handed to consumers **by reference on purpose**: a config slot's
+ * `promotedBase` (the one literal every track sitting at base resolves to) and a
+ * stored user preference (a promoted display-type default, read by every
+ * following display). Sharing the reference is load-bearing in both cases —
+ * `===` stability is what lets a display's cached MobX computed re-resolve
+ * without waking anything downstream — so handing out a defensive copy per read
+ * would trade a silent hazard for a real re-render on every read. Freezing keeps
+ * the identity and makes "nothing mutates this" throw rather than quietly
+ * rewriting a value every other track is reading.
+ *
+ * Both callers freeze once, at schema build or at the store write, over a value
+ * that has to survive `postMessage` anyway — so the recursion is over small JSON
+ * and costs nothing per read. Cyclic input terminates: each object is frozen
+ * before its children are visited.
+ *
+ * **Unconditional, deliberately unlike MST's own `deepFreeze`** (whose body this
+ * otherwise mirrors), which is gated on `devMode()`. MST gates because it freezes
+ * on every snapshot read and can't pay for that in production; these callers pay
+ * once per slot and per write, so the cost that justifies the gate doesn't exist
+ * here — and inheriting the gate would leave only its downside. A dev-only freeze
+ * means a mutation throws where it is cheap to find and silently corrupts every
+ * other track where it isn't: the user-visible bug would exist *only* in
+ * production. Don't add the gate.
+ */
+export declare function freezeDeep<T>(value: T): T;

package/esm/util/freezeDeep.js

@@ -0,0 +1,41 @@
+// local rather than the `isObject` in `util/index.ts`, which re-exports this
+// file — importing it back would be a module cycle for one predicate
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Freeze `value` and everything reachable from it, in place, and return it.
+ *
+ * For a value handed to consumers **by reference on purpose**: a config slot's
+ * `promotedBase` (the one literal every track sitting at base resolves to) and a
+ * stored user preference (a promoted display-type default, read by every
+ * following display). Sharing the reference is load-bearing in both cases —
+ * `===` stability is what lets a display's cached MobX computed re-resolve
+ * without waking anything downstream — so handing out a defensive copy per read
+ * would trade a silent hazard for a real re-render on every read. Freezing keeps
+ * the identity and makes "nothing mutates this" throw rather than quietly
+ * rewriting a value every other track is reading.
+ *
+ * Both callers freeze once, at schema build or at the store write, over a value
+ * that has to survive `postMessage` anyway — so the recursion is over small JSON
+ * and costs nothing per read. Cyclic input terminates: each object is frozen
+ * before its children are visited.
+ *
+ * **Unconditional, deliberately unlike MST's own `deepFreeze`** (whose body this
+ * otherwise mirrors), which is gated on `devMode()`. MST gates because it freezes
+ * on every snapshot read and can't pay for that in production; these callers pay
+ * once per slot and per write, so the cost that justifies the gate doesn't exist
+ * here — and inheriting the gate would leave only its downside. A dev-only freeze
+ * means a mutation throws where it is cheap to find and silently corrupts every
+ * other track where it isn't: the user-visible bug would exist *only* in
+ * production. Don't add the gate.
+ */
+export function freezeDeep(value) {
+    if (isObjectLike(value) && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value)) {
+            freezeDeep(child);
+        }
+    }
+    return value;
+}

package/esm/util/geneticCodes.d.ts

@@ -0,0 +1,56 @@
+export interface NcbiGeneticCode {
+    id: number;
+    name: string;
+    ncbieaa: string;
+    sncbieaa: string;
+}
+export declare const ncbiGeneticCodes: NcbiGeneticCode[];
+export interface GeneticCode {
+    id: number;
+    name: string;
+    codonTable: Record<string, string>;
+    starts: string[];
+}
+export declare function parseTranslTable(value: unknown): number | undefined;
+export interface TranslExcept {
+    start: number;
+    end: number;
+    aa: string;
+}
+export declare function parseTranslExcept(value: unknown): TranslExcept[];
+export declare function relativizeTranslExcept({ raw, featureStart, featureLength, strand, }: {
+    raw: unknown;
+    featureStart: number;
+    featureLength: number;
+    strand?: number;
+}): TranslExcept[];
+/**
+ * Expand an uppercase codon -> amino acid map so every case combination of a
+ * triplet ('atg', 'Atg', 'aTG', ...) resolves, which is what callers reading
+ * raw sequence need.
+ */
+export declare function generateCodonTable(table: Record<string, string>): Record<string, string>;
+export declare function getGeneticCode(id?: number): GeneticCode;
+/**
+ * The standard genetic code's codon map, case-expanded. Callers that translate
+ * without knowing (or caring about) a `transl_table` use this; anything reading
+ * a feature's declared table should call {@link getGeneticCode} instead.
+ *
+ * Derived from NCBI table 1 rather than kept as its own literal: the two were
+ * duplicated, and a hand-maintained 64-entry map is exactly the kind of thing
+ * that drifts silently. Living here (rather than in `seqUtils`, where it used
+ * to) is also what keeps the dependency one-way — `geneticCodes` needed
+ * `generateCodonTable` from `seqUtils`, so defining this the other way round
+ * made the two modules mutually dependent and the const load-order sensitive.
+ */
+export declare const codonTable: Record<string, string>;
+/**
+ * The standard genetic code as a raw uppercase map, i.e. the input
+ * {@link generateCodonTable} case-expands into {@link codonTable}. Nothing in
+ * this repo needs it — it stays exported because the `@jbrowse/core/util` barrel
+ * is the runtime ABI external plugins link against, and jbrowse-plugin-protein3d
+ * calls `generateCodonTable(defaultCodonTable)` itself. Dropping it turned that
+ * into `Object.keys(undefined)` inside the published plugin, which surfaced as
+ * "Could not launch protein view: TypeError".
+ */
+export declare const defaultCodonTable: Record<string, string>;

package/esm/util/geneticCodes.js

@@ -0,0 +1,371 @@
+import { revlist } from './revlist.js';
+export const ncbiGeneticCodes = [
+    {
+        id: 1,
+        name: 'Standard',
+        ncbieaa: 'FFLLSSSSYY**CC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------**--*----M---------------M----------------------------',
+    },
+    {
+        id: 2,
+        name: 'Vertebrate Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIMMTTTTNNKKSS**VVVVAAAADDEEGGGG',
+        sncbieaa: '----------**--------------------MMMM----------**---M------------',
+    },
+    {
+        id: 3,
+        name: 'Yeast Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWTTTTPPPPHHQQRRRRIIMMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**----------------------MM---------------M------------',
+    },
+    {
+        id: 4,
+        name: 'Mold Mitochondrial; Protozoan Mitochondrial; Coelenterate Mitochondrial; Mycoplasma; Spiroplasma',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '--MM------**-------M------------MMMM---------------M------------',
+    },
+    {
+        id: 5,
+        name: 'Invertebrate Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIMMTTTTNNKKSSSSVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------**--------------------MMMM---------------M------------',
+    },
+    {
+        id: 6,
+        name: 'Ciliate Nuclear; Dasycladacean Nuclear; Hexamita Nuclear',
+        ncbieaa: 'FFLLSSSSYYQQCC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '--------------*--------------------M----------------------------',
+    },
+    {
+        id: 9,
+        name: 'Echinoderm Mitochondrial; Flatworm Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIIMTTTTNNNKSSSSVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**-----------------------M---------------M------------',
+    },
+    {
+        id: 10,
+        name: 'Euplotid Nuclear',
+        ncbieaa: 'FFLLSSSSYY**CCCWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**-----------------------M----------------------------',
+    },
+    {
+        id: 11,
+        name: 'Bacterial, Archaeal and Plant Plastid',
+        ncbieaa: 'FFLLSSSSYY**CC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------**--*----M------------MMMM---------------M------------',
+    },
+    {
+        id: 12,
+        name: 'Alternative Yeast Nuclear',
+        ncbieaa: 'FFLLSSSSYY**CC*WLLLSPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**--*----M---------------M----------------------------',
+    },
+    {
+        id: 13,
+        name: 'Ascidian Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIMMTTTTNNKKSSGGVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------**----------------------MM---------------M------------',
+    },
+    {
+        id: 14,
+        name: 'Alternative Flatworm Mitochondrial',
+        ncbieaa: 'FFLLSSSSYYY*CCWWLLLLPPPPHHQQRRRRIIIMTTTTNNNKSSSSVVVVAAAADDEEGGGG',
+        sncbieaa: '-----------*-----------------------M----------------------------',
+    },
+    {
+        id: 15,
+        name: 'Blepharisma Macronuclear',
+        ncbieaa: 'FFLLSSSSYY*QCC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------*---*--------------------M----------------------------',
+    },
+    {
+        id: 16,
+        name: 'Chlorophycean Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY*LCC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------*---*--------------------M----------------------------',
+    },
+    {
+        id: 21,
+        name: 'Trematode Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIMMTTTTNNNKSSSSVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**-----------------------M---------------M------------',
+    },
+    {
+        id: 22,
+        name: 'Scenedesmus obliquus Mitochondrial',
+        ncbieaa: 'FFLLSS*SYY*LCC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '------*---*---*--------------------M----------------------------',
+    },
+    {
+        id: 23,
+        name: 'Thraustochytrium Mitochondrial',
+        ncbieaa: 'FF*LSSSSYY**CC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '--*-------**--*-----------------M--M---------------M------------',
+    },
+    {
+        id: 24,
+        name: 'Rhabdopleuridae Mitochondrial',
+        ncbieaa: 'FFLLSSSSYY**CCWWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSSKVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------**-------M---------------M---------------M------------',
+    },
+    {
+        id: 25,
+        name: 'Candidate Division SR1 and Gracilibacteria',
+        ncbieaa: 'FFLLSSSSYY**CCGWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------**-----------------------M---------------M------------',
+    },
+    {
+        id: 26,
+        name: 'Pachysolen tannophilus Nuclear',
+        ncbieaa: 'FFLLSSSSYY**CC*WLLLAPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**--*----M---------------M----------------------------',
+    },
+    {
+        id: 27,
+        name: 'Karyorelict Nuclear',
+        ncbieaa: 'FFLLSSSSYYQQCCWWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '--------------*--------------------M----------------------------',
+    },
+    {
+        id: 28,
+        name: 'Condylostoma Nuclear',
+        ncbieaa: 'FFLLSSSSYYQQCCWWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**--*--------------------M----------------------------',
+    },
+    {
+        id: 29,
+        name: 'Mesodinium Nuclear',
+        ncbieaa: 'FFLLSSSSYYYYCC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '--------------*--------------------M----------------------------',
+    },
+    {
+        id: 30,
+        name: 'Peritrich Nuclear',
+        ncbieaa: 'FFLLSSSSYYEECC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '--------------*--------------------M----------------------------',
+    },
+    {
+        id: 31,
+        name: 'Blastocrithidia Nuclear',
+        ncbieaa: 'FFLLSSSSYYEECCWWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '----------**-----------------------M----------------------------',
+    },
+    {
+        id: 32,
+        name: 'Balanophoraceae Plastid',
+        ncbieaa: 'FFLLSSSSYY*WCC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG',
+        sncbieaa: '---M------*---*----M------------MMMM---------------M------------',
+    },
+    {
+        id: 33,
+        name: 'Cephalodiscidae Mitochondrial',
+        ncbieaa: 'FFLLSSSSYYY*CCWWLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSSKVVVVAAAADDEEGGGG',
+        sncbieaa: '---M-------*-------M---------------M---------------M------------',
+    },
+];
+// The codon order shared by every NCBI table — the Base1/Base2/Base3 comment
+// rows in gc.prt. codon i = BASE1[i] + BASE2[i] + BASE3[i].
+const BASE1 = 'TTTTTTTTTTTTTTTTCCCCCCCCCCCCCCCCAAAAAAAAAAAAAAAAGGGGGGGGGGGGGGGG';
+const BASE2 = 'TTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGGTTTTCCCCAAAAGGGG';
+const BASE3 = 'TCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAG';
+// Parses a GFF/GenBank `transl_table` attribute value into an NCBI table id. The
+// GFF adapter yields a string (or an array if the attribute repeated), so this
+// normalizes both; returns undefined for a missing or non-positive-integer value
+// so callers fall back to their default code.
+export function parseTranslTable(value) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+// The INSDC `transl_except`/`anticodon` `aa:` vocabulary mapped to 1-letter
+// codes (https://www.ddbj.nig.ac.jp/ddbj/code-e.html); any unrecognized value
+// passes through unchanged (so a code already given as a 1-letter IUPAC symbol
+// survives). NCBI spells the substituted residue with its 3-letter name — e.g.
+// `aa:Leu` for a CUG initiator (PTEN-L) or `aa:Sec` for selenocysteine — and
+// EVERY entry below must collapse to a single character: a multi-character value
+// landing in the protein string lengthens it and frame-shifts every downstream
+// residue index. TERM is a stop; OTHER is an unspecified residue (X, used when a
+// genomic stop is thought erroneous in a model RefSeq); Asx/Glx/Xle/Xaa are the
+// IUPAC ambiguity codes; the rest are the 20 standard residues plus Sec/Pyl.
+const translExceptAa = {
+    TERM: '*',
+    OTHER: 'X',
+    Ala: 'A',
+    Arg: 'R',
+    Asn: 'N',
+    Asp: 'D',
+    Cys: 'C',
+    Gln: 'Q',
+    Glu: 'E',
+    Gly: 'G',
+    His: 'H',
+    Ile: 'I',
+    Leu: 'L',
+    Lys: 'K',
+    Met: 'M',
+    Phe: 'F',
+    Pro: 'P',
+    Ser: 'S',
+    Thr: 'T',
+    Trp: 'W',
+    Tyr: 'Y',
+    Val: 'V',
+    Sec: 'U',
+    Pyl: 'O',
+    Asx: 'B',
+    Glx: 'Z',
+    Xle: 'J',
+    Xaa: 'X',
+};
+// Parses a GFF/GenBank `transl_except` attribute. The attribute value is one or
+// more parenthesised entries of the form `(pos:<loc>,aa:X)`, where `<loc>` is a
+// 1-based closed coordinate range. Besides the bare `N` / `N..M` form, NCBI's
+// genomic GFF3 wraps the location in INSDC descriptors —`complement(...)` for
+// minus-strand genes, `join(...)` for a codon split across an intron — and may
+// prefix coordinates with a contig accession, e.g.
+// `(pos:complement(NC_000003.11:49395565..49395567),aa:Sec)`. We take the first
+// coordinate range and ignore the descriptors: strand is resolved elsewhere,
+// contig identity comes from the feature, and every base of a codon stitches to
+// the same codon index, so the first base of a split codon suffices. The
+// accession is stripped before reading digits so its own digits (e.g. the
+// `000003` in `NC_000003.11`) aren't mistaken for a coordinate. GFF3 URL-encoding
+// is already decoded upstream (commas arrive plain, not %2C). Returns positions
+// as 0-based half-open intervals.
+export function parseTranslExcept(value) {
+    const vals = Array.isArray(value)
+        ? value.map(String)
+        : typeof value === 'string'
+            ? [value]
+            : [];
+    return vals.flatMap(v => 
+    // The location descriptor is bounded to a generous max length (real
+    // descriptors like `complement(NC_000003.11:49395565..49395567)` are
+    // well under this) so a missing `,aa:` can't make the lazy `.*?` scan
+    // to the end of an attacker-controlled string from every `(pos:` it
+    // finds, which would otherwise be quadratic in input length.
+    [...v.matchAll(/\(pos:(.{0,500}?),aa:(\w+)\)/g)].flatMap(m => {
+        const loc = m[1].replaceAll(/[A-Za-z_][\w.]*:/g, '');
+        const range = /(\d+)(?:\.\.(\d+))?/.exec(loc);
+        const rawAa = m[2];
+        // The override is spliced into the protein string as-is, so it must be
+        // exactly one character: a known name maps via translExceptAa, a value
+        // already given as a 1-letter code passes through, and anything else
+        // (an unknown multi-char token) degrades to X rather than frame-shifting
+        // every downstream residue index.
+        const mappedAa = translExceptAa[rawAa] ?? (rawAa.length === 1 ? rawAa : 'X');
+        return range
+            ? [
+                {
+                    start: Number(range[1]) - 1,
+                    end: range[2] === undefined ? Number(range[1]) : Number(range[2]),
+                    aa: mappedAa,
+                },
+            ]
+            : [];
+    }));
+}
+// Converts a raw GFF `transl_except` attribute into the coordinate system
+// `convertCodingSequenceToPeptides` expects: feature-relative, and reversed for
+// minus-strand features so positions line up with the revcom'd CDS sequence.
+// Shared by the protein detail view and the in-track peptide overlay so their
+// coordinate handling can't drift.
+export function relativizeTranslExcept({ raw, featureStart, featureLength, strand, }) {
+    const relative = parseTranslExcept(raw).map(e => ({
+        ...e,
+        start: e.start - featureStart,
+        end: e.end - featureStart,
+    }));
+    return strand === -1 ? revlist(relative, featureLength) : relative;
+}
+// codon i = BASE1[i] + BASE2[i] + BASE3[i]
+const CODONS = Array.from({ length: 64 }, (_, i) => BASE1[i] + BASE2[i] + BASE3[i]);
+const ncbiCodeById = new Map(ncbiGeneticCodes.map(t => [t.id, t]));
+/**
+ * Expand an uppercase codon -> amino acid map so every case combination of a
+ * triplet ('atg', 'Atg', 'aTG', ...) resolves, which is what callers reading
+ * raw sequence need.
+ */
+export function generateCodonTable(table) {
+    const tempCodonTable = {};
+    for (const codon of Object.keys(table)) {
+        const aa = table[codon];
+        const nucs = [];
+        for (let i = 0; i < 3; i++) {
+            const nuc = codon.charAt(i);
+            nucs[i] = [];
+            nucs[i][0] = nuc.toUpperCase();
+            nucs[i][1] = nuc.toLowerCase();
+        }
+        for (let i = 0; i < 2; i++) {
+            const n0 = nucs[0][i];
+            for (let j = 0; j < 2; j++) {
+                const n1 = nucs[1][j];
+                for (let k = 0; k < 2; k++) {
+                    const n2 = nucs[2][k];
+                    const triplet = n0 + n1 + n2;
+                    tempCodonTable[triplet] = aa;
+                }
+            }
+        }
+    }
+    return tempCodonTable;
+}
+// The uppercase-only codon -> amino acid map for a table, plus its start
+// codons. `generateCodonTable` case-expands the map; this is the input to that.
+function buildRawTable(id) {
+    const def = ncbiCodeById.get(id);
+    if (!def && id !== 1) {
+        console.warn(`Unknown genetic code (transl_table=${id}); using standard code`);
+    }
+    const { id: resolvedId, name, ncbieaa, sncbieaa, } = def ?? ncbiCodeById.get(1);
+    const table = {};
+    const starts = [];
+    for (const [i, codon] of CODONS.entries()) {
+        table[codon] = ncbieaa[i];
+        if (sncbieaa[i] === 'M') {
+            starts.push(codon);
+        }
+    }
+    return { id: resolvedId, name, table, starts };
+}
+function buildGeneticCode(id) {
+    const { id: resolvedId, name, table, starts } = buildRawTable(id);
+    return { id: resolvedId, name, codonTable: generateCodonTable(table), starts };
+}
+const geneticCodeCache = new Map();
+// Resolves the codon map + start set for an NCBI translation-table id, falling
+// back to the standard code (1) for an unrecognized id. Memoized: the result is
+// immutable and there are only ~27 tables, so hot callers (the per-frame
+// sequence-translation paint) reuse one expanded 64-codon table instead of
+// rebuilding it.
+export function getGeneticCode(id = 1) {
+    let code = geneticCodeCache.get(id);
+    if (!code) {
+        code = buildGeneticCode(id);
+        geneticCodeCache.set(id, code);
+    }
+    return code;
+}
+/**
+ * The standard genetic code's codon map, case-expanded. Callers that translate
+ * without knowing (or caring about) a `transl_table` use this; anything reading
+ * a feature's declared table should call {@link getGeneticCode} instead.
+ *
+ * Derived from NCBI table 1 rather than kept as its own literal: the two were
+ * duplicated, and a hand-maintained 64-entry map is exactly the kind of thing
+ * that drifts silently. Living here (rather than in `seqUtils`, where it used
+ * to) is also what keeps the dependency one-way — `geneticCodes` needed
+ * `generateCodonTable` from `seqUtils`, so defining this the other way round
+ * made the two modules mutually dependent and the const load-order sensitive.
+ */
+export const codonTable = getGeneticCode(1).codonTable;
+/**
+ * The standard genetic code as a raw uppercase map, i.e. the input
+ * {@link generateCodonTable} case-expands into {@link codonTable}. Nothing in
+ * this repo needs it — it stays exported because the `@jbrowse/core/util` barrel
+ * is the runtime ABI external plugins link against, and jbrowse-plugin-protein3d
+ * calls `generateCodonTable(defaultCodonTable)` itself. Dropping it turned that
+ * into `Object.keys(undefined)` inside the published plugin, which surfaced as
+ * "Could not launch protein view: TypeError".
+ */
+export const defaultCodonTable = buildRawTable(1).table;

package/esm/util/getFileName.d.ts

@@ -0,0 +1,11 @@
+import type { FileLocation } from './types/data.ts';
+/**
+ * The bare filename a location refers to, for every location type — a Blob and
+ * a FileHandle carry their name directly, a URI and a local path carry it as the
+ * last path segment.
+ *
+ * Its own module rather than living in `tracks.ts` because the assembly form
+ * helpers need it too, and `tracks.ts` pulls in MST and the configuration
+ * system. Re-exported from `tracks.ts`, which is the import path plugins use.
+ */
+export declare function getFileName(location: FileLocation): string;