@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/scheduleDetachedDestroy.d.ts

@@ -0,0 +1,18 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Free a tree an action has already let go of — a superseded session, a view
+ * taken out of one, a superseded rootModel the React host has detached.
+ *
+ * A task rather than a microtask: the wait is for React to unmount the
+ * components rendering it, which happens on the re-render that the action's own
+ * reactions schedule. Deferring is acceptable here, and is not elsewhere,
+ * because the node stays alive and detached until it fires — a late read gets a
+ * live tree nobody is rendering. ADR-069.
+ *
+ * The destroy itself is not optional. `beforeDestroy` is a plugin-facing
+ * contract (jbrowse-plugin-apollo aborts its in-flight fetches there) and core's
+ * `BaseTrackModel` releases the `rpcSessionId` claim that lets
+ * `CoreFreeResources` evict a parsed adapter from the worker — so detaching and
+ * forgetting would trade a console warning for an unbounded leak.
+ */
+export declare function scheduleDetachedDestroy(node: IAnyStateTreeNode): void;

package/esm/util/scheduleDetachedDestroy.js

@@ -0,0 +1,24 @@
+import { destroy, isAlive } from '@jbrowse/mobx-state-tree';
+/**
+ * Free a tree an action has already let go of — a superseded session, a view
+ * taken out of one, a superseded rootModel the React host has detached.
+ *
+ * A task rather than a microtask: the wait is for React to unmount the
+ * components rendering it, which happens on the re-render that the action's own
+ * reactions schedule. Deferring is acceptable here, and is not elsewhere,
+ * because the node stays alive and detached until it fires — a late read gets a
+ * live tree nobody is rendering. ADR-069.
+ *
+ * The destroy itself is not optional. `beforeDestroy` is a plugin-facing
+ * contract (jbrowse-plugin-apollo aborts its in-flight fetches there) and core's
+ * `BaseTrackModel` releases the `rpcSessionId` claim that lets
+ * `CoreFreeResources` evict a parsed adapter from the worker — so detaching and
+ * forgetting would trade a console warning for an unbounded leak.
+ */
+export function scheduleDetachedDestroy(node) {
+    setTimeout(() => {
+        if (isAlive(node)) {
+            destroy(node);
+        }
+    }, 0);
+}

package/esm/util/scrollLatch.d.ts

@@ -0,0 +1,5 @@
+export declare function createScrollLatch(timeoutMs?: number): {
+    scroll(e: WheelEvent, cur: number, delta: number, max: number, min?: number): number | null;
+    holds(e: WheelEvent): boolean;
+    reset(): void;
+};

package/esm/util/scrollLatch.js

@@ -0,0 +1,67 @@
+// Native browsers latch a wheel gesture to the inner scroller: once an inner
+// panel starts consuming scroll, continued momentum stays in that panel even
+// after it reaches its boundary, and only after the gesture pauses does scroll
+// chain to the outer page. Raw wheel bubbling lacks this — the event spills to
+// the page the instant the panel hits its limit, so a single continuous gesture
+// scrolls the page unexpectedly. createScrollLatch reproduces the native
+// behavior in one place so every wheel handler gets it identically.
+// gap between wheel events long enough to count as a new gesture; continuous
+// trackpad/mouse scrolling fires every ~16ms, so 200ms reliably marks a pause
+const LATCH_TIMEOUT_MS = 200;
+export function createScrollLatch(timeoutMs = LATCH_TIMEOUT_MS) {
+    // timestamp of the previous wheel event (any event, not just ones that
+    // moved the panel) and whether the current gesture has latched onto this
+    // panel by actually scrolling it. A gap > timeoutMs between events marks a
+    // pause, i.e. the start of a new gesture.
+    let lastEvent = -Infinity;
+    let latched = false;
+    return {
+        // Apply one wheel event to a vertical panel with native-style latching.
+        // Given the current scroll offset, the delta (already normalized to
+        // pixels), and the scrollable max (min defaults to 0), returns the clamped
+        // new offset when the panel moves, or null when it stays put. preventDefault
+        // fires both when the panel scrolls AND when it sits at a boundary mid-
+        // gesture, so the page only takes over after the gesture pauses. The whole
+        // boundary/latch/preventDefault contract lives here so no caller can derive
+        // it incorrectly — they just apply the returned offset.
+        //
+        // Latching keys off gesture continuity, not panel movement: once a
+        // continuous gesture has scrolled the panel it stays latched — suppressing
+        // page scroll — through any amount of continued over-scroll at the
+        // boundary, and only releases after the wheel events actually pause. A
+        // gesture that *starts* at the boundary never latches, so it chains to the
+        // page immediately (native behavior).
+        scroll(e, cur, delta, max, min = 0) {
+            if (e.timeStamp - lastEvent >= timeoutMs) {
+                latched = false;
+            }
+            lastEvent = e.timeStamp;
+            const next = Math.max(min, Math.min(max, cur + delta));
+            if (next !== cur) {
+                latched = true;
+                e.preventDefault();
+                return next;
+            }
+            if (latched) {
+                e.preventDefault();
+            }
+            return null;
+        },
+        // Whether this panel already owns the gesture `e` belongs to, i.e. it has
+        // scrolled during a run of events this one continues. Callers ask before
+        // declining an event on their own rules: a gesture that has latched keeps
+        // every event it fires, cross-axis momentum included, which is the whole
+        // point of latching.
+        holds(e) {
+            return latched && e.timeStamp - lastEvent < timeoutMs;
+        },
+        // Forget the gesture state so the next event is treated as a fresh gesture.
+        // Called when the pointer leaves the panel: a gesture the browser has
+        // latched to this element must not keep the page suppressed once the cursor
+        // is elsewhere.
+        reset() {
+            lastEvent = -Infinity;
+            latched = false;
+        },
+    };
+}

package/esm/util/selectEncodedFeature.d.ts

@@ -0,0 +1,16 @@
+import type { createAbortRotation } from './createAbortRotation.ts';
+import type { CoreGetEncodedLayersArgs } from './markEncodingTypes.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api
+ * Open the feature widget on the feature behind one instance of a
+ * `CoreGetEncodedLayers` answer. A display holds channels, not records, so it
+ * sends `CoreGetEncodedFeature` the request the instance's region came back
+ * under, and the worker answers the entry of `layer`'s list that the
+ * instance's `featureIndex` names: the record as the adapter wrote it, or the
+ * bin or run the steps made. A second click aborts the first.
+ */
+export declare function selectEncodedFeature(self: IStateTreeNode, rotation: ReturnType<typeof createAbortRotation>, args: Omit<CoreGetEncodedLayersArgs, 'byteLimit'> & {
+    layer: number;
+    featureIndex: number;
+}): void;

package/esm/util/selectEncodedFeature.js

@@ -0,0 +1,34 @@
+import { openFeatureWidget } from './openFeatureWidget.js';
+import { getRpcSessionId } from './parentWalk.js';
+import { getRpcHost } from './sessionServices.js';
+import SimpleFeature from './simpleFeature.js';
+import { withFeatureDetails } from './withFeatureDetails.js';
+/**
+ * #api
+ * Open the feature widget on the feature behind one instance of a
+ * `CoreGetEncodedLayers` answer. A display holds channels, not records, so it
+ * sends `CoreGetEncodedFeature` the request the instance's region came back
+ * under, and the worker answers the entry of `layer`'s list that the
+ * instance's `featureIndex` names: the record as the adapter wrote it, or the
+ * bin or run the steps made. A second click aborts the first.
+ */
+export function selectEncodedFeature(self, rotation, args) {
+    const fetch = rotation.begin();
+    void withFeatureDetails(self, async () => {
+        try {
+            const feature = await getRpcHost(self).rpcManager.call(getRpcSessionId(self), 'CoreGetEncodedFeature', {
+                ...args,
+                signal: fetch.signal,
+                statusCallback: fetch.statusCallback,
+            });
+            return feature && fetch.isCurrent()
+                ? new SimpleFeature(feature)
+                : undefined;
+        }
+        finally {
+            fetch.end();
+        }
+    }, feature => {
+        openFeatureWidget(self, feature.toJSON(), { feature });
+    });
+}

package/esm/util/selectNamedRegions.d.ts

@@ -0,0 +1,136 @@
+import type { Region } from './types/data.ts';
+/**
+ * Resolve caller-supplied region names against an assembly's own regions,
+ * preserving the requested order and dropping names that match nothing.
+ *
+ * An entry containing `*` is a glob matched against the refName, which is what
+ * makes a fragmented assembly tractable: a haplotype-resolved genome wants "all
+ * of hap1" (`*_hap1`), not a hand-maintained list of its 16 scaffolds that goes
+ * stale the moment the assembly is rebuilt. A glob contributes its matches in
+ * the ASSEMBLY's order (the only order it can mean); exact names contribute in
+ * the CALLER's order, so an explicit list still controls layout. Duplicates
+ * across entries are dropped, so `['chr1_hap1', '*_hap1']` is chr1 first then
+ * the rest.
+ *
+ * AN EXACT REFNAME BEATS THE GLOB READING, which is the only reason `*` is safe
+ * to hand a user as a syntax: `*` is a legal character in a real contig name and
+ * the names carrying it are the ones nobody would think to escape. GRCh38's ALT
+ * decoys are HLA allele names — `HLA-A*01:01:01:01` — so a pattern typed to name
+ * one allele was compiled to `^HLA-A.*01:01:01:01$`, which matches that contig
+ * (hence it looked fine) and every other HLA-A allele with the same last four
+ * fields. Trying the literal lookup first costs one Map hit and means a name
+ * that IS a contig always resolves to that contig; only a name matching nothing
+ * is reinterpreted as a pattern.
+ *
+ * Selecting from the assembly's own region objects (rather than synthesizing
+ * them) keeps coordinates and lengths correct.
+ *
+ * THERE IS DELIBERATELY NO CEILING on how many regions a glob may resolve to.
+ * `["*"]` on a scaffold-level assembly really does mean every contig, which is
+ * no more than `showAllRegionsInAssembly` already hands to `setDisplayedRegions`.
+ * A cap here could only truncate — silently returning some of what was asked
+ * for, which is the failure mode this file keeps being fixed for. The search
+ * box's picker does bound its bulk-select row, and that is a different thing: it
+ * withholds an OFFER, leaving every match still pickable one at a time, rather
+ * than quietly resolving a list to a prefix of itself.
+ *
+ * BOTH READINGS GO THROUGH THE ASSEMBLY'S ALIASES, and they have to, because
+ * only one of them used to. An exact name has always resolved via
+ * `getCanonicalRefName`, so `['chr1']` picks out a contig an Ensembl-named
+ * assembly calls `1` — but the glob was tested against `region.refName`, the
+ * canonical name alone, so `['chr*']` on that same assembly matched nothing at
+ * all. The literal working where the pattern silently fails is the worst
+ * possible split: the caller has no way to tell "this assembly has no such
+ * contigs" from "globs don't see the names you're using". Pass `allRefNames`
+ * (canonical names AND aliases — `buildRefNameMaps` identity-maps every region,
+ * so it is a strict superset) and a pattern sees what a literal sees.
+ *
+ * It is optional ONLY because this is published ABI and the three-argument form
+ * predates it; an external plugin still calling that gets the canonical-only
+ * matching it always got. It is not optional because there is a state where an
+ * assembly has regions but not yet names — `setLoaded` writes `volatileRegions`
+ * and `refNameAliases` in one action, so no such state exists, and every
+ * in-tree caller (all of them through `resolveNamedRegions`) passes both.
+ */
+export declare function selectNamedRegions(regions: readonly Region[], names: readonly string[], getCanonicalRefName: (name: string) => string | undefined, allRefNames?: readonly string[]): Region[];
+/**
+ * Split a user-typed or URL-supplied region list into the entries
+ * `selectNamedRegions` takes. Comma-separated, because the two things anyone
+ * writes here are one glob (`*_MATERNAL`) or a short explicit list
+ * (`chr1, chr2`), and neither wants punctuation ceremony. Only the comma
+ * splits, so an HLA allele name — which carries both `*` and `:` — survives
+ * intact.
+ *
+ * Whitespace-trimmed and empties dropped, so a trailing comma, a box holding
+ * only spaces, and a bare `&regions=` all mean the same thing as nothing at
+ * all: no restriction, whole assembly. That last one is why this lives in core
+ * beside the matcher rather than next to the text box that first needed it —
+ * `&regions=` was reading the same syntax through a bare `split(',')`, so
+ * `&regions=chr1,%20chr2` dropped chr2 on the floor without a word and
+ * `&regions=` warned that a list of one empty name had matched nothing.
+ */
+export declare function parseRegionNames(value: string): string[];
+/**
+ * `selectNamedRegions` plus the report a miss owes the user, which each of the
+ * four views taking `displayedRegionNames` had written out for itself — and two
+ * of them had not written at all, so a typo there showed the whole assembly and
+ * read as the field being ignored. A typo is no longer only a hand-authored-JSON
+ * mistake either: the dotplot and synteny import forms put this syntax in a text
+ * box.
+ *
+ * `undefined` means "this list picks out nothing" — the caller's cue to apply
+ * its own fallback, which is the part that genuinely differs between them: the
+ * LGV keeps a defaultSession's existing navigation, the circular view and a
+ * synteny row draw the whole assembly, and a dotplot axis is left as the
+ * regions autorun populated it.
+ */
+export declare function resolveNamedRegions({ regions, names, assemblyName, getCanonicalRefName, allRefNames, notify, }: {
+    regions: readonly Region[];
+    names: readonly string[];
+    assemblyName: string;
+    getCanonicalRefName: (name: string) => string | undefined;
+    allRefNames?: readonly string[];
+    notify: (message: string) => void;
+}): Region[] | undefined;
+export interface RefNameMatchSource {
+    regions?: readonly {
+        refName: string;
+    }[];
+    allRefNames?: readonly string[];
+    getCanonicalRefName: (name: string) => string | undefined;
+}
+/**
+ * How many regions an INTERACTIVE glob will open at once. Displaying a few
+ * hundred whole chromosomes is ordinary — GRCh38 with its alts and decoys is
+ * ~640 refNames, and showAllRegionsInAssembly lays out every one — so this sits
+ * well above any real chromosome set and well below a scaffold-level assembly's
+ * contig count. Past it the offer is WITHHELD, never truncated: a bulk action
+ * reading "all of them" that opens the first thousand is the one behaviour not
+ * worth having.
+ *
+ * `selectNamedRegions` itself is deliberately unbounded — see its docstring.
+ * The bound belongs to the surfaces a person types at, not to the resolver a
+ * session spec goes through, because only the former has a way to say "too
+ * many, narrow it" and only the latter is a written-down intention.
+ */
+export declare const MAX_GLOB_REGIONS = 1000;
+/**
+ * The canonical refNames a search-box query picks out, in ASSEMBLY order.
+ *
+ * Shared by the dropdown's option list and by what Enter does, which is the
+ * whole point of it being one function: those two answer for the same typed
+ * text, and a surface-by-surface reading of one syntax is the split this file
+ * keeps being fixed for. A substring match (what the box has always done) and,
+ * when the text contains `*`, an anchored glob — union, never one instead of
+ * the other, since `*` is a legal refName character and a literal hit must
+ * survive the pattern reading of the same text.
+ *
+ * Matching runs over every name the assembly answers to, aliases included, and
+ * resolves hits to the canonical name — the name the view will display, and the
+ * same choice `searchRefNames` makes. Emitting by walking `regions` is what
+ * keeps assembly order rather than alias-file order.
+ *
+ * Bounded: matching stops one hit past `ceiling`, so a caller can tell "at the
+ * limit" from "under it" without the scan being unbounded.
+ */
+export declare function matchRefNames(assembly: RefNameMatchSource | undefined, inputValue: string, ceiling: number): string[];

package/esm/util/selectNamedRegions.js

@@ -0,0 +1,222 @@
+/**
+ * `*` is the only metacharacter; everything else in a name is matched literally,
+ * so a refName containing regex punctuation (`chr1.1`, `scaffold[2]`) can't turn
+ * into an accidental pattern. Anchored, so a pattern names whole refNames.
+ *
+ * Case-INSENSITIVE, and not optionally: the literal reading beside it resolves
+ * through getCanonicalRefName, which falls back to `lowerCaseRefNameAliases`, so
+ * `CHR1` has always found `chr1`. A case-sensitive glob meant `CHR1*` found
+ * nothing on the same assembly — literal working where pattern silently fails,
+ * which is the same split the alias fix removed and is no more tellable apart
+ * from "this assembly has no such contigs" here than it was there. No caller
+ * wants the other behaviour, so it is baked in rather than passed.
+ *
+ * Module-private, and worth keeping that way: both readings of `*` — the
+ * resolver's and the search box's — live in this file precisely so a pattern
+ * that selects a set in a session spec selects the same set typed into the box.
+ * A third caller reaching in from elsewhere is how that stops being true.
+ */
+function globToRegExp(pattern) {
+    const escaped = pattern.replaceAll(/[.*+?^${}()|[\]\\]/g, m => m === '*' ? '.*' : `\\${m}`);
+    return new RegExp(`^${escaped}$`, 'i');
+}
+/**
+ * Resolve caller-supplied region names against an assembly's own regions,
+ * preserving the requested order and dropping names that match nothing.
+ *
+ * An entry containing `*` is a glob matched against the refName, which is what
+ * makes a fragmented assembly tractable: a haplotype-resolved genome wants "all
+ * of hap1" (`*_hap1`), not a hand-maintained list of its 16 scaffolds that goes
+ * stale the moment the assembly is rebuilt. A glob contributes its matches in
+ * the ASSEMBLY's order (the only order it can mean); exact names contribute in
+ * the CALLER's order, so an explicit list still controls layout. Duplicates
+ * across entries are dropped, so `['chr1_hap1', '*_hap1']` is chr1 first then
+ * the rest.
+ *
+ * AN EXACT REFNAME BEATS THE GLOB READING, which is the only reason `*` is safe
+ * to hand a user as a syntax: `*` is a legal character in a real contig name and
+ * the names carrying it are the ones nobody would think to escape. GRCh38's ALT
+ * decoys are HLA allele names — `HLA-A*01:01:01:01` — so a pattern typed to name
+ * one allele was compiled to `^HLA-A.*01:01:01:01$`, which matches that contig
+ * (hence it looked fine) and every other HLA-A allele with the same last four
+ * fields. Trying the literal lookup first costs one Map hit and means a name
+ * that IS a contig always resolves to that contig; only a name matching nothing
+ * is reinterpreted as a pattern.
+ *
+ * Selecting from the assembly's own region objects (rather than synthesizing
+ * them) keeps coordinates and lengths correct.
+ *
+ * THERE IS DELIBERATELY NO CEILING on how many regions a glob may resolve to.
+ * `["*"]` on a scaffold-level assembly really does mean every contig, which is
+ * no more than `showAllRegionsInAssembly` already hands to `setDisplayedRegions`.
+ * A cap here could only truncate — silently returning some of what was asked
+ * for, which is the failure mode this file keeps being fixed for. The search
+ * box's picker does bound its bulk-select row, and that is a different thing: it
+ * withholds an OFFER, leaving every match still pickable one at a time, rather
+ * than quietly resolving a list to a prefix of itself.
+ *
+ * BOTH READINGS GO THROUGH THE ASSEMBLY'S ALIASES, and they have to, because
+ * only one of them used to. An exact name has always resolved via
+ * `getCanonicalRefName`, so `['chr1']` picks out a contig an Ensembl-named
+ * assembly calls `1` — but the glob was tested against `region.refName`, the
+ * canonical name alone, so `['chr*']` on that same assembly matched nothing at
+ * all. The literal working where the pattern silently fails is the worst
+ * possible split: the caller has no way to tell "this assembly has no such
+ * contigs" from "globs don't see the names you're using". Pass `allRefNames`
+ * (canonical names AND aliases — `buildRefNameMaps` identity-maps every region,
+ * so it is a strict superset) and a pattern sees what a literal sees.
+ *
+ * It is optional ONLY because this is published ABI and the three-argument form
+ * predates it; an external plugin still calling that gets the canonical-only
+ * matching it always got. It is not optional because there is a state where an
+ * assembly has regions but not yet names — `setLoaded` writes `volatileRegions`
+ * and `refNameAliases` in one action, so no such state exists, and every
+ * in-tree caller (all of them through `resolveNamedRegions`) passes both.
+ */
+export function selectNamedRegions(regions, names, getCanonicalRefName, allRefNames) {
+    const byRefName = new Map(regions.map(r => [r.refName, r]));
+    // every name a glob may match on — see above for why the absent case is a
+    // legacy call rather than an unloaded assembly
+    const candidates = allRefNames?.length
+        ? allRefNames
+        : regions.map(r => r.refName);
+    const out = [];
+    const seen = new Set();
+    const take = (r) => {
+        if (r && !seen.has(r.refName)) {
+            seen.add(r.refName);
+            out.push(r);
+        }
+    };
+    for (const name of names) {
+        const exact = byRefName.get(getCanonicalRefName(name) ?? name);
+        if (exact) {
+            take(exact);
+        }
+        else if (name.includes('*')) {
+            const re = globToRegExp(name);
+            // Resolve every matching NAME to the region it names, then walk `regions`
+            // to emit them — the two passes are what keeps a glob's contribution in
+            // ASSEMBLY order. Matching over `candidates` directly would order by the
+            // alias map instead, which is the order the alias file happened to list.
+            const hits = new Set();
+            for (const candidate of candidates) {
+                if (re.test(candidate)) {
+                    hits.add(getCanonicalRefName(candidate) ?? candidate);
+                }
+            }
+            for (const r of regions) {
+                if (hits.has(r.refName)) {
+                    take(r);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Split a user-typed or URL-supplied region list into the entries
+ * `selectNamedRegions` takes. Comma-separated, because the two things anyone
+ * writes here are one glob (`*_MATERNAL`) or a short explicit list
+ * (`chr1, chr2`), and neither wants punctuation ceremony. Only the comma
+ * splits, so an HLA allele name — which carries both `*` and `:` — survives
+ * intact.
+ *
+ * Whitespace-trimmed and empties dropped, so a trailing comma, a box holding
+ * only spaces, and a bare `&regions=` all mean the same thing as nothing at
+ * all: no restriction, whole assembly. That last one is why this lives in core
+ * beside the matcher rather than next to the text box that first needed it —
+ * `&regions=` was reading the same syntax through a bare `split(',')`, so
+ * `&regions=chr1,%20chr2` dropped chr2 on the floor without a word and
+ * `&regions=` warned that a list of one empty name had matched nothing.
+ */
+export function parseRegionNames(value) {
+    return value
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s !== '');
+}
+/**
+ * `selectNamedRegions` plus the report a miss owes the user, which each of the
+ * four views taking `displayedRegionNames` had written out for itself — and two
+ * of them had not written at all, so a typo there showed the whole assembly and
+ * read as the field being ignored. A typo is no longer only a hand-authored-JSON
+ * mistake either: the dotplot and synteny import forms put this syntax in a text
+ * box.
+ *
+ * `undefined` means "this list picks out nothing" — the caller's cue to apply
+ * its own fallback, which is the part that genuinely differs between them: the
+ * LGV keeps a defaultSession's existing navigation, the circular view and a
+ * synteny row draw the whole assembly, and a dotplot axis is left as the
+ * regions autorun populated it.
+ */
+export function resolveNamedRegions({ regions, names, assemblyName, getCanonicalRefName, allRefNames, notify, }) {
+    const picked = selectNamedRegions(regions, names, getCanonicalRefName, allRefNames);
+    if (picked.length) {
+        return picked;
+    }
+    notify(`displayedRegionNames matched no regions in ${assemblyName}: ${names.join(', ')}`);
+    return undefined;
+}
+/**
+ * How many regions an INTERACTIVE glob will open at once. Displaying a few
+ * hundred whole chromosomes is ordinary — GRCh38 with its alts and decoys is
+ * ~640 refNames, and showAllRegionsInAssembly lays out every one — so this sits
+ * well above any real chromosome set and well below a scaffold-level assembly's
+ * contig count. Past it the offer is WITHHELD, never truncated: a bulk action
+ * reading "all of them" that opens the first thousand is the one behaviour not
+ * worth having.
+ *
+ * `selectNamedRegions` itself is deliberately unbounded — see its docstring.
+ * The bound belongs to the surfaces a person types at, not to the resolver a
+ * session spec goes through, because only the former has a way to say "too
+ * many, narrow it" and only the latter is a written-down intention.
+ */
+export const MAX_GLOB_REGIONS = 1000;
+/**
+ * The canonical refNames a search-box query picks out, in ASSEMBLY order.
+ *
+ * Shared by the dropdown's option list and by what Enter does, which is the
+ * whole point of it being one function: those two answer for the same typed
+ * text, and a surface-by-surface reading of one syntax is the split this file
+ * keeps being fixed for. A substring match (what the box has always done) and,
+ * when the text contains `*`, an anchored glob — union, never one instead of
+ * the other, since `*` is a legal refName character and a literal hit must
+ * survive the pattern reading of the same text.
+ *
+ * Matching runs over every name the assembly answers to, aliases included, and
+ * resolves hits to the canonical name — the name the view will display, and the
+ * same choice `searchRefNames` makes. Emitting by walking `regions` is what
+ * keeps assembly order rather than alias-file order.
+ *
+ * Bounded: matching stops one hit past `ceiling`, so a caller can tell "at the
+ * limit" from "under it" without the scan being unbounded.
+ */
+export function matchRefNames(assembly, inputValue, ceiling) {
+    const regions = assembly?.regions ?? [];
+    const query = inputValue.toLowerCase();
+    const glob = query.includes('*') ? globToRegExp(query) : undefined;
+    // getCanonicalRefName THROWS before aliases load, and is only ever reached
+    // for a name that came out of this list, which is empty in that state
+    const candidates = assembly?.allRefNames ?? [];
+    const hits = new Set();
+    for (const name of candidates) {
+        if (name.toLowerCase().includes(query) || glob?.test(name)) {
+            hits.add(assembly?.getCanonicalRefName(name) ?? name);
+            if (hits.size > ceiling) {
+                break;
+            }
+        }
+    }
+    const out = [];
+    for (const { refName } of regions) {
+        if (hits.has(refName)) {
+            out.push(refName);
+            // every hit is placed, so nothing later in `regions` can match
+            if (out.length === hits.size) {
+                break;
+            }
+        }
+    }
+    return out;
+}

package/esm/util/seqUtils.d.ts

@@ -0,0 +1,17 @@
+export declare const complementTable: Record<string, string>;
+export declare function revcom(str: string): string;
+export declare function reverse(str: string): string;
+export declare function complement(str: string): string;
+export type Frame = 1 | 2 | 3 | -1 | -2 | -3;
+export declare function getFrame(start: number, end: number, strand: 1 | -1, phase: 0 | 1 | 2): Frame;
+/**
+ * The start codon the sequence track highlights. Deliberately NOT
+ * `getGeneticCode(1).starts`, which is `['TTG','CTG','ATG']` — NCBI marks the
+ * alternative initiators, but highlighting every TTG and CTG in a reference
+ * sequence would be noise. This is a display convention, not the genetic code.
+ */
+export declare const defaultStarts: string[];
+export declare function stitch(subfeats: {
+    start: number;
+    end: number;
+}[], sequence: string): string;

package/esm/util/seqUtils.js

@@ -0,0 +1,80 @@
+// from bioperl: tr/acgtrymkswhbvdnxACGTRYMKSWHBVDNX/tgcayrkmswdvbhnxTGCAYRKMSWDVBHNX/
+// generated with:
+// perl -MJSON -E '@l = split "","acgtrymkswhbvdnxACGTRYMKSWHBVDNX"; print to_json({ map { my $in = $_; tr/acgtrymkswhbvdnxACGTRYMKSWHBVDNX/tgcayrkmswdvbhnxTGCAYRKMSWDVBHNX/; $in => $_ } @l})'
+export const complementTable = {
+    S: 'S',
+    w: 'w',
+    T: 'A',
+    r: 'y',
+    a: 't',
+    N: 'N',
+    K: 'M',
+    x: 'x',
+    d: 'h',
+    Y: 'R',
+    V: 'B',
+    y: 'r',
+    M: 'K',
+    h: 'd',
+    k: 'm',
+    C: 'G',
+    g: 'c',
+    t: 'a',
+    A: 'T',
+    n: 'n',
+    W: 'W',
+    X: 'X',
+    m: 'k',
+    v: 'b',
+    B: 'V',
+    s: 's',
+    H: 'D',
+    c: 'g',
+    D: 'H',
+    b: 'v',
+    R: 'Y',
+    G: 'C',
+};
+export function revcom(str) {
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const c = str[n - 1 - i];
+        arr[i] = complementTable[c] ?? c;
+    }
+    return arr.join('');
+}
+export function reverse(str) {
+    // index loop rather than [...str] spread: sequences can be large and the
+    // spread's code-point iterator is markedly slower than raw UTF-16 access
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        arr[i] = str[n - 1 - i];
+    }
+    return arr.join('');
+}
+export function complement(str) {
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const c = str[i];
+        arr[i] = complementTable[c] ?? c;
+    }
+    return arr.join('');
+}
+export function getFrame(start, end, strand, phase) {
+    return strand === 1
+        ? (((start + phase) % 3) + 1)
+        : (-1 * ((end - phase) % 3) - 1);
+}
+/**
+ * The start codon the sequence track highlights. Deliberately NOT
+ * `getGeneticCode(1).starts`, which is `['TTG','CTG','ATG']` — NCBI marks the
+ * alternative initiators, but highlighting every TTG and CTG in a reference
+ * sequence would be noise. This is a display convention, not the genetic code.
+ */
+export const defaultStarts = ['ATG'];
+export function stitch(subfeats, sequence) {
+    return subfeats.map(sub => sequence.slice(sub.start, sub.end)).join('');
+}

package/esm/util/sessionServices.d.ts

@@ -0,0 +1,29 @@
+import type { DialogHost, NotificationSink, PaletteHost, RpcHost, SessionServices } from './types/services.ts';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * The services a session offers that cost nothing application-shaped to name.
+ * Prefer one of the narrower accessors below, which say which of them the
+ * calling module actually uses.
+ */
+export declare function getSessionServices(node: IAnyStateTreeNode): SessionServices;
+/**
+ * #api core/util
+ * The host's RPC entry point, for a module that issues RPCs and nothing else.
+ */
+export declare function getRpcHost(node: IAnyStateTreeNode): RpcHost;
+/**
+ * #api core/util
+ * Where a display puts a message it cannot draw itself.
+ */
+export declare function getNotificationSink(node: IAnyStateTreeNode): NotificationSink;
+/**
+ * #api core/util
+ * Where a display puts a dialog it cannot mount itself.
+ */
+export declare function getDialogHost(node: IAnyStateTreeNode): DialogHost;
+/**
+ * #api core/util
+ * The colors to draw with, and the args that rebuild them in a worker.
+ */
+export declare function getPaletteHost(node: IAnyStateTreeNode): PaletteHost;