@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/mstUtils.js

@@ -0,0 +1,122 @@
+import { getEnv as getEnvMST } from '@jbrowse/mobx-state-tree';
+import { cachedParent, findParentThatIs } from './parentWalk.js';
+import { isDisplayModel, isSessionModel, isTrackModel, isViewModel, } from './types/index.js';
+export { findParentThat, findParentThatIs, getRpcSessionId, } from './parentWalk.js';
+const containingDisplayCache = new WeakMap();
+const containingTrackCache = new WeakMap();
+const containingViewCache = new WeakMap();
+const sessionCache = new WeakMap();
+/**
+ * #api core/util
+ * Returns the JBrowse session model for any node in the state tree. Throws if
+ * the node has no session ancestor.
+ */
+export function getSession(node) {
+    return cachedParent(sessionCache, node, () => findParentThatIs(node, isSessionModel), 'no session model found!');
+}
+/**
+ * #api core/util
+ * Returns the view model that contains the given node. Throws if the node has no
+ * containing view.
+ */
+export function getContainingView(node) {
+    return cachedParent(containingViewCache, node, () => findParentThatIs(node, isViewModel), 'no containing view found');
+}
+/**
+ * #api core/util
+ * Returns the track model that contains the given node. Throws if the node has
+ * no containing track.
+ */
+export function getContainingTrack(node) {
+    return cachedParent(containingTrackCache, node, () => findParentThatIs(node, isTrackModel), 'no containing track found');
+}
+/**
+ * #api core/util
+ * Returns the display model that contains the given node. Throws if the node has
+ * no containing display.
+ */
+export function getContainingDisplay(node) {
+    return cachedParent(containingDisplayCache, node, () => findParentThatIs(node, isDisplayModel), 'no containing display found');
+}
+/**
+ * #api core/util
+ * The host's assembly manager, for a module that resolves names and nothing
+ * else.
+ *
+ * Unlike the accessors in `sessionServices.ts` this one buys the caller no
+ * smaller type graph — an `AssemblyManager` is an MST model a `PluginManager`
+ * built, so naming it costs what naming a session costs. It is here to say
+ * which service is wanted, and because that cost is the finding: the assembly
+ * manager is the one thing on `AbstractSessionModel` a third-party host cannot
+ * simply implement.
+ */
+export function getAssemblyHost(node) {
+    return getSession(node);
+}
+/**
+ * #api core/util
+ * Everything a display needs of its host in order to draw a region: the
+ * assemblies, the RPC entry point and the colors.
+ */
+export function getRenderingServices(node) {
+    return getSession(node);
+}
+/**
+ * #api core/util
+ * Resolve user-authored refName text against the assembly of the view
+ * containing `node` — the one normalization layer, which resolves aliases and
+ * casing together. Falls back to the input when the assembly is absent or its
+ * aliases have not loaded.
+ *
+ * Keyed off the VIEW's assembly rather than the track's, because the view is
+ * what the comparison is against: displayed regions, loaded regions and blocks
+ * all carry the refNames the view laid out.
+ *
+ * Reach for this wherever a refName a *person* wrote is about to be compared
+ * against regions, features or blocks, which carry the assembly's canonical
+ * name. A refName a display copied off a region is canonical already and needs
+ * nothing; one that arrived in a session spec, a config slot or a URL is
+ * whatever the author read out of the location box.
+ *
+ * Skipping it fails silently and, worse, assembly-dependently: `chr12` matches
+ * on an assembly canonicalized `chr12` and matches nothing on one canonicalized
+ * `12`, so the same spec key works on one config and quietly does nothing on
+ * the next, with no error for anyone to act on.
+ *
+ * Resolves through `getCanonicalRefName2`, whose fallback is what keeps a spec
+ * read before the alias file has loaded from throwing — and the getters that
+ * read user specs do run from the first render.
+ *
+ * Takes a refName, not a spec that might hold one: the resolver reads
+ * `refName.toLowerCase()`, so anything else throws once the aliases are there,
+ * and a caller reading an untyped `frozen` slot has to establish that it names
+ * a refName at all before this is the right question to ask of it.
+ */
+export function canonicalizeViewRefName(node, refName) {
+    const { assemblyManager } = getSession(node);
+    const name = getContainingView(node).assemblyNames?.[0];
+    const assembly = name ? assemblyManager.get(name) : undefined;
+    return assembly?.getCanonicalRefName2(refName) ?? refName;
+}
+/**
+ * #api core/util
+ * Returns the MST environment for a node, which carries the `pluginManager`.
+ */
+export function getEnv(obj) {
+    return getEnvMST(obj);
+}
+export function hashCode(str) {
+    let hash = 0;
+    if (str.length === 0) {
+        return hash;
+    }
+    for (let i = 0; i < str.length; i++) {
+        const chr = str.charCodeAt(i);
+        hash = (hash << 5) - hash + chr;
+        hash |= 0;
+    }
+    return hash;
+}
+export function objectHash(obj) {
+    return `${hashCode(JSON.stringify(obj))}`;
+}

package/esm/util/nanoid.d.ts

@@ -1,5 +1 @@
-export declare const urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
-export declare const random: (bytes: number) => Uint8Array<ArrayBuffer>;
-export declare const customRandom: (alphabet: string, defaultSize: number, getRandom: (bytes: number) => Uint8Array) => (size?: number) => string;
-export declare const customAlphabet: (alphabet: string, size?: number) => (size?: number) => string;
 export declare const nanoid: (size?: number) => string;

package/esm/util/nanoid.js

@@ -1,29 +1,19 @@
-export const urlAlphabet = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
-export const random = (bytes) => crypto.getRandomValues(new Uint8Array(bytes));
-export const customRandom = (alphabet, defaultSize, getRandom) => {
-    const mask = (2 << (Math.log(alphabet.length - 1) / Math.LN2)) - 1;
-    const step = -~((1.6 * mask * defaultSize) / alphabet.length);
-    return (size = defaultSize) => {
-        let id = '';
-        while (true) {
-            const bytes = getRandom(step);
-            let j = step;
-            while (j--) {
-                id += alphabet[bytes[j] & mask] || '';
-                if (id.length === size) {
-                    return id;
-                }
-            }
-        }
-    };
-};
-export const customAlphabet = (alphabet, size = 21) => customRandom(alphabet, size, random);
+// The web-crypto branch of nanoid (https://github.com/ai/nanoid, MIT), reduced
+// to the one generator we call. The custom-alphabet machinery was carried along
+// unused; restore it from upstream if a non-default alphabet is ever needed.
 export const nanoid = (size = 21) => crypto.getRandomValues(new Uint8Array(size)).reduce((id, byte) => {
+    // It is incorrect to use bytes exceeding the alphabet size.
+    // The following mask reduces the random byte in the 0-255 value
+    // range to the 0-63 value range. Therefore, adding hacks, such
+    // as empty string fallback or magic numbers, is unnecessary because
+    // the bitmask trims bytes down to the alphabet size.
     byte &= 63;
     if (byte < 36) {
+        // `0-9a-z`
         id += byte.toString(36);
     }
     else if (byte < 62) {
+        // `A-Z`
         id += (byte - 26).toString(36).toUpperCase();
     }
     else if (byte > 62) {

package/esm/util/numericUtils.d.ts

@@ -0,0 +1,20 @@
+export declare function clamp(num: number, min: number, max: number): number;
+export declare function minmax(a: number, b: number): readonly [number, number];
+export declare function max(arr: ArrayLike<number>, init?: number): number;
+export declare function maxFinite(arr: ArrayLike<number>, init?: number): number;
+export declare function min(arr: ArrayLike<number>, init?: number): number;
+export declare function sum(arr: ArrayLike<number>): number;
+export declare function avg(arr: ArrayLike<number>): number;
+export declare function setNumberGrouping(enabled: boolean): void;
+export declare function getNumberGrouping(): boolean;
+export declare function toLocale(n: number): string;
+export declare function toPrecision(s: number, n?: number): number;
+export declare function reducePrecision(s: number, n?: number): string;
+/**
+ * A byte count as a person reads it. Shared by the region-too-large banner and
+ * the save-track-data dialog, which quote the same index estimate and would
+ * otherwise word the same number two ways.
+ */
+export declare function getDisplayStr(totalBytes: number): string;
+export declare function radToDeg(radians: number): number;
+export declare function polarToCartesian(rho: number, theta: number): [number, number];

package/esm/util/numericUtils.js

@@ -0,0 +1,127 @@
+export function clamp(num, min, max) {
+    if (num < min) {
+        return min;
+    }
+    if (num > max) {
+        return max;
+    }
+    return num;
+}
+export function minmax(a, b) {
+    return [Math.min(a, b), Math.max(a, b)];
+}
+// Index iteration so these accept both arrays and typed arrays (e.g.
+// Float32Array) without requiring Iterable.
+export function max(arr, init = Number.NEGATIVE_INFINITY) {
+    let max = init;
+    for (let i = 0; i < arr.length; i++) {
+        max = Math.max(arr[i], max);
+    }
+    return max;
+}
+// Like max() but skips NaN/Infinity entries rather than propagating them (a
+// single NaN poisons Math.max). Used where an array can legitimately carry
+// gaps, e.g. a score series with unmeasured bins in it.
+export function maxFinite(arr, init = Number.NEGATIVE_INFINITY) {
+    let max = init;
+    for (let i = 0; i < arr.length; i++) {
+        const v = arr[i];
+        if (Number.isFinite(v) && v > max) {
+            max = v;
+        }
+    }
+    return max;
+}
+export function min(arr, init = Number.POSITIVE_INFINITY) {
+    let min = init;
+    for (let i = 0; i < arr.length; i++) {
+        min = Math.min(arr[i], min);
+    }
+    return min;
+}
+export function sum(arr) {
+    let sum = 0;
+    for (let i = 0; i < arr.length; i++) {
+        sum += arr[i];
+    }
+    return sum;
+}
+export function avg(arr) {
+    return sum(arr) / arr.length;
+}
+// Thousand separators are a display convention, not part of the number. They
+// make a coordinate readable, but they survive a copy-paste into tools that
+// then choke on them, so users who copy coordinates out of the app more than
+// they read them can turn them off (the `numberGrouping` preference).
+//
+// A plain variable rather than an observable, because every number the app
+// displays funnels through here — including strings built worker-side, where a
+// jexl `mouseover` slot formats a tooltip against the full feature. A
+// main-thread-only reactive value would leave those stale, so the app would sit
+// half-formatted until every track refetched. Instead each realm sets this once
+// at startup (the worker gets it in its boot configuration, see RpcManager) and
+// the preference asks for a reload, which buys uniformity for one page load.
+let numberGrouping = true;
+export function setNumberGrouping(enabled) {
+    numberGrouping = enabled;
+}
+// read when handing the setting to another realm; not a display path
+export function getNumberGrouping() {
+    return numberGrouping;
+}
+// Fast number formatter with thousand separators.
+// Benchmarked at 5-67x faster than toLocaleString('en-US')
+export function toLocale(n) {
+    const abs = Math.abs(n);
+    // `!(abs >= 1000)` also covers NaN, which has no digits to group, and
+    // String() switches to exponential form at 1e21 and for Infinity, where a
+    // thousands separator is meaningless
+    if (!numberGrouping || !(abs >= 1000) || abs >= 1e21) {
+        return String(n);
+    }
+    const str = String(abs);
+    // separators count from the decimal point, not the end of the string
+    const intLen = Number.isInteger(abs) ? str.length : str.indexOf('.');
+    let result = n < 0 ? '-' : '';
+    for (let i = 0; i < intLen; i++) {
+        if (i > 0 && (intLen - i) % 3 === 0) {
+            result += ',';
+        }
+        result += str[i];
+    }
+    return intLen === str.length ? result : result + str.slice(intLen);
+}
+// numeric significant-figure rounding; reducePrecision is the formatted form
+export function toPrecision(s, n = 3) {
+    return Number.parseFloat(s.toPrecision(n));
+}
+export function reducePrecision(s, n = 3) {
+    return toLocale(toPrecision(s, n));
+}
+/**
+ * A byte count as a person reads it. Shared by the region-too-large banner and
+ * the save-track-data dialog, which quote the same index estimate and would
+ * otherwise word the same number two ways.
+ */
+export function getDisplayStr(totalBytes) {
+    // pick the unit from the rounded value so e.g. 999,999 bytes reads "1 Mb"
+    // rather than "1000 Kb"
+    const mb = toPrecision(totalBytes / 1_000_000);
+    const kb = toPrecision(totalBytes / 1000);
+    if (mb >= 1) {
+        return `${mb} Mb`;
+    }
+    else if (kb >= 1) {
+        return `${kb} Kb`;
+    }
+    else {
+        return `${Math.floor(totalBytes)} bytes`;
+    }
+}
+const oneEightyOverPi = 180 / Math.PI;
+export function radToDeg(radians) {
+    return (radians * oneEightyOverPi) % 360;
+}
+export function polarToCartesian(rho, theta) {
+    return [rho * Math.cos(theta), rho * Math.sin(theta)];
+}

package/esm/util/objectUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function isObject(x: unknown): x is Record<string | symbol | number, unknown>;
+export declare function isPlainObject(x: unknown): x is Record<string, unknown>;

package/esm/util/objectUtils.js

@@ -0,0 +1,9 @@
+// MIT https://github.com/inspect-js/is-object
+export function isObject(x) {
+    return typeof x === 'object' && x !== null;
+}
+// `isObject` minus arrays: the branch `deepEqual` and `deepMerge` recurse into
+// key by key, as opposed to the one they walk by index.
+export function isPlainObject(x) {
+    return isObject(x) && !Array.isArray(x);
+}

package/esm/util/offscreenCanvasPonyfill.d.ts

@@ -1,5 +1,6 @@
-export { collectTransferables, isDetachedBuffer } from './transferables.ts';
-export declare function isImageBitmap(value: unknown): value is 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 declare function drawImageOntoCanvasContext(imageData: any, context: CanvasRenderingContext2D): void;
-export declare function createCanvas(width: number, height: number): any;
-export declare function createImageBitmap(canvas: any): Promise<unknown>;

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;