@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/offscreenCanvasPonyfill.js

@@ -1,9 +1,9 @@
 import { CanvasSequence } from 'canvas-sequencer-ts';
-import isNode from 'detect-node';
-export { collectTransferables, isDetachedBuffer } from "./transferables.js";
-export function isImageBitmap(value) {
-    return typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap;
-}
+/**
+ * Paint a worker-produced image onto a 2d context: either a real
+ * ImageBitmap/canvas, or the serialized canvas-sequencer command list a worker
+ * without OffscreenCanvas sends instead.
+ */
 export function drawImageOntoCanvasContext(imageData, context) {
     if (imageData.serializedCommands) {
         const seq = new CanvasSequence(imageData.serializedCommands);
@@ -13,45 +13,3 @@ export function drawImageOntoCanvasContext(imageData, context) {
         context.drawImage(imageData, 0, 0);
     }
 }
-export function createCanvas(width, height) {
-    if (typeof OffscreenCanvas === 'function') {
-        return new OffscreenCanvas(width, height);
-    }
-    else if (isNode) {
-        return nodeCreateCanvas(width, height);
-    }
-    else {
-        const context = new CanvasSequence();
-        return {
-            width,
-            height,
-            getContext() {
-                return context;
-            },
-        };
-    }
-}
-export async function createImageBitmap(canvas) {
-    if (typeof OffscreenCanvas === 'function') {
-        return canvas.transferToImageBitmap();
-    }
-    else if (isNode) {
-        const dataUri = canvas.toDataURL();
-        const img = new nodeImage();
-        return new Promise((resolve, reject) => {
-            img.onload = () => {
-                resolve(img);
-            };
-            img.onerror = reject;
-            img.src = dataUri;
-        });
-    }
-    else {
-        const ctx = canvas.getContext('2d');
-        return {
-            height: canvas.height,
-            width: canvas.width,
-            serializedCommands: ctx.toJSON(),
-        };
-    }
-}

package/esm/util/openDisplays.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvableDisplay } from '../configuration/promotableResolve.ts';
+import type { AbstractSessionModel } from './types/index.ts';
+/**
+ * #api core/util
+ * Every display on an open track, across all open views — the reach of anything
+ * that acts on "the tracks the user is looking at": a promoted default's "apply
+ * to open tracks", and the share/export bake. One walk so those can't drift
+ * apart.
+ *
+ * Recurses into composite views. A display nested in one resolves the cascade
+ * like any other but was invisible to both callers, so the share/export bake
+ * didn't bake its inherited values and a shared session containing a
+ * breakpoint-split or synteny view rendered differently for the recipient.
+ * `LGVSyntenyDisplay` is only ever reached through this branch, so don't flatten
+ * the recursion away. `hasChildViews` names the one composite shape it does not
+ * cover.
+ *
+ * A view holding neither (e.g. spreadsheet) drops out via the structural guards.
+ * A view whose displays declare no promotable slot (e.g. dotplot, which does
+ * hold tracks) is walked and contributes nothing — harmless, and cheaper than
+ * asking each display whether it has anything to promote.
+ */
+export declare function openPromotableDisplays(session: AbstractSessionModel): ResolvableDisplay[];

package/esm/util/openDisplays.js

@@ -0,0 +1,79 @@
+/**
+ * @module
+ * One walk of "every display on an open track, across all open views".
+ *
+ * Lives here rather than in `configuration/promotableDefaults.ts`, where it grew:
+ * nothing about it is a cascade concern — it answers "the tracks the user is
+ * looking at", and its two callers want that for different reasons (the promoted
+ * default's "apply to open tracks", and `product-core`'s share/export bake). It
+ * cannot move next to either one: `product-core` imports `@jbrowse/core`, never
+ * the reverse.
+ *
+ * The displays are typed `ResolvableDisplay` because both callers immediately
+ * resolve config off them, and that shape (`IStateTreeNode` + `type` +
+ * `configuration`) is the smallest thing either needs.
+ */
+import { isObject } from './objectUtils.js';
+import { isViewContainer } from './types/index.js';
+// A view whose open tracks we can enumerate. The generic view interface doesn't
+// surface `tracks`, so narrow structurally — the declared display shape is the
+// same ResolvableDisplay the cascade already operates on.
+//
+// Checks the elements, not just that `tracks` is an array: this narrowing is
+// what every consumer downstream trusts, and an element without `displays`
+// would put `undefined` in the walk and throw at the first `display.type` —
+// inside a share/export bake, i.e. as far from the cause as it gets. Every
+// `tracks`-bearing view today holds real track models, so this only ever
+// confirms what is already true.
+function hasOpenTracks(view) {
+    return ('tracks' in view &&
+        Array.isArray(view.tracks) &&
+        view.tracks.every(t => isObject(t) && Array.isArray(t.displays)));
+}
+// A composite view holding child views in a `views` array: breakpoint-split and
+// the linear-comparative family incl. synteny. Not exclusive with
+// `hasOpenTracks`: LinearComparativeView has both its own synteny tracks and two
+// child LGVs.
+//
+// A view that holds its children under *named* props instead (SvInspectorView's
+// `spreadsheetView`/`circularView`) is NOT reached. Enumerating a view's own
+// properties to find them isn't an option — reading every key of an MST node
+// invokes every computed view on it, several of which throw before the view is
+// initialized. No display reachable that way declares a promotable slot today,
+// so nothing is currently missed; if one ever does, give that view a `views`
+// getter returning its children rather than duck-typing harder here.
+function hasChildViews(view) {
+    return ('views' in view &&
+        Array.isArray(view.views) &&
+        view.views.every(v => typeof v === 'object' && v !== null));
+}
+function displaysInView(view) {
+    return [
+        ...(hasOpenTracks(view) ? view.tracks.flatMap(t => t.displays) : []),
+        ...(hasChildViews(view) ? view.views.flatMap(displaysInView) : []),
+    ];
+}
+/**
+ * #api core/util
+ * Every display on an open track, across all open views — the reach of anything
+ * that acts on "the tracks the user is looking at": a promoted default's "apply
+ * to open tracks", and the share/export bake. One walk so those can't drift
+ * apart.
+ *
+ * Recurses into composite views. A display nested in one resolves the cascade
+ * like any other but was invisible to both callers, so the share/export bake
+ * didn't bake its inherited values and a shared session containing a
+ * breakpoint-split or synteny view rendered differently for the recipient.
+ * `LGVSyntenyDisplay` is only ever reached through this branch, so don't flatten
+ * the recursion away. `hasChildViews` names the one composite shape it does not
+ * cover.
+ *
+ * A view holding neither (e.g. spreadsheet) drops out via the structural guards.
+ * A view whose displays declare no promotable slot (e.g. dotplot, which does
+ * hold tracks) is walked and contributes nothing — harmless, and cheaper than
+ * asking each display whether it has anything to promote.
+ */
+export function openPromotableDisplays(session) {
+    const views = isViewContainer(session) ? session.views : [];
+    return views.flatMap(displaysInView);
+}

package/esm/util/openFeatureWidget.d.ts

@@ -0,0 +1,33 @@
+import type { Feature, SimpleFeatureSerialized } from './simpleFeature.ts';
+import type { Widget } from './types/index.ts';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface FeatureWidgetTypeRef {
+    type: string;
+    id: string;
+}
+export declare function openFeatureWidget(node: IAnyStateTreeNode, featureData: SimpleFeatureSerialized, opts?: {
+    widget?: FeatureWidgetTypeRef;
+    extra?: Record<string, unknown>;
+    feature?: Feature;
+}): Widget | undefined;
+/**
+ * The other half of the flow above: the details lookup came back with nothing,
+ * so there is no widget to open.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on click, so a lookup can come back empty for reasons the user cannot see —
+ * the data was evicted under them, or the id does not compare in the tier that
+ * answered. **Silently doing nothing is the worst response to a click**, and it
+ * was what three canvas paths did.
+ *
+ * Here rather than per plugin because the sentence is one fact and the two
+ * families would otherwise word it differently for the same event. It is
+ * deliberately NOT what an *error* says: a throw already reaches `notifyError`
+ * with the reason, and a display that notifies both tells the user off twice for
+ * one click.
+ *
+ * A **speculative** lookup must not call this — alignments pre-warms the read
+ * behind a context menu, and the user asked for nothing there, so the menu just
+ * doesn't grow its feature items.
+ */
+export declare function notifyFeatureDetailsMiss(node: IAnyStateTreeNode): void;

package/esm/util/openFeatureWidget.js

@@ -0,0 +1,64 @@
+// straight from mstUtils rather than the barrel, which re-exports this module:
+// a value import of './index.ts' from a module the barrel re-exports is the
+// cycle shape that bites under Rollup (TDZ) and babel/CJS (getter before
+// require) alike
+import { getContainingTrack, getContainingView, getSession, } from './mstUtils.js';
+import { getNotificationSink } from './sessionServices.js';
+import SimpleFeature from './simpleFeature.js';
+import { isSessionModelWithWidgets } from './types/index.js';
+const DEFAULT_FEATURE_WIDGET = {
+    type: 'BaseFeatureWidget',
+    id: 'baseFeature',
+};
+// Open a feature widget for the given featureData and mark it as the
+// session's selected feature. Node is any MST node in the display tree —
+// used to resolve session + containing view + containing track. Returns
+// the new widget, or undefined if the session can't host widgets (e.g.
+// headless export contexts).
+//
+// This consolidates the addWidget/showWidget/setSelection/getContainingView/
+// getContainingTrack/isSessionModelWithWidgets boilerplate that every
+// "click a feature → open details" flow had to repeat. setSelection is
+// always called so cross-view selection-sync features work uniformly —
+// callers previously split on this, which was likely accidental (the
+// non-BaseLinearDisplay-composers had hand-rolled selectFeature actions
+// and just omitted it).
+export function openFeatureWidget(node, featureData, opts = {}) {
+    const session = getSession(node);
+    if (!isSessionModelWithWidgets(session)) {
+        return undefined;
+    }
+    session.setSelection(opts.feature ?? new SimpleFeature(featureData));
+    const { type, id } = opts.widget ?? DEFAULT_FEATURE_WIDGET;
+    const widget = session.addWidget(type, id, {
+        featureData,
+        view: getContainingView(node),
+        track: getContainingTrack(node),
+        ...opts.extra,
+    });
+    session.showWidget(widget);
+    return widget;
+}
+/**
+ * The other half of the flow above: the details lookup came back with nothing,
+ * so there is no widget to open.
+ *
+ * Every display paints from slim render arrays and re-fetches the whole feature
+ * on click, so a lookup can come back empty for reasons the user cannot see —
+ * the data was evicted under them, or the id does not compare in the tier that
+ * answered. **Silently doing nothing is the worst response to a click**, and it
+ * was what three canvas paths did.
+ *
+ * Here rather than per plugin because the sentence is one fact and the two
+ * families would otherwise word it differently for the same event. It is
+ * deliberately NOT what an *error* says: a throw already reaches `notifyError`
+ * with the reason, and a display that notifies both tells the user off twice for
+ * one click.
+ *
+ * A **speculative** lookup must not call this — alignments pre-warms the read
+ * behind a context menu, and the user asked for nothing there, so the menu just
+ * doesn't grow its feature items.
+ */
+export function notifyFeatureDetailsMiss(node) {
+    getNotificationSink(node).notify('Could not load details for this feature', 'warning');
+}

package/esm/util/paintLayer.d.ts

@@ -0,0 +1,32 @@
+import { SvgCanvas } from './SvgCanvas.ts';
+import type { SvgRasterCanvasOpts } from './createSvgRasterCanvas.ts';
+import type React from 'react';
+export type Ctx2D = CanvasRenderingContext2D | SvgCanvas;
+export type PaintLayerOpts = SvgRasterCanvasOpts & {
+    rasterizeLayers?: boolean;
+};
+/**
+ * Paint into either a 2× rasterize canvas (PNG-embedded as <image>) or an
+ * SvgCanvas (serialized into a <g>). Renders one element — callers don't
+ * branch on which mode was picked.
+ *
+ * Used by every renderSvg.tsx that has a heavy draw path: the same `paint`
+ * callback runs on both surfaces, with `paint(ctx)` doing whatever drawing
+ * the plugin needs in logical coordinates (the raster canvas is pre-scaled, so
+ * callbacks never deal with devicePixelRatio). Width 0 or height 0 falls
+ * through to the vector branch (canvas creation rejects 0×0).
+ *
+ * A vector layer whose `paint` drew nothing renders nothing — not an empty
+ * `<g>`. Layers are routinely conditional on data (a highlight pass with no
+ * highlighted feature, a legend-less track, a band that is switched off), and
+ * every such layer was leaving a stray group in the file for a reader to open
+ * and find empty. The raster branch has no cheap equivalent — asking whether a
+ * canvas is blank means reading its pixels back — and it does not need one: a
+ * fully transparent PNG is a couple of hundred bytes.
+ */
+export declare function PaintLayer({ width, height, opts, paint, }: {
+    width: number;
+    height: number;
+    opts?: PaintLayerOpts;
+    paint: (ctx: Ctx2D) => void;
+}): React.ReactNode;

package/esm/util/paintLayer.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SvgCanvas } from './SvgCanvas.js';
+import { createSvgRasterCanvas } from './createSvgRasterCanvas.js';
+/**
+ * Paint into either a 2× rasterize canvas (PNG-embedded as <image>) or an
+ * SvgCanvas (serialized into a <g>). Renders one element — callers don't
+ * branch on which mode was picked.
+ *
+ * Used by every renderSvg.tsx that has a heavy draw path: the same `paint`
+ * callback runs on both surfaces, with `paint(ctx)` doing whatever drawing
+ * the plugin needs in logical coordinates (the raster canvas is pre-scaled, so
+ * callbacks never deal with devicePixelRatio). Width 0 or height 0 falls
+ * through to the vector branch (canvas creation rejects 0×0).
+ *
+ * A vector layer whose `paint` drew nothing renders nothing — not an empty
+ * `<g>`. Layers are routinely conditional on data (a highlight pass with no
+ * highlighted feature, a legend-less track, a band that is switched off), and
+ * every such layer was leaving a stray group in the file for a reader to open
+ * and find empty. The raster branch has no cheap equivalent — asking whether a
+ * canvas is blank means reading its pixels back — and it does not need one: a
+ * fully transparent PNG is a couple of hundred bytes.
+ */
+export function PaintLayer({ width, height, opts, paint, }) {
+    if (opts?.rasterizeLayers && width > 0 && height > 0) {
+        const { canvas, ctx } = createSvgRasterCanvas(width, height, opts);
+        paint(ctx);
+        return (_jsx("image", { width: width, height: height, xlinkHref: canvas.toDataURL('image/png') }));
+    }
+    const svg = new SvgCanvas();
+    paint(svg);
+    const markup = svg.getSerializedSvg();
+    return markup ? (_jsx("g", { dangerouslySetInnerHTML: { __html: markup } })) : null;
+}

package/esm/util/parentWalk.d.ts

@@ -0,0 +1,32 @@
+import type { TypeTestedByPredicate } from './types/predicate.ts';
+import type { IAnyStateTreeNode, IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export declare function findParentThat(node: IAnyStateTreeNode, predicate: (thing: IAnyStateTreeNode) => boolean): IStateTreeNode<IAnyStateTreeNode> | (object & IStateTreeNode<import("@jbrowse/mobx-state-tree").IAnyComplexType>);
+export declare function findParentThatIs<T extends (a: IAnyStateTreeNode) => boolean>(node: IAnyStateTreeNode, predicate: T): TypeTestedByPredicate<T>;
+/**
+ * Memoized ancestor lookups, and load-bearing ones: `getSession` alone has 465
+ * call sites and is reached from render paths, while the walk it replaces is
+ * six `getParent` hops — every MST array between a display and the session is a
+ * node of its own. Worth 13.6-17.6x, and 3.2-3.7x even inside a reaction
+ * (`packages/core/benches/parentWalkMemo.bench.ts`, which also rules out the
+ * obvious alternative: the predicate's `in` checks are ~1% of the walk, so
+ * making it cheaper buys nothing).
+ *
+ * Keying on the node is safe because nothing re-parents one — both `detach`
+ * call sites hand the node straight to `scheduleDetachedDestroy` (ADR-069), so
+ * a cached ancestor can only go stale by dying, which the `isAlive` check
+ * catches. That is the difference from the three memos REJECTED_IDEAS records
+ * removing: each keyed on something its caller had just allocated.
+ */
+export declare function cachedParent<T>(cache: WeakMap<IAnyStateTreeNode, T>, node: IAnyStateTreeNode, finder: () => T, errorMsg: string): T;
+/**
+ * The `rpcSessionId` of the highest node at or above `thisNode` that declares
+ * one — which webworker its work is routed to.
+ *
+ * The walk includes the root. It used to stop *before* it (`!isRoot(node)` as
+ * the loop condition), which silently made a tree whose only rpcSessionId-
+ * bearing node was the root throw "no parent node in the state tree has an
+ * `rpcSessionId`". Nothing in the app hit that — the id lives on a track, deep
+ * in the tree — but a test building a minimal session had to wrap it in a
+ * throwaway root purely to dodge this.
+ */
+export declare function getRpcSessionId(thisNode: IAnyStateTreeNode): string;

package/esm/util/parentWalk.js

@@ -0,0 +1,84 @@
+import { getParent, hasParent, isAlive, isRoot } from '@jbrowse/mobx-state-tree';
+// The ancestor walk itself, with no application in its type graph.
+// `mstUtils.ts` is where the walks that return an `AbstractSessionModel` live
+// and is therefore as expensive to import as the session interface;
+// `sessionServices.ts` gets the same primitives without paying for that.
+export function findParentThat(node, predicate) {
+    if (!hasParent(node)) {
+        const alive = isAlive(node);
+        const nodeType = node.type;
+        console.warn(`[findParentThat] node has no parent: alive=${alive} type=${nodeType}`);
+        throw new Error('node does not have parent');
+    }
+    let currentNode = getParent(node);
+    while (isAlive(currentNode)) {
+        if (predicate(currentNode)) {
+            return currentNode;
+        }
+        if (hasParent(currentNode)) {
+            currentNode = getParent(currentNode);
+        }
+        else {
+            break;
+        }
+    }
+    throw new Error('no matching node found');
+}
+export function findParentThatIs(node, predicate) {
+    return findParentThat(node, predicate);
+}
+/**
+ * Memoized ancestor lookups, and load-bearing ones: `getSession` alone has 465
+ * call sites and is reached from render paths, while the walk it replaces is
+ * six `getParent` hops — every MST array between a display and the session is a
+ * node of its own. Worth 13.6-17.6x, and 3.2-3.7x even inside a reaction
+ * (`packages/core/benches/parentWalkMemo.bench.ts`, which also rules out the
+ * obvious alternative: the predicate's `in` checks are ~1% of the walk, so
+ * making it cheaper buys nothing).
+ *
+ * Keying on the node is safe because nothing re-parents one — both `detach`
+ * call sites hand the node straight to `scheduleDetachedDestroy` (ADR-069), so
+ * a cached ancestor can only go stale by dying, which the `isAlive` check
+ * catches. That is the difference from the three memos REJECTED_IDEAS records
+ * removing: each keyed on something its caller had just allocated.
+ */
+export function cachedParent(cache, node, finder, errorMsg) {
+    const cached = cache.get(node);
+    if (cached && isAlive(cached)) {
+        return cached;
+    }
+    try {
+        const result = finder();
+        cache.set(node, result);
+        return result;
+    }
+    catch (e) {
+        throw new Error(errorMsg, { cause: e });
+    }
+}
+/**
+ * The `rpcSessionId` of the highest node at or above `thisNode` that declares
+ * one — which webworker its work is routed to.
+ *
+ * The walk includes the root. It used to stop *before* it (`!isRoot(node)` as
+ * the loop condition), which silently made a tree whose only rpcSessionId-
+ * bearing node was the root throw "no parent node in the state tree has an
+ * `rpcSessionId`". Nothing in the app hit that — the id lives on a track, deep
+ * in the tree — but a test building a minimal session had to wrap it in a
+ * throwaway root purely to dodge this.
+ */
+export function getRpcSessionId(thisNode) {
+    let highestRpcSessionId;
+    for (let node = thisNode;; node = getParent(node)) {
+        if ('rpcSessionId' in node) {
+            highestRpcSessionId = node.rpcSessionId;
+        }
+        if (isRoot(node)) {
+            break;
+        }
+    }
+    if (!highestRpcSessionId) {
+        throw new Error('getRpcSessionId failed, no parent node in the state tree has an `rpcSessionId` attribute');
+    }
+    return highestRpcSessionId;
+}

package/esm/util/parseLineByLine.d.ts

@@ -1,3 +1,46 @@
-export type StatusCallback = (arg: string) => void;
+import { IntervalTree } from './IntervalTree.ts';
+import type { StatusCallback } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+export type { StatusCallback };
 export type LineCallback = (line: string, lineIndex: number) => boolean | undefined;
-export declare function parseLineByLine(buffer: Uint8Array, lineCallback: LineCallback, statusCallback?: StatusCallback): void;
+/**
+ * Scan a tab-delimited genomic flat file (GFF3, GTF, BED, …), grouping
+ * feature lines by reference name (first tab-delimited column).
+ * Stops at an embedded FASTA section (`>`). Lines starting with `#` are
+ * collected as header lines.
+ */
+export declare function groupLinesByRef(buffer: Uint8Array, statusCallback?: StatusCallback): {
+    headerLines: string[];
+    linesByRef: Record<string, string[]>;
+};
+/**
+ * Build a `refName -> lazy IntervalTree` map from feature lines grouped by ref
+ * (the output of {@link groupLinesByRef}). Each ref's lines are parsed and
+ * indexed into an interval tree on first access, then the raw lines are
+ * released. Shared scaffolding for the plain-text GFF3 and GTF adapters, which
+ * differ only in how they parse a ref's lines into features.
+ */
+export declare function makeFeatureIntervalTreeMap<T extends {
+    start: number;
+    end: number;
+}>(linesByRef: Record<string, string[]>, parse: (lines: string[], refName: string) => T[], parsingStatusMessage: string): {
+    [k: string]: (statusCallback?: StatusCallback) => IntervalTree<T>;
+};
+/**
+ * Parse buffer line by line, calling a callback for each line
+ * @param buffer - The buffer to parse
+ * @param lineCallback - Callback function called for each line. Return false to stop parsing.
+ * @param statusCallback - Progress channel, or `undefined` for none. A required
+ *   parameter with a nullable value rather than an optional one, so a caller
+ *   states which it means; `undefined` is the value the rest of this module's
+ *   contract is built on ("no channel, skip the bookkeeping"), and it used to
+ *   default to `() => {}`, which says the opposite.
+ * @param opts - `label` names the phase on the progress bar (a multi-phase
+ *   adapter wants "Parsing PAF", not another "Loading" indistinguishable from
+ *   the download that preceded it); `stopToken` makes a multi-GB parse
+ *   interruptible instead of running to completion after a cancel.
+ */
+export declare function parseLineByLine(buffer: Uint8Array, lineCallback: LineCallback, statusCallback: StatusCallback | undefined, opts?: {
+    label?: string;
+    stopToken?: StopToken;
+}): void;