@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.2

package/esm/pluggableElementTypes/models/BaseDisplayModel.js

@@ -1,5 +1,5 @@
 import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
-import { getConf } from '../../configuration/index.js';
+import { getConf, isConfigurationSlot, preProcessSlotValues, } from '../../configuration/index.js';
 import { getContainingTrack, getEnv, statusFraction, statusMessageText, } from '../../util/index.js';
 import { ElementId } from '../../util/types/mst.js';
 /**
@@ -210,6 +210,79 @@ function stateModelFactory() {
          * base display reload does nothing, see specialized displays for details
          */
         reload() { },
+        /**
+         * #action
+         * Apply a bag of display settings to the LIVE display, and report what
+         * landed. Each key runs through the display config schema's
+         * `preProcessSnapshot` (shorthand expansions, legacy-key migrations —
+         * the same lowering a session spec's inline track keys get in
+         * `showTrackGeneric`), then writes the matching config slot. Keys that
+         * are not slots come back in `unapplied` rather than vanishing: the
+         * settings vocabulary's historical failure mode is the silently dropped
+         * key.
+         *
+         * `allowSetters` additionally routes a non-slot key to a conventionally
+         * named single-argument `set<Key>` action. Opt-in, never the default:
+         * the declarative surfaces (session specs, share links, embeds) feed
+         * this whole bags of untyped JSON, and a blanket fallback would let
+         * them reach internal setters (`setError`, `setScrollTop`, ...) and
+         * call multi-argument setters with one argument. A caller that wants a
+         * specific action can also simply call it.
+         *
+         * A key whose write THREW is reported separately, in `failed` — it is the
+         * only one of the three that means the caller got something wrong, and
+         * the only one worth a notification. `unapplied` is not: at the
+         * `showTrackGeneric` call site it also collects keys that surface
+         * consumed itself (`type`) and MST display props the display snapshot
+         * already applied (`resolution`), so treating it as "dropped" would
+         * report a correct call as broken.
+         *
+         * Per-key errors do not abort the rest of the bag — a caller
+         * mid-`showTrack` has already pushed the track, and one rejected value
+         * must not strand a half-configured track.
+         */
+        applyDisplaySettings(settings, options) {
+            // configuration is the reference every concrete display adds at
+            // instantiation (see DisplayModel below); the base model composes
+            // before it exists, hence the cast rather than a prop
+            const { configuration } = self;
+            const applied = [];
+            const unapplied = [];
+            const failed = [];
+            const slots = preProcessSlotValues(configuration, settings);
+            for (const [key, value] of Object.entries(slots)) {
+                if (!key || key === 'type') {
+                    unapplied.push(key ? 'type (switch the display type instead)' : '(empty key)');
+                    continue;
+                }
+                try {
+                    if (isConfigurationSlot(configuration, key)) {
+                        // the key arrives from runtime JSON; setConf's slot name is a
+                        // compile-time type
+                        // eslint-disable-next-line no-restricted-syntax
+                        configuration.setSlot(key, value);
+                        applied.push(key);
+                        continue;
+                    }
+                    const setter = self[`set${key[0].toUpperCase()}${key.slice(1)}`];
+                    if (typeof setter !== 'function') {
+                        unapplied.push(key);
+                    }
+                    else if (options?.allowSetters) {
+                        ;
+                        setter(value);
+                        applied.push(`${key} (via setter)`);
+                    }
+                    else {
+                        unapplied.push(`${key} (not a config slot; a set${key[0].toUpperCase()}${key.slice(1)} action exists — call it, or pass { allowSetters: true })`);
+                    }
+                }
+                catch (e) {
+                    failed.push({ key, error: `${e}` });
+                }
+            }
+            return { applied, unapplied, failed };
+        },
     }));
 }
 export const BaseDisplay = stateModelFactory();

package/esm/pluggableElementTypes/models/BaseTrackModel.d.ts

@@ -144,6 +144,27 @@ export declare function createBaseTrackModel(pm: PluginManager, trackType: strin
      * #action
      */
     setResizing(flag: boolean): void;
+    /**
+     * #action
+     * `applyDisplaySettings` on the display being drawn (`activeDisplay`,
+     * which a shown track always has — this is not meaningful on a bare
+     * config node) — the track-level entry for "restyle this track in
+     * place" (a session spec's inline keys, an agent's settings bag). Only
+     * that one display: settings vocabularies are per display type, so
+     * broadcasting one bag across a track's other displays would mis-route
+     * keys; address a non-active display directly if that is what you mean.
+     * See BaseDisplayModel for the routing and the `allowSetters` opt-in.
+     */
+    applyDisplaySettings(settings: Record<string, unknown>, options?: {
+        allowSetters?: boolean;
+    }): {
+        applied: string[];
+        unapplied: string[];
+        failed: {
+            key: string;
+            error: string;
+        }[];
+    };
     /**
      * #action
      */

package/esm/pluggableElementTypes/models/BaseTrackModel.js

@@ -1,5 +1,5 @@
 import { lazy } from 'react';
-import { addDisposer, getSnapshot, types } from '@jbrowse/mobx-state-tree';
+import { addDisposer, getSnapshot, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import Save from '@mui/icons-material/Save';
 import { compareStructural, reaction } from 'mobx';
 import { ConfigurationReference, getConf } from '../../configuration/index.js';
@@ -251,6 +251,20 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
         setResizing(flag) {
             self.resizing = flag;
         },
+        /**
+         * #action
+         * `applyDisplaySettings` on the display being drawn (`activeDisplay`,
+         * which a shown track always has — this is not meaningful on a bare
+         * config node) — the track-level entry for "restyle this track in
+         * place" (a session spec's inline keys, an agent's settings bag). Only
+         * that one display: settings vocabularies are per display type, so
+         * broadcasting one bag across a track's other displays would mis-route
+         * keys; address a non-active display directly if that is what you mean.
+         * See BaseDisplayModel for the routing and the `allowSetters` opt-in.
+         */
+        applyDisplaySettings(settings, options) {
+            return self.activeDisplay.applyDisplaySettings(settings, options);
+        },
         /**
          * #action
          */
@@ -261,6 +275,12 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
             }
             const displays = self.configuration.displays;
             const displayConf = getDisplayConf(displays, newDisplayId);
+            // same interception showTrackGeneric makes: a registered-but-unloaded
+            // display would otherwise fail as an opaque union mismatch below
+            const displayRecord = pm.resolveDisplayTypeRecord(displayConf.type);
+            if (displayRecord && !displayRecord.isStateModelLoaded) {
+                throw new Error(`state model for display type ${displayConf.type} is not loaded yet — await getDisplayType('${displayConf.type}').loadStateModel() first`);
+            }
             self.displays[idx] = {
                 ...initialSnapshot,
                 type: displayConf.type,
@@ -434,9 +454,24 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
                                     // being replaced, so leaving the menu up would keep a
                                     // list of items built against a destroyed MST node
                                     keepMenuOpen: false,
+                                    // the chosen display's state model may still be a dynamic
+                                    // import away, so load it before swapping — replaceDisplay
+                                    // itself stays a plain sync action
                                     onClick: () => {
                                         if (d.displayId !== shownId) {
-                                            self.replaceDisplay(shownId, d.displayId, self.activeDisplay.getPortableSettings?.(d.displayId) ?? {});
+                                            void (async () => {
+                                                try {
+                                                    await pm
+                                                        .resolveDisplayTypeRecord(d.type)
+                                                        ?.loadStateModel();
+                                                    if (isAlive(self)) {
+                                                        self.replaceDisplay(shownId, d.displayId, self.activeDisplay.getPortableSettings?.(d.displayId) ?? {});
+                                                    }
+                                                }
+                                                catch (e) {
+                                                    getSession(self).notifyError(`${e}`, e);
+                                                }
+                                            })();
                                         }
                                     },
                                 };

package/esm/pluggableElementTypes/models/BaseViewModel.d.ts

@@ -1,4 +1,5 @@
 import type { MenuItem } from '../../ui/index.ts';
+import type { AbstractTrackModel, AbstractViewModel } from '../../util/types/index.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
 /**
  * #stateModel BaseViewModel
@@ -66,6 +67,30 @@ declare const BaseViewModel: import("@jbrowse/mobx-state-tree").IModelType<{
      * #method
      */
     menuItems(): MenuItem[];
+    /**
+     * #getter
+     * Every track open on this view itself: its own `tracks` array plus any
+     * track containers it owns instead (the synteny view keeps one list per
+     * band on `trackContainers` and its own `tracks` empty). Tracks on nested
+     * views are `allTracks`'s, not this getter's.
+     */
+    readonly ownTracks: AbstractTrackModel[];
+    /**
+     * #getter
+     * This view and every view nested inside it, to any depth — a synteny
+     * stack's genome rows, a breakpoint split view's panels. Each view answers
+     * for its own children, so a consumer never walks the nesting itself:
+     * before this getter, four consumers each carried a copy of the walk and
+     * two of them had drifted (one read `levels`, one read `trackContainers`,
+     * and each was blind to the other's spelling).
+     */
+    readonly allViews: AbstractViewModel[];
+} & {
+    /**
+     * #getter
+     * Every track open on this view or any view nested inside it.
+     */
+    readonly allTracks: AbstractTrackModel[];
 } & {
     /**
      * #action
@@ -172,6 +197,30 @@ export declare const BaseViewModelWithDisplayedRegions: import("@jbrowse/mobx-st
      * #method
      */
     menuItems(): MenuItem[];
+    /**
+     * #getter
+     * Every track open on this view itself: its own `tracks` array plus any
+     * track containers it owns instead (the synteny view keeps one list per
+     * band on `trackContainers` and its own `tracks` empty). Tracks on nested
+     * views are `allTracks`'s, not this getter's.
+     */
+    readonly ownTracks: AbstractTrackModel[];
+    /**
+     * #getter
+     * This view and every view nested inside it, to any depth — a synteny
+     * stack's genome rows, a breakpoint split view's panels. Each view answers
+     * for its own children, so a consumer never walks the nesting itself:
+     * before this getter, four consumers each carried a copy of the walk and
+     * two of them had drifted (one read `levels`, one read `trackContainers`,
+     * and each was blind to the other's spelling).
+     */
+    readonly allViews: AbstractViewModel[];
+} & {
+    /**
+     * #getter
+     * Every track open on this view or any view nested inside it.
+     */
+    readonly allTracks: AbstractTrackModel[];
 } & {
     /**
      * #action

package/esm/pluggableElementTypes/models/BaseViewModel.js

@@ -94,6 +94,45 @@ const BaseViewModel = types
     menuItems() {
         return [];
     },
+    /**
+     * #getter
+     * Every track open on this view itself: its own `tracks` array plus any
+     * track containers it owns instead (the synteny view keeps one list per
+     * band on `trackContainers` and its own `tracks` empty). Tracks on nested
+     * views are `allTracks`'s, not this getter's.
+     */
+    get ownTracks() {
+        const s = self;
+        return [
+            ...(s.tracks ?? []),
+            ...(s.trackContainers ?? []).flatMap(c => c.tracks ?? []),
+        ];
+    },
+    /**
+     * #getter
+     * This view and every view nested inside it, to any depth — a synteny
+     * stack's genome rows, a breakpoint split view's panels. Each view answers
+     * for its own children, so a consumer never walks the nesting itself:
+     * before this getter, four consumers each carried a copy of the walk and
+     * two of them had drifted (one read `levels`, one read `trackContainers`,
+     * and each was blind to the other's spelling).
+     */
+    get allViews() {
+        const s = self;
+        return [
+            self,
+            ...(s.views ?? []).flatMap(v => v.allViews ?? []),
+        ];
+    },
+}))
+    .views(self => ({
+    /**
+     * #getter
+     * Every track open on this view or any view nested inside it.
+     */
+    get allTracks() {
+        return self.allViews.flatMap(v => v.ownTracks);
+    },
 }))
     .actions(self => ({
     /**

package/esm/pluggableElementTypes/models/assertDisplayContract.d.ts

@@ -1,8 +1,10 @@
 import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
 /**
- * Dev-only check that a display's fetch foundation attached it exactly once —
- * the one ordering contract here that is a *state* rather than a declaration,
- * so no selector can reach it. No-op in production.
+ * Checks that a display's fetch foundation attached it exactly once — the one
+ * ordering contract here that is a *state* rather than a declaration, so no
+ * selector can reach it. Costs a `WeakSet` lookup, so it runs in a production
+ * build too and reports through `contractReports`, which is silent until
+ * something arms it.
  *
  * Called once per display from **whichever fetch foundation installed its
  * autoruns** — `MultiRegionDisplayMixin`'s `afterAttach` for the per-region
@@ -69,14 +71,15 @@ interface RetryContractHost {
      */
     viewportEmpty?: boolean;
 }
-/** Called by `FetchMixin.runFetch`. Dev-only. */
+/** Called by `FetchMixin.runFetch`. */
 export declare function noteFetchStarted(self: object): void;
 /** Reads and clears the flag above, so each check starts from a known state. */
 export declare function takeFetchStarted(self: object): boolean;
 /**
- * Dev-only check that a display's `reload()` can actually reach a fetch — the
- * retry contract, which `DisplayErrorBar` depends on and which no type can
- * state. No-op in production.
+ * Checks that a display's `reload()` can actually reach a fetch — the retry
+ * contract, which `DisplayErrorBar` depends on and which no type can state.
+ * Costs an `untracked` read per autorun run against a fetch, so it runs in a
+ * production build too and reports through `contractReports`.
  *
  * **The button is the contract.** `DisplayErrorBar`'s only action is
  * `model.reload()`, so every state that can raise the error bar has to be one

package/esm/pluggableElementTypes/models/assertDisplayContract.js

@@ -1,19 +1,19 @@
 import { getMembers } from '@jbrowse/mobx-state-tree';
+import { reportContractViolation } from '@jbrowse/render-core/contractReports';
 import { untracked } from 'mobx';
 // Nodes whose fetch foundation has already installed its autoruns. Keyed on the
 // node rather than the model type: every display of a type would otherwise
 // report from the second instance onward.
 const attached = new WeakSet();
 function report(message) {
-    // `console.error`, never `throw`: an error escaping `afterAttach` is read by
-    // the session loader as an invalid track and the display is silently dropped
-    // — which would hide the very contract violation this is reporting.
-    console.error(`[jbrowse display contract] ${message}`);
+    reportContractViolation('display', message);
 }
 /**
- * Dev-only check that a display's fetch foundation attached it exactly once —
- * the one ordering contract here that is a *state* rather than a declaration,
- * so no selector can reach it. No-op in production.
+ * Checks that a display's fetch foundation attached it exactly once — the one
+ * ordering contract here that is a *state* rather than a declaration, so no
+ * selector can reach it. Costs a `WeakSet` lookup, so it runs in a production
+ * build too and reports through `contractReports`, which is silent until
+ * something arms it.
  *
  * Called once per display from **whichever fetch foundation installed its
  * autoruns** — `MultiRegionDisplayMixin`'s `afterAttach` for the per-region
@@ -46,19 +46,17 @@ function report(message) {
  * points nowhere near the cause.
  */
 export function assertDisplayContract(self, installedBy = "the per-region fetch foundation's afterAttach") {
-    if (process.env.NODE_ENV !== 'production') {
-        if (attached.has(self)) {
-            report(`${getMembers(self).name}: ${installedBy} ran twice on one display, ` +
-                `so its fetch autoruns are installed twice (double fetches, double ` +
-                `clears). Our MST fork auto-chains lifecycle hooks, so the usual ` +
-                `cause is a superAfterAttach() call in this display's afterAttach — ` +
-                `delete it. Otherwise this display composes two fetch foundations, ` +
-                `or calls an installer it already gets from a mixin. ` +
-                `See agent-docs/ARCHITECTURE.md §"What not to do".`);
-        }
-        else {
-            attached.add(self);
-        }
+    if (attached.has(self)) {
+        report(`${getMembers(self).name}: ${installedBy} ran twice on one display, ` +
+            `so its fetch autoruns are installed twice (double fetches, double ` +
+            `clears). Our MST fork auto-chains lifecycle hooks, so the usual ` +
+            `cause is a superAfterAttach() call in this display's afterAttach — ` +
+            `delete it. Otherwise this display composes two fetch foundations, ` +
+            `or calls an installer it already gets from a mixin. ` +
+            `See agent-docs/ARCHITECTURE.md §"What not to do".`);
+    }
+    else {
+        attached.add(self);
     }
 }
 // Displays whose fetch has started since the last time the caller looked, and
@@ -85,11 +83,8 @@ export function assertDisplayContract(self, installedBy = "the per-region fetch
 // on the display with the liveliest one.
 const fetchStarted = new WeakSet();
 const ledgers = new WeakMap();
-/** Called by `FetchMixin.runFetch`. Dev-only. */
+/** Called by `FetchMixin.runFetch`. */
 export function noteFetchStarted(self) {
-    if (process.env.NODE_ENV === 'production') {
-        return;
-    }
     fetchStarted.add(self);
     ledgers.get(self)?.('fetched');
 }
@@ -98,9 +93,10 @@ export function takeFetchStarted(self) {
     return fetchStarted.delete(self);
 }
 /**
- * Dev-only check that a display's `reload()` can actually reach a fetch — the
- * retry contract, which `DisplayErrorBar` depends on and which no type can
- * state. No-op in production.
+ * Checks that a display's `reload()` can actually reach a fetch — the retry
+ * contract, which `DisplayErrorBar` depends on and which no type can state.
+ * Costs an `untracked` read per autorun run against a fetch, so it runs in a
+ * production build too and reports through `contractReports`.
  *
  * **The button is the contract.** `DisplayErrorBar`'s only action is
  * `model.reload()`, so every state that can raise the error bar has to be one
@@ -195,9 +191,6 @@ export function takeFetchStarted(self) {
  * is worse than the bug being checked for.
  */
 export function makeRetryContractCheck(self) {
-    if (process.env.NODE_ENV === 'production') {
-        return () => { };
-    }
     // eslint-disable-next-line no-restricted-syntax -- instrumentation
     let lastCounter = untracked(() => self.reloadCounter);
     function noteRetryContractOutcome(outcome) {

package/esm/rpc/RpcRegistry.d.ts

@@ -1,3 +1,4 @@
+import type { FeatureDensity } from '../data_adapters/BaseAdapter/featureDensity.ts';
 import type { StatusCallback } from '../util/progress.ts';
 import type { UnwrapRpcResult } from '../util/rpc.ts';
 import type { Feature, SimpleFeatureSerialized } from '../util/simpleFeature.ts';
@@ -52,6 +53,15 @@ export interface RpcRegistry {
         };
         return: number | undefined;
     };
+    CoreGetFeatureDensity: {
+        args: {
+            adapterConfig: Record<string, unknown>;
+            regions: RegionLike[];
+            bpPerPx: number;
+            headers?: Record<string, string>;
+        };
+        return: FeatureDensity[] | undefined;
+    };
     CoreGetInfo: {
         args: {
             adapterConfig: Record<string, unknown>;

package/esm/rpc/byteBudget.d.ts

@@ -6,6 +6,15 @@ import type { AugmentedRegion } from '../util/types/data.ts';
  * budget, or the save dialog's bound on the whole download.
  */
 export type ByteEstimateScope = 'largestRegion' | 'wholeRequest';
+/**
+ * The one spelling of a gated feature RPC's budget argument: the number the
+ * worker measures against, undefined when the gate declined to act and nothing
+ * is measured. A call-site argument, never part of `rpcProps`, because it
+ * swings at 20kb and on force-load.
+ */
+export interface GatedFetchArgs {
+    byteLimit?: number;
+}
 export interface ByteMeasurableAdapter {
     getRegionByteSize: (regions: AugmentedRegion[], opts?: {
         stopToken?: StopToken;

package/esm/rpc/coreRpcMethods.d.ts

@@ -5,5 +5,6 @@ export { default as CoreGetFeatures } from './methods/CoreGetFeatures.ts';
 export { default as CoreGetSequence } from './methods/CoreGetSequence.ts';
 export { default as CoreFreeResources } from './methods/CoreFreeResources.ts';
 export { default as CoreGetRegionByteEstimate } from './methods/CoreGetRegionByteEstimate.ts';
+export { default as CoreGetFeatureDensity } from './methods/CoreGetFeatureDensity.ts';
 export { default as CoreGetRegions } from './methods/CoreGetRegions.ts';
 export { default as CoreGetExportData } from './methods/CoreGetExportData.ts';

package/esm/rpc/coreRpcMethods.js

@@ -5,5 +5,6 @@ export { default as CoreGetFeatures } from './methods/CoreGetFeatures.js';
 export { default as CoreGetSequence } from './methods/CoreGetSequence.js';
 export { default as CoreFreeResources } from './methods/CoreFreeResources.js';
 export { default as CoreGetRegionByteEstimate } from './methods/CoreGetRegionByteEstimate.js';
+export { default as CoreGetFeatureDensity } from './methods/CoreGetFeatureDensity.js';
 export { default as CoreGetRegions } from './methods/CoreGetRegions.js';
 export { default as CoreGetExportData } from './methods/CoreGetExportData.js';

package/esm/rpc/methods/CoreGetFeatureDensity.d.ts

@@ -0,0 +1,11 @@
+import RpcMethodTypeWithRenameRegions from '../../pluggableElementTypes/RpcMethodTypeWithRenameRegions.ts';
+import type { RpcExecuteArgs } from '../RpcRegistry.ts';
+/**
+ * The density tier's read: features per bin at the view's bp/px for regions the
+ * region-too-large gate refused. Answers `undefined` for an adapter with no
+ * density source, and the display keeps the banner.
+ */
+export default class CoreGetFeatureDensity extends RpcMethodTypeWithRenameRegions<'CoreGetFeatureDensity'> {
+    name: 'CoreGetFeatureDensity';
+    execute(args: RpcExecuteArgs<'CoreGetFeatureDensity'>): Promise<import("../../data_adapters/BaseAdapter/featureDensity.ts").FeatureDensity[] | undefined>;
+}

package/esm/rpc/methods/CoreGetFeatureDensity.js

@@ -0,0 +1,22 @@
+import { isFeatureAdapter } from '../../data_adapters/BaseAdapter/index.js';
+import { getAdapter } from '../../data_adapters/dataAdapterCache.js';
+import RpcMethodTypeWithRenameRegions from '../../pluggableElementTypes/RpcMethodTypeWithRenameRegions.js';
+/**
+ * The density tier's read: features per bin at the view's bp/px for regions the
+ * region-too-large gate refused. Answers `undefined` for an adapter with no
+ * density source, and the display keeps the banner.
+ */
+export default class CoreGetFeatureDensity extends RpcMethodTypeWithRenameRegions {
+    name = 'CoreGetFeatureDensity';
+    async execute(args) {
+        const { adapterConfig, sessionId, regions, bpPerPx, stopToken } = args;
+        const { dataAdapter } = await getAdapter(this.pluginManager, sessionId, adapterConfig);
+        return isFeatureAdapter(dataAdapter)
+            ? dataAdapter.getFeatureDensity(regions, {
+                bpPerPx,
+                stopToken,
+                statusCallback: args.statusCallback,
+            })
+            : undefined;
+    }
+}

package/esm/svg/svgReady.d.ts

@@ -94,6 +94,7 @@ export declare function awaitSvgReady(model: Pick<SvgExportable, 'svgReady' | 'e
 export declare function awaitViewInitialized(view: {
     initialized: boolean;
     error: unknown;
+    pendingLaunch?: unknown;
 }): Promise<void>;
 /**
  * How the export answers "a track failed": by failing. A track whose data won't

package/esm/ui/CascadingMenu.js

@@ -6,7 +6,7 @@ import { makeStyles } from '../util/tss-react/index.js';
 import { useEventCallback } from '../util/useEventCallback.js';
 import HoverMenu from './HoverMenu.js';
 import { MenuItemTrailing } from './MenuItemTrailing.js';
-import { staysOpenOnClick } from './MenuTypes.js';
+import { resolveSubMenu, staysOpenOnClick } from './MenuTypes.js';
 import { hasMenuItemAdornment } from './menuItemAdornment.js';
 import { isAimedAtPanel } from './submenuAim.js';
 // Compact section headers so tall menus (e.g. a display's flat "Show..."
@@ -24,6 +24,12 @@ const useStyles = makeStyles()(theme => ({
         borderTop: `1px solid ${theme.palette.divider}`,
         marginTop: 4,
     },
+    // a leading subHeader has no rows above it to divide from, so the rule and
+    // its space would float against the menu's top edge
+    leadingSubHeader: {
+        borderTopWidth: 0,
+        marginTop: 0,
+    },
 }));
 const CascadingMenuContext = createContext(undefined);
 function useCascadingMenu() {
@@ -312,17 +318,36 @@ function CascadingSubmenu({ item, itemKey, inset, columns, hover, onNavigateBack
                 // up
                 paperRef: isOpen ? hover.panelRef : undefined, onClose: () => {
                     hover.setSubmenu(undefined);
-                }, children: _jsx(CascadingMenuList, { menuItems: item.subMenu, onNavigateBack: () => {
+                }, children: _jsx(SubMenuList, { item: item, onNavigateBack: () => {
                         hover.setSubmenu(undefined);
                         anchorEl?.focus();
                     } }) })] }));
 }
+// Resolves the rows inside the panel, which MUI mounts only while it is open:
+// a function-form `subMenu` is not called by listing the parent menu. An
+// observer so the observables that builder reads re-render the open panel, the
+// way an array built in the root observer's render already did.
+const SubMenuList = observer(function SubMenuList({ item, onNavigateBack, }) {
+    return (_jsx(CascadingMenuList, { menuItems: resolveSubMenu(item), onNavigateBack: onNavigateBack }));
+});
 // One clickable menu row: label (with optional leading icon) plus its trailing
 // value/help/adornment decorations. The menu-wide `columns` flags let every row
 // reserve matching decoration slots so the columns line up down the menu.
 function CascadingMenuItem({ item, inset, columns, onNavigateBack, onHover, }) {
     const { closeAfterItemClick, onMenuItemClick, onCloseRoot } = useCascadingMenu();
-    return (_jsx(DisabledTooltip, { item: item, children: _jsxs(MenuItem, { "data-testid": makeTestId('menuitem', item.label), disabled: item.disabled, onClick: () => {
+    return (_jsx(DisabledTooltip, { item: item, children: _jsxs(MenuItem, { "data-testid": makeTestId('menuitem', item.label), disabled: item.disabled, 
+            // A checkbox or radio row states its own value. The glyph
+            // `MenuItemEndDecoration` swaps is an `aria-hidden` icon, so without
+            // these a screen reader reads "Curved lines" identically whether the
+            // setting is on or off, and a test has no way to ask but the MUI icon's
+            // internal testid.
+            role: item.type === 'checkbox'
+                ? 'menuitemcheckbox'
+                : item.type === 'radio'
+                    ? 'menuitemradio'
+                    : undefined, "aria-checked": item.type === 'checkbox' || item.type === 'radio'
+                ? item.checked
+                : undefined, onClick: () => {
                 // onCloseRoot runs before the callback, so item.onClick must NOT read
                 // model state that closing clears (e.g. a right-click menu's ephemeral
                 // hit/context fields): capture that state when the menu items are
@@ -339,7 +364,7 @@ function CascadingMenuItem({ item, inset, columns, onNavigateBack, onHover, }) {
             }, children: [_jsx(MenuItemLeadingIcon, { Icon: item.icon }), _jsx(ListItemText, { primary: item.label, secondary: item.subLabel, inset: inset }), _jsx(MenuItemTrailing, { item: item, columns: columns })] }) }));
 }
 function CascadingMenuList({ menuItems, onNavigateBack, }) {
-    const { classes } = useStyles();
+    const { classes, cx } = useStyles();
     const hover = useSubmenuHover();
     // every row a pointer can rest on asks for the open panel to go away; only a
     // row that owns a submenu, or the panel itself, keeps one up. Whether the ask
@@ -360,10 +385,7 @@ function CascadingMenuList({ menuItems, onNavigateBack, }) {
                 return _jsx(Divider, { component: "li" }, `divider-${idx}`);
             }
             if (item.type === 'subHeader') {
-                return (_jsx(ListSubheader, { className: classes.subHeader, onMouseEnter: closeOnHover, 
-                    // a leading subHeader has no rows above it to divide from, so drop
-                    // the divider rule that would otherwise float at the menu's top edge
-                    sx: idx === 0 ? { borderTop: 'none', marginTop: 0 } : undefined, children: item.label }, `subHeader-${item.label}`));
+                return (_jsx(ListSubheader, { className: cx(classes.subHeader, idx === 0 && classes.leadingSubHeader), onMouseEnter: closeOnHover, children: item.label }, `subHeader-${item.label}`));
             }
             if (item.type === 'custom') {
                 return (_jsx(CustomMenuRow, { item: item, onHover: closeOnHover }, `custom-${item.label}`));

package/esm/ui/LoadingOverlay.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Returns false, then flips true once `active` has stayed true continuously for
+ * `delayMs`. Each activation gets a fresh delay, and the flag drops the moment
+ * `active` does.
+ *
+ * Keyed on a count of RISING edges rather than on `active` itself, so the
+ * falling edge does no work at all. A display refetching through a wheel zoom
+ * flips `active` several times a second — it finishes a fetch, waits out the
+ * debounce, starts the next — and an effect depending on `active` tore its timer
+ * down and built a new one on each of those, twice over, for a scrim that by
+ * construction never appears. Deriving the flag from a comparison instead means
+ * one `setTimeout` per loading pulse, which is the floor for these semantics.
+ */
+export declare function useDelayedFlag(active: boolean, delayMs: number): boolean;
 export default function LoadingOverlay({ statusMessage, progress, isVisible, immediate, canceled, onCancel, onRetry, }: {
     statusMessage?: string;
     progress?: number;

package/esm/ui/LoadingOverlay.js

@@ -27,7 +27,7 @@ const flashDelayMs = 250;
  * construction never appears. Deriving the flag from a comparison instead means
  * one `setTimeout` per loading pulse, which is the floor for these semantics.
  */
-function useDelayedFlag(active, delayMs) {
+export function useDelayedFlag(active, delayMs) {
     const [previous, setPrevious] = useState(active);
     const [activation, setActivation] = useState(0);
     if (previous !== active) {