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

package/esm/util/installFetch.js

@@ -33,7 +33,7 @@ export async function runFetchOnce(self, active, args, { run, commit, setError,
     const { stopToken, isCurrent, statusCallback, end } = active;
     // synchronous, so it lands while this run is by construction the current one
     setError(undefined);
-    onBegin?.(active);
+    onBegin?.(stopToken);
     try {
         const result = await run(args, makeFetchContext(self, {
             stopToken,
@@ -65,7 +65,7 @@ export async function runFetchOnce(self, active, args, { run, commit, setError,
     }
 }
 /**
- * The two dev-only checks every fetch installer owes, together because they are
+ * The two contract checks every fetch installer owes, together because they are
  * the same doctrine: one reports a foundation attached twice, the other reports
  * a `reload()` the gate still declines — the dead Retry button.
  */
@@ -73,38 +73,62 @@ function installContractChecks(self, contract) {
     assertDisplayContract(self, contract);
     return makeRetryContractCheck(self);
 }
+/**
+ * The rotation for an installation that was lent none: created here, so
+ * disposed here — a lent one is the host's, and resetting its status window
+ * would drop a write the host's other operations are still owed.
+ */
+function ownRotation(self, report) {
+    const rotation = createStopTokenRotation(self, report);
+    addDisposer(self, () => {
+        rotation.dispose();
+    });
+    return rotation;
+}
 /**
  * A whole fetch, installed: the rotation, the leading-edge autorun, the
  * unconditional trigger reads, the gates, and {@link runFetchOnce} under them.
  *
- * Every fetch in the tree is this shape except one — the prerequisite reads
- * (HiC's header, the multi-sample sample list), both comparative displays, the
- * circular view's chord fetch, the breakpoint overlay fetch and the multi-way
- * synteny display's two DEPENDENT fetches (lane genes, lane links, each gated on
- * the key its own commit stamps) all take it. The
- * exception is `FetchMixin.runFetch`, the viewport fetch of an LGV display: its
- * rotation is a member rather than a closure (so `cancelFetch` can reach it)
- * and its trigger list is the per-region or global foundation's, so it holds
- * `runFetchOnce` directly and the autorun above it is that foundation's.
+ * Every fetch in the tree is this shape except one family — the prerequisite
+ * reads (HiC's header, the multi-sample sample list), the two keyed families
+ * (`installGlobalFetchAutorun` and `installComparativeFetchAutorun`, which lend
+ * `FetchMixin`'s rotation through the `rotation` option so `cancelFetch` and
+ * the Cancel button reach the fetch they install), the circular view's chord
+ * fetch, the breakpoint overlay fetch and the multi-way synteny display's two
+ * DEPENDENT fetches (lane genes, lane links, each gated on the key its own
+ * commit stamps) all take it. The
+ * exception is the per-region family's `FetchMixin.runFetch`: its trigger is
+ * `planRegionFetch`'s autorun and its commits stream per region through
+ * `ctx.commitRegion`, so it holds `runFetchOnce` directly and the autorun above
+ * it is that foundation's.
  *
  * What a caller supplies is exactly what differs between them: which reads wake
  * it (`prepare`, plus `gate`), what a round trip commits, where the loading
  * flag lives (`onBegin` / `onEnd`) and where the status goes (`report`).
- *
- * Returns the rotation's `cancel`, for a family whose model owns the user-facing
- * Cancel button: the flag alone is not a cancel — nothing rotates the token, the
- * stopped RPC stays current, and it commits over the load the user just stopped.
  */
-export function installFetch(self, { name, delay, report, gate, contract, fetchKey, committedKey, prepare, run, commit, setError, onBegin, onEnd, }) {
+export function installFetch(self, opts) {
+    const { name, delay, gate, contract, fetchKey, loadedKey, heldAnswers, prepare, run, commit, setError, onBegin, onEnd, } = opts;
     const noteFetchAutorunRun = contract === undefined ? undefined : installContractChecks(self, contract);
-    const rotation = createStopTokenRotation(self, report);
+    const lent = opts.rotation;
+    const rotation = lent === undefined ? ownRotation(self, opts.report) : lent;
     // The `reloadCounter` this installation last issued a fetch at. Per
     // installation and per instance, so a host with several fetches gives each its
     // own — and a closure rather than model state, because nothing outside reads
     // it and a volatile would be one more thing a host has to declare.
     let issuedEpoch;
-    const stamp = committedKey ? undefined : observable.box();
-    const heldKey = committedKey ?? (() => stamp.get());
+    // The skeleton's own stamp exists only where there is a key to stamp — a
+    // fetch with no `fetchKey` never reads it, so allocating one would only feed
+    // it `undefined` on every commit.
+    const stamp = loadedKey === undefined && fetchKey !== undefined
+        ? observable.box()
+        : undefined;
+    const heldKey = loadedKey ?? (() => stamp?.get());
+    // the freshness gate in whichever form the caller declared it
+    const held = heldAnswers !== undefined
+        ? heldAnswers
+        : fetchKey !== undefined
+            ? (args) => isDataCurrent(heldKey(), fetchKey(args))
+            : undefined;
     const commitAndStamp = stamp
         ? (result, args) => {
             runInAction(() => {
@@ -113,9 +137,6 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
             });
         }
         : commit;
-    addDisposer(self, () => {
-        rotation.dispose();
-    });
     leadingEdgeAutorun(self, 
     // #region voidTracking
     () => {
@@ -128,13 +149,23 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
         // Cancel would be a one-way door with a Retry button on it. Order, not
         // just position: counter first, then this, then the gates.
         const canceled = self.fetchCanceled === true;
+        // Above the gate, not only above `prepare`: teardown mutates the
+        // observables this body reads before the disposers run, and every `gate`
+        // but the breakpoint view's reaches the containing view or track through a
+        // parent walk (`host.initialized`, `isMinimized`, `getContainingView`),
+        // which throws once the node has left the tree. This catches the destroyed
+        // node; the detached-and-still-alive window (ADR-069) is covered only by
+        // the walk's own cache. Nothing is reported for a dead node — there is no
+        // Retry button left to be dead, and the check would read three more
+        // members of a corpse to decide it.
+        if (!isAlive(self)) {
+            return false;
+        }
         if (canceled || gate?.() === false) {
             noteFetchAutorunRun?.('gated');
             return false;
         }
-        // Teardown mutates observables `prepare` reads before the disposers run,
-        // and getContainingView on a detached node warns then throws.
-        const args = isAlive(self) ? prepare() : undefined;
+        const args = prepare();
         if (args === undefined) {
             noteFetchAutorunRun?.('declined');
             return false;
@@ -145,9 +176,7 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
         // consuming the retry here costs nothing — while a reload landing
         // mid-flight is answered by the re-run the counter read above already
         // guarantees.
-        if (fetchKey !== undefined &&
-            isDataCurrent(heldKey(), fetchKey(args)) &&
-            reloadEpoch === issuedEpoch) {
+        if (held !== undefined && held(args) && reloadEpoch === issuedEpoch) {
             noteFetchAutorunRun?.('declined');
             return false;
         }
@@ -174,5 +203,4 @@ export function installFetch(self, { name, delay, report, gate, contract, fetchK
     }, 
     // #endregion
     { name, delay });
-    return rotation.cancel;
 }

package/esm/util/installInitAutorun.d.ts

@@ -1,13 +1,13 @@
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 interface InitAutorunHost<T> extends IStateTreeNode {
-    init?: T;
-    setInit: (init?: T) => void;
+    pendingLaunch?: T;
+    setLaunch: (launch?: T) => void;
     setError: (error: unknown) => void;
 }
 export interface InitApplyContext {
     /**
      * True once this init can no longer be the one being applied: the node is
-     * gone, or a newer `setInit` has replaced it. Any mid-apply wait that can
+     * gone, or a newer `setLaunch` has replaced it. Any mid-apply wait that can
      * park indefinitely must fold this into its condition — an unbounded wait on
      * state that never arrives holds the drain open, and the newer init that
      * would have superseded it is exactly what gets stranded. This is the causal
@@ -26,35 +26,36 @@ interface InitAutorunOptions<T> {
      */
     ready: () => boolean;
     /**
-     * Whether the view has materialized — the same line each view's
-     * postProcessSnapshot draws for persistence (dotplot: assemblyNames set;
-     * synteny: rows built). Decides the failure policy, see below.
+     * Whether the view has materialized — the line `withLaunchInput`'s
+     * `materialized` draws for persistence, read from the live node (dotplot:
+     * assemblyNames set; synteny: rows built). Decides the failure policy, see
+     * below.
      */
     materialized: () => boolean;
     /** Apply one init blob. Owns the ordered steps; never clears `init`. */
     apply: (init: T, ctx: InitApplyContext) => Promise<void>;
 }
 /**
- * The init state machine shared by the views that take a declarative `init`
+ * The launch state machine shared by the views that take a declarative launch
  * blob (LinearGenomeView, DotplotView, LinearSyntenyView): the re-entry guard,
  * the readiness gate, the serialized drain, the identity-checked clear, the
  * isAlive guards, and one failure policy.
  *
- * The failure policy keys off `materialized`, the same line each view's
- * postProcessSnapshot already draws for persistence:
+ * The failure policy keys off `materialized`, the same line `withLaunchInput`
+ * draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - Not materialized — nothing is on screen and `launch` is still persisted, so
  *   keep it for a reload retry and `setError`. That flips the view onto its
  *   import form, which renders the error in its own banner; a snackbar would
  *   state the same failure twice and the banner is the one that persists.
  * - Materialized — the view works, so a later failure is one sub-step's
  *   problem and must not take the view down with it. `setError` would, since
  *   showImportForm keys off `error` alone and would discard rows that loaded
- *   fine, so report it as a snackbar instead. Clearing `init` is also what
+ *   fine, so report it as a snackbar instead. Clearing `launch` is also what
  *   disarms the re-fire: `ready` usually folds in the measured width, so
- *   leaving it set lets any resize re-run `apply` over a half-applied init.
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
  *
- * `apply` therefore never clears `init` and never catches for reporting — it
+ * `apply` therefore never clears `launch` and never catches for reporting — it
  * catches only the failures it wants to keep going through (a bad locstring in
  * one row), and everything it lets escape is fatal-as-of-that-point.
  */

package/esm/util/installInitAutorun.js

@@ -1,19 +1,19 @@
 import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
 import { getNotificationSink } from './sessionServices.js';
-// Clear only when `init` is still the exact object we applied. A setInit that
-// lands while `apply` is awaiting (React StrictMode remounts, a programmatic
-// re-launch) swaps in a new object; clearing unconditionally would silently
-// drop that pending init. Leaving it lets the drain loop apply it next.
+// Clear only when the pending blob is still the exact object we applied. A
+// setLaunch that lands while `apply` is awaiting (React StrictMode remounts, a
+// programmatic re-launch) swaps in a new object; clearing unconditionally would
+// silently drop it. Leaving it lets the drain loop apply it next.
 function clearIfUnchanged(self, init) {
-    if (isAlive(self) && self.init === init) {
-        self.setInit(undefined);
+    if (isAlive(self) && self.pendingLaunch === init) {
+        self.setLaunch(undefined);
     }
 }
 async function applyInitOnce(self, init, { apply, materialized }) {
     try {
         await apply(init, {
-            superseded: () => !isAlive(self) || self.init !== init,
+            superseded: () => !isAlive(self) || self.pendingLaunch !== init,
         });
         clearIfUnchanged(self, init);
     }
@@ -34,7 +34,7 @@ async function applyInitOnce(self, init, { apply, materialized }) {
     }
 }
 function currentInit(self, { ready }) {
-    return isAlive(self) && ready() ? self.init : undefined;
+    return isAlive(self) && ready() ? self.pendingLaunch : undefined;
 }
 // Apply pending inits one at a time until none remain. Serializing (rather
 // than letting the autorun run `apply` concurrently) is what keeps re-entrant
@@ -47,32 +47,32 @@ async function drainInit(self, opts) {
     while (pending !== undefined) {
         await applyInitOnce(self, pending, opts);
         const next = currentInit(self, opts);
-        // a fatal failure keeps `init` for a reload retry; the same object still
+        // a fatal failure keeps `launch` for a reload retry; the same object still
         // sitting there means it was not consumed, so stop rather than spin on it
         pending = next === pending ? undefined : next;
     }
 }
 /**
- * The init state machine shared by the views that take a declarative `init`
+ * The launch state machine shared by the views that take a declarative launch
  * blob (LinearGenomeView, DotplotView, LinearSyntenyView): the re-entry guard,
  * the readiness gate, the serialized drain, the identity-checked clear, the
  * isAlive guards, and one failure policy.
  *
- * The failure policy keys off `materialized`, the same line each view's
- * postProcessSnapshot already draws for persistence:
+ * The failure policy keys off `materialized`, the same line `withLaunchInput`
+ * draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - Not materialized — nothing is on screen and `launch` is still persisted, so
  *   keep it for a reload retry and `setError`. That flips the view onto its
  *   import form, which renders the error in its own banner; a snackbar would
  *   state the same failure twice and the banner is the one that persists.
  * - Materialized — the view works, so a later failure is one sub-step's
  *   problem and must not take the view down with it. `setError` would, since
  *   showImportForm keys off `error` alone and would discard rows that loaded
- *   fine, so report it as a snackbar instead. Clearing `init` is also what
+ *   fine, so report it as a snackbar instead. Clearing `launch` is also what
  *   disarms the re-fire: `ready` usually folds in the measured width, so
- *   leaving it set lets any resize re-run `apply` over a half-applied init.
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
  *
- * `apply` therefore never clears `init` and never catches for reporting — it
+ * `apply` therefore never clears `launch` and never catches for reporting — it
  * catches only the failures it wants to keep going through (a bad locstring in
  * one row), and everything it lets escape is fatal-as-of-that-point.
  */
@@ -93,7 +93,7 @@ export function installInitAutorun(self, opts) {
         // reading a detached node throws — here into an unawaited promise.
         const alive = isAlive(self);
         const isReady = alive && opts.ready();
-        const init = alive ? self.init : undefined;
+        const init = alive ? self.pendingLaunch : undefined;
         if (isReady && init !== undefined && !draining) {
             draining = true;
             try {

package/esm/util/installPrerequisiteFetch.d.ts

@@ -0,0 +1,86 @@
+import type { StatusReporter } from './createStopTokenRotation.ts';
+import type { FetchContext } from './fetchContext.ts';
+import type { FetchSkeletonHost } from './installFetch.ts';
+/**
+ * What a prerequisite read needs of the display it runs on, beside the
+ * skeleton's own three. Duck-typed rather than a foundation's `Instance` type,
+ * because the hosts compose different foundations — one per fetch family, and
+ * the comparative displays compose none of them — and this is the only thing
+ * they have in common.
+ */
+export interface PrerequisiteFetchHost extends FetchSkeletonHost {
+    /**
+     * Read in `prepare`, so it is **tracked**: an adapter edited in the config
+     * editor has to re-read, and `run`'s own reads are untracked by contract.
+     */
+    adapterConfig: Record<string, unknown>;
+    isMinimized: boolean;
+}
+/**
+ * A **prerequisite read**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Three in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; and the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for —
+ * and they sit on three different fetch foundations, which is why this sits in
+ * core beside the skeleton and not beside any of them.
+ *
+ * They had the shape below hand-copied, comment for comment, and each term is a
+ * rule rather than a preference:
+ *
+ * - **the adapter config is the whole trigger and the whole key.** Tracked in
+ *   `prepare` so a config-editor edit re-reads; keyed on the same value so an
+ *   un-minimize over the same file re-reads nothing. Getting one without the
+ *   other gives either a stale header or a walk of a `.hic` norm-vector index on
+ *   every expand.
+ * - **minimized is the gate**, and a display with a second condition of its own
+ *   passes `gate` — the sample-list read waits for the LGV to be measured as
+ *   well, so a full-file scan does not start ahead of the display's own first
+ *   fetch, and the tier read waits on the track declaring a tier threshold at
+ *   all.
+ * - **no `contract`.** This is the second fetch on a display whose foundation
+ *   installed both checks already: `assertDisplayContract` would report the
+ *   double-attach it exists to catch, and a second retry check would consume the
+ *   same `reloadCounter` bumps as the first.
+ * - **where the status goes is the caller's** (`report`). The two LGV reads
+ *   lend the display's own status window, so the read takes a slot beside the
+ *   primary fetch rather than opening a second writer over the one status field
+ *   (ADR-081) — and it matters more here than for most fetches: a prerequisite
+ *   runs inside the pre-first-paint window, where the scrim is up because
+ *   nothing is drawn rather than because `isLoading` is, so `statusMessage` is
+ *   the only thing that can say what is happening. The tier read narrates
+ *   nothing; a header is not a load.
+ *
+ * `createAdapterMetadataFetch` keys on the same adapter config and is
+ * deliberately NOT one of these: no trigger, no stop token and no status,
+ * because it is fetched lazily when a details widget opens and the widget opens
+ * on the result. A prerequisite read is the one a display's own fetch waits on.
+ *
+ * **A declaration, not the skeleton this name used to be.** There was an
+ * `installPrerequisiteFetch` until 2026-08-23, and `3c5aa7fce2` deleted it for
+ * a good reason: it carried a `runOne` of its own — a fifth copy of begin →
+ * clear → run → commit-if-current → `handleFetchError` → end — and once
+ * `installFetch` owned that sequence, a second one was pure drift surface. This
+ * one adds no sequence, no rotation and no error rule; it is terms handed to
+ * `installFetch`, the same shape `installGlobalFetchAutorun` and
+ * `installComparativeFetchAutorun` are. Add nothing here that a family could
+ * not state as an option to the skeleton.
+ *
+ * Everything the skeleton gives it is the point of going through the skeleton:
+ * the latest-wins rotation (so a superseding read aborts the one it replaced,
+ * and only a superseding read does — a user cancel of the primary fetch cannot
+ * strand the display the way sharing its token would), the clear at the start,
+ * the currency-guarded error rule, the unconditional `reloadCounter` read that
+ * makes the chrome's Retry re-run this, and the retired status slot that keeps a
+ * failed read from leaving a progress chip up for good.
+ */
+export declare function installPrerequisiteFetch<TResult>(self: PrerequisiteFetchHost, { name, delay, report, gate, run, commit, setError, }: {
+    name: string;
+    delay: number;
+    report: StatusReporter;
+    /** an extra term of the display's own, ANDed under `!isMinimized` */
+    gate?: () => boolean;
+    run: (adapterConfig: Record<string, unknown>, ctx: FetchContext) => Promise<TResult | undefined>;
+    commit: (result: TResult) => void;
+    setError: (error?: unknown) => void;
+}): void;

package/esm/util/installPrerequisiteFetch.js

@@ -0,0 +1,73 @@
+import { adapterConfigKey } from './adapterConfigKey.js';
+import { installFetch } from './installFetch.js';
+/**
+ * A **prerequisite read**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Three in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; and the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for —
+ * and they sit on three different fetch foundations, which is why this sits in
+ * core beside the skeleton and not beside any of them.
+ *
+ * They had the shape below hand-copied, comment for comment, and each term is a
+ * rule rather than a preference:
+ *
+ * - **the adapter config is the whole trigger and the whole key.** Tracked in
+ *   `prepare` so a config-editor edit re-reads; keyed on the same value so an
+ *   un-minimize over the same file re-reads nothing. Getting one without the
+ *   other gives either a stale header or a walk of a `.hic` norm-vector index on
+ *   every expand.
+ * - **minimized is the gate**, and a display with a second condition of its own
+ *   passes `gate` — the sample-list read waits for the LGV to be measured as
+ *   well, so a full-file scan does not start ahead of the display's own first
+ *   fetch, and the tier read waits on the track declaring a tier threshold at
+ *   all.
+ * - **no `contract`.** This is the second fetch on a display whose foundation
+ *   installed both checks already: `assertDisplayContract` would report the
+ *   double-attach it exists to catch, and a second retry check would consume the
+ *   same `reloadCounter` bumps as the first.
+ * - **where the status goes is the caller's** (`report`). The two LGV reads
+ *   lend the display's own status window, so the read takes a slot beside the
+ *   primary fetch rather than opening a second writer over the one status field
+ *   (ADR-081) — and it matters more here than for most fetches: a prerequisite
+ *   runs inside the pre-first-paint window, where the scrim is up because
+ *   nothing is drawn rather than because `isLoading` is, so `statusMessage` is
+ *   the only thing that can say what is happening. The tier read narrates
+ *   nothing; a header is not a load.
+ *
+ * `createAdapterMetadataFetch` keys on the same adapter config and is
+ * deliberately NOT one of these: no trigger, no stop token and no status,
+ * because it is fetched lazily when a details widget opens and the widget opens
+ * on the result. A prerequisite read is the one a display's own fetch waits on.
+ *
+ * **A declaration, not the skeleton this name used to be.** There was an
+ * `installPrerequisiteFetch` until 2026-08-23, and `3c5aa7fce2` deleted it for
+ * a good reason: it carried a `runOne` of its own — a fifth copy of begin →
+ * clear → run → commit-if-current → `handleFetchError` → end — and once
+ * `installFetch` owned that sequence, a second one was pure drift surface. This
+ * one adds no sequence, no rotation and no error rule; it is terms handed to
+ * `installFetch`, the same shape `installGlobalFetchAutorun` and
+ * `installComparativeFetchAutorun` are. Add nothing here that a family could
+ * not state as an option to the skeleton.
+ *
+ * Everything the skeleton gives it is the point of going through the skeleton:
+ * the latest-wins rotation (so a superseding read aborts the one it replaced,
+ * and only a superseding read does — a user cancel of the primary fetch cannot
+ * strand the display the way sharing its token would), the clear at the start,
+ * the currency-guarded error rule, the unconditional `reloadCounter` read that
+ * makes the chrome's Retry re-run this, and the retired status slot that keeps a
+ * failed read from leaving a progress chip up for good.
+ */
+export function installPrerequisiteFetch(self, { name, delay, report, gate = () => true, run, commit, setError, }) {
+    installFetch(self, {
+        name,
+        delay,
+        report,
+        gate: () => !self.isMinimized && gate(),
+        prepare: () => ({ adapterConfig: self.adapterConfig }),
+        fetchKey: ({ adapterConfig }) => adapterConfigKey(adapterConfig),
+        run: ({ adapterConfig }, ctx) => run(adapterConfig, ctx),
+        commit,
+        setError,
+    });
+}

package/esm/util/lazyAfterAttach.d.ts

@@ -0,0 +1,13 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export declare function runLazyAfterAttach<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>): void;

package/esm/util/lazyAfterAttach.js

@@ -0,0 +1,31 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export function runLazyAfterAttach(self, load) {
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    ;
+    (async () => {
+        try {
+            const install = await load();
+            if (isAlive(self)) {
+                install(self);
+            }
+        }
+        catch (e) {
+            if (isAlive(self)) {
+                console.error(e);
+                getNotificationSink(self).notifyError(`${e}`, e);
+            }
+        }
+    })();
+}

package/esm/util/legendCandidates.d.ts

@@ -0,0 +1,50 @@
+export interface LegendCandidate {
+    rowIndex: number;
+    label: string;
+    color: number;
+}
+export interface LegendEntry {
+    label: string;
+    color: number;
+}
+export declare const MAX_LEGEND_ENTRIES = 30;
+export declare const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, name, color) combinations a packer walks
+ * past, in first-seen order and bounded — the small list `unionLegendCandidates`
+ * derives a key from, so the main thread never re-walks the features. Fed scalar
+ * by scalar, from the loop that already holds the three values.
+ *
+ * Deduped on the whole triple rather than on (row, color): the union takes the
+ * first NAME it sees for a color, so where that name is already spoken for, the
+ * second name on that color has to still be in the list to carry it.
+ *
+ * A nameless feature contributes nothing, which is the union's rule too — so a
+ * track whose features have no names ships an empty list rather than one entry
+ * per feature.
+ */
+export declare function createLegendCandidateCollector(maxCandidates?: number): {
+    candidates: LegendCandidate[];
+    add(rowIndex: number, label: string, color: number): void;
+};
+export interface LegendCandidateSource {
+    candidates: readonly LegendCandidate[];
+    rowPaintsCandidateColor: (rowIndex: number) => boolean;
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color, labeled by the first name seen in that color, in first-seen
+ * order.
+ *
+ * Keyed by color rather than by name, so each key row is 1:1 with a color — a
+ * row is normally a toggle and hiding a category hides features BY color, so two
+ * names sharing one color must collapse to a single row. A name reused across
+ * two colors keeps its first-seen color.
+ *
+ * `[]` when the data carries no categorical signal: nothing named, or more than
+ * `maxEntries` distinct colors.
+ *
+ * `regions` is consumed lazily, so a caller able to answer without reading any
+ * of them can pass a generator and have none of them touched.
+ */
+export declare function unionLegendCandidates<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, maxEntries?: number): LegendEntry[];

package/esm/util/legendCandidates.js

@@ -0,0 +1,87 @@
+// How many distinct colors a derived key may name and still BE a key. Past this
+// the data is not a categorical vocabulary (a track keyed by unique per-feature
+// names), and a list of every feature is the thing a key exists instead of.
+//
+// A different question from `legendIsReadable`'s lower bar, which asks whether a
+// key a display already has is worth the rows it costs.
+export const MAX_LEGEND_ENTRIES = 30;
+// Bound on the candidate list one region ships. Far above MAX_LEGEND_ENTRIES, so
+// a vocabulary that is categorical at all crosses whole, and a track with a name
+// per feature ships a prefix that reads the same way it would have.
+export const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, name, color) combinations a packer walks
+ * past, in first-seen order and bounded — the small list `unionLegendCandidates`
+ * derives a key from, so the main thread never re-walks the features. Fed scalar
+ * by scalar, from the loop that already holds the three values.
+ *
+ * Deduped on the whole triple rather than on (row, color): the union takes the
+ * first NAME it sees for a color, so where that name is already spoken for, the
+ * second name on that color has to still be in the list to carry it.
+ *
+ * A nameless feature contributes nothing, which is the union's rule too — so a
+ * track whose features have no names ships an empty list rather than one entry
+ * per feature.
+ */
+export function createLegendCandidateCollector(maxCandidates = MAX_LEGEND_CANDIDATES) {
+    const candidates = [];
+    const colorsSeen = new Map();
+    return {
+        candidates,
+        add(rowIndex, label, color) {
+            if (label !== '' && candidates.length < maxCandidates) {
+                let byLabel = colorsSeen.get(rowIndex);
+                if (byLabel === undefined) {
+                    byLabel = new Map();
+                    colorsSeen.set(rowIndex, byLabel);
+                }
+                let colors = byLabel.get(label);
+                if (colors === undefined) {
+                    colors = new Set();
+                    byLabel.set(label, colors);
+                }
+                if (!colors.has(color)) {
+                    colors.add(color);
+                    candidates.push({ rowIndex, label, color });
+                }
+            }
+        },
+    };
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color, labeled by the first name seen in that color, in first-seen
+ * order.
+ *
+ * Keyed by color rather than by name, so each key row is 1:1 with a color — a
+ * row is normally a toggle and hiding a category hides features BY color, so two
+ * names sharing one color must collapse to a single row. A name reused across
+ * two colors keeps its first-seen color.
+ *
+ * `[]` when the data carries no categorical signal: nothing named, or more than
+ * `maxEntries` distinct colors.
+ *
+ * `regions` is consumed lazily, so a caller able to answer without reading any
+ * of them can pass a generator and have none of them touched.
+ */
+export function unionLegendCandidates(regions, resolve, maxEntries = MAX_LEGEND_ENTRIES) {
+    const entries = [];
+    const seenColors = new Set();
+    const seenLabels = new Set();
+    for (const region of regions) {
+        const { candidates, rowPaintsCandidateColor } = resolve(region);
+        for (const { rowIndex, label, color } of candidates) {
+            if (rowPaintsCandidateColor(rowIndex) &&
+                !seenLabels.has(label) &&
+                !seenColors.has(color)) {
+                seenLabels.add(label);
+                seenColors.add(color);
+                entries.push({ label, color });
+                if (entries.length > maxEntries) {
+                    return [];
+                }
+            }
+        }
+    }
+    return entries;
+}