@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/quantileExtent.d.ts

@@ -0,0 +1,49 @@
+/** The quantile "Clip outliers" clips at on a scale whose own default is the extremes. */
+export declare const DEFAULT_CLIP_QUANTILE = 0.99;
+/**
+ * #api
+ * The quantile a clip toggle writes: a scale's declared default where that
+ * clips, below 1, else {@link DEFAULT_CLIP_QUANTILE}.
+ */
+export declare function clipQuantileOf(declaredDefault: unknown): number;
+/**
+ * #api
+ * The `k`th smallest of `a[0, n)`, permuting `a` in place. Exact, where a
+ * histogram collapses skewed contact counts into its bottom bucket, and O(n)
+ * where a sort of 4.5M counts measured ~1s. Median-of-three because Hi-C
+ * contacts arrive nearly sorted.
+ */
+export declare function selectNth(a: Float32Array, n: number, k: number): number;
+/**
+ * #api
+ * The least and greatest finite values of `values[0, count)`,
+ * `[Infinity, -Infinity]` where none is finite.
+ */
+export declare function finiteExtremes(values: ArrayLike<number>, count: number): [number, number];
+/**
+ * #api
+ * The nearest-rank `quantile` of `a[0, n)`: the smallest value at least that
+ * share of them sit at or below, so a handful of values clips at their
+ * maximum. Permutes `a`; 0 where `n` is.
+ */
+export declare function quantileOf(a: Float32Array, n: number, quantile: number): number;
+/**
+ * #api
+ * What the open ends of a scale follow over `values[0, count)`: at a
+ * `quantile` of 1 their finite extremes, and below it each end clipped at
+ * that quantile of the values on its side of 0, so one spike takes neither
+ * the axis nor the ramp, and a sparse tail of the other sign keeps its own
+ * end. An axis that starts at 0 adds it itself. Under 0.5 reads as 0.5,
+ * where the ends meet rather than cross. `scales.y.domainQuantile` and a
+ * colour's `domainQuantile` both name it. `[Infinity, -Infinity]` where
+ * nothing is finite.
+ */
+export declare function quantileExtent(values: ArrayLike<number>, count: number, quantile?: number): [number, number];
+/**
+ * #api
+ * {@link quantileExtent} as a scale's open ends read it: over every finite
+ * value on a linear scale, and on a log scale over the positive ones, since a
+ * 0 or a negative met there would floor the domain at 1 and fold a domain
+ * below 1 flat. `[Infinity, -Infinity]` where the scale reads nothing.
+ */
+export declare function scaleExtent(values: ArrayLike<number>, count: number, scale: string, quantile?: number): [number, number];

package/esm/util/quantileExtent.js

@@ -0,0 +1,162 @@
+/** The quantile "Clip outliers" clips at on a scale whose own default is the extremes. */
+export const DEFAULT_CLIP_QUANTILE = 0.99;
+/**
+ * #api
+ * The quantile a clip toggle writes: a scale's declared default where that
+ * clips, below 1, else {@link DEFAULT_CLIP_QUANTILE}.
+ */
+export function clipQuantileOf(declaredDefault) {
+    return typeof declaredDefault === 'number' && declaredDefault < 1
+        ? declaredDefault
+        : DEFAULT_CLIP_QUANTILE;
+}
+function swap(a, i, j) {
+    const t = a[i];
+    a[i] = a[j];
+    a[j] = t;
+}
+/**
+ * #api
+ * The `k`th smallest of `a[0, n)`, permuting `a` in place. Exact, where a
+ * histogram collapses skewed contact counts into its bottom bucket, and O(n)
+ * where a sort of 4.5M counts measured ~1s. Median-of-three because Hi-C
+ * contacts arrive nearly sorted.
+ */
+export function selectNth(a, n, k) {
+    let lo = 0;
+    let hi = n - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (a[mid] < a[lo]) {
+            swap(a, mid, lo);
+        }
+        if (a[hi] < a[lo]) {
+            swap(a, hi, lo);
+        }
+        if (a[hi] < a[mid]) {
+            swap(a, hi, mid);
+        }
+        const pivot = a[mid];
+        let i = lo;
+        let j = hi;
+        while (i <= j) {
+            while (a[i] < pivot) {
+                i++;
+            }
+            while (a[j] > pivot) {
+                j--;
+            }
+            if (i <= j) {
+                swap(a, i, j);
+                i++;
+                j--;
+            }
+        }
+        if (k <= j) {
+            hi = j;
+        }
+        else if (k >= i) {
+            lo = i;
+        }
+        else {
+            return a[k];
+        }
+    }
+    return a[k];
+}
+/**
+ * #api
+ * The least and greatest finite values of `values[0, count)`,
+ * `[Infinity, -Infinity]` where none is finite.
+ */
+export function finiteExtremes(values, count) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < count; i++) {
+        const v = values[i];
+        if (Number.isFinite(v)) {
+            if (v < min) {
+                min = v;
+            }
+            if (v > max) {
+                max = v;
+            }
+        }
+    }
+    return [min, max];
+}
+/**
+ * #api
+ * The nearest-rank `quantile` of `a[0, n)`: the smallest value at least that
+ * share of them sit at or below, so a handful of values clips at their
+ * maximum. Permutes `a`; 0 where `n` is.
+ */
+export function quantileOf(a, n, quantile) {
+    return n === 0
+        ? 0
+        : selectNth(a, n, Math.min(n - 1, Math.max(0, Math.ceil(quantile * n) - 1)));
+}
+function lowQuantileOf(a, n, quantile) {
+    return n === 0
+        ? 0
+        : selectNth(a, n, Math.max(0, Math.min(n - 1, n - Math.ceil(quantile * n))));
+}
+/**
+ * #api
+ * What the open ends of a scale follow over `values[0, count)`: at a
+ * `quantile` of 1 their finite extremes, and below it each end clipped at
+ * that quantile of the values on its side of 0, so one spike takes neither
+ * the axis nor the ramp, and a sparse tail of the other sign keeps its own
+ * end. An axis that starts at 0 adds it itself. Under 0.5 reads as 0.5,
+ * where the ends meet rather than cross. `scales.y.domainQuantile` and a
+ * colour's `domainQuantile` both name it. `[Infinity, -Infinity]` where
+ * nothing is finite.
+ */
+export function quantileExtent(values, count, quantile = 1) {
+    if (!(quantile < 1)) {
+        return finiteExtremes(values, count);
+    }
+    const q = Math.max(0.5, quantile);
+    const positive = new Float32Array(count);
+    const negative = new Float32Array(count);
+    let np = 0;
+    let nn = 0;
+    for (let i = 0; i < count; i++) {
+        const v = values[i];
+        if (Number.isFinite(v)) {
+            if (v >= 0) {
+                positive[np++] = v;
+            }
+            else {
+                negative[nn++] = v;
+            }
+        }
+    }
+    if (np + nn === 0) {
+        return [Infinity, -Infinity];
+    }
+    const low = nn > 0 ? lowQuantileOf(negative, nn, q) : lowQuantileOf(positive, np, q);
+    const high = np > 0 ? quantileOf(positive, np, q) : quantileOf(negative, nn, q);
+    return [Math.min(low, high), high];
+}
+/**
+ * #api
+ * {@link quantileExtent} as a scale's open ends read it: over every finite
+ * value on a linear scale, and on a log scale over the positive ones, since a
+ * 0 or a negative met there would floor the domain at 1 and fold a domain
+ * below 1 flat. `[Infinity, -Infinity]` where the scale reads nothing.
+ */
+export function scaleExtent(values, count, scale, quantile = 1) {
+    if (scale !== 'log') {
+        return quantileExtent(values, count, quantile);
+    }
+    const positive = new Float32Array(count);
+    let np = 0;
+    for (let i = 0; i < count; i++) {
+        const v = values[i];
+        if (v > 0 && Number.isFinite(v)) {
+            positive[np++] = v;
+        }
+    }
+    return quantileExtent(positive, np, quantile);
+}

package/esm/util/range.d.ts

@@ -1,3 +1,48 @@
+/**
+ * fast low-level intersection of 2 coordinate ranges. assumes interbase coordinates.
+ *
+ * assumes `left <= right` for both ranges
+ *
+ * @returns array of [left, right], or [] if the ranges do not intersect. the choice of [] is because it allows destructuring array assignment without check for undefined return
+ */
 export declare function intersection2(left1: number, right1: number, left2: number, right2: number): [number, number] | [];
+/**
+ * Return whether 2 interbase coordinate ranges intersect.
+ *
+ * @param left1 -
+ * @param right1 -
+ * @param left2 -
+ * @param right2 -
+ *
+ * @returns true if the two ranges intersect
+ */
 export declare function doesIntersect2(left1: number, right1: number, left2: number, right2: number): boolean;
-export declare function isContainedWithin(left1: number, right1: number, left2: number, right2: number): boolean;
+/**
+ * Compute the expanded fetch range a tabix adapter must "redispatch" to when
+ * features found in a query extend past the requested window. Returns the union
+ * of the query with the bounds of every line `expands` admits, or `undefined`
+ * when nothing extends past the query (no redispatch needed).
+ *
+ * **A predicate, not a set of types**, because the useful question is not what a
+ * record is called. The bound exists to reach a record's *children*, so what
+ * disqualifies a record is having none — and in GFF3 that is answerable exactly,
+ * from whether the record carries an `ID` for a `Parent` to reference. A type
+ * blocklist can only ever approximate it, and it is the caller's format that
+ * knows how: this file reads no column but the coordinates.
+ *
+ * Feature coordinates arrive interbase, matching the query: @gmod/tabix applies
+ * the index's coordinate offset before invoking the line callback, so a GFF/GTF
+ * line's 1-based start is already decremented by the time it gets here.
+ *
+ * Seeding the accumulator with the query bounds is what makes the result a
+ * union rather than just the feature bounds. A redispatch narrower than the
+ * original window would drop an excluded line that the first fetch found inside
+ * the query but that falls outside the expanded range.
+ */
+export declare function calculateRedispatchRange<T extends {
+    start: number;
+    end: number;
+}>(features: T[], expands: (feature: T) => boolean, queryStart: number, queryEnd: number): {
+    start: number;
+    end: number;
+} | undefined;

package/esm/util/range.js

@@ -1,21 +1,87 @@
+/**
+ * fast low-level intersection of 2 coordinate ranges. assumes interbase coordinates.
+ *
+ * assumes `left <= right` for both ranges
+ *
+ * @returns array of [left, right], or [] if the ranges do not intersect. the choice of [] is because it allows destructuring array assignment without check for undefined return
+ */
 export function intersection2(left1, right1, left2, right2) {
+    // this code is verbose because "if" statements are faster than Math.min and Math.max
     if (right1 > left2 && left1 < right2 && right2 - left2 && right1 - left1) {
         if (left1 > left2) {
             if (right1 < right2) {
+                // 1     |-------|
+                //     |------------|
                 return [left1, right1];
             }
+            // 2         |----|
+            //      |------|
             return [left1, right2];
         }
         if (right1 < right2) {
+            // 3  |-----|
+            //       |------|
             return [left2, right1];
         }
+        // 4     |------------|
+        //         |-------|
         return [left2, right2];
     }
     return [];
 }
+/**
+ * Return whether 2 interbase coordinate ranges intersect.
+ *
+ * @param left1 -
+ * @param right1 -
+ * @param left2 -
+ * @param right2 -
+ *
+ * @returns true if the two ranges intersect
+ */
 export function doesIntersect2(left1, right1, left2, right2) {
     return right1 > left2 && left1 < right2;
 }
-export function isContainedWithin(left1, right1, left2, right2) {
-    return left2 <= left1 && right2 >= right1;
+/**
+ * Compute the expanded fetch range a tabix adapter must "redispatch" to when
+ * features found in a query extend past the requested window. Returns the union
+ * of the query with the bounds of every line `expands` admits, or `undefined`
+ * when nothing extends past the query (no redispatch needed).
+ *
+ * **A predicate, not a set of types**, because the useful question is not what a
+ * record is called. The bound exists to reach a record's *children*, so what
+ * disqualifies a record is having none — and in GFF3 that is answerable exactly,
+ * from whether the record carries an `ID` for a `Parent` to reference. A type
+ * blocklist can only ever approximate it, and it is the caller's format that
+ * knows how: this file reads no column but the coordinates.
+ *
+ * Feature coordinates arrive interbase, matching the query: @gmod/tabix applies
+ * the index's coordinate offset before invoking the line callback, so a GFF/GTF
+ * line's 1-based start is already decremented by the time it gets here.
+ *
+ * Seeding the accumulator with the query bounds is what makes the result a
+ * union rather than just the feature bounds. A redispatch narrower than the
+ * original window would drop an excluded line that the first fetch found inside
+ * the query but that falls outside the expanded range.
+ */
+export function calculateRedispatchRange(features, expands, queryStart, queryEnd) {
+    let minStart = queryStart;
+    let maxEnd = queryEnd;
+    // bounds first: only a line reaching past the current bound can widen it, so
+    // the predicate, which may scan the line's text, runs on those few lines and
+    // not on every line in the window
+    for (const feature of features) {
+        if ((feature.start < minStart || feature.end > maxEnd) &&
+            expands(feature)) {
+            if (feature.start < minStart) {
+                minStart = feature.start;
+            }
+            if (feature.end > maxEnd) {
+                maxEnd = feature.end;
+            }
+        }
+    }
+    return minStart < queryStart || maxEnd > queryEnd
+        ? { start: minStart, end: maxEnd }
+        : undefined;
 }

package/esm/util/renameRegions.d.ts

@@ -0,0 +1,41 @@
+import type { StatusCallback } from './progress.ts';
+import type { AssemblyManager, Region } from './types/index.ts';
+import type { Region as MUIRegion } from './types/mst.ts';
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function renameRegionIfNeeded(refNameMap: Record<string, string> | undefined, region: Region | Instance<typeof MUIRegion>, getSeqAdapterRefName?: (refName: string) => string): Region & {
+    originalRefName?: string;
+};
+interface RenameArgs {
+    regions?: Region[];
+    signal?: AbortSignal;
+    adapterConfig: Record<string, unknown>;
+    sessionId: string;
+    statusCallback?: StatusCallback;
+}
+/**
+ * Rename for a request about one genome, which is every request but a
+ * comparative one. The call's genome is its regions' genome, and renaming
+ * writes it as the call's `assemblyName`, the one field a call names its
+ * genome in: `RpcMethodType.serializeArguments` turns it into the reference a
+ * BAM/CRAM or scan adapter is built with. A region on another assembly is
+ * refused: a request over a synteny adapter renames with
+ * {@link renameComparativeRegions}.
+ */
+export declare function renameRegionsIfNeeded<ARGTYPE extends RenameArgs>(assemblyManager: AssemblyManager, args: ARGTYPE): Promise<ARGTYPE & {
+    assemblyName: string | undefined;
+    regions: (Region & {
+        originalRefName?: string;
+    })[];
+}>;
+/**
+ * Rename for a comparative request (synteny, dotplot, chords), whose regions
+ * sit on two or more assemblies and are each renamed against their own. Such a
+ * request has no genome of its own, so it names none and no reference rides
+ * on it; a synteny adapter reads no reference.
+ */
+export declare function renameComparativeRegions<ARGTYPE extends RenameArgs>(assemblyManager: AssemblyManager, args: ARGTYPE): Promise<ARGTYPE & {
+    regions: (Region & {
+        originalRefName?: string;
+    })[];
+}>;
+export {};

package/esm/util/renameRegions.js

@@ -0,0 +1,143 @@
+import { getSnapshot, isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+// Maps a region's refName to the track adapter's name (via refNameMap), and
+// sets originalRefName to the seq adapter (FASTA) name so that CRAM/BAM
+// adapters can fetch reference sequence correctly.
+//
+// This is DESTRUCTIVE, and it runs inside `serializeArguments` — so the array
+// that reaches a worker is not the one the display handed to `rpcManager.call`,
+// with no cue at the call site. `refName` means the assembly's canonical name
+// before this and the track adapter's name after, in the same field of the same
+// type. Renaming is required for anything the worker compares or fetches
+// against the file, and wrong for anything it hands back as user-facing text: a
+// worker that labels a locus from its own output must be given the view's names
+// separately, captured before the call (hic's `HicViewBlock` does this, because
+// its hover prints a locus directly under the ruler). `originalRefName` is NOT
+// that name — it is a third scheme, the FASTA's, load-bearing for CRAM/BAM
+// reference fetch.
+//
+// That third scheme is the general case in miniature, and worth naming: a
+// rename is a property of an (assembly, adapter) PAIR, and this renames against
+// exactly one adapter — `args.adapterConfig`. An RPC that reaches a SECOND file
+// gets no renaming for it, and the failure is silent in the usual way: the query
+// goes out under the first file's spelling, matches nothing, and reads as "no
+// data here". So an RPC naming two adapters needs two passes, not one.
+//
+// **Prefer giving the second file its own RPC**, where `adapterConfig` names the
+// file being read and the ordinary pass is simply right — MAF's annotation
+// overlay is called that way. Thread a second name only when the two results
+// cannot be joined by the caller: GWAS LD coloring can't, because the r²-to-
+// feature join is per feature and features never cross the boundary, so the
+// display resolves the LD file's name before the RPC and hands it to the
+// adapter in `opts.ld.refName`
+// (`plugins/gwas/src/LinearManhattanDisplay/ldJoinResolver.ts`). That and
+// `originalRefName` are the only two, and there is no reason to expect a third:
+// a sub-adapter is normally the same data in another form, named the same way.
+export function renameRegionIfNeeded(refNameMap, region, getSeqAdapterRefName) {
+    const isNode = isStateTreeNode(region);
+    if (isNode && !isAlive(region)) {
+        return region;
+    }
+    const newRef = refNameMap?.[region.refName];
+    if (newRef) {
+        return {
+            ...(isNode ? getSnapshot(region) : region),
+            refName: newRef,
+            originalRefName: getSeqAdapterRefName?.(region.refName) ?? region.refName,
+        };
+    }
+    return region;
+}
+// Region-shaped enough that, if it slipped through under a `region` key, it was
+// meant to be renamed. Used only by the guard below.
+function isRegionShaped(r) {
+    return (!!r &&
+        typeof r === 'object' &&
+        'refName' in r &&
+        'assemblyName' in r &&
+        'start' in r &&
+        'end' in r);
+}
+function checkRenameArgs(args) {
+    if (!args.sessionId) {
+        throw new Error('sessionId is required');
+    }
+    // Renaming only ever touches the `regions` array. An RPC method that instead
+    // carries a singular `region` (e.g. by pairing a one-region wire contract
+    // with a *plural* rename base class) would silently fetch against un-renamed
+    // refNames — the exact bug where an assembly's `5` never maps to an adapter's
+    // `chr5`. The legitimate singular base class (RpcMethodTypeWithRenameRegion)
+    // always mirrors `region` into a populated `regions`, so flag only the
+    // un-mirrored case and fail loudly instead of returning wrong data.
+    if (!args.regions?.length &&
+        isRegionShaped(args.region)) {
+        throw new Error('renameRegionsIfNeeded got a singular `region` but no `regions` array; ' +
+            'refName renaming applies only to `regions`. Pass `regions: [region]` ' +
+            '(or extend RpcMethodTypeWithRenameRegion) so the region is renamed.');
+    }
+}
+// What one assembly contributes to a rename, off the loaded assembly: resolved
+// via requireAssembly (which awaits registration and load) so the refName map
+// and getSeqAdapterRefName come from one handle. A synchronous
+// assemblyManager.get() could miss an assembly still registering, leaving
+// originalRefName (CRAM/BAM's reference fetch name) on the canonical name
+// instead of the FASTA's. Require, not wait: a region names an assembly, so
+// failing to resolve it is renaming that cannot be done, not nothing to rename,
+// and an empty map would query un-renamed refNames and draw an empty track
+// with no word about why. Only an unnamed assembly is a legitimate no-op.
+async function assemblyRenameData(assemblyManager, assemblyName, args) {
+    if (!assemblyName) {
+        return undefined;
+    }
+    const assembly = await assemblyManager.requireAssembly(assemblyName);
+    return {
+        refNameMap: await assembly.getRefNameMapForAdapter(args.adapterConfig, args),
+        getSeqAdapterRefName: (r) => assembly.getSeqAdapterRefName(r),
+    };
+}
+function renamed(region, data) {
+    return renameRegionIfNeeded(data?.refNameMap, region, data?.getSeqAdapterRefName);
+}
+/**
+ * Rename for a request about one genome, which is every request but a
+ * comparative one. The call's genome is its regions' genome, and renaming
+ * writes it as the call's `assemblyName`, the one field a call names its
+ * genome in: `RpcMethodType.serializeArguments` turns it into the reference a
+ * BAM/CRAM or scan adapter is built with. A region on another assembly is
+ * refused: a request over a synteny adapter renames with
+ * {@link renameComparativeRegions}.
+ */
+export async function renameRegionsIfNeeded(assemblyManager, args) {
+    checkRenameArgs(args);
+    const { regions = [] } = args;
+    // read before the await, since MST regions may be dead after
+    const assemblyName = regions[0]?.assemblyName;
+    const stray = regions.find(r => r.assemblyName !== assemblyName);
+    if (stray) {
+        throw new Error(`regions on ${assemblyName} and ${stray.assemblyName} in one request: a request is about one genome, and a comparative request (synteny, dotplot) renames with renameComparativeRegions`);
+    }
+    const data = await assemblyRenameData(assemblyManager, assemblyName, args);
+    return {
+        ...args,
+        assemblyName,
+        regions: regions.map(region => renamed(region, data)),
+    };
+}
+/**
+ * Rename for a comparative request (synteny, dotplot, chords), whose regions
+ * sit on two or more assemblies and are each renamed against their own. Such a
+ * request has no genome of its own, so it names none and no reference rides
+ * on it; a synteny adapter reads no reference.
+ */
+export async function renameComparativeRegions(assemblyManager, args) {
+    checkRenameArgs(args);
+    const { regions = [] } = args;
+    const assemblyNames = regions.map(r => r.assemblyName);
+    const data = new Map(await Promise.all([...new Set(assemblyNames)].map(async (name) => [
+        name,
+        await assemblyRenameData(assemblyManager, name, args),
+    ])));
+    return {
+        ...args,
+        regions: regions.map((region, i) => renamed(region, data.get(assemblyNames[i]))),
+    };
+}

package/esm/util/renderToStaticMarkup.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare function renderToStaticMarkup(node: React.ReactElement): string;

package/esm/util/renderToStaticMarkup.js

@@ -0,0 +1,60 @@
+import React from 'react';
+import createCache from '@emotion/cache';
+import { CacheProvider } from '@emotion/react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+// Deliberately not re-exported from the `util` barrel: it is the barrel's only
+// reason to pull react/react-dom/@emotion, and the barrel is imported by
+// worker-side adapter code that never renders.
+//
+// It is not part of the plugin ABI either, and that removal did break two
+// published bundles before anyone noticed: react-msaview's SVG export read it
+// off `@jbrowse/core/util`, and jbrowse-plugin-msaview and -tview bundle
+// react-msaview. Resolved on their side -- react-msaview owns its own copy now
+// (packages/lib/src/renderToStaticMarkup.ts there) -- because a rendering
+// library asking its host for a renderer was the coupling worth removing, and
+// because react-dom is a host external for a plugin anyway, so it costs them a
+// few hundred bytes rather than a duplicate react. Re-exporting it from the
+// barrel would also stub `@jbrowse/core/util` in the worker, since the
+// generator stubs a module whose graph reaches react-dom; workerModules.test.ts
+// fails on that.
+//
+// https://react.dev/reference/react-dom/server/renderToString#removing-rendertostring-from-the-client-code
+export function renderToStaticMarkup(node) {
+    const div = document.createElement('div');
+    // makeStyles components (via __unsafe_useEmotionCache) need an emotion cache
+    // in context. The browser has an ambient default cache, but node/jsdom (e.g.
+    // jbrowse-img) loads @emotion/react before `document` exists, so its default
+    // cache context is null — provide one explicitly here.
+    const cache = createCache({ key: 'css' });
+    // a client root reports a render error and unmounts, so without this the
+    // export is an empty string its caller writes as a file
+    const uncaught = [];
+    const root = createRoot(div, {
+        onUncaughtError: error => {
+            uncaught.push(error);
+        },
+    });
+    let html;
+    try {
+        // eslint-disable-next-line @eslint-react/dom-no-flush-sync
+        flushSync(() => {
+            root.render(React.createElement(CacheProvider, { value: cache }, node));
+        });
+        if (uncaught.length > 0) {
+            throw uncaught[0];
+        }
+        html = div.innerHTML;
+    }
+    finally {
+        // This is a *real* client root, not a server render: its effects run, so
+        // every `observer` in the tree ends up with a live MobX reaction. Leaving
+        // the root mounted therefore keeps the whole detached export tree — and an
+        // SVG export of a full view is tens of thousands of nodes — subscribed to
+        // the session's models for the rest of the session, re-rendering it into a
+        // dead <div> on every pan and zoom, once per export ever taken. Unmount
+        // once the markup is a string, which no longer depends on the DOM.
+        root.unmount();
+    }
+    return html;
+}

package/esm/util/reorder.d.ts

@@ -0,0 +1,35 @@
+export type ReorderDirection = 'up' | 'down' | 'top' | 'bottom';
+/**
+ * Move `idx` within the subsequence of `arr` that `inScope` selects, leaving
+ * every out-of-scope element where it sits.
+ *
+ * The scoped move: one list holds everything, but a move is only ever relative
+ * to a subset of it. "Move this view up" in a tabbed workspace means up past the
+ * previous view IN THIS PANEL, not past whatever happens to precede it in
+ * `session.views` — which may be in another panel entirely and would make the
+ * move look like a no-op.
+ *
+ * Implemented as a permutation of the in-scope positions: pull out the in-scope
+ * elements, reorder that list, then write it back into the same index slots.
+ * That is what keeps out-of-scope elements pinned, and what makes an unscoped
+ * move (everything in scope) exactly `reorder`.
+ */
+export declare function reorderWithin<T>(arr: readonly T[], idx: number, direction: ReorderDirection, inScope: (item: T, index: number) => boolean): T[];
+/**
+ * Move the element at `idx` within `arr` in the given direction, returning a new
+ * array. An edge move (already at top/bottom) returns an unchanged copy.
+ */
+export declare function reorder<T>(arr: readonly T[], idx: number, direction: ReorderDirection): T[];
+/**
+ * Put the elements whose id appears in `ids` into that relative order, leaving
+ * every other element in its own slot.
+ *
+ * The same slot permutation `reorderWithin` performs, driven by a stated order
+ * rather than by a direction. It exists because an order can arrive in another
+ * vocabulary entirely — a session spec's `layout` names views per panel, top to
+ * bottom — and there is one list that order has to land in.
+ *
+ * Elements named in `ids` but absent from `arr` are ignored, so a layout may
+ * name a view that failed to open.
+ */
+export declare function applyOrderWithin<T>(arr: readonly T[], ids: readonly string[], getId: (item: T) => string): T[];