@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/range.d.ts

@@ -1,3 +1,48 @@
+/**
+ * fast low-level intersection of 2 coordinate ranges. assumes interbase coordinates.
+ *
+ * assumes `left <= right` for both ranges
+ *
+ * @returns array of [left, right], or [] if the ranges do not intersect. the choice of [] is because it allows destructuring array assignment without check for undefined return
+ */
 export declare function intersection2(left1: number, right1: number, left2: number, right2: number): [number, number] | [];
+/**
+ * Return whether 2 interbase coordinate ranges intersect.
+ *
+ * @param left1 -
+ * @param right1 -
+ * @param left2 -
+ * @param right2 -
+ *
+ * @returns true if the two ranges intersect
+ */
 export declare function doesIntersect2(left1: number, right1: number, left2: number, right2: number): boolean;
-export declare function isContainedWithin(left1: number, right1: number, left2: number, right2: number): boolean;
+/**
+ * Compute the expanded fetch range a tabix adapter must "redispatch" to when
+ * features found in a query extend past the requested window. Returns the union
+ * of the query with the bounds of every line `expands` admits, or `undefined`
+ * when nothing extends past the query (no redispatch needed).
+ *
+ * **A predicate, not a set of types**, because the useful question is not what a
+ * record is called. The bound exists to reach a record's *children*, so what
+ * disqualifies a record is having none — and in GFF3 that is answerable exactly,
+ * from whether the record carries an `ID` for a `Parent` to reference. A type
+ * blocklist can only ever approximate it, and it is the caller's format that
+ * knows how: this file reads no column but the coordinates.
+ *
+ * Feature coordinates arrive interbase, matching the query: @gmod/tabix applies
+ * the index's coordinate offset before invoking the line callback, so a GFF/GTF
+ * line's 1-based start is already decremented by the time it gets here.
+ *
+ * Seeding the accumulator with the query bounds is what makes the result a
+ * union rather than just the feature bounds. A redispatch narrower than the
+ * original window would drop an excluded line that the first fetch found inside
+ * the query but that falls outside the expanded range.
+ */
+export declare function calculateRedispatchRange<T extends {
+    start: number;
+    end: number;
+}>(features: T[], expands: (feature: T) => boolean, queryStart: number, queryEnd: number): {
+    start: number;
+    end: number;
+} | undefined;

package/esm/util/range.js

@@ -1,21 +1,87 @@
+/**
+ * fast low-level intersection of 2 coordinate ranges. assumes interbase coordinates.
+ *
+ * assumes `left <= right` for both ranges
+ *
+ * @returns array of [left, right], or [] if the ranges do not intersect. the choice of [] is because it allows destructuring array assignment without check for undefined return
+ */
 export function intersection2(left1, right1, left2, right2) {
+    // this code is verbose because "if" statements are faster than Math.min and Math.max
     if (right1 > left2 && left1 < right2 && right2 - left2 && right1 - left1) {
         if (left1 > left2) {
             if (right1 < right2) {
+                // 1     |-------|
+                //     |------------|
                 return [left1, right1];
             }
+            // 2         |----|
+            //      |------|
             return [left1, right2];
         }
         if (right1 < right2) {
+            // 3  |-----|
+            //       |------|
             return [left2, right1];
         }
+        // 4     |------------|
+        //         |-------|
         return [left2, right2];
     }
     return [];
 }
+/**
+ * Return whether 2 interbase coordinate ranges intersect.
+ *
+ * @param left1 -
+ * @param right1 -
+ * @param left2 -
+ * @param right2 -
+ *
+ * @returns true if the two ranges intersect
+ */
 export function doesIntersect2(left1, right1, left2, right2) {
     return right1 > left2 && left1 < right2;
 }
-export function isContainedWithin(left1, right1, left2, right2) {
-    return left2 <= left1 && right2 >= right1;
+/**
+ * Compute the expanded fetch range a tabix adapter must "redispatch" to when
+ * features found in a query extend past the requested window. Returns the union
+ * of the query with the bounds of every line `expands` admits, or `undefined`
+ * when nothing extends past the query (no redispatch needed).
+ *
+ * **A predicate, not a set of types**, because the useful question is not what a
+ * record is called. The bound exists to reach a record's *children*, so what
+ * disqualifies a record is having none — and in GFF3 that is answerable exactly,
+ * from whether the record carries an `ID` for a `Parent` to reference. A type
+ * blocklist can only ever approximate it, and it is the caller's format that
+ * knows how: this file reads no column but the coordinates.
+ *
+ * Feature coordinates arrive interbase, matching the query: @gmod/tabix applies
+ * the index's coordinate offset before invoking the line callback, so a GFF/GTF
+ * line's 1-based start is already decremented by the time it gets here.
+ *
+ * Seeding the accumulator with the query bounds is what makes the result a
+ * union rather than just the feature bounds. A redispatch narrower than the
+ * original window would drop an excluded line that the first fetch found inside
+ * the query but that falls outside the expanded range.
+ */
+export function calculateRedispatchRange(features, expands, queryStart, queryEnd) {
+    let minStart = queryStart;
+    let maxEnd = queryEnd;
+    // bounds first: only a line reaching past the current bound can widen it, so
+    // the predicate, which may scan the line's text, runs on those few lines and
+    // not on every line in the window
+    for (const feature of features) {
+        if ((feature.start < minStart || feature.end > maxEnd) &&
+            expands(feature)) {
+            if (feature.start < minStart) {
+                minStart = feature.start;
+            }
+            if (feature.end > maxEnd) {
+                maxEnd = feature.end;
+            }
+        }
+    }
+    return minStart < queryStart || maxEnd > queryEnd
+        ? { start: minStart, end: maxEnd }
+        : undefined;
 }

package/esm/util/renameRegions.d.ts

@@ -0,0 +1,21 @@
+import type { StatusCallback } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+import type { AssemblyManager, Region } from './types/index.ts';
+import type { Region as MUIRegion } from './types/mst.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function renameRegionIfNeeded(refNameMap: Record<string, string> | undefined, region: Region | Instance<typeof MUIRegion>, getSeqAdapterRefName?: (refName: string) => string): Region & {
+    originalRefName?: string;
+};
+export declare function renameRegionsIfNeeded<ARGTYPE extends {
+    assemblyName?: string;
+    regions?: Region[];
+    stopToken?: StopToken;
+    adapterConfig: Record<string, unknown>;
+    sessionId: string;
+    statusCallback?: StatusCallback;
+}>(assemblyManager: AssemblyManager, args: ARGTYPE): Promise<ARGTYPE & {
+    sequenceAdapter: Record<string, unknown> | undefined;
+    regions: (Region & {
+        originalRefName?: string;
+    })[];
+}>;

package/esm/util/renameRegions.js

@@ -0,0 +1,129 @@
+import { getSnapshot, isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { getSequenceAdapterConfig } from '../assemblyManager/getSequenceAdapterConfig.js';
+// Maps a region's refName to the track adapter's name (via refNameMap), and
+// sets originalRefName to the seq adapter (FASTA) name so that CRAM/BAM
+// adapters can fetch reference sequence correctly.
+//
+// This is DESTRUCTIVE, and it runs inside `serializeArguments` — so the array
+// that reaches a worker is not the one the display handed to `rpcManager.call`,
+// with no cue at the call site. `refName` means the assembly's canonical name
+// before this and the track adapter's name after, in the same field of the same
+// type. Renaming is required for anything the worker compares or fetches
+// against the file, and wrong for anything it hands back as user-facing text: a
+// worker that labels a locus from its own output must be given the view's names
+// separately, captured before the call (hic's `HicViewBlock` does this, because
+// its hover prints a locus directly under the ruler). `originalRefName` is NOT
+// that name — it is a third scheme, the FASTA's, load-bearing for CRAM/BAM
+// reference fetch.
+//
+// That third scheme is the general case in miniature, and worth naming: a
+// rename is a property of an (assembly, adapter) PAIR, and this renames against
+// exactly one adapter — `args.adapterConfig`. An RPC that reaches a SECOND file
+// gets no renaming for it, and the failure is silent in the usual way: the query
+// goes out under the first file's spelling, matches nothing, and reads as "no
+// data here". So an RPC naming two adapters needs two passes, not one.
+//
+// **Prefer giving the second file its own RPC**, where `adapterConfig` names the
+// file being read and the ordinary pass is simply right — MAF's annotation
+// overlay is called that way. Thread a second name only when the two results
+// cannot be joined by the caller: GWAS LD coloring can't, because the r²-to-
+// feature join is per feature and features never cross the boundary, so it
+// resolves a second pass in `serializeArguments` and ships `ldRefName`
+// (`plugins/gwas/src/ManhattanRPC/GetManhattanData.ts`). That and
+// `originalRefName` are the only two, and there is no reason to expect a third:
+// a sub-adapter is normally the same data in another form, named the same way.
+export function renameRegionIfNeeded(refNameMap, region, getSeqAdapterRefName) {
+    const isNode = isStateTreeNode(region);
+    if (isNode && !isAlive(region)) {
+        return region;
+    }
+    const newRef = refNameMap?.[region.refName];
+    if (newRef) {
+        return {
+            ...(isNode ? getSnapshot(region) : region),
+            refName: newRef,
+            originalRefName: getSeqAdapterRefName?.(region.refName) ?? region.refName,
+        };
+    }
+    return region;
+}
+// Region-shaped enough that, if it slipped through under a `region` key, it was
+// meant to be renamed. Used only by the guard below.
+function isRegionShaped(r) {
+    return (!!r &&
+        typeof r === 'object' &&
+        'refName' in r &&
+        'assemblyName' in r &&
+        'start' in r &&
+        'end' in r);
+}
+export async function renameRegionsIfNeeded(assemblyManager, args) {
+    const { regions = [], adapterConfig } = args;
+    if (!args.sessionId) {
+        throw new Error('sessionId is required');
+    }
+    // Renaming only ever touches the `regions` array. An RPC method that instead
+    // carries a singular `region` (e.g. by pairing a one-region wire contract
+    // with a *plural* rename base class) would silently fetch against un-renamed
+    // refNames — the exact bug where an assembly's `5` never maps to an adapter's
+    // `chr5`. The legitimate singular base class (RpcMethodTypeWithRenameRegion)
+    // always mirrors `region` into a populated `regions`, so flag only the
+    // un-mirrored case and fail loudly instead of returning wrong data.
+    if (regions.length === 0 &&
+        isRegionShaped(args.region)) {
+        throw new Error('renameRegionsIfNeeded got a singular `region` but no `regions` array; ' +
+            'refName renaming applies only to `regions`. Pass `regions: [region]` ' +
+            '(or extend RpcMethodTypeWithRenameRegion) so the region is renamed.');
+    }
+    // capture assembly names before the await, since MST regions may be dead after
+    const assemblyNames = regions.map(r => r.assemblyName);
+    const uniqueAssemblyNames = [...new Set(assemblyNames)];
+    // annotated, because Object.fromEntries over an array whose element type is
+    // not a tuple selects its `any` overload — which left refNameMap and
+    // getSeqAdapterRefName unchecked all the way to renameRegionIfNeeded
+    const assemblyData = Object.fromEntries(await Promise.all(uniqueAssemblyNames.map(async (name) => {
+        // resolve the assembly once via requireAssembly (which awaits both
+        // registration and load) and derive the refName map AND
+        // getSeqAdapterRefName from this single loaded handle. A synchronous
+        // assemblyManager.get() here could miss an assembly still being
+        // registered, leaving getSeqAdapterRefName undefined so
+        // originalRefName (used by CRAM/BAM to fetch reference bases) falls
+        // back to the canonical name instead of the FASTA name.
+        //
+        // require, not wait: a region names an assembly, so failing to
+        // resolve it is not "nothing to rename", it is renaming that cannot
+        // be done. Substituting an empty map leaves the adapter querying
+        // un-renamed refNames, which finds nothing and draws an empty track
+        // with no indication that the assembly is what is missing. Only an
+        // unnamed assembly is a legitimate no-op.
+        const assembly = name
+            ? await assemblyManager.requireAssembly(name)
+            : undefined;
+        return [
+            name,
+            {
+                refNameMap: assembly
+                    ? await assembly.getRefNameMapForAdapter(adapterConfig, args)
+                    : {},
+                getSeqAdapterRefName: assembly
+                    ? (r) => assembly.getSeqAdapterRefName(r)
+                    : undefined,
+                sequenceAdapter: getSequenceAdapterConfig(assembly),
+            },
+        ];
+    })));
+    return {
+        ...args,
+        // Supplied here, not by each caller: this is the one place that has already
+        // resolved the assembly a fetch is against, and it is the same handle
+        // `originalRefName` is a name into. Every caller that passed its own wrote
+        // these same two lines, and the three that forgot — `CoreGetExportData`,
+        // `BreakpointGetFeatures`, `fetchTrackData` — failed silently, saved only by
+        // whichever call happened to prime the adapter instance first.
+        sequenceAdapter: assemblyData[assemblyNames[0]]?.sequenceAdapter,
+        regions: regions.map((region, i) => {
+            const data = assemblyData[assemblyNames[i]];
+            return renameRegionIfNeeded(data?.refNameMap, region, data?.getSeqAdapterRefName);
+        }),
+    };
+}

package/esm/util/renderToStaticMarkup.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare function renderToStaticMarkup(node: React.ReactElement): string;

package/esm/util/renderToStaticMarkup.js

@@ -0,0 +1,50 @@
+import React from 'react';
+import createCache from '@emotion/cache';
+import { CacheProvider } from '@emotion/react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+// Deliberately not re-exported from the `util` barrel: it is the barrel's only
+// reason to pull react/react-dom/@emotion, and the barrel is imported by
+// worker-side adapter code that never renders.
+//
+// https://react.dev/reference/react-dom/server/renderToString#removing-rendertostring-from-the-client-code
+export function renderToStaticMarkup(node) {
+    const div = document.createElement('div');
+    // makeStyles components (via __unsafe_useEmotionCache) need an emotion cache
+    // in context. The browser has an ambient default cache, but node/jsdom (e.g.
+    // jbrowse-img) loads @emotion/react before `document` exists, so its default
+    // cache context is null — provide one explicitly here.
+    const cache = createCache({ key: 'css' });
+    const root = createRoot(div);
+    let html;
+    try {
+        // eslint-disable-next-line @eslint-react/dom-no-flush-sync
+        flushSync(() => {
+            root.render(React.createElement(CacheProvider, { value: cache }, node));
+        });
+        html = div.innerHTML;
+    }
+    finally {
+        // This is a *real* client root, not a server render: its effects run, so
+        // every `observer` in the tree ends up with a live MobX reaction. Leaving
+        // the root mounted therefore keeps the whole detached export tree — and an
+        // SVG export of a full view is tens of thousands of nodes — subscribed to
+        // the session's models for the rest of the session, re-rendering it into a
+        // dead <div> on every pan and zoom, once per export ever taken. Unmount
+        // once the markup is a string, which no longer depends on the DOM.
+        root.unmount();
+    }
+    // SVG 1.1 presentation attributes (`fill`, `stroke`) take a <color>, which
+    // does not include rgba() — alpha belongs in a separate fill-opacity /
+    // stroke-opacity. Illustrator and older Inkscape drop an element whose fill
+    // they cannot parse, so the alpha is stripped rather than left to break the
+    // whole shape. It is *dropped*, not converted, so a translucent color exports
+    // fully opaque: components that need transparency to survive set a separate
+    // opacity attribute instead (`CrossHatches`, `MultiWiggleOverlayLines`).
+    //
+    // Rewriting `fill="rgba(r,g,b,a)"` into `fill="rgb(r,g,b)" fill-opacity="a"`
+    // would preserve the appearance and let those two drop their workarounds, but
+    // it changes the pixels of every export carrying an rgba color, so it needs a
+    // visual pass before the snapshots are regenerated.
+    return html.replaceAll(/\brgba\((.+?),[^,]+?\)/g, 'rgb($1)');
+}

package/esm/util/reorder.d.ts

@@ -0,0 +1,35 @@
+export type ReorderDirection = 'up' | 'down' | 'top' | 'bottom';
+/**
+ * Move `idx` within the subsequence of `arr` that `inScope` selects, leaving
+ * every out-of-scope element where it sits.
+ *
+ * The scoped move: one list holds everything, but a move is only ever relative
+ * to a subset of it. "Move this view up" in a tabbed workspace means up past the
+ * previous view IN THIS PANEL, not past whatever happens to precede it in
+ * `session.views` — which may be in another panel entirely and would make the
+ * move look like a no-op.
+ *
+ * Implemented as a permutation of the in-scope positions: pull out the in-scope
+ * elements, reorder that list, then write it back into the same index slots.
+ * That is what keeps out-of-scope elements pinned, and what makes an unscoped
+ * move (everything in scope) exactly `reorder`.
+ */
+export declare function reorderWithin<T>(arr: readonly T[], idx: number, direction: ReorderDirection, inScope: (item: T, index: number) => boolean): T[];
+/**
+ * Move the element at `idx` within `arr` in the given direction, returning a new
+ * array. An edge move (already at top/bottom) returns an unchanged copy.
+ */
+export declare function reorder<T>(arr: readonly T[], idx: number, direction: ReorderDirection): T[];
+/**
+ * Put the elements whose id appears in `ids` into that relative order, leaving
+ * every other element in its own slot.
+ *
+ * The same slot permutation `reorderWithin` performs, driven by a stated order
+ * rather than by a direction. It exists because an order can arrive in another
+ * vocabulary entirely — a session spec's `layout` names views per panel, top to
+ * bottom — and there is one list that order has to land in.
+ *
+ * Elements named in `ids` but absent from `arr` are ignored, so a layout may
+ * name a view that failed to open.
+ */
+export declare function applyOrderWithin<T>(arr: readonly T[], ids: readonly string[], getId: (item: T) => string): T[];

package/esm/util/reorder.js

@@ -0,0 +1,83 @@
+/**
+ * Move `idx` within the subsequence of `arr` that `inScope` selects, leaving
+ * every out-of-scope element where it sits.
+ *
+ * The scoped move: one list holds everything, but a move is only ever relative
+ * to a subset of it. "Move this view up" in a tabbed workspace means up past the
+ * previous view IN THIS PANEL, not past whatever happens to precede it in
+ * `session.views` — which may be in another panel entirely and would make the
+ * move look like a no-op.
+ *
+ * Implemented as a permutation of the in-scope positions: pull out the in-scope
+ * elements, reorder that list, then write it back into the same index slots.
+ * That is what keeps out-of-scope elements pinned, and what makes an unscoped
+ * move (everything in scope) exactly `reorder`.
+ */
+export function reorderWithin(arr, idx, direction, inScope) {
+    const slots = [];
+    const scoped = [];
+    for (const [i, item] of arr.entries()) {
+        if (inScope(item, i)) {
+            slots.push(i);
+            scoped.push(item);
+        }
+    }
+    const scopedIdx = slots.indexOf(idx);
+    if (scopedIdx === -1) {
+        return [...arr];
+    }
+    const moved = reorder(scoped, scopedIdx, direction);
+    const next = [...arr];
+    for (const [i, slot] of slots.entries()) {
+        next[slot] = moved[i];
+    }
+    return next;
+}
+/**
+ * Move the element at `idx` within `arr` in the given direction, returning a new
+ * array. An edge move (already at top/bottom) returns an unchanged copy.
+ */
+export function reorder(arr, idx, direction) {
+    const next = [...arr];
+    if (idx >= 0 && idx < arr.length) {
+        const [item] = next.splice(idx, 1);
+        const target = direction === 'up'
+            ? Math.max(0, idx - 1)
+            : direction === 'down'
+                ? Math.min(arr.length - 1, idx + 1)
+                : direction === 'top'
+                    ? 0
+                    : arr.length - 1;
+        next.splice(target, 0, item);
+    }
+    return next;
+}
+/**
+ * Put the elements whose id appears in `ids` into that relative order, leaving
+ * every other element in its own slot.
+ *
+ * The same slot permutation `reorderWithin` performs, driven by a stated order
+ * rather than by a direction. It exists because an order can arrive in another
+ * vocabulary entirely — a session spec's `layout` names views per panel, top to
+ * bottom — and there is one list that order has to land in.
+ *
+ * Elements named in `ids` but absent from `arr` are ignored, so a layout may
+ * name a view that failed to open.
+ */
+export function applyOrderWithin(arr, ids, getId) {
+    const rank = new Map(ids.map((id, i) => [id, i]));
+    const slots = [];
+    for (const [i, item] of arr.entries()) {
+        if (rank.has(getId(item))) {
+            slots.push(i);
+        }
+    }
+    const ordered = slots
+        .map(i => arr[i])
+        .sort((a, b) => rank.get(getId(a)) - rank.get(getId(b)));
+    const next = [...arr];
+    for (const [i, slot] of slots.entries()) {
+        next[slot] = ordered[i];
+    }
+    return next;
+}

package/esm/util/resolveRowHeight.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve a multi-row display's raw `rowHeight` setting, where `0` is the
+ * fit-to-display-height sentinel, into the px height consumers actually draw
+ * with and divide by. The other half of the contract `applyRowResizeWheel` and
+ * tree-sidebar's `TreeDrawingModel` both spell `effectiveRowHeight` — see
+ * agent-docs/reference/ROW_HEIGHT_AND_FIT.md.
+ *
+ * Two rules, and they pull in opposite directions, which is why they live here
+ * rather than being restated per display:
+ *
+ * - **A sub-pixel fit height is legitimate and must pass through.** A cohort
+ *   with more rows than the display has pixels genuinely has a fractional row
+ *   height, and flooring it makes the content taller than the height it was
+ *   asked to fit inside — which re-grows the track and makes fit mode report a
+ *   scroll it is documented never to have. (2000 species floored to 1px re-grew
+ *   a MAF track to 2045px; the same regression hit the variant displays.) So
+ *   `autoRowHeight` itself is never floored.
+ * - **The resolved value must never be non-positive.** Consumers divide by it
+ *   (`rowAtY`, the hit tests, the renderers), so a `0` propagates NaN/Infinity.
+ *   A rows viewport can legitimately reach 0px — the variant matrix's
+ *   connector-line zone can swallow the whole display height — so this is
+ *   reachable, and it is the one place the floor belongs.
+ *
+ * Multi-wiggle is always-fit and has no sentinel to resolve, so it computes its
+ * `effectiveRowHeight` directly rather than calling this.
+ */
+export declare function resolveRowHeight(rowHeight: number, autoRowHeight: number): number;

package/esm/util/resolveRowHeight.js

@@ -0,0 +1,30 @@
+/**
+ * Resolve a multi-row display's raw `rowHeight` setting, where `0` is the
+ * fit-to-display-height sentinel, into the px height consumers actually draw
+ * with and divide by. The other half of the contract `applyRowResizeWheel` and
+ * tree-sidebar's `TreeDrawingModel` both spell `effectiveRowHeight` — see
+ * agent-docs/reference/ROW_HEIGHT_AND_FIT.md.
+ *
+ * Two rules, and they pull in opposite directions, which is why they live here
+ * rather than being restated per display:
+ *
+ * - **A sub-pixel fit height is legitimate and must pass through.** A cohort
+ *   with more rows than the display has pixels genuinely has a fractional row
+ *   height, and flooring it makes the content taller than the height it was
+ *   asked to fit inside — which re-grows the track and makes fit mode report a
+ *   scroll it is documented never to have. (2000 species floored to 1px re-grew
+ *   a MAF track to 2045px; the same regression hit the variant displays.) So
+ *   `autoRowHeight` itself is never floored.
+ * - **The resolved value must never be non-positive.** Consumers divide by it
+ *   (`rowAtY`, the hit tests, the renderers), so a `0` propagates NaN/Infinity.
+ *   A rows viewport can legitimately reach 0px — the variant matrix's
+ *   connector-line zone can swallow the whole display height — so this is
+ *   reachable, and it is the one place the floor belongs.
+ *
+ * Multi-wiggle is always-fit and has no sentinel to resolve, so it computes its
+ * `effectiveRowHeight` directly rather than calling this.
+ */
+export function resolveRowHeight(rowHeight, autoRowHeight) {
+    const height = rowHeight === 0 ? autoRowHeight : rowHeight;
+    return height > 0 ? height : 1;
+}

package/esm/util/revlist.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flip a list of intervals onto the opposite strand of a `seqlen`-long
+ * sequence, returning them in ascending order. Every field other than
+ * start/end is carried through, so a CDS keeps its phase and type.
+ *
+ * Its own module because both the sequence helpers and `geneticCodes` need it,
+ * and `geneticCodes` importing `seqUtils` for it is what made the two mutually
+ * dependent — see the codon-table note in geneticCodes.ts.
+ */
+export declare function revlist<T extends {
+    start: number;
+    end: number;
+}>(list: T[], seqlen: number): T[];

package/esm/util/revlist.js

@@ -0,0 +1,14 @@
+/**
+ * Flip a list of intervals onto the opposite strand of a `seqlen`-long
+ * sequence, returning them in ascending order. Every field other than
+ * start/end is carried through, so a CDS keeps its phase and type.
+ *
+ * Its own module because both the sequence helpers and `geneticCodes` need it,
+ * and `geneticCodes` importing `seqUtils` for it is what made the two mutually
+ * dependent — see the codon-table note in geneticCodes.ts.
+ */
+export function revlist(list, seqlen) {
+    return list
+        .map(sub => ({ ...sub, start: seqlen - sub.end, end: seqlen - sub.start }))
+        .sort((a, b) => a.start - b.start);
+}

package/esm/util/rowStackGeometry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Mouse-Y → row index for the displays that stack rows behind
+ * `useRowVirtualScroll`.
+ *
+ * That hook is what makes the arithmetic subtle, so the reader lives beside it.
+ * `applyRowResizeWheel` sets `scrollTop` to `rowUnderMouse * newRowHeight -
+ * mouseY` to pin the row under the cursor, which leaves it fractional, and it
+ * lets `rowHeight` fall to `viewportHeight / nrow` — sub-pixel on a
+ * cohort-sized track. Two rules follow, and each caller used to restate them:
+ *
+ * - **Ask at the pixel's centre.** Rasterization fills a pixel when its centre
+ *   falls inside the rect, so the centre is the scanline the colour the reader
+ *   is pointing at was decided on. The top edge misses by `0.5 / rowHeight`
+ *   rows — 5.4 of them on a 2,504-sample matrix at the default fit height.
+ * - **Floor `mouseY` before adding `scrollTop`.** The canvas draws at
+ *   `row * rowHeight - scrollTop` with `scrollTop` unrounded; flooring the sum
+ *   snaps to a pixel grid the content is not on. This is the half a reader gets
+ *   backwards.
+ */
+export interface RowStack {
+    /** resolved height, never the 0/fit sentinel — this is divided into */
+    rowHeight: number;
+    /** unrounded, and routinely fractional */
+    scrollTop?: number;
+    /** chrome above the rows area, e.g. MAF's stacked bands */
+    topOffset?: number;
+}
+/** Content-space Y of the centre of the screen pixel `mouseY` is in. */
+export declare function contentYAt(mouseY: number, stack: RowStack): number;
+/** Continuous row coordinate at `mouseY`; callers round to suit. */
+export declare function rowCoordAt(mouseY: number, stack: RowStack): number;
+/** The row `mouseY` is on. Negative above the rows area, and not range-checked. */
+export declare function rowIndexAt(mouseY: number, stack: RowStack): number;
+/**
+ * Half-open `[startRow, endRow)` covered by a vertical px span, ready to
+ * `slice` a sample list with.
+ *
+ * Both ends are the row at that pixel's centre and the range includes both, so
+ * a span can never come back empty: a drag straight across one row — which
+ * `useDragSelection` supports, gating on X alone — covers the row it is on.
+ * Taking `endRow` as the `ceil` of the same coordinate instead collapsed on
+ * every exact row boundary, one pixel row in every `rowHeight`.
+ */
+export declare function rowSpanAt(y0: number, y1: number, stack: RowStack): {
+    startRow: number;
+    endRow: number;
+};
+/**
+ * The rows whose *drawn* cell covers `mouseY`, nearest first.
+ *
+ * Row r occupies `[r*rowHeight, r*rowHeight + drawnRowHeight)`.
+ * `drawnRowHeight` is the height the painter *resolved* for this `rowHeight`,
+ * not the floor it clamps to — pass `drawnCellHeightPx(rowHeight)` from the
+ * module generated out of the display's own shader (ADR-051), so what is
+ * painted and what is pickable stay one rule. At `rowHeight` above the floor it
+ * equals `rowHeight`, the band collapses to `nearest`, and only sub-pixel rows
+ * stack several under one drawn pixel — where the last drawn wins, and
+ * `nearest` is it.
+ *
+ * Walking down to `lowest` keeps those rows hoverable when the nearest one has
+ * nothing to report.
+ */
+export declare function rowsUnderPointer(mouseY: number, stack: RowStack, drawnRowHeight: number): {
+    nearest: number;
+    lowest: number;
+};