@jbrowse/plugin-blat 4.3.0

package/esm/ispcrQuery.js

@@ -0,0 +1,160 @@
+import { challengeError, isChallengePage } from './blatQuery.js';
+// UCSC hgPcr (In-Silico PCR). Unlike hgBlat there is no output=json mode; a
+// successful query returns an HTML page whose <PRE> block holds FASTA amplicons
+// with headers like:
+//   >chr9:132576352+132576623 272bp GTGACGTCG... CCTAGGTTG...
+// where the sign between the two 1-based coordinates is the product strand and
+// the two trailing tokens are the forward and reverse primers as submitted.
+//
+// Not anchored to the start of a line. The whole shape — a '>', a locus with a
+// strand sign inside it, a bp count, two primers — is specific enough on its
+// own, and the anchor was a standing bet that markup never precedes the '>' on
+// its line. `<PRE>` opening on the same line as the first amplicon is all it
+// would take to lose that product, and this parser has already shipped one
+// silent zero-products bug of exactly that kind (see the anchored-header test).
+// A '>' still may not reach across a newline to claim a header below it.
+const AMPLICON_HEADER = />[^\S\n]*(\S+):(\d+)([+-])(\d+)\s+(\d+)bp\s+(\S+)\s+(\S+)/g;
+export const UCSC_ISPCR_URL = 'https://genome.ucsc.edu/cgi-bin/hgPcr';
+// The jbrowse.org proxy, for the same reasons as DEFAULT_BLAT_URL: it holds the
+// apiKey, so a first query costs neither a key nor a CAPTCHA, and desktop keeps
+// UCSC_ISPCR_URL in reserve for when the proxy cannot serve.
+export const DEFAULT_ISPCR_URL = 'https://api.jbrowse.org/ucsc/v1/ispcr';
+// hgPcr's default cap; also the server-side max the CGI accepts without error
+export const DEFAULT_MAX_PRODUCT_SIZE = 4000;
+// primers shorter than this are rejected by hgPcr as too unspecific
+export const MINIMUM_PRIMER_LENGTH = 15;
+/**
+ * The two primer footprints, low coordinate first.
+ *
+ * A primer pair converges: the footprint at the low coordinate reads rightward
+ * and the one at the high coordinate reads leftward, whichever of the two the
+ * submitter called forward. Only *which* is which follows the product strand —
+ * on a plus product the forward primer sits at the low end, on a minus product
+ * it sits at the high end.
+ *
+ * Each footprint carries the primer's own bases, which is what lets a mismatch
+ * against the template be drawn rather than a perfect anneal assumed. They are
+ * as submitted, i.e. 5'->3' on the strand that primer anneals to, so a footprint
+ * at the low end reads on the reference's plus strand and one at the high end
+ * has to be reverse-complemented to sit on it ({@link ispcrToSam} does that).
+ */
+export function productFootprints(product) {
+    const { start, end, strand, forwardPrimer, reversePrimer } = product;
+    const lowIsForward = strand === 1;
+    const lowPrimer = lowIsForward ? forwardPrimer : reversePrimer;
+    const highPrimer = lowIsForward ? reversePrimer : forwardPrimer;
+    return {
+        low: {
+            name: lowIsForward ? 'forward primer' : 'reverse primer',
+            role: lowIsForward ? 'fwd' : 'rev',
+            start,
+            end: start + lowPrimer.length,
+            primer: lowPrimer,
+        },
+        high: {
+            name: lowIsForward ? 'reverse primer' : 'forward primer',
+            role: lowIsForward ? 'rev' : 'fwd',
+            start: end - highPrimer.length,
+            end,
+            primer: highPrimer,
+        },
+    };
+}
+export function parseIsPcrProducts(text) {
+    // a successful result is HTML (FASTA inside <PRE>), and so are the "no
+    // results" and Cloudflare Turnstile pages, so we can't reject on the leading
+    // '<' the way BLAT's JSON path does. Scan for amplicon headers first; only if
+    // none are found do we distinguish a challenge from a genuine empty result,
+    // which avoids mistaking incidental "cf-"/"challenge" markup on a real result
+    // page for a CAPTCHA
+    //
+    // hgPcr links each amplicon's position to the browser, so a real header is
+    //   &gt;<A HREF="../cgi-bin/hgTracks?...">chr17:7676521+7676667</A> 147bp ...
+    // and the position never followed the '>' directly. Strip markup before
+    // decoding entities, in that order: tags first, so escaped text can't be read
+    // as a tag, then '&gt;' becomes the '>' the header starts with.
+    const decoded = text
+        .replaceAll(/<[^>]*>/g, '')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&lt;', '<');
+    const products = [];
+    for (const match of decoded.matchAll(AMPLICON_HEADER)) {
+        const [, refName, startStr, sign, endStr, sizeStr, fwd, rev] = match;
+        products.push({
+            refName: refName,
+            // headers are 1-based inclusive; convert to interbase half-open
+            start: Number(startStr) - 1,
+            end: Number(endStr),
+            strand: sign === '-' ? -1 : 1,
+            size: Number(sizeStr),
+            forwardPrimer: fwd,
+            reversePrimer: rev,
+        });
+    }
+    // the raw text, not `decoded`: a challenge page IS markup, so stripping tags
+    // would throw away the very thing that identifies it
+    if (!products.length && isChallengePage(text)) {
+        throw challengeError();
+    }
+    return products;
+}
+export function pcrProductsToFeatures(products) {
+    return products.map(product => {
+        const { refName, start, end, strand, size } = product;
+        const uniqueId = `ispcr-${refName}-${start}-${end}-${strand}`;
+        const { low, high } = productFootprints(product);
+        return {
+            uniqueId,
+            refName,
+            start,
+            end,
+            strand,
+            type: 'PCR_product',
+            name: `${size} bp`,
+            forwardPrimer: product.forwardPrimer,
+            reversePrimer: product.reversePrimer,
+            // the footprints converge, so their strands are +1 and -1 whatever the
+            // product's is: a primer's direction is its own, not the amplicon's
+            subfeatures: [
+                {
+                    uniqueId: `${uniqueId}-${low.role}`,
+                    name: low.name,
+                    refName,
+                    start: low.start,
+                    end: low.end,
+                    strand: 1,
+                    type: 'primer',
+                },
+                {
+                    uniqueId: `${uniqueId}-${high.role}`,
+                    name: high.name,
+                    refName,
+                    start: high.start,
+                    end: high.end,
+                    strand: -1,
+                    type: 'primer',
+                },
+            ],
+        };
+    });
+}
+export function parseIsPcrResponse(text) {
+    return pcrProductsToFeatures(parseIsPcrProducts(text));
+}
+export function buildIsPcrBody({ db, forwardPrimer, reversePrimer, maxProductSize = DEFAULT_MAX_PRODUCT_SIZE, apiKey, }) {
+    const params = new URLSearchParams({
+        db,
+        wp_target: 'genome',
+        wp_f: forwardPrimer,
+        wp_r: reversePrimer,
+        wp_size: String(maxProductSize),
+        wp_perfect: '15',
+        wp_good: '15',
+        'boolshad.wp_flipReverse': '0',
+    });
+    // as with hgBlat, an account apiKey bypasses the Cloudflare Turnstile
+    if (apiKey) {
+        params.set('apiKey', apiKey);
+    }
+    return params.toString();
+}

package/esm/ispcrToSam.d.ts

@@ -0,0 +1,9 @@
+import type { PcrProduct } from './ispcrQuery.ts';
+/**
+ * A set of hgPcr products as SAM text, ready to hand a SamAdapter as `samText`.
+ *
+ * No `@SQ` lines: hgPcr's page states no chromosome sizes, and inventing one
+ * would be a lie the adapter then reports as the reference length. A headerless
+ * SAM takes its reference names from the records instead.
+ */
+export declare function ispcrToSam(products: PcrProduct[]): string;

package/esm/ispcrToSam.js

@@ -0,0 +1,86 @@
+import { revcom } from '@jbrowse/core/util';
+import { productFootprints } from './ispcrQuery.js';
+/**
+ * A PCR product has the same shape as a paired-end read: two short oriented
+ * footprints pointing at each other, with an unsequenced insert between them.
+ * So each product becomes a read pair — the primers are the mates, the amplicon
+ * interior is the insert, and TLEN is the product size, which is the band the
+ * bench sees on a gel. Shown in an alignments track with view-as-pairs on, that
+ * draws the arrows-facing-inward glyph a primer pair is always drawn as, and it
+ * comes with the pairing machinery (insert-size sort and color) already attached.
+ *
+ * The other thing the pair buys is primer *quality*: hgPcr accepts imperfect
+ * matches, and a mismatch near a primer's 3' end is a real reason an
+ * amplification fails. SEQ carries the primer's own bases in reference
+ * orientation, so the pileup marks every base that disagrees with the template
+ * rather than leaving the reader to assume a perfect anneal.
+ */
+// SAM FLAG bits
+const PAIRED = 1;
+const PROPER = 2;
+const REVERSE = 16;
+const MATE_REVERSE = 32;
+const FIRST = 64;
+const SECOND = 128;
+// BLAT and hgPcr both report a match, not a mapping probability, so a MAPQ here
+// would be invented; 255 is the spec's "unavailable".
+const MAPQ = 255;
+function samLine(fields) {
+    return fields.join('\t');
+}
+/**
+ * The two mates of one product. Names are per-product and unique: two products
+ * sharing a QNAME would be read as one pair spanning both of them.
+ */
+function productToSamLines(product) {
+    const { refName, start, end, strand } = product;
+    const { low, high } = productFootprints(product);
+    const size = end - start;
+    const lowPos = low.start + 1;
+    const highPos = high.start + 1;
+    const qName = `${refName}:${lowPos}-${end}_${size}bp`;
+    // the forward primer is read 1, which is at the low end of a plus product and
+    // the high end of a minus one
+    const lowIsForward = strand === 1;
+    return [
+        samLine([
+            qName,
+            PAIRED | PROPER | MATE_REVERSE | (lowIsForward ? FIRST : SECOND),
+            refName,
+            lowPos,
+            MAPQ,
+            `${low.primer.length}M`,
+            '=',
+            highPos,
+            size,
+            // a footprint at the low end matches the plus strand as submitted
+            low.primer,
+            '*',
+        ]),
+        samLine([
+            qName,
+            PAIRED | PROPER | REVERSE | (lowIsForward ? SECOND : FIRST),
+            refName,
+            highPos,
+            MAPQ,
+            `${high.primer.length}M`,
+            '=',
+            lowPos,
+            -size,
+            // SEQ is always reference-forward, and the high footprint's primer anneals
+            // to the other strand, so it is stored reverse-complemented
+            revcom(high.primer),
+            '*',
+        ]),
+    ];
+}
+/**
+ * A set of hgPcr products as SAM text, ready to hand a SamAdapter as `samText`.
+ *
+ * No `@SQ` lines: hgPcr's page states no chromosome sizes, and inventing one
+ * would be a lie the adapter then reports as the reference length. A headerless
+ * SAM takes its reference names from the records instead.
+ */
+export function ispcrToSam(products) {
+    return ['@HD\tVN:1.6', ...products.flatMap(productToSamLines), ''].join('\n');
+}

package/esm/pslToSam.d.ts

@@ -0,0 +1,54 @@
+import type { PslRow } from './blatQuery.ts';
+/**
+ * PSL states a hit as a list of aligned blocks in both query and target
+ * coordinates, which is exactly the information a CIGAR encodes: each block is
+ * an M run, the target gap between two blocks is a D, the query gap an I, and
+ * the unaligned query ends are soft clips.
+ *
+ * D rather than N for every target gap: a DNA BLAT hit cannot tell an intron
+ * from a deletion (a spliced-mRNA query would want N, a diverged genomic query
+ * D), and psl2sam takes the same position. The gap is drawn either way.
+ *
+ * Coordinates are the ones PSL states, which for a `-` strand hit means
+ * `blockSizes`/`qStarts` are in reverse-complement query space — the same space
+ * as the SEQ a reverse-strand SAM record carries. That correspondence is what
+ * makes the soft clips and the per-base mismatches land in the right place, so
+ * {@link pslQuerySeq} reverse-complements to match.
+ */
+export declare function pslToCigar({ blockSizes, qStarts, tStarts, qSize, }: {
+    blockSizes: number[];
+    qStarts: number[];
+    tStarts: number[];
+    qSize: number;
+}): string;
+/**
+ * The submitted query in the orientation the hit aligned it, which is what SAM's
+ * SEQ column holds. Answers "do I have the bases this row describes", so it
+ * checks the length the row states as well as the name: the CIGAR spans `qSize`
+ * query bases by construction, and bases of any other length would sit out of
+ * register against the reference, drawing mismatches the whole way along a hit
+ * BLAT scored as near-perfect. Returns undefined for both misses, and the record
+ * then carries `*` and renders its block structure without per-base mismatches.
+ */
+export declare function pslQuerySeq(row: PslRow, querySequences: Map<string, string>): string | undefined;
+/**
+ * A PSL result set as SAM text, ready to hand to a SamAdapter as `samText`.
+ * `@SQ` lines come from the target sizes PSL already states, so the track knows
+ * its reference names without consulting the assembly.
+ *
+ * Rows arrive best-first (pslToFeatures sorts by score), which is what decides
+ * each query's primary alignment.
+ */
+export declare function pslToSam(rows: PslRow[], querySequences: Map<string, string>): string;
+/**
+ * The submitted query text as name -> residues. hgBlat places each FASTA record
+ * separately and labels its hits with that record's name, so this is the map
+ * from a hit back to the bases it was made of.
+ *
+ * Keeps only letters, which is what Kent's FASTA reader counts: a pasted
+ * sequence carrying line numbers, or alignment-gap dashes, is those bases to
+ * BLAT and so `qSize` excludes them. Stripping only whitespace left our text
+ * longer than the hit it describes, which is exactly the off-by-N that puts
+ * every base out of register.
+ */
+export declare function parseQuerySequences(text: string): Map<string, string>;

package/esm/pslToSam.js

@@ -0,0 +1,153 @@
+import { revcom } from '@jbrowse/core/util';
+/**
+ * PSL states a hit as a list of aligned blocks in both query and target
+ * coordinates, which is exactly the information a CIGAR encodes: each block is
+ * an M run, the target gap between two blocks is a D, the query gap an I, and
+ * the unaligned query ends are soft clips.
+ *
+ * D rather than N for every target gap: a DNA BLAT hit cannot tell an intron
+ * from a deletion (a spliced-mRNA query would want N, a diverged genomic query
+ * D), and psl2sam takes the same position. The gap is drawn either way.
+ *
+ * Coordinates are the ones PSL states, which for a `-` strand hit means
+ * `blockSizes`/`qStarts` are in reverse-complement query space — the same space
+ * as the SEQ a reverse-strand SAM record carries. That correspondence is what
+ * makes the soft clips and the per-base mismatches land in the right place, so
+ * {@link pslQuerySeq} reverse-complements to match.
+ */
+export function pslToCigar({ blockSizes, qStarts, tStarts, qSize, }) {
+    // a row stating no blocks describes no alignment; '*' is SAM's word for that,
+    // where the empty string the loop would otherwise build is an unparseable
+    // CIGAR column
+    if (!blockSizes.length) {
+        return '*';
+    }
+    const ops = [];
+    const leadingClip = qStarts[0] ?? 0;
+    if (leadingClip > 0) {
+        ops.push(`${leadingClip}S`);
+    }
+    for (let i = 0; i < blockSizes.length; i++) {
+        if (i > 0) {
+            const queryGap = qStarts[i] - (qStarts[i - 1] + blockSizes[i - 1]);
+            const targetGap = tStarts[i] - (tStarts[i - 1] + blockSizes[i - 1]);
+            if (queryGap > 0) {
+                ops.push(`${queryGap}I`);
+            }
+            if (targetGap > 0) {
+                ops.push(`${targetGap}D`);
+            }
+        }
+        ops.push(`${blockSizes[i]}M`);
+    }
+    const last = blockSizes.length - 1;
+    const trailingClip = qSize - (qStarts[last] + blockSizes[last]);
+    if (trailingClip > 0) {
+        ops.push(`${trailingClip}S`);
+    }
+    return ops.join('');
+}
+/**
+ * The submitted query in the orientation the hit aligned it, which is what SAM's
+ * SEQ column holds. Answers "do I have the bases this row describes", so it
+ * checks the length the row states as well as the name: the CIGAR spans `qSize`
+ * query bases by construction, and bases of any other length would sit out of
+ * register against the reference, drawing mismatches the whole way along a hit
+ * BLAT scored as near-perfect. Returns undefined for both misses, and the record
+ * then carries `*` and renders its block structure without per-base mismatches.
+ */
+export function pslQuerySeq(row, querySequences) {
+    const seq = querySequences.get(row.qName) ??
+        // hgBlat labels a headerless query "YourSeq"; a single submitted record is
+        // unambiguously the one every hit came from whatever it ended up named
+        (querySequences.size === 1 ? [...querySequences.values()][0] : undefined);
+    return seq?.length === row.qSize
+        ? row.strand < 0
+            ? revcom(seq)
+            : seq
+        : undefined;
+}
+// Kent's psl2sam: the edit distance is the mismatched bases plus the bases
+// inserted on either side.
+function editDistance(row) {
+    return row.misMatches + row.qBaseInsert + row.tBaseInsert;
+}
+/**
+ * One SAM alignment line per PSL row. `bestOf` names the queries whose leading
+ * hit has already been emitted: BLAT returns every placement of a query, and
+ * all but its best are secondary alignments (0x100) — competing mappings of one
+ * sequence, which is what keeps them off the best hit's row in the pileup.
+ * MAPQ is 255, the spec's "unavailable": BLAT reports identity, not a mapping
+ * probability, so any number here would be invented.
+ */
+function pslRowToSamLine(row, querySequences, bestOf) {
+    const secondary = bestOf.has(row.qName);
+    bestOf.add(row.qName);
+    const seq = pslQuerySeq(row, querySequences);
+    return [
+        row.qName,
+        (row.strand < 0 ? 16 : 0) | (secondary ? 256 : 0),
+        row.tName,
+        row.tStart + 1,
+        255,
+        pslToCigar(row),
+        '*',
+        0,
+        0,
+        seq ?? '*',
+        '*',
+        `NM:i:${editDistance(row)}`,
+        `AS:i:${row.score}`,
+    ].join('\t');
+}
+/**
+ * A PSL result set as SAM text, ready to hand to a SamAdapter as `samText`.
+ * `@SQ` lines come from the target sizes PSL already states, so the track knows
+ * its reference names without consulting the assembly.
+ *
+ * Rows arrive best-first (pslToFeatures sorts by score), which is what decides
+ * each query's primary alignment.
+ */
+export function pslToSam(rows, querySequences) {
+    const targetSizes = new Map(rows.map(row => [row.tName, row.tSize]));
+    const bestOf = new Set();
+    return [
+        '@HD\tVN:1.6',
+        ...[...targetSizes].map(([name, size]) => `@SQ\tSN:${name}\tLN:${size}`),
+        ...rows.map(row => pslRowToSamLine(row, querySequences, bestOf)),
+        '',
+    ].join('\n');
+}
+/**
+ * The submitted query text as name -> residues. hgBlat places each FASTA record
+ * separately and labels its hits with that record's name, so this is the map
+ * from a hit back to the bases it was made of.
+ *
+ * Keeps only letters, which is what Kent's FASTA reader counts: a pasted
+ * sequence carrying line numbers, or alignment-gap dashes, is those bases to
+ * BLAT and so `qSize` excludes them. Stripping only whitespace left our text
+ * longer than the hit it describes, which is exactly the off-by-N that puts
+ * every base out of register.
+ */
+export function parseQuerySequences(text) {
+    const sequences = new Map();
+    let name = 'YourSeq';
+    let residues = [];
+    const flush = () => {
+        if (residues.length) {
+            sequences.set(name, residues.join(''));
+        }
+    };
+    for (const line of text.split('\n')) {
+        if (line.startsWith('>')) {
+            flush();
+            name = /^>\s*(\S+)/.exec(line)?.[1] ?? 'YourSeq';
+            residues = [];
+        }
+        else {
+            residues.push(line.replaceAll(/[^A-Za-z]/g, ''));
+        }
+    }
+    flush();
+    return sequences;
+}

package/esm/ucscDbMap.d.ts

@@ -0,0 +1,2 @@
+export declare function assemblyToUcscDb(name: string): string;
+export declare function looksLikeUcscDb(db: string): boolean;

package/esm/ucscDbMap.js

@@ -0,0 +1,25 @@
+// jb2hubs assemblies are frequently already named with UCSC db ids (hg38, mm39,
+// …) so identity is the default. This covers the common GRC/T2T aliases that
+// aren't literal UCSC db names.
+const aliases = {
+    GRCh38: 'hg38',
+    GRCh37: 'hg19',
+    GRCm39: 'mm39',
+    GRCm38: 'mm10',
+    'T2T-CHM13v2.0': 'hs1',
+    'T2T-CHM13': 'hs1',
+    chm13: 'hs1',
+};
+export function assemblyToUcscDb(name) {
+    return aliases[name] ?? name;
+}
+// UCSC db names are a lowercase organism prefix plus a version (hg38, mm39,
+// danRer11, hs1), and GenArk accessions resolve on hgBlat directly. Neither
+// shape proves UCSC hosts the db, but a name outside both — a genome opened
+// from local files, "my_assembly" — certainly isn't one, and that is worth
+// saying before a query goes out rather than after it comes back empty.
+const UCSC_DB = /^[a-z][A-Za-z]*\d+$/;
+const GENARK_ACCESSION = /^GC[AF]_\d+\.\d+$/;
+export function looksLikeUcscDb(db) {
+    return UCSC_DB.test(db) || GENARK_ACCESSION.test(db);
+}

package/esm/ucscShared.d.ts

@@ -0,0 +1,40 @@
+import type { AbstractViewContainer, AssemblyHost, DialogHost, NotificationSink, SimpleFeatureSerialized } from '@jbrowse/core/util';
+/**
+ * What this plugin asks of the host it is installed into: an assembly to
+ * resolve a UCSC db against, views to navigate, somewhere to report a hit it
+ * could not reach, and somewhere to put its two dialogs. Everything else it
+ * needs — adding the result track, opening the results panel — it asks for with
+ * a guard, because a host may not offer it.
+ */
+export interface UcscHost extends AbstractViewContainer, AssemblyHost, NotificationSink, DialogHost {
+}
+export declare function ucscDbStamp(session: UcscHost, name: string): string | undefined;
+export declare function resolveUcscDb(session: UcscHost, name: string): string;
+/**
+ * Whether this host can draw a hit as an alignment rather than as plain blocks.
+ *
+ * Results are added as an AlignmentsTrack over a SamAdapter, which is what draws
+ * the blocks, the indels, the soft-clipped query ends and the per-base
+ * mismatches. SamAdapter arrived in JBrowse after v4.3.0, and an external plugin
+ * is loaded by whatever host a config points it at — including releases older
+ * than the plugin itself. Asking the host is the difference between quietly
+ * falling back to the block-structure track BLAT results always used to be, and
+ * adding a track whose adapter cannot resolve.
+ */
+export declare function canRenderAlignments(session: UcscHost): boolean;
+export declare function featureLocString(feature: SimpleFeatureSerialized): string;
+export declare function navToFeature(session: UcscHost, assembly: string, feature: SimpleFeatureSerialized): Promise<void>;
+export interface ResultTrackConf {
+    type: string;
+    adapter: Record<string, unknown>;
+    displayDefaults?: Record<string, unknown>;
+}
+export declare function addResultTrack({ session, assembly, features, trackIdPrefix, trackName, trackConf, resultNoun, }: {
+    session: UcscHost;
+    assembly: string;
+    features: SimpleFeatureSerialized[];
+    trackIdPrefix: string;
+    trackName: string;
+    trackConf?: ResultTrackConf;
+    resultNoun?: 'hit' | 'product';
+}): Promise<void>;

package/esm/ucscShared.js

@@ -0,0 +1,116 @@
+import { getConf } from '@jbrowse/core/configuration';
+import { getEnv, isSessionModelWithWidgets, isSessionWithAddSessionTrack, } from '@jbrowse/core/util';
+import { assemblyToUcscDb } from './ucscDbMap.js';
+function isNavigableView(view) {
+    return ('showTrack' in view &&
+        typeof view.showTrack === 'function' &&
+        'navToLocString' in view &&
+        typeof view.navToLocString === 'function');
+}
+// jb2hubs stamps the UCSC db on the assembly's sequence.metadata. Its presence
+// is also the one positive proof that UCSC can search the assembly, so the
+// dialogs read it directly to decide whether to warn.
+export function ucscDbStamp(session, name) {
+    const assembly = session.assemblyManager.get(name);
+    const stamped = assembly
+        ? getConf(assembly, ['sequence', 'metadata', 'blatDb'])
+        : undefined;
+    return stamped;
+}
+// Prefers the stamp, falling back to the static alias map for assemblies whose
+// configs predate it. Shared by the BLAT and in-silico PCR dialogs.
+export function resolveUcscDb(session, name) {
+    const stamped = ucscDbStamp(session, name);
+    return stamped ? stamped : assemblyToUcscDb(name);
+}
+/**
+ * Whether this host can draw a hit as an alignment rather than as plain blocks.
+ *
+ * Results are added as an AlignmentsTrack over a SamAdapter, which is what draws
+ * the blocks, the indels, the soft-clipped query ends and the per-base
+ * mismatches. SamAdapter arrived in JBrowse after v4.3.0, and an external plugin
+ * is loaded by whatever host a config points it at — including releases older
+ * than the plugin itself. Asking the host is the difference between quietly
+ * falling back to the block-structure track BLAT results always used to be, and
+ * adding a track whose adapter cannot resolve.
+ */
+export function canRenderAlignments(session) {
+    const { pluginManager } = getEnv(session);
+    return (pluginManager.adapterTypes.has('SamAdapter') &&
+        pluginManager.trackTypes.has('AlignmentsTrack'));
+}
+// Builds a locstring from a feature. Feature coordinates are interbase, so the
+// start needs +1 to become the 1-based coordinate a locstring names.
+export function featureLocString(feature) {
+    return `${feature.refName}:${feature.start + 1}-${feature.end}`;
+}
+function findNavigableView(session, assembly) {
+    const view = session.views.find(v => v.type === 'LinearGenomeView' && !!v.assemblyNames?.includes(assembly));
+    return view && isNavigableView(view) ? view : undefined;
+}
+// Navigates an open view to a hit, growing the window so it lands with flanking
+// context rather than filling the viewport edge to edge. Shared by the
+// post-query navigation and the results widget's per-hit links.
+export async function navToFeature(session, assembly, feature) {
+    const view = findNavigableView(session, assembly);
+    const loc = featureLocString(feature);
+    if (view) {
+        try {
+            await view.navToLocString(loc, assembly, 0.2);
+        }
+        catch (e) {
+            // a hit on a refName the loaded assembly doesn't know (the UCSC db and
+            // the loaded assembly aren't the same build, or lack an alias) still
+            // belongs in the track — report the coordinates rather than dropping them
+            session.notify(`Could not navigate to ${loc}: ${e}`, 'warning');
+        }
+    }
+    else {
+        session.notify(`No open view displays ${assembly}`, 'warning');
+    }
+}
+// Turns a UCSC query result into an on-the-fly track, shows it, and opens the
+// result list in the drawer. Deliberately does NOT navigate: "first" is the
+// server's ordering, not the user's intent, so jumping there picks a result for
+// them — an off-target product can take the view — and it throws away wherever
+// they were when they asked. The drawer lists every result as a link, so going to
+// one is a click, and which one is theirs to choose. Callers pass `features`
+// best-first (pslToFeatures sorts by score; hgPcr returns its products in order).
+export async function addResultTrack({ session, assembly, features, trackIdPrefix, trackName, trackConf, resultNoun, }) {
+    if (!isSessionWithAddSessionTrack(session)) {
+        throw new Error("Can't add tracks to this session");
+    }
+    const trackId = `${trackIdPrefix}-${Date.now()}`;
+    const resultTrack = trackConf ?? {
+        type: 'FeatureTrack',
+        adapter: { type: 'FromConfigAdapter', features },
+    };
+    session.addSessionTrackConf({
+        ...resultTrack,
+        trackId,
+        name: trackName,
+        assemblyNames: [assembly],
+    });
+    const view = findNavigableView(session, assembly);
+    if (view) {
+        view.showTrack(trackId);
+    }
+    else {
+        session.notify(`Added track "${trackId}" but no open view displays ${assembly}`, 'warning');
+    }
+    // #region showWidget
+    // addWidget constructs the widget and returns it; showWidget is what puts it
+    // in the drawer. The third argument is the initial state, so its keys are the
+    // properties UcscResultsWidget's state model declares. Not every session has
+    // a drawer — an embedded component may be built without one — so the guard is
+    // not optional.
+    if (isSessionModelWithWidgets(session)) {
+        session.showWidget(session.addWidget('UcscResultsWidget', 'ucscResults', {
+            features,
+            assembly,
+            trackName,
+            resultNoun,
+        }));
+    }
+    // #endregion
+}