@jbrowse/render-core 4.3.0

package/esm/RenderLifecycleMixin.js

@@ -0,0 +1,279 @@
+import { types } from '@jbrowse/mobx-state-tree';
+import { namedAutorun } from './namedReactions.js';
+/**
+ * Owns the GPU draw lifecycle for any display that paints to a canvas.
+ *
+ * Plugins compose this mixin (directly or via `MultiRegionDisplayMixin` /
+ * `GlobalFetchMixin`) and call
+ * `self.attachRenderingBackend(backend, () => ({ upload, render }))` from their
+ * own `startRenderingBackend(backend)` action. **The second argument is a thunk
+ * because it runs exactly once**, on the first attach: `startRenderingBackend`
+ * fires again on every context-loss recovery, and the autoruns keep the
+ * callbacks they were given first. Anything the callbacks close over — an
+ * upload sync's memo of what it last sent — is built inside it, so it lives as
+ * long as the callbacks that read it rather than being allocated per recovery
+ * and discarded. The mixin owns:
+ *
+ *  - `canvasDrawn` — observable flag read by test-selector `data-testid` attributes to detect first paint.
+ *  - `currentRenderingBackend` — the backend reference, updated on context-loss
+ *    recovery. Autoruns read it each tick so they re-fire against the new
+ *    one without being reinstalled.
+ *  - `renderTick` — counter the render autorun observes; bumped by
+ *    `renderNow()` (tab-visibility restore) and after every upload
+ *    (ensures render re-fires when an upload happens but renderState
+ *    identity stays stable).
+ *  - `autorunsInstalled` — guards `attachRenderingBackend` so the autorun
+ *    pair is spawned once per model instance, not once per backend
+ *    assignment.
+ *
+ * The `upload` callback runs in one autorun, `render` in another. Inside
+ * each, every observable read is auto-tracked by MobX — no getter-layer
+ * indirection, no multi-entry config. `render` returns `true` when the
+ * backend actually painted content (flips `canvasDrawn`), `false` to skip
+ * this tick (e.g. `renderState` not yet computed or no regions loaded).
+ *
+ * #stateModel RenderLifecycleMixin
+ * #category display
+ * @see RenderLifecycleMixin.test.ts for the upload/render autorun behavior
+ */
+export function RenderLifecycleMixin() {
+    return types
+        .model('RenderLifecycle', {})
+        .volatile(() => ({
+        /**
+         * #volatile
+         * flips true on first paint; read by test selectors to detect render
+         */
+        canvasDrawn: false,
+        /**
+         * #volatile
+         * current backend reference, updated on context-loss recovery.
+         * Typed `unknown` (not generic `B`) on purpose: this mixin is composed
+         * by every display via a non-generic factory, so the per-display backend
+         * type `B` isn't known here — it's supplied at `attachRenderingBackend<B>`
+         * and narrowed with `as B` inside the autoruns. Don't "fix" the cast.
+         */
+        currentRenderingBackend: undefined,
+        /**
+         * #volatile
+         * counter the render autorun observes; bumped to force a re-render
+         */
+        renderTick: 0,
+        /**
+         * #volatile
+         * guards attachRenderingBackend so the autorun pair spawns once per instance
+         */
+        autorunsInstalled: false,
+        /**
+         * #volatile
+         * the render-backend (GPU/Canvas2D init or context-loss) error, or
+         * undefined. Single source of truth for the render-error terminal state:
+         * `useRenderingBackend` writes it from the canvas-init mechanism so the
+         * model — not React-local hook state — owns every terminal state. Read by
+         * `displayPhase` (whose `renderError` term outranks `loading`, suppressing
+         * the scrim) and by `DisplayChrome` (shows the retry overlay).
+         */
+        renderError: undefined,
+    }))
+        .views(() => ({
+        /**
+         * #getter
+         * Overridable precondition (default true): both lifecycle autoruns skip
+         * their callback entirely while this is false, so a display never has to
+         * open its own `upload`/`render` with a readiness check.
+         *
+         * The LGV mixins override it with `view.initialized`, because before the
+         * view is measured its geometry throws by design (`view.width`, and so
+         * `visibleRegions` / `trackWidthPx` with it) and a throw in either callback
+         * is routed to `renderError` — surfacing "not measured yet" as the GPU
+         * render-error banner. Because it's an observable read inside the autoruns,
+         * the pair re-fires the moment it flips. This is the *precondition* axis
+         * only: whether any data has arrived stays the render callback's own gate
+         * (return `false` to skip a tick), which is why `renderState` getters can
+         * be plain resolved values.
+         */
+        get canRender() {
+            return true;
+        },
+        /**
+         * #getter
+         * Overridable hook (default true): whether this display paints a canvas
+         * in its **current** configuration, as opposed to a deliberate static
+         * placeholder (LD with the triangle off, sequence past base resolution —
+         * both render a message where the `<canvas>` would go, so `canvasRef` is
+         * never called and `canvasDrawn` can never flip).
+         *
+         * Lives here, beside `canvasDrawn`, because every consumer of "has this
+         * display painted" needs the pair — and until 2026-08 each family
+         * declared its own copy (per-region hard-coded `true`, global carried the
+         * hook for LD), so a display could express the state only to whichever
+         * family it happened to compose. See `painted` below for the reader that
+         * was missed.
+         */
+        get rendersCanvas() {
+            return true;
+        },
+        /**
+         * #getter
+         * Overridable hook (default false): the display has reached a state it
+         * will not paint its way out of, so `painted` below should answer
+         * *finished* rather than *pending*. Both LGV fetch families fill it with
+         * `!!error` — a fetch that failed before first paint keeps its canvas
+         * mounted, since the error bar is an overlay rather than a subtree
+         * replacement, so nothing ever draws into it. Named for `fetchInert` on
+         * the comparative side.
+         *
+         * A hook rather than a read of `error` here, for two reasons that both
+         * bite: this package is a leaf and `error` belongs to the fetch mixins,
+         * and declaring that name here would *collide* with `FetchMixin`'s
+         * volatile — `types.compose` gives the collision to its later argument,
+         * and the two families compose the two mixins in opposite orders.
+         */
+        get paintInert() {
+            return false;
+        },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * **The first-paint answer every consumer outside the display should
+         * read**, `canvasDrawn` being only the raw flag: a display that is
+         * deliberately not painting a canvas has finished, and saying otherwise
+         * is a lie that never resolves.
+         *
+         * The two `rendersCanvas: false` states each had three of their four
+         * consumers wired by hand — the loading scrim (`rendersCanvas` /
+         * `fetchInert`) and the SVG export (`fetchInert`) —
+         * while the fourth, `data-display-drawn`, went on publishing `"false"`
+         * forever off the raw flag. That attribute is what `PENDING_DISPLAYS`
+         * (`@jbrowse/browser-test-utils`) selects on, so a zoomed-out reference
+         * sequence track made every `waitForDisplaysDone` on the page burn its
+         * full timeout — silently, since that wait swallows its own. Same shape
+         * as `fetchInert` on the comparative side: the reader you forget is the
+         * one outside the display, so the display has to publish one name for it.
+         *
+         * `paintInert` is the third term and the same argument once more, for the
+         * state where a display *would* paint a canvas and never gets to — a fetch
+         * that failed before first paint. See that hook.
+         */
+        get painted() {
+            return self.canvasDrawn || !self.rendersCanvas || self.paintInert;
+        },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         */
+        markCanvasDrawn() {
+            if (!self.canvasDrawn) {
+                self.canvasDrawn = true;
+            }
+        },
+        /**
+         * #action
+         */
+        resetCanvasDrawn() {
+            if (self.canvasDrawn) {
+                self.canvasDrawn = false;
+            }
+        },
+        /**
+         * #action
+         */
+        stopRenderingBackend() {
+            self.currentRenderingBackend = undefined;
+            self.canvasDrawn = false;
+        },
+        /**
+         * #action
+         */
+        renderNow() {
+            self.renderTick += 1;
+        },
+        /**
+         * #action
+         * set/clear the render-backend error. Called by `useRenderingBackend`:
+         * with the error when the canvas factory rejects (or context-loss
+         * re-init fails), and with `undefined` on successful (re)init and on
+         * retry.
+         */
+        setRenderError(error) {
+            // Reference-identity guard, not value-equality: the render catch passes
+            // a fresh Error object per throw, so a repeatedly-failing render still
+            // reassigns each time (cosmetic MST churn). Harmless — nothing reads
+            // renderError inside a hot autorun — but the guard does dedupe the
+            // common set-then-clear-with-same-value (undefined) transitions.
+            if (self.renderError !== error) {
+                self.renderError = error;
+            }
+        },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * attach a GPU/Canvas2D backend and install the upload + render autorun
+         * pair. Idempotent: re-calling swaps the backend and does not run `setup`
+         * again, so the callbacks and everything they close over are the first
+         * call's.
+         */
+        attachRenderingBackend(backend, setup) {
+            self.currentRenderingBackend = backend;
+            if (self.autorunsInstalled) {
+                return;
+            }
+            // Before the flag, so a throw in `setup` leaves the display
+            // un-installed and the next backend can try again.
+            const cbs = setup();
+            self.autorunsInstalled = true;
+            namedAutorun(self, () => {
+                const b = self.currentRenderingBackend;
+                if (b === undefined || !self.canRender) {
+                    return;
+                }
+                // A throw in the upload callback (malformed worker data, a bad
+                // buffer-packing edge case) is routed to `renderError` for the
+                // same reason as the render autorun below: an uncaught reaction
+                // error would skip `renderNow()`, never flip `canvasDrawn`, and
+                // strand the display on 'loading' forever with no retry. For
+                // DisplayChrome consumers setting `renderError` unmounts the
+                // canvas and disposes the backend, so this can't re-fire into a
+                // loop; a shared-canvas consumer (dotplot, synteny) keeps the
+                // canvas mounted through an error (ADR-025), so there the only
+                // pacing is that autoruns re-fire on dep changes — a
+                // deterministically-throwing callback re-throws once per change,
+                // each landing on `setRenderError`'s identity guard.
+                try {
+                    if (cbs.upload(b)) {
+                        self.renderNow();
+                    }
+                }
+                catch (e) {
+                    self.setRenderError(e);
+                }
+            }, { name: 'RenderLifecycle:upload' });
+            namedAutorun(self, () => {
+                const b = self.currentRenderingBackend;
+                void self.renderTick;
+                if (b === undefined || !self.canRender) {
+                    return;
+                }
+                // A throw in the render callback (e.g. an invalid render-state
+                // input like an empty rendering type) would otherwise escape as
+                // an uncaught reaction error and leave the display stuck on
+                // "loading" forever. Route it to `renderError` so it surfaces as
+                // the render-error overlay (with the message + retry) instead.
+                // Same loop caveat as the upload autorun above: the
+                // unmount-and-dispose that prevents re-fire is DisplayChrome's,
+                // not a shared canvas's.
+                try {
+                    if (cbs.render(b)) {
+                        self.markCanvasDrawn();
+                    }
+                }
+                catch (e) {
+                    self.setRenderError(e);
+                }
+            }, { name: 'RenderLifecycle:render' });
+        },
+    }));
+}

package/esm/ScrollLockedOverlay.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+/**
+ * DOM overlay layer for a display that scrolls a fixed GPU canvas virtually (a
+ * `VerticalScrollbar` overlay + `useVirtualScrollWheel`, everything positioned
+ * from `model.scrollTop`).
+ *
+ * The GPU canvas paints glyphs at `y - model.scrollTop`. Any DOM overlay
+ * (labels, highlights, hover boxes) that annotates those glyphs must derive its
+ * screen Y from the SAME `model.scrollTop`, or it drifts away from its glyph on
+ * scroll. This component clips to the viewport and translates its children by
+ * `-scrollTop` so they track the canvas exactly — one scroll source, no
+ * tearing.
+ *
+ * Render it as an absolute sibling of the canvas inside the display's
+ * position:relative container. Children position in raw content coordinates (y
+ * from 0..contentHeight); this applies the `-scrollTop` shift. `pointerEvents`
+ * is none so mouse events fall through to the canvas; interactive children
+ * re-enable `pointerEvents:auto`.
+ */
+export declare function ScrollLockedOverlay({ scrollTop, viewportHeight, contentHeight, children, }: {
+    /** the model's scroll offset — the same value the GPU shader paints from */
+    scrollTop: number;
+    /** the visible viewport height (clips overflow) */
+    viewportHeight: number;
+    /** the full scrollable content height (the children's coordinate space) */
+    contentHeight: number;
+    children: React.ReactNode;
+}): React.JSX.Element;

package/esm/ScrollLockedOverlay.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+/**
+ * DOM overlay layer for a display that scrolls a fixed GPU canvas virtually (a
+ * `VerticalScrollbar` overlay + `useVirtualScrollWheel`, everything positioned
+ * from `model.scrollTop`).
+ *
+ * The GPU canvas paints glyphs at `y - model.scrollTop`. Any DOM overlay
+ * (labels, highlights, hover boxes) that annotates those glyphs must derive its
+ * screen Y from the SAME `model.scrollTop`, or it drifts away from its glyph on
+ * scroll. This component clips to the viewport and translates its children by
+ * `-scrollTop` so they track the canvas exactly — one scroll source, no
+ * tearing.
+ *
+ * Render it as an absolute sibling of the canvas inside the display's
+ * position:relative container. Children position in raw content coordinates (y
+ * from 0..contentHeight); this applies the `-scrollTop` shift. `pointerEvents`
+ * is none so mouse events fall through to the canvas; interactive children
+ * re-enable `pointerEvents:auto`.
+ */
+export function ScrollLockedOverlay({ scrollTop, viewportHeight, contentHeight, children, }) {
+    return (_jsx("div", { style: {
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            width: '100%',
+            height: viewportHeight,
+            overflow: 'hidden',
+            pointerEvents: 'none',
+        }, children: _jsx("div", { 
+            // Sized to the full content height so absolutely-positioned children
+            // keep a stable coordinate space; the transform shifts them by
+            // -scrollTop (and, being a transform, makes this their containing block).
+            style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                height: contentHeight,
+                transform: `translateY(${-scrollTop}px)`,
+            }, children: children }) }));
+}

package/esm/blockClipUtils.d.ts

@@ -0,0 +1,27 @@
+import type { CanvasScale } from './canvas2dUtils.ts';
+import type { BpRegionBounds } from './renderBlock.ts';
+export declare function splitPositionWithFrac(value: number): [number, number];
+export interface BlockClipResult {
+    scissorX: number;
+    scissorW: number;
+    pxX: number;
+    pxW: number;
+    pxH: number;
+    /**
+     * The vertical scale the backing store ACTUALLY got — `hal.resize`'s answer,
+     * not `getDpr()`. Carried through so a renderer scissoring bands out of one
+     * canvas (`devicePxBand`) has the ratio the clip was built with rather than
+     * reconstructing it as `pxH / canvasHeight`, which is a division by a height
+     * that can be 0.
+     */
+    scaleY: number;
+    bpStartHi: number;
+    bpStartLo: number;
+    bpEndHi: number;
+    bpEndLo: number;
+    clippedLengthBp: number;
+    bpPerPx: number;
+}
+export declare function bpRangeXTuple(clip: BlockClipResult, reversed: boolean): [number, number, number];
+export declare function writeBpRangeUniforms(uniformF32: Float32Array, offsetF32: number, clip: BlockClipResult, reversed: boolean): void;
+export declare function clipBlock(block: BpRegionBounds, canvasWidth: number, canvasHeight: number, scale: CanvasScale): BlockClipResult | null;

package/esm/blockClipUtils.js

@@ -0,0 +1,101 @@
+import { clampBlockScissor, devicePxSpan } from './canvas2dUtils.js';
+// hp-math split: factor a bp position into a (hi, lo) pair safe to feed
+// shaders as float32 (cumulative-bp coordinates can exceed 2^31, so a plain
+// `intValue & 0xfff` would wrap). Float64 modulo handles the full 2^53
+// safe range. The CPU counterpart of the shader-side `hpSplitUint` in
+// shaders/hpmath.slang — but not a byte-for-byte mirror: `hpSplitUint` masks a
+// `uint`, whereas this also carries the fractional part and tolerates
+// cumulative-bp beyond 2^31. Renderer-side uniform writes use this to mirror
+// the shader's hi/lo coordinate space.
+export function splitPositionWithFrac(value) {
+    const intValue = Math.floor(value);
+    const frac = value - intValue;
+    // Genomic positions are non-negative, so % matches Math.floor(intValue/4096)*4096
+    // pattern while making the modulo intent explicit.
+    const loInt = intValue % 4096;
+    const hi = intValue - loInt;
+    const lo = loInt + frac;
+    return [hi, lo];
+}
+// [hi, lo, ±clippedLengthBp] — the first three floats of the HP uniform buffer
+// used by hpmath.slang's hpToClipX. Reversed blocks pivot on bpEnd with a
+// negated length.
+export function bpRangeXTuple(clip, reversed) {
+    return reversed
+        ? [clip.bpEndHi, clip.bpEndLo, -clip.clippedLengthBp]
+        : [clip.bpStartHi, clip.bpStartLo, clip.clippedLengthBp];
+}
+// Poke the hp-math bpRangeX tuple (hi, lo, ±clippedLengthBp) into the uniform
+// buffer at `offsetF32` — pass the shader's `UNIFORM_OFFSET_F32.bpRangeX`.
+//
+// **The offset-poke form, for a renderer that writes its uniforms
+// incrementally.** A renderer that sets the whole block in one place says
+// `bpRangeX: bpRangeXTuple(clip, reversed)` inside the generated
+// `writeUniforms` instead, which is every genome-mapped renderer in tree today.
+// Either way the point is the same and is the reason neither is spelled out at
+// the call site: the reversed-block pivot and the hi/lo split live in one place,
+// and a hand-rolled `uniformF32[U.bpRangeX + n] = …` triple is easy to get
+// subtly wrong for reversed blocks.
+export function writeBpRangeUniforms(uniformF32, offsetF32, clip, reversed) {
+    const [hi, lo, len] = bpRangeXTuple(clip, reversed);
+    uniformF32[offsetF32] = hi;
+    uniformF32[offsetF32 + 1] = lo;
+    uniformF32[offsetF32 + 2] = len;
+}
+export function clipBlock(block, canvasWidth, canvasHeight, 
+// The scale the backing store actually got, per axis (`hal.resize`), NOT
+// `getDpr()`: only one axis clamps at a time, so past `MAX_CANVAS_DIM_PX` a
+// canvas is 2x on one axis and less on the other.
+scale) {
+    const clamp = clampBlockScissor(block.screenStartPx, block.screenEndPx, canvasWidth);
+    if (!clamp) {
+        return null;
+    }
+    const { scissorX, scissorEnd, scissorW } = clamp;
+    const fullBlockWidth = block.screenEndPx - block.screenStartPx;
+    const regionLengthBp = block.end - block.start;
+    // A degenerate block (no pixel span, or no bp span) still survives
+    // clampBlockScissor — floor/ceil widen a zero-width span straddling a pixel
+    // boundary to scissorW === 1. Dividing by it yields Infinity/NaN, which
+    // propagates through splitPositionWithFrac into every bpRangeX uniform and
+    // silently poisons the draw. Nothing is visible in a zero-width block, so
+    // skip it the same way a fully off-screen one is skipped.
+    if (fullBlockWidth <= 0 || regionLengthBp <= 0) {
+        return null;
+    }
+    const { start: pxX, width: pxW } = devicePxSpan(scissorX, scissorEnd, scale.x);
+    const pxH = Math.round(canvasHeight * scale.y);
+    const bpPerPx = regionLengthBp / fullBlockWidth;
+    // How much the clip cut off each SCREEN edge of the block.
+    const trimLeftPx = scissorX - block.screenStartPx;
+    const trimRightPx = block.screenEndPx - scissorEnd;
+    // `bpStart` is the LOW bp on both orientations and `bpEnd` the high one
+    // (`bpRangeXTuple` pivots on bpEnd when reversed), so each is pulled in by the
+    // trim on ITS OWN end — and which screen edge that is flips with the
+    // orientation, since a reversed block runs bp leftward from `end`. The two
+    // orientations agree exactly when nothing is trimmed, which is why the
+    // forward-only spelling survived — but `canvasWidth` is `trackWidthPx`, i.e.
+    // `view.width - 2` whenever track outlines are on (the default), so the
+    // rightmost block is clipped on every view and a reversed one had its whole
+    // painting shifted 2px against `makeBpMapper` (the Canvas2D painter and every
+    // hit-test). Another member of the reversed-block family in this package's
+    // CLAUDE.md: invisible forward, only ever wrong on a flipped view.
+    const clippedBpStart = block.start + (block.reversed ? trimRightPx : trimLeftPx) * bpPerPx;
+    const clippedBpEnd = block.end - (block.reversed ? trimLeftPx : trimRightPx) * bpPerPx;
+    const [bpStartHi, bpStartLo] = splitPositionWithFrac(clippedBpStart);
+    const [bpEndHi, bpEndLo] = splitPositionWithFrac(clippedBpEnd);
+    return {
+        scissorX,
+        scissorW,
+        pxX,
+        pxW,
+        pxH,
+        scaleY: scale.y,
+        bpStartHi,
+        bpStartLo,
+        bpEndHi,
+        bpEndLo,
+        clippedLengthBp: clippedBpEnd - clippedBpStart,
+        bpPerPx,
+    };
+}