@jbrowse/render-core 4.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2020] [Evolutionary Software Foundation]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/esm/OverlayCanvas.d.ts

@@ -0,0 +1,29 @@
+/**
+ * An absolutely-positioned, non-interactive Canvas2D layer that composites over
+ * a display's main canvas. Callers pass a `draw` closure capturing their
+ * current data; the effect re-runs whenever that closure or the size changes.
+ *
+ * Wrap the caller in `observer` (mobx-react memoizes it) so the component
+ * re-renders exactly when its own inputs change — `draw`'s identity then
+ * changes exactly when those inputs do, and an unrelated parent re-render
+ * (hover, scroll) costs no redraw.
+ *
+ * Lives here rather than in a plugin because the marker-overlay pattern is the
+ * Canvas2D counterpart of a GPU pass: every display that draws positioned marks
+ * over a rendering backend needs the same absolutely-positioned,
+ * `pointerEvents: 'none'`, dpr-prepared canvas. MAF has seven such overlays;
+ * alignments and canvas each had a hand-rolled copy.
+ *
+ * **The explicit CSS `width`/`height` are the load-bearing part.** A canvas is a
+ * replaced element, so `inset: 0` does not stretch it the way it stretches a
+ * div: with no CSS size it takes its INTRINSIC size, which `prepareCanvas` has
+ * just set to the DPR-scaled backing store. A hand-rolled copy that reached for
+ * `inset: 0` therefore drew everything at twice its x on a retina display and
+ * dropped the right half off the edge, while looking entirely plausible.
+ */
+export default function OverlayCanvas({ width, height, draw, 'data-testid': testId, }: {
+    width: number;
+    height: number;
+    draw: (ctx: CanvasRenderingContext2D) => void;
+    'data-testid'?: string;
+}): import("react").JSX.Element;

package/esm/OverlayCanvas.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { getPreparedCanvas2D } from './canvas2dUtils.js';
+/**
+ * An absolutely-positioned, non-interactive Canvas2D layer that composites over
+ * a display's main canvas. Callers pass a `draw` closure capturing their
+ * current data; the effect re-runs whenever that closure or the size changes.
+ *
+ * Wrap the caller in `observer` (mobx-react memoizes it) so the component
+ * re-renders exactly when its own inputs change — `draw`'s identity then
+ * changes exactly when those inputs do, and an unrelated parent re-render
+ * (hover, scroll) costs no redraw.
+ *
+ * Lives here rather than in a plugin because the marker-overlay pattern is the
+ * Canvas2D counterpart of a GPU pass: every display that draws positioned marks
+ * over a rendering backend needs the same absolutely-positioned,
+ * `pointerEvents: 'none'`, dpr-prepared canvas. MAF has seven such overlays;
+ * alignments and canvas each had a hand-rolled copy.
+ *
+ * **The explicit CSS `width`/`height` are the load-bearing part.** A canvas is a
+ * replaced element, so `inset: 0` does not stretch it the way it stretches a
+ * div: with no CSS size it takes its INTRINSIC size, which `prepareCanvas` has
+ * just set to the DPR-scaled backing store. A hand-rolled copy that reached for
+ * `inset: 0` therefore drew everything at twice its x on a retina display and
+ * dropped the right half off the edge, while looking entirely plausible.
+ */
+export default function OverlayCanvas({ width, height, draw, 'data-testid': testId, }) {
+    const canvasRef = useRef(null);
+    useEffect(() => {
+        const ctx = getPreparedCanvas2D(canvasRef.current, width, height);
+        if (ctx) {
+            draw(ctx);
+        }
+    }, [draw, width, height]);
+    return (_jsx("canvas", { ref: canvasRef, "data-testid": testId, style: {
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            width,
+            height,
+            pointerEvents: 'none',
+        } }));
+}

package/esm/RenderCanvas.d.ts

@@ -0,0 +1,76 @@
+import type { DisplayStatusPhase } from './displayPhase.ts';
+import type { ComponentPropsWithoutRef } from 'react';
+/**
+ * The two fields of `useRenderingBackend`'s return value this needs, duck-typed
+ * so the hook's generic backend parameter doesn't have to be threaded here.
+ */
+export interface RenderCanvasHandle {
+    canvasRef: (node: HTMLCanvasElement | null) => void;
+    canvasKey: number;
+}
+/**
+ * The `<canvas>` for a rendering backend owned **outside** `DisplayChrome` — the
+ * sanctioned drop-to-primitive path for the non-LGV views (dotplot, the synteny
+ * level), which have no `ChromeModel` contract and render their own banners.
+ *
+ * It exists for one invariant that was previously carried by prose:
+ * **`key={canvasKey}`**. Every backend re-init needs a canvas element that never
+ * held a context — `getContext('webgl2')` hands back the *same lost* context,
+ * and `getContext('2d')` returns **null** on any element that once had WebGL, so
+ * reusing the element turns a recoverable context loss into a permanent "Canvas
+ * 2D context not available" — and more generally a canvas's context kind is
+ * permanent, so a re-init whose HAL ladder lands on a different rung than last
+ * time cannot bind at all. These consumers keep their canvas mounted through an
+ * error by design (ADR-025), so they must key it; `DisplayChromeBase` keys its
+ * render-prop body on the same value for the displays on the chrome, which it
+ * does *not* get for free from the `renderError` unmount (that covers only a
+ * reported loss — see the `canvasKey` note in useRenderingBackend.ts).
+ * GPU_RENDERING.md said so and ended with "any new consumer rendering its own
+ * banner must too" — a rule enforced by remembering to read the doc. Rendering
+ * the element here makes it structural instead: there is no way to mount this
+ * canvas without the key.
+ *
+ * It owns the key and **nothing else** — everything (sizing, class, mouse
+ * handlers, `data-testid`) is forwarded.
+ *
+ * There used to be a readiness convention to fold in here and there is not any
+ * more: these two views spelled it `synteny_canvas_done` /
+ * `dotplot_webgl_canvas_done`, with an **underscore**, against `DisplayChrome`'s
+ * `-done`, and ADR-065 deleted both in favour of the `data-display-drawn` this
+ * component already publishes. Their readiness flag is still `settled` rather
+ * than `canvasDrawn`, which is a real distinction and not a naming one — a
+ * shared canvas repaints unconditionally, so `canvasDrawn` says nothing
+ * (ADR-009's scope clause) — so `drawn` is passed at the call site.
+ */
+export default function RenderCanvas({ handle, drawn, phase, ...canvasProps }: {
+    handle: RenderCanvasHandle;
+    /**
+     * Whether this canvas holds finished content — each view's own `settled`, the
+     * same flag its `*_canvas_done` testid is built from. Published as
+     * `data-display-drawn`, which is what `PENDING_DISPLAYS`
+     * (`@jbrowse/browser-test-utils`) selects on, so these views answer "has
+     * everything painted?" with the same attribute every LGV display does.
+     *
+     * Required, and that is the point: `PENDING_DISPLAYS` used to name
+     * `synteny_canvas` explicitly and simply **forgot dotplot**, so an unpainted
+     * dotplot counted as finished and a capture could land on it blank. A new
+     * drop-to-primitive view would have been forgotten the same way.
+     */
+    drawn: boolean;
+    /**
+     * The surface's own mutually-exclusive state, published as
+     * `data-display-phase` — the same attribute `DisplayStatusChrome` gives every
+     * LGV display, and the same split of meaning: `drawn` above is FINISHED
+     * CONTENT, this is still WORKING, and an error separates them.
+     *
+     * Required for the reason `drawn` is. Every DOM-level doneness wait
+     * (`waitForDisplayPhases`, the busy selector, `Instrumentation.displayPhase`)
+     * keys on `[data-display-phase]`, and a view that published none turned each
+     * of them into an assertion about an absent selector — satisfied by a canvas
+     * that had not begun to draw. That was true of both of these views.
+     *
+     * A shared canvas carries the ranking over its displays rather than one
+     * display's phase; `comparativeSurfacePhase` is where that ranking lives.
+     */
+    phase: DisplayStatusPhase;
+} & Omit<ComponentPropsWithoutRef<'canvas'>, 'ref'>): import("react").JSX.Element;

package/esm/RenderCanvas.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The `<canvas>` for a rendering backend owned **outside** `DisplayChrome` — the
+ * sanctioned drop-to-primitive path for the non-LGV views (dotplot, the synteny
+ * level), which have no `ChromeModel` contract and render their own banners.
+ *
+ * It exists for one invariant that was previously carried by prose:
+ * **`key={canvasKey}`**. Every backend re-init needs a canvas element that never
+ * held a context — `getContext('webgl2')` hands back the *same lost* context,
+ * and `getContext('2d')` returns **null** on any element that once had WebGL, so
+ * reusing the element turns a recoverable context loss into a permanent "Canvas
+ * 2D context not available" — and more generally a canvas's context kind is
+ * permanent, so a re-init whose HAL ladder lands on a different rung than last
+ * time cannot bind at all. These consumers keep their canvas mounted through an
+ * error by design (ADR-025), so they must key it; `DisplayChromeBase` keys its
+ * render-prop body on the same value for the displays on the chrome, which it
+ * does *not* get for free from the `renderError` unmount (that covers only a
+ * reported loss — see the `canvasKey` note in useRenderingBackend.ts).
+ * GPU_RENDERING.md said so and ended with "any new consumer rendering its own
+ * banner must too" — a rule enforced by remembering to read the doc. Rendering
+ * the element here makes it structural instead: there is no way to mount this
+ * canvas without the key.
+ *
+ * It owns the key and **nothing else** — everything (sizing, class, mouse
+ * handlers, `data-testid`) is forwarded.
+ *
+ * There used to be a readiness convention to fold in here and there is not any
+ * more: these two views spelled it `synteny_canvas_done` /
+ * `dotplot_webgl_canvas_done`, with an **underscore**, against `DisplayChrome`'s
+ * `-done`, and ADR-065 deleted both in favour of the `data-display-drawn` this
+ * component already publishes. Their readiness flag is still `settled` rather
+ * than `canvasDrawn`, which is a real distinction and not a naming one — a
+ * shared canvas repaints unconditionally, so `canvasDrawn` says nothing
+ * (ADR-009's scope clause) — so `drawn` is passed at the call site.
+ */
+export default function RenderCanvas({ handle, drawn, phase, ...canvasProps }) {
+    return (_jsx("canvas", { "data-display-drawn": drawn, "data-display-phase": phase, ref: handle.canvasRef, ...canvasProps }, handle.canvasKey));
+}

package/esm/RenderLifecycleMixin.d.ts

@@ -0,0 +1,180 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * The slice of a display an installer needs. Every display that paints composes
+ * {@link RenderLifecycleMixin} (directly or through `MultiRegionDisplayMixin` /
+ * `GlobalFetchMixin`), so this is satisfied by construction; it exists so
+ * the installers can take `self` without importing a plugin's model type.
+ */
+export interface LifecycleHost extends IStateTreeNode {
+    attachRenderingBackend: <B>(b: B, setup: () => RenderingBackendCallbacks<B>) => void;
+}
+export interface RenderingBackendCallbacks<B> {
+    /**
+     * Push bytes for the current data and say whether anything reached the
+     * backend. `true` forces a redraw, which a first arrival needs when the
+     * render callback's own dependencies are identity-stable across it; the
+     * map-diffing installers answer `false` for a run that uploaded nothing.
+     */
+    upload: (backend: B) => boolean;
+    /**
+     * Issue draw calls for the current frame. Return `true` if something was
+     * actually drawn (flips `canvasDrawn`), `false` to skip this tick
+     * (e.g. `renderState` not yet computed). Returning `true` without
+     * having drawn — or forgetting a return branch — will flip the
+     * `canvasDrawn` flag spuriously, which test selectors and overlay UI
+     * depend on.
+     */
+    render: (backend: B) => boolean;
+}
+/**
+ * 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 declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree").IModelType<{}, {
+    canvasDrawn: boolean;
+    currentRenderingBackend: unknown;
+    renderTick: number;
+    autorunsInstalled: boolean;
+    renderError: unknown;
+} & {
+    /**
+     * #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.
+     */
+    readonly canRender: boolean;
+    /**
+     * #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.
+     */
+    readonly rendersCanvas: boolean;
+    /**
+     * #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.
+     */
+    readonly paintInert: boolean;
+} & {
+    /**
+     * #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.
+     */
+    readonly painted: boolean;
+} & {
+    /**
+     * #action
+     */
+    markCanvasDrawn(): void;
+    /**
+     * #action
+     */
+    resetCanvasDrawn(): void;
+    /**
+     * #action
+     */
+    stopRenderingBackend(): void;
+    /**
+     * #action
+     */
+    renderNow(): void;
+    /**
+     * #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: unknown): void;
+} & {
+    /**
+     * #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<B>(backend: B, setup: () => RenderingBackendCallbacks<B>): void;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;