@jbrowse/plugin-blat 4.3.0

package/esm/UcscResultsWidget/stateModel.d.ts

@@ -0,0 +1,42 @@
+import type { SimpleFeatureSerialized } from '@jbrowse/core/util';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel UcscResultsWidget
+ * The hit table for one UCSC BLAT or in-silico PCR query. The features are the
+ * same ones the result track was built from, so the list and the track can't
+ * disagree.
+ */
+export declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     */
+    id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+    /**
+     * #property
+     */
+    type: import("@jbrowse/mobx-state-tree").ILiteralType<"UcscResultsWidget">;
+    /**
+     * #property
+     * hits, best first (BLAT sorts by score; hgPcr returns products in order)
+     */
+    features: import("@jbrowse/mobx-state-tree").IType<SimpleFeatureSerialized[] | null | undefined, SimpleFeatureSerialized[], SimpleFeatureSerialized[]>;
+    /**
+     * #property
+     * assembly the hits are on, for navigating and for the header line
+     */
+    assembly: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+    /**
+     * #property
+     * name of the on-the-fly track these hits were added as
+     */
+    trackName: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+    /**
+     * #property
+     * what one result is called. A BLAT result is a hit; an hgPcr result is a
+     * product, which is a band on a gel — the word a bench scientist reasons in,
+     * and "2 hits" understates what two of them mean for a PCR run
+     */
+    resultNoun: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+}, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+export type UcscResultsWidgetStateModel = ReturnType<typeof stateModelFactory>;
+export type UcscResultsWidgetModel = Instance<UcscResultsWidgetStateModel>;

package/esm/UcscResultsWidget/stateModel.js

@@ -0,0 +1,41 @@
+import { types } from '@jbrowse/mobx-state-tree';
+/**
+ * #stateModel UcscResultsWidget
+ * The hit table for one UCSC BLAT or in-silico PCR query. The features are the
+ * same ones the result track was built from, so the list and the track can't
+ * disagree.
+ */
+export function stateModelFactory() {
+    return types.model('UcscResultsWidget', {
+        /**
+         * #property
+         */
+        id: types.identifier,
+        /**
+         * #property
+         */
+        type: types.literal('UcscResultsWidget'),
+        /**
+         * #property
+         * hits, best first (BLAT sorts by score; hgPcr returns products in order)
+         */
+        features: types.frozen([]),
+        /**
+         * #property
+         * assembly the hits are on, for navigating and for the header line
+         */
+        assembly: types.string,
+        /**
+         * #property
+         * name of the on-the-fly track these hits were added as
+         */
+        trackName: types.string,
+        /**
+         * #property
+         * what one result is called. A BLAT result is a hit; an hgPcr result is a
+         * product, which is a band on a gel — the word a bench scientist reasons in,
+         * and "2 hits" understates what two of them mean for a PCR run
+         */
+        resultNoun: types.optional(types.enumeration(['hit', 'product']), 'hit'),
+    });
+}

package/esm/blatQuery.d.ts

@@ -0,0 +1,75 @@
+import type { SimpleFeatureSerialized } from '@jbrowse/core/util';
+interface BlatJsonResponse {
+    fields: string[];
+    blat: (string | number)[][];
+    genome?: string;
+}
+/**
+ * One PSL hit, with the column-name indirection resolved and the derived
+ * kent numbers (score, identity, coverage) computed once. Both consumers read
+ * this: the hit-list features, and the SAM conversion that turns the blocks into
+ * a CIGAR alignment.
+ */
+export interface PslRow {
+    matches: number;
+    misMatches: number;
+    repMatches: number;
+    qNumInsert: number;
+    qBaseInsert: number;
+    tNumInsert: number;
+    tBaseInsert: number;
+    strand: 1 | -1;
+    qName: string;
+    qSize: number;
+    qStart: number;
+    qEnd: number;
+    tName: string;
+    tSize: number;
+    tStart: number;
+    tEnd: number;
+    blockSizes: number[];
+    qStarts: number[];
+    tStarts: number[];
+    score: number;
+    identity: number;
+    coverage: number;
+}
+export declare function parsePslRows(data: BlatJsonResponse): PslRow[];
+export declare function pslToFeatures(rows: PslRow[]): SimpleFeatureSerialized[];
+export declare const MINIMUM_BLAT_LENGTH = 20;
+export declare const MAXIMUM_BLAT_LENGTH = 25000;
+export declare const MAXIMUM_BLAT_QUERIES = 25;
+export declare function stripFasta(seq: string): string;
+export declare function fastaRecordCount(seq: string): number;
+export declare function queryLabel(seq: string): string;
+export declare function buildBlatBody({ db, seq, apiKey, }: {
+    db: string;
+    seq: string;
+    apiKey?: string;
+}): string;
+export declare class BlatChallengeError extends Error {
+    name: string;
+}
+export declare function isChallengePage(text: string): boolean;
+export declare function challengeError(): BlatChallengeError;
+export declare function parseBlatResponse(text: string): PslRow[];
+export declare const UCSC_BLAT_URL = "https://genome.ucsc.edu/cgi-bin/hgBlat";
+/**
+ * Where the dialog points when the user has not typed a server of their own:
+ * the jbrowse.org proxy, which injects a UCSC apiKey server-side and meters the
+ * budget everyone using it shares (`products/aws/blat-proxy`). That is what makes
+ * a first BLAT work with no key and no CAPTCHA.
+ *
+ * A browser has nowhere else to go — it cannot call genome.ucsc.edu at all (no
+ * CORS headers) and must not carry a key in a public bundle. Desktop can reach
+ * UCSC itself, since `blatFetch` runs in the main process, so it keeps
+ * {@link UCSC_BLAT_URL} in reserve two ways: as the fallback when the proxy is
+ * out of budget or down, and as where the server field moves outright once the
+ * user supplies an apiKey of their own. The proxy overwrites a client key with
+ * its own, so a key only ever spends against UCSC direct.
+ *
+ * Either way this is only a default — the dialog's server field overrides it,
+ * which is how someone runs their own proxy or their own gfServer.
+ */
+export declare const DEFAULT_BLAT_URL = "https://api.jbrowse.org/ucsc/v1/blat";
+export {};

package/esm/blatQuery.js

@@ -0,0 +1,245 @@
+// PSL packs the per-block coordinates as comma-separated lists with a trailing
+// comma, e.g. "31,101,13,"
+function parseCommaList(value) {
+    return value.split(',').filter(Boolean).map(Number);
+}
+// kent's pslCalcMilliBad with isMrna=true, which is what hgBlat's own hit table
+// reports: a target span longer than the query is an intron rather than a
+// penalty, and target inserts aren't charged. Integer-divided like the C
+// original so the percentage matches the number UCSC prints.
+function pslMilliBad({ matches, misMatches, repMatches, qNumInsert, qAliSize, tAliSize, }) {
+    const total = matches + repMatches + misMatches;
+    const sizeDif = Math.max(0, qAliSize - tAliSize);
+    return Math.min(qAliSize, tAliSize) <= 0 || total === 0
+        ? 0
+        : Math.trunc((1000 *
+            (misMatches + qNumInsert + Math.round(3 * Math.log(1 + sizeDif)))) /
+            total);
+}
+function pslRow(row, col) {
+    const str = (name) => String(row[col[name]] ?? '');
+    const num = (name) => Number(row[col[name]] ?? 0);
+    const matches = num('matches');
+    const misMatches = num('misMatches');
+    const repMatches = num('repMatches');
+    const qNumInsert = num('qNumInsert');
+    const tNumInsert = num('tNumInsert');
+    const qStart = num('qStart');
+    const qEnd = num('qEnd');
+    const qSize = num('qSize');
+    const tStart = num('tStart');
+    const tEnd = num('tEnd');
+    return {
+        matches,
+        misMatches,
+        repMatches,
+        qNumInsert,
+        qBaseInsert: num('qBaseInsert'),
+        tNumInsert,
+        tBaseInsert: num('tBaseInsert'),
+        strand: str('strand').startsWith('-') ? -1 : 1,
+        qName: str('qName'),
+        qSize,
+        qStart,
+        qEnd,
+        tName: str('tName'),
+        tSize: num('tSize'),
+        tStart,
+        tEnd,
+        blockSizes: parseCommaList(str('blockSizes')),
+        qStarts: parseCommaList(str('qStarts')),
+        tStarts: parseCommaList(str('tStarts')),
+        // kent's pslScore, which ranks the hit table: repeat matches count half
+        score: matches + (repMatches >> 1) - misMatches - qNumInsert - tNumInsert,
+        identity: 100 -
+            pslMilliBad({
+                matches,
+                misMatches,
+                repMatches,
+                qNumInsert,
+                qAliSize: qEnd - qStart,
+                tAliSize: tEnd - tStart,
+            }) /
+                10,
+        // how much of the submitted sequence this hit accounts for — the other half
+        // of "did my sequence map here", since a high-identity hit over 10% of the
+        // query is not the locus you were looking for
+        coverage: qSize > 0 ? (100 * (qEnd - qStart)) / qSize : 0,
+    };
+}
+// Sorted by score descending, matching the order hgBlat lists its hit table in,
+// so consumers can treat the first row as the best placement of the query.
+export function parsePslRows(data) {
+    // JSON that is not a PSL table at all — a proxy or mirror relaying its own
+    // envelope, a kent JSON error — otherwise reached `.map` on undefined and
+    // surfaced a TypeError where the server's own words belong
+    if (!Array.isArray(data.fields) || !Array.isArray(data.blat)) {
+        throw new Error('BLAT server returned JSON without the expected fields/blat columns');
+    }
+    const col = Object.fromEntries(data.fields.map((f, i) => [f, i]));
+    return data.blat
+        .map(row => pslRow(row, col))
+        .sort((a, b) => b.score - a.score);
+}
+function pslRowToFeature(row, featureIndex) {
+    const { tName: refName, strand, identity, blockSizes, tStarts } = row;
+    const uniqueId = `blat-${featureIndex}`;
+    return {
+        uniqueId,
+        refName,
+        start: row.tStart,
+        end: row.tEnd,
+        strand,
+        type: 'match',
+        name: `${row.qName} ${identity.toFixed(1)}%`,
+        score: row.score,
+        identity: Number(identity.toFixed(1)),
+        coverage: Number(row.coverage.toFixed(1)),
+        matches: row.matches,
+        misMatches: row.misMatches,
+        queryName: row.qName,
+        queryStart: row.qStart,
+        queryEnd: row.qEnd,
+        querySize: row.qSize,
+        blockCount: blockSizes.length,
+        subfeatures: blockSizes.map((size, i) => ({
+            uniqueId: `${uniqueId}-block-${i}`,
+            refName,
+            start: tStarts[i],
+            end: tStarts[i] + size,
+            strand,
+            type: 'match_part',
+        })),
+    };
+}
+export function pslToFeatures(rows) {
+    return rows.map((row, i) => pslRowToFeature(row, i));
+}
+export const MINIMUM_BLAT_LENGTH = 20;
+// UCSC rejects queries over 25kb server-side; enforce locally for a clear message
+export const MAXIMUM_BLAT_LENGTH = 25000;
+// hgBlat's per-submission cap on FASTA records
+export const MAXIMUM_BLAT_QUERIES = 25;
+// residues only, for the length limits. The query itself goes to the server
+// verbatim: hgBlat parses FASTA and labels each hit with its record's name, so
+// stripping headers here would fuse a multi-record paste into one chimeric
+// query and throw away the names that tell the hits apart.
+//
+// Letters only, which is what kent's FASTA reader counts and therefore what the
+// limits are stated in — a sequence pasted with line numbers or alignment-gap
+// dashes is fewer bases to BLAT than it has characters. Counting whitespace out
+// but digits in measured a 25kb-limited query against a number the server does
+// not use. Same rule as parseQuerySequences, which has to agree with `qSize`.
+export function stripFasta(seq) {
+    return seq
+        .split('\n')
+        .filter(line => !line.startsWith('>'))
+        .join('')
+        .replaceAll(/[^A-Za-z]/g, '');
+}
+// hgBlat places each FASTA record separately, so records are queries
+export function fastaRecordCount(seq) {
+    const headers = seq.match(/^>/gm);
+    return headers ? headers.length : 1;
+}
+// names the result track after what was searched: the first FASTA header, or
+// the leading bases of a bare sequence
+export function queryLabel(seq) {
+    const header = /^>\s*(\S+)/m.exec(seq);
+    const residues = stripFasta(seq);
+    return header
+        ? header[1]
+        : residues.slice(0, 12) + (residues.length > 12 ? '…' : '');
+}
+export function buildBlatBody({ db, seq, apiKey, }) {
+    const params = new URLSearchParams({
+        userSeq: seq,
+        type: 'DNA',
+        db,
+        output: 'json',
+    });
+    // UCSC removed open programmatic BLAT access in 2025; an account apiKey
+    // (Genome Browser account → Hub Development → API key) bypasses the
+    // Cloudflare Turnstile that otherwise fronts hgBlat
+    if (apiKey) {
+        params.set('apiKey', apiKey);
+    }
+    return params.toString();
+}
+// thrown when the server returns its CAPTCHA challenge page instead of results
+// — the caller surfaces a "solve challenge" affordance for this case (and, when
+// available, an apiKey avoids the challenge entirely)
+export class BlatChallengeError extends Error {
+    name = 'BlatChallengeError';
+}
+// Markers on a Cloudflare Turnstile challenge page. Every marker has to be
+// specific to the challenge itself: a bare `cf-`, `captcha` or `challenge` also
+// matches an ordinary UCSC page, whose standard nav links to
+// FAQdownloads.html#CAPTCHA and whose scripts load from challenges.cloudflare.com.
+// Those two words made a failed parse of a perfectly good result page report
+// itself as a CAPTCHA, sending the user off to solve one that wasn't there.
+//
+// Duplicated in `products/aws/blat-proxy/src/routes.ts`, which decides the same thing
+// about the same pages server-side. The proxy is a standalone package and cannot
+// import this one, so the copies are deliberate: narrow one and narrow both.
+const CHALLENGE_MARKERS = /turnstile|cf[-_]chl/i;
+export function isChallengePage(text) {
+    return CHALLENGE_MARKERS.test(text);
+}
+export function challengeError() {
+    return new BlatChallengeError('The UCSC server returned a CAPTCHA challenge instead of results. ' +
+        'Solve it in the window, or supply a UCSC apiKey (Genome Browser ' +
+        'account → Hub Development → API key) to avoid it.');
+}
+// kent CGIs report a bad db ("Can't find database …") or a server-side failure
+// by errAbort-ing into an HTML page, usually inside a <pre>. Pull that text out
+// so an assembly UCSC doesn't host says why, rather than "unexpected HTML".
+function htmlErrorMessage(text) {
+    const pre = /<pre[^>]*>([\S\s]*?)<\/pre>/i.exec(text);
+    return (pre ? pre[1] : text)
+        .replaceAll(/<(script|style)[\S\s]*?<\/\1>/gi, ' ')
+        .replaceAll(/<[^>]*>/g, ' ')
+        .replaceAll('&nbsp;', ' ')
+        .replaceAll('&quot;', '"')
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&amp;', '&')
+        .replaceAll(/\s+/g, ' ')
+        .trim()
+        .slice(0, 300);
+}
+// hgBlat returns text/html content-type with a JSON body, and both non-match
+// errors and the Cloudflare Turnstile challenge come back as HTML pages, so we
+// parse the text ourselves and give a readable error if it isn't JSON
+export function parseBlatResponse(text) {
+    if (text.trimStart().startsWith('<')) {
+        if (isChallengePage(text)) {
+            throw challengeError();
+        }
+        const message = htmlErrorMessage(text);
+        throw new Error(message
+            ? `BLAT server error: ${message}`
+            : 'BLAT server returned an unexpected HTML response instead of JSON');
+    }
+    const data = JSON.parse(text);
+    return parsePslRows(data);
+}
+export const UCSC_BLAT_URL = 'https://genome.ucsc.edu/cgi-bin/hgBlat';
+/**
+ * Where the dialog points when the user has not typed a server of their own:
+ * the jbrowse.org proxy, which injects a UCSC apiKey server-side and meters the
+ * budget everyone using it shares (`products/aws/blat-proxy`). That is what makes
+ * a first BLAT work with no key and no CAPTCHA.
+ *
+ * A browser has nowhere else to go — it cannot call genome.ucsc.edu at all (no
+ * CORS headers) and must not carry a key in a public bundle. Desktop can reach
+ * UCSC itself, since `blatFetch` runs in the main process, so it keeps
+ * {@link UCSC_BLAT_URL} in reserve two ways: as the fallback when the proxy is
+ * out of budget or down, and as where the server field moves outright once the
+ * user supplies an apiKey of their own. The proxy overwrites a client key with
+ * its own, so a key only ever spends against UCSC direct.
+ *
+ * Either way this is only a default — the dialog's server field overrides it,
+ * which is how someone runs their own proxy or their own gfServer.
+ */
+export const DEFAULT_BLAT_URL = 'https://api.jbrowse.org/ucsc/v1/blat';

package/esm/desktopBlat.d.ts

@@ -0,0 +1,9 @@
+export declare function desktopBlatFetch({ url, body, }: {
+    url: string;
+    body: string;
+}): Promise<{
+    ok: boolean;
+    status: number;
+    text: string;
+}>;
+export declare function openBlatChallenge(url: string): Promise<boolean>;

package/esm/desktopBlat.js

@@ -0,0 +1,22 @@
+// Bridge to the jbrowse-desktop main process. BLAT requests are routed through
+// the main process for two reasons: the renderer is CORS-bound like a browser
+// (so a direct cross-origin hgBlat call fails), and the cf_clearance cookie
+// from a solved Cloudflare Turnstile challenge (held in the default session)
+// attaches first-party there. A user-supplied apiKey avoids the challenge; the
+// solve-window path is the fallback when there's no key.
+// window.require('electron') is the desktop preload bridge; typed narrowly here
+// rather than polluting the global Window type from a plugin
+function getIpcRenderer() {
+    const req = window
+        .require;
+    if (!req) {
+        throw new Error('electron ipcRenderer unavailable');
+    }
+    return req('electron').ipcRenderer;
+}
+export async function desktopBlatFetch({ url, body, }) {
+    return (await getIpcRenderer().invoke('blatFetch', url, body));
+}
+export async function openBlatChallenge(url) {
+    return (await getIpcRenderer().invoke('openBlatChallenge', url));
+}

package/esm/index.d.ts

@@ -0,0 +1,7 @@
+import Plugin from '@jbrowse/core/Plugin';
+import type PluginManager from '@jbrowse/core/PluginManager';
+export default class BlatPlugin extends Plugin {
+    name: string;
+    install(pluginManager: PluginManager): void;
+    configure(pluginManager: PluginManager): void;
+}

package/esm/index.js

@@ -0,0 +1,37 @@
+import Plugin from '@jbrowse/core/Plugin';
+import { isAbstractMenuManager } from '@jbrowse/core/util';
+import BiotechIcon from '@mui/icons-material/Biotech';
+import SearchIcon from '@mui/icons-material/Search';
+import BlatDialog from './BlatDialog.js';
+import IsPcrDialog from './IsPcrDialog.js';
+import UcscResultsWidgetF from './UcscResultsWidget/index.js';
+export default class BlatPlugin extends Plugin {
+    name = 'BlatPlugin';
+    install(pluginManager) {
+        UcscResultsWidgetF(pluginManager);
+    }
+    configure(pluginManager) {
+        if (isAbstractMenuManager(pluginManager.rootModel)) {
+            pluginManager.rootModel.appendToMenu('Tools', {
+                label: 'BLAT search…',
+                icon: SearchIcon,
+                onClick: (session) => {
+                    session.queueDialog(handleClose => [
+                        BlatDialog,
+                        { session, handleClose },
+                    ]);
+                },
+            });
+            pluginManager.rootModel.appendToMenu('Tools', {
+                label: 'In-silico PCR…',
+                icon: BiotechIcon,
+                onClick: (session) => {
+                    session.queueDialog(handleClose => [
+                        IsPcrDialog,
+                        { session, handleClose },
+                    ]);
+                },
+            });
+        }
+    }
+}

package/esm/ispcrQuery.d.ts

@@ -0,0 +1,59 @@
+import type { SimpleFeatureSerialized } from '@jbrowse/core/util';
+export declare const UCSC_ISPCR_URL = "https://genome.ucsc.edu/cgi-bin/hgPcr";
+export declare const DEFAULT_ISPCR_URL = "https://api.jbrowse.org/ucsc/v1/ispcr";
+export declare const DEFAULT_MAX_PRODUCT_SIZE = 4000;
+export declare const MINIMUM_PRIMER_LENGTH = 15;
+/** One amplicon, in the terms the header states it. */
+export interface PcrProduct {
+    refName: string;
+    /** interbase, half-open */
+    start: number;
+    end: number;
+    /** the strand hgPcr reports the product on, i.e. which primer was forward */
+    strand: 1 | -1;
+    size: number;
+    /** the primers as submitted, 5'->3' */
+    forwardPrimer: string;
+    reversePrimer: string;
+}
+/**
+ * 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 declare function productFootprints(product: PcrProduct): {
+    low: {
+        name: string;
+        role: "fwd" | "rev";
+        start: number;
+        end: number;
+        primer: string;
+    };
+    high: {
+        name: string;
+        role: "fwd" | "rev";
+        start: number;
+        end: number;
+        primer: string;
+    };
+};
+export declare function parseIsPcrProducts(text: string): PcrProduct[];
+export declare function pcrProductsToFeatures(products: PcrProduct[]): SimpleFeatureSerialized[];
+export declare function parseIsPcrResponse(text: string): SimpleFeatureSerialized[];
+export declare function buildIsPcrBody({ db, forwardPrimer, reversePrimer, maxProductSize, apiKey, }: {
+    db: string;
+    forwardPrimer: string;
+    reversePrimer: string;
+    maxProductSize?: number;
+    apiKey?: string;
+}): string;