@jbrowse/display-ui 4.3.0

package/esm/DisplayUIProvider.d.ts

@@ -0,0 +1,70 @@
+import type { DisplayChromeOverlays } from './chromeOverlays.ts';
+import type { TrackControlComponent } from './trackControl/types.ts';
+import type { ReactNode } from 'react';
+export declare function resolveOverlays(overlays?: Partial<DisplayChromeOverlays>): DisplayChromeOverlays;
+/**
+ * #api
+ * Both bring-your-own seams at once: what a display draws that is not data.
+ *
+ * There are two contexts underneath because two different things render them —
+ * the chrome around a display draws the status states, the display itself draws
+ * its bottom-right controls — and that split is real at the implementation
+ * level, since `DisplayChromeBase` takes its overlay set as a *prop* and never
+ * renders a track control. It is not real for an embedder: nobody wants stock
+ * Material loading scrims with plain corner controls, or the reverse. Every
+ * consumer in this repo mounts the two together.
+ *
+ * ```tsx
+ * <DisplayUIProvider>{tracks}</DisplayUIProvider>
+ * ```
+ *
+ * Both props default to the plain, toolkit-free sets, so the common case — "I
+ * do not want Material UI in my app" — needs no arguments and no second import.
+ *
+ * **`overlays` is a partial set**, merged over the plain one, so replacing a
+ * single state is one entry rather than five:
+ *
+ * ```tsx
+ * <DisplayUIProvider overlays={{ ErrorBar: MyErrorBar }}>
+ * ```
+ *
+ * Partial rather than whole for two reasons. A host writing four of the five
+ * states by hand only ever wanted one of them, and every example of this had
+ * spread `plainChromeOverlays` in to say so. And a *sixth* state is a thing
+ * JBrowse can add: with a whole set the host's object goes stale on upgrade —
+ * a compile error if they typecheck, a missing component if they ship JS — while
+ * a partial one keeps working and picks up the new plain default.
+ *
+ * Declare that object at module scope if you can. The merge is stable per
+ * object (`resolveOverlays`), so a constant costs one merge for the life of the
+ * app; a literal written inline in JSX is a new object every render, and this
+ * value goes into a context, so every display beneath re-renders with it.
+ *
+ * **The contexts themselves still default to `undefined`, and that stays true.**
+ * A display rendering outside any provider — a unit test, the SVG export,
+ * breakpoint-split-view's `overlayUtils` — keeps JBrowse's own Material look,
+ * because a plain ambient default would degrade those invisibly. Defaulting
+ * *this component's props* is a different thing: mounting it is a deliberate
+ * act, and the act means "not the Material default". Nothing gets a plain set
+ * without someone having asked.
+ *
+ * Colors are not a seam and are not here. A display reads `usePalette()` for its
+ * own content colors, which is a palette of strings rather than a UI toolkit, so
+ * it arrives through `SessionPaletteProvider`
+ * (`@jbrowse/core/ui/PaletteContext`) whatever these are set to. A feature track
+ * needs it even with plain chrome.
+ *
+ * This module reaches no `@mui/*` module, and `muiFree.test.ts` keeps it
+ * that way — asking for less Material UI must not download more of it. What it
+ * cannot do is unship the Material components a *stock display* imports:
+ * `DisplayChrome` and `TrackControl` are in that display's chunk either way,
+ * and merely stop rendering. Keeping them out of the graph means writing your
+ * own display component over `DisplayChromeBase`, which takes `overlays` as a
+ * prop and imports no toolkit. See
+ * [DISPLAYCHROME.md](https://github.com/GMOD/jbrowse-components/blob/main/agent-docs/reference/DISPLAYCHROME.md).
+ */
+export default function DisplayUIProvider({ overlays, trackControl, children, }: {
+    overlays?: Partial<DisplayChromeOverlays>;
+    trackControl?: TrackControlComponent;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/esm/DisplayUIProvider.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DisplayChromeOverlayProvider } from './chromeOverlayContext.js';
+import plainChromeOverlays from './plainChromeOverlays.js';
+import plainTrackControl from './trackControl/plainTrackControl.js';
+import { TrackControlProvider } from './trackControl/trackControlContext.js';
+// One merged set per caller's object, for the life of that object.
+//
+// The value goes into a context, so a fresh identity on each render re-renders
+// every display beneath it — and `observer()` wraps `React.memo`, so a new
+// `overlays` prop defeats the memo on each display's whole chrome. Stability is
+// the point; the allocation is nothing.
+//
+// A `useMemo` would do it and is worse in three small ways: it is per component
+// *instance*, so two providers handed the same set produce two identities and
+// two re-render groups; React may discard the cache; and it makes a plain
+// merge into a hook, unusable from a test or a caller building the value by
+// hand. Keyed weakly, so an inline literal — which misses either way — is
+// collected rather than accumulated.
+const merged = new WeakMap();
+export function resolveOverlays(overlays) {
+    // the common case allocates nothing: no argument means the plain set itself,
+    // which is already a module constant
+    if (!overlays) {
+        return plainChromeOverlays;
+    }
+    let full = merged.get(overlays);
+    if (!full) {
+        full = { ...plainChromeOverlays, ...overlays };
+        merged.set(overlays, full);
+    }
+    return full;
+}
+/**
+ * #api
+ * Both bring-your-own seams at once: what a display draws that is not data.
+ *
+ * There are two contexts underneath because two different things render them —
+ * the chrome around a display draws the status states, the display itself draws
+ * its bottom-right controls — and that split is real at the implementation
+ * level, since `DisplayChromeBase` takes its overlay set as a *prop* and never
+ * renders a track control. It is not real for an embedder: nobody wants stock
+ * Material loading scrims with plain corner controls, or the reverse. Every
+ * consumer in this repo mounts the two together.
+ *
+ * ```tsx
+ * <DisplayUIProvider>{tracks}</DisplayUIProvider>
+ * ```
+ *
+ * Both props default to the plain, toolkit-free sets, so the common case — "I
+ * do not want Material UI in my app" — needs no arguments and no second import.
+ *
+ * **`overlays` is a partial set**, merged over the plain one, so replacing a
+ * single state is one entry rather than five:
+ *
+ * ```tsx
+ * <DisplayUIProvider overlays={{ ErrorBar: MyErrorBar }}>
+ * ```
+ *
+ * Partial rather than whole for two reasons. A host writing four of the five
+ * states by hand only ever wanted one of them, and every example of this had
+ * spread `plainChromeOverlays` in to say so. And a *sixth* state is a thing
+ * JBrowse can add: with a whole set the host's object goes stale on upgrade —
+ * a compile error if they typecheck, a missing component if they ship JS — while
+ * a partial one keeps working and picks up the new plain default.
+ *
+ * Declare that object at module scope if you can. The merge is stable per
+ * object (`resolveOverlays`), so a constant costs one merge for the life of the
+ * app; a literal written inline in JSX is a new object every render, and this
+ * value goes into a context, so every display beneath re-renders with it.
+ *
+ * **The contexts themselves still default to `undefined`, and that stays true.**
+ * A display rendering outside any provider — a unit test, the SVG export,
+ * breakpoint-split-view's `overlayUtils` — keeps JBrowse's own Material look,
+ * because a plain ambient default would degrade those invisibly. Defaulting
+ * *this component's props* is a different thing: mounting it is a deliberate
+ * act, and the act means "not the Material default". Nothing gets a plain set
+ * without someone having asked.
+ *
+ * Colors are not a seam and are not here. A display reads `usePalette()` for its
+ * own content colors, which is a palette of strings rather than a UI toolkit, so
+ * it arrives through `SessionPaletteProvider`
+ * (`@jbrowse/core/ui/PaletteContext`) whatever these are set to. A feature track
+ * needs it even with plain chrome.
+ *
+ * This module reaches no `@mui/*` module, and `muiFree.test.ts` keeps it
+ * that way — asking for less Material UI must not download more of it. What it
+ * cannot do is unship the Material components a *stock display* imports:
+ * `DisplayChrome` and `TrackControl` are in that display's chunk either way,
+ * and merely stop rendering. Keeping them out of the graph means writing your
+ * own display component over `DisplayChromeBase`, which takes `overlays` as a
+ * prop and imports no toolkit. See
+ * [DISPLAYCHROME.md](https://github.com/GMOD/jbrowse-components/blob/main/agent-docs/reference/DISPLAYCHROME.md).
+ */
+export default function DisplayUIProvider({ overlays, trackControl = plainTrackControl, children, }) {
+    return (_jsx(DisplayChromeOverlayProvider, { value: resolveOverlays(overlays), children: _jsx(TrackControlProvider, { value: trackControl, children: children }) }));
+}

package/esm/FloatingLegend.d.ts

@@ -0,0 +1,16 @@
+import type { LegendItem, LegendSection } from '@jbrowse/core/ui/legendSpec';
+import type { ReactNode } from 'react';
+export type { LegendItem, LegendMark, LegendSection, LegendSpec, LegendSwatch, } from '@jbrowse/core/ui/legendSpec';
+declare const FloatingLegend: ({ items, sections, title, onDismiss, onDismissSection, onItemClick, maxItems, maxWidth, top, children, }: {
+    items?: LegendItem[];
+    sections?: LegendSection[];
+    title?: string;
+    children?: ReactNode;
+    onDismiss?: () => void;
+    onDismissSection?: (id: string) => void;
+    onItemClick?: (item: LegendItem, section: LegendSection) => void;
+    maxItems?: number;
+    maxWidth?: number;
+    top?: number;
+}) => import("react").JSX.Element | null;
+export default FloatingLegend;

package/esm/FloatingLegend.js

@@ -0,0 +1,213 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+// deep subpaths, never the `@jbrowse/core/ui` barrel: a display renders this
+// legend directly, so it sits behind neither bring-your-own seam, and one named
+// import of that barrel lands FileSelector, FatalErrorDialog and the
+// cascading-menu stack in the chunk. `muiFree.test.ts` fails on it.
+import { LegendSwatchGlyph } from '@jbrowse/core/ui/LegendSwatchGlyph';
+import { legendSwatches, nonEmptyLegendSections, } from '@jbrowse/core/ui/legendSpec';
+import { cx, makeStyles } from '@jbrowse/core/util/tss-react';
+import { observer } from 'mobx-react';
+import Tooltip from './tooltip/Tooltip.js';
+import { TrackOverlayPortal } from './trackOverlay/TrackOverlayPortal.js';
+const useStyles = makeStyles()(theme => ({
+    legend: {
+        position: 'absolute',
+        right: 10,
+        background: theme.palette.background.paper,
+        // A hairline edge, because `background.paper` on a track whose canvas is
+        // also paper-white is no edge at all: the key read as loose text floating
+        // over the features rather than as a panel, and the swatches were the only
+        // thing announcing it (reviewer, on cookbook_color_by_type: "legend needs a
+        // light border ... very subtle. just enough to notice because it is hard to
+        // see at a glance"). `divider` is the theme's own hairline, so this stays
+        // right in both themes and against a dark track.
+        border: `1px solid ${theme.palette.divider}`,
+        borderRadius: 3,
+        padding: 3,
+        fontSize: 10,
+        zIndex: 100,
+        // the default; `maxWidth` overrides it per display
+        // portaled into the TrackContainer's above-the-masks overlay node, which is
+        // pointer-events:none so it doesn't eat canvas events; re-enable events on
+        // the legend itself so its close buttons/links stay clickable (harmless when
+        // rendered inline, where events already pass through)
+        pointerEvents: 'auto',
+    },
+    // A plain <button>, not MUI's IconButton, and the glyph is `×` rather than
+    // the Material Close icon.
+    //
+    // This component is rendered by canvas, alignments, variants and multi-wiggle
+    // displays *directly*, behind neither bring-your-own seam, so a Material
+    // widget here reaches an embedder who has opted out of both — and the
+    // build-your-own site's zero-MUI census, which no page currently trips only
+    // because no page turns on a colorBy that raises a legend. Same call
+    // `BaseTooltip` made in 2026-08: what it needed was colors, and colors have a
+    // toolkit-free home already. See DISPLAYCHROME.md, "a third seam was
+    // considered for the tooltip and rejected".
+    //
+    // `×` is what `SvgColorLegend` already draws for this control, so the
+    // exported legend and the on-screen one now agree.
+    closeButton: {
+        position: 'absolute',
+        top: 0,
+        right: 0,
+        font: 'inherit',
+        lineHeight: 1,
+        padding: '1px 3px',
+        border: 0,
+        background: 'none',
+        color: theme.palette.text.secondary,
+        cursor: 'pointer',
+        '&:hover': {
+            color: theme.palette.text.primary,
+        },
+    },
+    withClose: {
+        paddingRight: 20,
+    },
+    topTitle: {
+        fontWeight: 'bold',
+        whiteSpace: 'nowrap',
+        marginBottom: 2,
+    },
+    section: {
+        '&:not(:last-child)': {
+            marginBottom: 4,
+        },
+    },
+    sectionHeader: {
+        display: 'flex',
+        alignItems: 'center',
+        marginBottom: 2,
+    },
+    sectionTitle: {
+        fontWeight: 'bold',
+        whiteSpace: 'nowrap',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+    },
+    sectionClose: {
+        font: 'inherit',
+        lineHeight: 1,
+        padding: 0,
+        marginLeft: 2,
+        border: 0,
+        background: 'none',
+        color: theme.palette.text.secondary,
+        cursor: 'pointer',
+        '&:hover': {
+            color: theme.palette.text.primary,
+        },
+    },
+    item: {
+        display: 'flex',
+        alignItems: 'center',
+        marginBottom: 1,
+        '&:last-child': {
+            marginBottom: 0,
+        },
+    },
+    // A row that acts: the same layout, as a plain button (see `closeButton`
+    // for why not Material's), so a key naming groups of rows can focus one.
+    itemButton: {
+        font: 'inherit',
+        padding: 0,
+        border: 0,
+        background: 'none',
+        width: '100%',
+        textAlign: 'left',
+        color: 'inherit',
+        cursor: 'pointer',
+        '&:hover': {
+            background: theme.palette.action.hover,
+        },
+    },
+    swatches: {
+        display: 'flex',
+        gap: 2,
+        marginRight: 6,
+        flexShrink: 0,
+    },
+    label: {
+        whiteSpace: 'nowrap',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+    },
+    // was `<Link component="button" underline="hover">`, which is the same
+    // element with Material's typography on it — see `closeButton` above for why
+    // that mattered
+    toggle: {
+        font: 'inherit',
+        fontSize: 10,
+        display: 'block',
+        marginTop: 2,
+        padding: 0,
+        border: 0,
+        background: 'none',
+        textAlign: 'left',
+        color: theme.palette.primary.main,
+        cursor: 'pointer',
+        '&:hover': {
+            textDecoration: 'underline',
+        },
+    },
+}));
+const DEFAULT_MAX_ITEMS = 12;
+const DEFAULT_MAX_WIDTH = 200;
+// Side of one mark. The old fixed color box's size, kept so a legend of plain
+// fills is pixel-identical to what shipped before marks existed.
+const SWATCH = 12;
+// One list of swatches with its own independent collapse state, so each section
+// in a multi-section legend expands/collapses on its own.
+const LegendItemList = observer(function LegendItemList({ items, maxItems, onItemClick, }) {
+    const { classes } = useStyles();
+    const [expanded, setExpanded] = useState(false);
+    const collapsible = items.length > maxItems;
+    const shown = collapsible && !expanded ? items.slice(0, maxItems) : items;
+    const hiddenCount = items.length - maxItems;
+    // Every row reserves the widest row's swatch column, so labels stay in one
+    // vertical line whether a row draws one mark or two — and so a color-less
+    // heading row indents like the swatches it heads, as the fixed-size box it
+    // replaces used to.
+    const columns = Math.max(1, ...shown.map(i => legendSwatches(i).length));
+    return (_jsxs(_Fragment, { children: [shown.map((item, i) => {
+                const row = (_jsxs(_Fragment, { children: [_jsx("div", { className: classes.swatches, style: { minWidth: columns * SWATCH + (columns - 1) * 2 }, children: legendSwatches(item).map(swatch => (_jsx("svg", { width: SWATCH, height: SWATCH, children: _jsx(LegendSwatchGlyph, { swatch: swatch, size: SWATCH }) }, `${swatch.color}-${swatch.mark ?? 'fill'}`))) }), _jsx("span", { className: classes.label, children: item.label })] }));
+                return onItemClick ? (_jsx("button", { type: "button", className: cx(classes.item, classes.itemButton), title: "Show only these rows", onClick: () => {
+                        onItemClick(item);
+                    }, children: row }, `${item.label}-${i}`)) : (_jsx("div", { className: classes.item, children: row }, `${item.label}-${i}`));
+            }), collapsible ? (_jsx("button", { type: "button", className: classes.toggle, onClick: () => {
+                    setExpanded(!expanded);
+                }, children: expanded ? 'Show less' : `Show ${hiddenCount} more…` })) : null] }));
+});
+// Floating color-key overlay. Pass a flat `items` list for a single scheme, or
+// `sections` to show several titled, individually-closable panels in one box
+// (e.g. genotype colors vs. sample-grouping colors on the multi-sample variant
+// display). Section titles + per-section close buttons only appear when there
+// is more than one section, so a single-scheme legend looks unchanged. `title`
+// is a heading for the whole box, shown regardless of section count.
+//
+// `onItemClick` makes the rows act — for a key whose entries name groups of
+// rows, clicking one focuses those rows. It is handed the section too, so a
+// display with several vocabularies can act on the one that names rows and
+// leave the others inert.
+const FloatingLegend = observer(function FloatingLegend({ items, sections, title, onDismiss, onDismissSection, onItemClick, maxItems = DEFAULT_MAX_ITEMS, maxWidth = DEFAULT_MAX_WIDTH, top = 10, children, }) {
+    const { classes } = useStyles();
+    const nonEmpty = nonEmptyLegendSections({ items, sections });
+    if (nonEmpty.length === 0 && !children) {
+        return null;
+    }
+    const multiSection = nonEmpty.length > 1;
+    // portal above the inter-region padding masks so the key isn't buried at
+    // whole-genome / multi-region scale (see TrackOverlayPortal)
+    return (_jsx(TrackOverlayPortal, { children: _jsxs("div", { className: cx(classes.legend, onDismiss && classes.withClose), style: { top, maxWidth }, "data-testid": "floating-legend", "data-gesture-owner": "true", children: [onDismiss ? (_jsx(Tooltip, { title: "Hide legend", children: _jsx("button", { type: "button", className: classes.closeButton, "aria-label": "Hide legend", onClick: () => {
+                            onDismiss();
+                        }, children: "\u00D7" }) })) : null, title ? _jsx("div", { className: classes.topTitle, children: title }) : null, children, nonEmpty.map(section => (_jsxs("div", { className: classes.section, children: [multiSection && section.title ? (_jsxs("div", { className: classes.sectionHeader, children: [_jsx("span", { className: classes.sectionTitle, children: section.title }), onDismissSection ? (_jsx(Tooltip, { title: `Hide ${section.title}`, children: _jsx("button", { type: "button", className: classes.sectionClose, "aria-label": `Hide ${section.title}`, onClick: () => {
+                                            onDismissSection(section.id);
+                                        }, children: "\u00D7" }) })) : null] })) : null, _jsx(LegendItemList, { items: section.items, maxItems: maxItems, onItemClick: onItemClick
+                                ? item => {
+                                    onItemClick(item, section);
+                                }
+                                : undefined })] }, section.id)))] }) }));
+});
+export default FloatingLegend;

package/esm/PointerLayer.d.ts

@@ -0,0 +1,26 @@
+import type { MouseState, MouseTracker } from '@jbrowse/core/ui/useMouseTracking';
+import type { ReactNode } from 'react';
+/**
+ * The part of a display that follows the pointer — guides, a tooltip, a
+ * highlighted column — rendered off the chrome's `mouseTracker` in a leaf of
+ * its own, so a mousemove re-renders this and nothing else. Read in the
+ * component that mounts `DisplayChrome` instead, the position would re-render
+ * the chrome, its status container and every overlay under it on each move
+ * (see `useMouseTracking`).
+ *
+ * `rowsTopOffset` answers whether the pointer is over the rows rather than a
+ * band stacked above them, for a display that gates its crosshair to the rows:
+ * a guide drawn while the pointer is over a variant lane or a connector zone
+ * names a row the pointer is not on. The tooltip is usually not gated with it,
+ * which is why the child decides. `children` is also handed an absent state, so
+ * a layer that has to render while nothing is hovered — the matrix display's
+ * connector lines, with no column highlighted — can.
+ *
+ * Four displays used to write this component out, with the same paragraph over
+ * each.
+ */
+export declare function PointerLayer({ mouseTracker, rowsTopOffset, children, }: {
+    mouseTracker: MouseTracker;
+    rowsTopOffset?: number;
+    children: (state: MouseState | undefined, inRows: boolean) => ReactNode;
+}): import("react").JSX.Element;

package/esm/PointerLayer.js

@@ -0,0 +1,27 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// deep subpath, never the `@jbrowse/core/ui` barrel: this package reaches no
+// UI toolkit, and the barrel pulls MUI in
+import { useMouseState } from '@jbrowse/core/ui/useMouseTracking';
+/**
+ * The part of a display that follows the pointer — guides, a tooltip, a
+ * highlighted column — rendered off the chrome's `mouseTracker` in a leaf of
+ * its own, so a mousemove re-renders this and nothing else. Read in the
+ * component that mounts `DisplayChrome` instead, the position would re-render
+ * the chrome, its status container and every overlay under it on each move
+ * (see `useMouseTracking`).
+ *
+ * `rowsTopOffset` answers whether the pointer is over the rows rather than a
+ * band stacked above them, for a display that gates its crosshair to the rows:
+ * a guide drawn while the pointer is over a variant lane or a connector zone
+ * names a row the pointer is not on. The tooltip is usually not gated with it,
+ * which is why the child decides. `children` is also handed an absent state, so
+ * a layer that has to render while nothing is hovered — the matrix display's
+ * connector lines, with no column highlighted — can.
+ *
+ * Four displays used to write this component out, with the same paragraph over
+ * each.
+ */
+export function PointerLayer({ mouseTracker, rowsTopOffset = 0, children, }) {
+    const state = useMouseState(mouseTracker);
+    return _jsx(_Fragment, { children: children(state, !!state && state.y > rowsTopOffset) });
+}

package/esm/bottomRightCorner.d.ts

@@ -0,0 +1,58 @@
+/**
+ * #api
+ * The one box per display that owns the bottom-right corner.
+ *
+ * It lives beside the overlay contract rather than with the chrome that mounts
+ * it, because it is the half of that contract the types cannot carry:
+ * `DisplayChromeOverlays.BackgroundProgress` is the one state told to render an
+ * in-flow chip with no `position` and no corner offsets, and this is the box it
+ * is laid out in. A host writing their own display over `DisplayChromeBase`
+ * needs to be able to build that corner; while this sat one layer up in the LGV
+ * plugin, the rule was a paragraph they could only obey by hand.
+ *
+ * Two independent things want that corner and neither could see the other:
+ * the display's own control row (`BottomRightIndicators` — track sizing, the
+ * isoform notice, the solo chip) and the chrome's background-progress chip
+ * (`DisplayChromeOverlays.BackgroundProgress`, the status channel for work with
+ * no fetch behind it). Both portal into the *same* per-track overlay node, and
+ * both used to claim `bottom: 2; right: 2` there with their own
+ * `position: absolute` box — so they simply drew on top of each other, the
+ * controls winning on z-index and the status text disappearing under them.
+ *
+ * It has never been reachable: the two displays that render the control row
+ * (alignments, canvas) are not among the four that report a `ready`-phase
+ * status (clustering, on multi-wiggle / multi-row features / maf / the
+ * multi-sample variant pair). That is the *reason* to make it structural rather
+ * than to leave it — nothing on either side is aware of the constraint, so the
+ * first display to want both would find the bug, and it presents as a status
+ * message that silently never appears.
+ *
+ * `BottomRightIndicators` already described itself as "the single anchor point
+ * for every bottom-right overlay ... so they lay out as one row instead of each
+ * picking their own position and colliding". This makes that true of the chip
+ * too: the chrome renders the anchor, puts its chip in it, and publishes the
+ * node here so the display's row — rendered several components away, inside the
+ * chrome's body — lands in the same flex box instead of over it.
+ *
+ * `null` outside a chrome (a display an embedder mounts standalone, a unit
+ * test, the SVG export), where `BottomRightIndicators` keeps its own anchored
+ * box. That fallback is why this can be added without every consumer changing.
+ */
+export declare const BottomRightCornerContext: import("react").Context<HTMLElement | null>;
+/**
+ * Members are stacked, not laid side by side, and ordered explicitly.
+ *
+ * Stacked because the status chip is much wider than a control (it carries a
+ * label and a 120px bar): in one horizontal row it would shove the controls
+ * leftwards whenever a background job started and let them snap back when it
+ * finished.
+ *
+ * Ordered by `order` rather than by DOM position because one member arrives as
+ * a portal and the other as an ordinary child, and the relative order of those
+ * two inside the container is not something React documents. Only the control
+ * row needs a value: the status chip takes CSS's default 0, so anything the
+ * chrome adds to the corner later sorts above the controls unless it says
+ * otherwise — which is the right default, the controls being the thing whose
+ * position in the corner users learn.
+ */
+export declare const BOTTOM_RIGHT_CONTROLS_ORDER = 1;

package/esm/bottomRightCorner.js

@@ -0,0 +1,59 @@
+import { createContext } from 'react';
+/**
+ * #api
+ * The one box per display that owns the bottom-right corner.
+ *
+ * It lives beside the overlay contract rather than with the chrome that mounts
+ * it, because it is the half of that contract the types cannot carry:
+ * `DisplayChromeOverlays.BackgroundProgress` is the one state told to render an
+ * in-flow chip with no `position` and no corner offsets, and this is the box it
+ * is laid out in. A host writing their own display over `DisplayChromeBase`
+ * needs to be able to build that corner; while this sat one layer up in the LGV
+ * plugin, the rule was a paragraph they could only obey by hand.
+ *
+ * Two independent things want that corner and neither could see the other:
+ * the display's own control row (`BottomRightIndicators` — track sizing, the
+ * isoform notice, the solo chip) and the chrome's background-progress chip
+ * (`DisplayChromeOverlays.BackgroundProgress`, the status channel for work with
+ * no fetch behind it). Both portal into the *same* per-track overlay node, and
+ * both used to claim `bottom: 2; right: 2` there with their own
+ * `position: absolute` box — so they simply drew on top of each other, the
+ * controls winning on z-index and the status text disappearing under them.
+ *
+ * It has never been reachable: the two displays that render the control row
+ * (alignments, canvas) are not among the four that report a `ready`-phase
+ * status (clustering, on multi-wiggle / multi-row features / maf / the
+ * multi-sample variant pair). That is the *reason* to make it structural rather
+ * than to leave it — nothing on either side is aware of the constraint, so the
+ * first display to want both would find the bug, and it presents as a status
+ * message that silently never appears.
+ *
+ * `BottomRightIndicators` already described itself as "the single anchor point
+ * for every bottom-right overlay ... so they lay out as one row instead of each
+ * picking their own position and colliding". This makes that true of the chip
+ * too: the chrome renders the anchor, puts its chip in it, and publishes the
+ * node here so the display's row — rendered several components away, inside the
+ * chrome's body — lands in the same flex box instead of over it.
+ *
+ * `null` outside a chrome (a display an embedder mounts standalone, a unit
+ * test, the SVG export), where `BottomRightIndicators` keeps its own anchored
+ * box. That fallback is why this can be added without every consumer changing.
+ */
+export const BottomRightCornerContext = createContext(null);
+/**
+ * Members are stacked, not laid side by side, and ordered explicitly.
+ *
+ * Stacked because the status chip is much wider than a control (it carries a
+ * label and a 120px bar): in one horizontal row it would shove the controls
+ * leftwards whenever a background job started and let them snap back when it
+ * finished.
+ *
+ * Ordered by `order` rather than by DOM position because one member arrives as
+ * a portal and the other as an ordinary child, and the relative order of those
+ * two inside the container is not something React documents. Only the control
+ * row needs a value: the status chip takes CSS's default 0, so anything the
+ * chrome adds to the corner later sorts above the controls unless it says
+ * otherwise — which is the right default, the controls being the thing whose
+ * position in the corner users learn.
+ */
+export const BOTTOM_RIGHT_CONTROLS_ORDER = 1;

package/esm/chromeOverlayContext.d.ts

@@ -0,0 +1,7 @@
+import type { DisplayChromeOverlays } from './chromeOverlays.ts';
+export declare const DisplayChromeOverlayProvider: import("react").Provider<DisplayChromeOverlays | undefined>;
+/**
+ * The set a provider installed, or `undefined` for "nobody asked". The caller
+ * supplies the default, which is what keeps this module free of one.
+ */
+export declare function useChromeOverlayOverride(): DisplayChromeOverlays | undefined;

package/esm/chromeOverlayContext.js

@@ -0,0 +1,44 @@
+import { createContext, use } from 'react';
+// The context alone, in a module of its own, so that consuming the seam does not
+// import the thing the seam exists to replace.
+//
+// `DisplayChrome.tsx` is where the Material set is bound, and it used to hold
+// this `createContext` too. That put 45 `@mui/*`-importing modules one hop from
+// `DisplayUIProvider` — the component whose whole purpose is "I do not want
+// Material UI in my app" — and the build agreed: the build-your-own site's
+// "Removing Material UI" page carried 34 first-party eager modules importing
+// `@mui/material` against 16 on the page that deliberately leaves the Material
+// chrome on screen, and 53 KB gzip more. Nothing rendered them. A DOM census
+// cannot see a module graph, so nothing said so.
+//
+// The rule that falls out, and it applies to any seam: **the override channel
+// must not live in the module that binds the default.** Everything toolkit-free
+// (`plainChromeOverlays`, `plainTrackControl`, `DisplayChromeBase`,
+// `DisplayUIProvider`) reaches zero `@mui/*` modules, and
+// `muiFreeSeam.test.ts` fails naming the import trail if that stops being true.
+/**
+ * Runtime override for the overlay set. **Defaults to undefined, not to a
+ * component set** — that is deliberate. A plain default would silently degrade
+ * every display that renders outside a provider (unit tests, SVG export,
+ * breakpoint-split-view's overlayUtils), and that degradation is invisible: the
+ * display still works, it just stops looking like JBrowse. Undefined means
+ * "nobody asked", so `DisplayChrome` keeps its MUI set and nothing changes.
+ *
+ * This is the escape hatch for embedders who want JBrowse's *own* displays
+ * (wiggle, alignments, variants — all of which import `DisplayChrome` directly
+ * and so can't be redirected at the import level) to draw with their overlays:
+ * no MUI rendered, no ThemeProvider needed, no emotion in their page.
+ *
+ * Prefer `DisplayUIProvider`, which mounts this and the track-control context
+ * together and accepts a partial set. Reach for this one only to override
+ * exactly one of the two seams.
+ */
+const DisplayChromeOverlayContext = createContext(undefined);
+export const DisplayChromeOverlayProvider = DisplayChromeOverlayContext.Provider;
+/**
+ * The set a provider installed, or `undefined` for "nobody asked". The caller
+ * supplies the default, which is what keeps this module free of one.
+ */
+export function useChromeOverlayOverride() {
+    return use(DisplayChromeOverlayContext);
+}