@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/tabix.d.ts

@@ -0,0 +1,126 @@
+import type { StatusCallback } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+/**
+ * A raw tabix line paired with the metadata the GFF3/GTF adapters need before
+ * parsing: `offset` (the tabix byte offset) mints a stable per-feature id that
+ * survives redispatch and panning, and start/end/type feed the redispatch
+ * calculation (see {@link calculateRedispatchRange}) that runs before any line
+ * is parsed.
+ *
+ * `start`/`end` are interbase, not the raw column values: @gmod/tabix applies
+ * the index's coordinate offset (-1 for a 1-based-closed preset such as GFF)
+ * before it calls back.
+ */
+export interface TabixLine {
+    line: string;
+    offset: number;
+    start: number;
+    end: number;
+    type: string;
+}
+/**
+ * Minimal structural view of `@gmod/tabix`'s `TabixIndexedFile.getLines`, so
+ * core needn't depend on `@gmod/tabix`.
+ */
+interface TabixLineSource {
+    getLines(refName: string, start: number | undefined, end: number | undefined, opts: {
+        lineCallback: (line: string, offset: number, start: number, end: number) => void;
+        onProgress?: (bytesDownloaded: number, totalBytes?: number) => void;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/**
+ * Fetch the tabix lines for a region under a "Downloading features" progress
+ * label, capturing each line's byte offset, indexed start/end, and feature type
+ * into a {@link TabixLine}. Shared by the GFF3 and GTF tabix adapters.
+ *
+ * The stop token becomes the read's `AbortSignal`, so a cancelled fetch drops
+ * its block reads at the socket instead of downloading them and discarding the
+ * lines. @gmod/tabix aborts a block shared between callers only once every
+ * joined caller has aborted (`AggregateAbortController`), so this can't cancel a
+ * chunk another region still needs.
+ */
+export declare function readTabixLines(gff: TabixLineSource, refName: string, start: number, end: number, statusCallback?: StatusCallback, stopToken?: StopToken): Promise<TabixLine[]>;
+/**
+ * Read a region's tabix lines, then — if any feature found there extends past
+ * the query — read the overhang on either side, so a parent line's children (a
+ * gene's exons, a transcript's CDS) outside the original window are pulled in
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
+ *
+ * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
+ * everything the first read already had — a second full read of the query range
+ * to collect a gene's tail. At the window sizes a GFF3 track is browsed at that
+ * is most of the work done twice, and it is the reason the download bar halved:
+ * the expansion arrived as a second phase whose total was the whole region
+ * again, so a region that had just reported 100% dropped to 50% and climbed back
+ * (measured: two `65536/65536` phases for one query). Reading only what is
+ * missing leaves the second phase the size of the overhang.
+ *
+ * The line sequence is unchanged by that. Tabix returns the lines *overlapping*
+ * a range, so the three ranges' lines are the union range's lines, with the ones
+ * straddling a boundary appearing twice; `offset` is a line's position in the
+ * file, so deduplicating and sorting on it reconstructs file order — which for
+ * an indexed file is coordinate order — exactly.
+ *
+ * The two flanks are read concurrently and so need a status slot each, or they
+ * take turns overwriting one label. Exactly one expansion happens: a flank's own
+ * overhang is not chased, which bounds the work at three reads per query and
+ * usually two.
+ *
+ * Shared by the GFF3 and GTF tabix adapters, which differ only in how they
+ * parse the returned lines.
+ */
+export declare function readTabixLinesRedispatched(file: TabixLineSource, query: {
+    refName: string;
+    start: number;
+    end: number;
+}, expands: (line: TabixLine) => boolean, opts?: {
+    statusCallback?: StatusCallback;
+    stopToken?: StopToken;
+}): Promise<TabixLine[]>;
+/**
+ * Minimal structural view of the `@gmod/tabix` call a header read needs, kept
+ * structural for the same reason as {@link TabixLineSource}.
+ */
+interface TabixHeaderSource {
+    getHeaderLines(): Promise<string[]>;
+}
+/**
+ * The header lines of a tabix-indexed file, however that file kept them.
+ *
+ * `getHeader()` alone is not that: it returns only lines beginning with the
+ * index's meta character (`#`). A header that is a plain row — which is what
+ * `tabix -S N` exists for, and what PLINK `.ld`, bedGraph and BED deflines
+ * routinely are — comes back as the empty string, even though the index records
+ * N in `skipLines`.
+ *
+ * Reading both is not backwards compatibility, and does not become unnecessary
+ * once our own files are written with commented headers. A bare header is the
+ * shape the data's publisher chose: Pan-UKB's TSVs and PLINK's `.ld` are
+ * distributed that way, and `-S N` is the only way to index one without
+ * rewriting a file the user did not write. Advice about how to generate a file
+ * reaches the files we generate; this reaches the rest.
+ *
+ * An adapter that stops at `getHeader()` therefore cannot tell "this file has
+ * no header" from "this file's header is not commented", and quietly falls back
+ * to an assumed column layout. That has cost real information more than once: a
+ * PLINK LD file lost its D' column, so `ldMetric: 'dprime'` silently served r²,
+ * and a bedGraph loses the names of its value columns. Nothing errors, because
+ * the assumed layout parses.
+ *
+ * That policy now lives in @gmod/tabix 3.5.4 as getHeaderLines, next to the
+ * index metadata that decides it, so this is a delegate. Deciding it there also
+ * costs one read of the file's leading blocks rather than two: asking for the
+ * commented block and then the counted rows used to fetch and decompress the
+ * same bytes twice, which every bare-header file did on every call.
+ */
+export declare function readTabixHeaderLines(file: TabixHeaderSource): Promise<string[]>;
+export {};

package/esm/util/tabix.js

@@ -0,0 +1,149 @@
+import { createStatusFanOut, downloadStatus } from './progress.js';
+import { calculateRedispatchRange } from './range.js';
+import { withStopTokenSignal } from './stopToken.js';
+/**
+ * Read the feature type (column 3) from a raw GFF3/GTF line without a full
+ * split. Used only to classify a line for redispatch.
+ */
+function extractType(line) {
+    const t1 = line.indexOf('\t');
+    const t2 = t1 === -1 ? -1 : line.indexOf('\t', t1 + 1);
+    const t3 = t2 === -1 ? -1 : line.indexOf('\t', t2 + 1);
+    // a truncated line has no column 3 to read; a final column 3 (no trailing
+    // tab) runs to the end of the line rather than one character short of it
+    return t2 === -1 ? '' : line.slice(t2 + 1, t3 === -1 ? line.length : t3);
+}
+/**
+ * Fetch the tabix lines for a region under a "Downloading features" progress
+ * label, capturing each line's byte offset, indexed start/end, and feature type
+ * into a {@link TabixLine}. Shared by the GFF3 and GTF tabix adapters.
+ *
+ * The stop token becomes the read's `AbortSignal`, so a cancelled fetch drops
+ * its block reads at the socket instead of downloading them and discarding the
+ * lines. @gmod/tabix aborts a block shared between callers only once every
+ * joined caller has aborted (`AggregateAbortController`), so this can't cancel a
+ * chunk another region still needs.
+ */
+export function readTabixLines(gff, refName, start, end, statusCallback, stopToken) {
+    const lines = [];
+    return withStopTokenSignal(stopToken, signal => downloadStatus('Downloading features', statusCallback, onProgress => gff.getLines(refName, start, end, {
+        lineCallback: (line, offset, s, e) => {
+            lines.push({
+                line,
+                offset,
+                start: s,
+                end: e,
+                type: extractType(line),
+            });
+        },
+        onProgress,
+        signal,
+    }))).then(() => lines);
+}
+/**
+ * Read a region's tabix lines, then — if any feature found there extends past
+ * the query — read the overhang on either side, so a parent line's children (a
+ * gene's exons, a transcript's CDS) outside the original window are pulled in
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
+ *
+ * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
+ * everything the first read already had — a second full read of the query range
+ * to collect a gene's tail. At the window sizes a GFF3 track is browsed at that
+ * is most of the work done twice, and it is the reason the download bar halved:
+ * the expansion arrived as a second phase whose total was the whole region
+ * again, so a region that had just reported 100% dropped to 50% and climbed back
+ * (measured: two `65536/65536` phases for one query). Reading only what is
+ * missing leaves the second phase the size of the overhang.
+ *
+ * The line sequence is unchanged by that. Tabix returns the lines *overlapping*
+ * a range, so the three ranges' lines are the union range's lines, with the ones
+ * straddling a boundary appearing twice; `offset` is a line's position in the
+ * file, so deduplicating and sorting on it reconstructs file order — which for
+ * an indexed file is coordinate order — exactly.
+ *
+ * The two flanks are read concurrently and so need a status slot each, or they
+ * take turns overwriting one label. Exactly one expansion happens: a flank's own
+ * overhang is not chased, which bounds the work at three reads per query and
+ * usually two.
+ *
+ * Shared by the GFF3 and GTF tabix adapters, which differ only in how they
+ * parse the returned lines.
+ */
+export async function readTabixLinesRedispatched(file, 
+// the region's locus only — kept structural, like TabixLineSource above, so
+// this module stays free of the `types` barrel and its MST models
+query, expands, opts = {}) {
+    const { statusCallback, stopToken } = opts;
+    // `cb` is not optional: each read decides where it reports, and the flanks
+    // report somewhere the first read does not
+    const read = (start, end, cb) => readTabixLines(file, query.refName, start, end, cb, stopToken);
+    const lines = await read(query.start, query.end, statusCallback);
+    const redispatch = calculateRedispatchRange(lines, expands, query.start, query.end);
+    if (redispatch) {
+        const slot = createStatusFanOut(statusCallback);
+        const flanks = await Promise.all([
+            redispatch.start < query.start
+                ? read(redispatch.start, query.start, slot())
+                : [],
+            redispatch.end > query.end ? read(query.end, redispatch.end, slot()) : [],
+        ]);
+        return mergeTabixLines(lines, ...flanks);
+    }
+    return lines;
+}
+/**
+ * The lines of several overlapping reads as one file-ordered run, each line
+ * once. Keyed on `offset` because that is what a line *is* — its position in the
+ * file — so a line two ranges both returned collapses to one entry and the sort
+ * puts the whole set back in the order a single read over their union would have
+ * produced.
+ */
+function mergeTabixLines(...groups) {
+    const byOffset = new Map();
+    for (const group of groups) {
+        for (const line of group) {
+            byOffset.set(line.offset, line);
+        }
+    }
+    return [...byOffset.values()].sort((a, b) => a.offset - b.offset);
+}
+/**
+ * The header lines of a tabix-indexed file, however that file kept them.
+ *
+ * `getHeader()` alone is not that: it returns only lines beginning with the
+ * index's meta character (`#`). A header that is a plain row — which is what
+ * `tabix -S N` exists for, and what PLINK `.ld`, bedGraph and BED deflines
+ * routinely are — comes back as the empty string, even though the index records
+ * N in `skipLines`.
+ *
+ * Reading both is not backwards compatibility, and does not become unnecessary
+ * once our own files are written with commented headers. A bare header is the
+ * shape the data's publisher chose: Pan-UKB's TSVs and PLINK's `.ld` are
+ * distributed that way, and `-S N` is the only way to index one without
+ * rewriting a file the user did not write. Advice about how to generate a file
+ * reaches the files we generate; this reaches the rest.
+ *
+ * An adapter that stops at `getHeader()` therefore cannot tell "this file has
+ * no header" from "this file's header is not commented", and quietly falls back
+ * to an assumed column layout. That has cost real information more than once: a
+ * PLINK LD file lost its D' column, so `ldMetric: 'dprime'` silently served r²,
+ * and a bedGraph loses the names of its value columns. Nothing errors, because
+ * the assumed layout parses.
+ *
+ * That policy now lives in @gmod/tabix 3.5.4 as getHeaderLines, next to the
+ * index metadata that decides it, so this is a delegate. Deciding it there also
+ * costs one read of the file's leading blocks rather than two: asking for the
+ * commented block and then the counted rows used to fetch and decompress the
+ * same bytes twice, which every bare-header file did on every call.
+ */
+export function readTabixHeaderLines(file) {
+    return file.getHeaderLines();
+}

package/esm/util/tags.d.ts

@@ -0,0 +1,2 @@
+export declare const tagRegex: RegExp;
+export declare function isValidTag(tag: string): boolean;

package/esm/util/tags.js

@@ -0,0 +1,5 @@
+// A SAM tag is two characters: a letter followed by a letter or digit.
+export const tagRegex = /^[A-Za-z][A-Za-z0-9]$/;
+export function isValidTag(tag) {
+    return tagRegex.test(tag);
+}

package/esm/util/temporaryAssembly.d.ts

@@ -0,0 +1,21 @@
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+/**
+ * Whether a track config names an assembly the session holds as **temporary** —
+ * the read-vs-ref pair a comparative view synthesizes, which goes away when that
+ * view closes (`releaseTemporaryAssemblies`).
+ *
+ * `some`, not `every`: a config half of whose assemblies survive is still one
+ * nothing can draw once the other half is gone, and unlike a sweep that DELETES
+ * a config this question never has to decide whose it is. The `every`/`some`
+ * distinction is what made the session-track sweep ADR-084 removed a judgment
+ * call; a question asked at the moment of the write has no such problem.
+ *
+ * Down here rather than beside the contract check that started it
+ * (`product-core/Session/temporaryAssemblyTracks.ts`) because two callers now
+ * ask it and they are on opposite sides of the dependency: the check and the
+ * track menu's copy guard in product-core, and `addTrackFromWidget` in this
+ * package, which routes a track around the session lists entirely when the
+ * answer is yes. A second copy of the predicate is the thing to avoid — a copied
+ * guard is where the escape clause gets added to only one of them.
+ */
+export declare function namesTemporaryAssembly(session: unknown, trackConf: AnyConfigurationModel | Record<string, unknown>): boolean;

package/esm/util/temporaryAssembly.js

@@ -0,0 +1,29 @@
+import { readConfObject } from '../configuration/index.js';
+/**
+ * Whether a track config names an assembly the session holds as **temporary** —
+ * the read-vs-ref pair a comparative view synthesizes, which goes away when that
+ * view closes (`releaseTemporaryAssemblies`).
+ *
+ * `some`, not `every`: a config half of whose assemblies survive is still one
+ * nothing can draw once the other half is gone, and unlike a sweep that DELETES
+ * a config this question never has to decide whose it is. The `every`/`some`
+ * distinction is what made the session-track sweep ADR-084 removed a judgment
+ * call; a question asked at the moment of the write has no such problem.
+ *
+ * Down here rather than beside the contract check that started it
+ * (`product-core/Session/temporaryAssemblyTracks.ts`) because two callers now
+ * ask it and they are on opposite sides of the dependency: the check and the
+ * track menu's copy guard in product-core, and `addTrackFromWidget` in this
+ * package, which routes a track around the session lists entirely when the
+ * answer is yes. A second copy of the predicate is the thing to avoid — a copied
+ * guard is where the escape clause gets added to only one of them.
+ */
+export function namesTemporaryAssembly(session, trackConf) {
+    const temporary = session
+        .temporaryAssemblies;
+    if (!temporary?.length) {
+        return false;
+    }
+    const names = readConfObject(trackConf, 'assemblyNames');
+    return !!names?.some(name => temporary.some(a => a.name === name));
+}

package/esm/util/tickLabels.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A region needs at least this many coordinate labels to be worth numbering.
+ *
+ * Tick pitch comes from the bpPerPx of the whole displayed-region set, so a
+ * region much narrower than that pitch still catches a tick or two. With every
+ * chromosome displayed at once — a whole-genome overview scalebar, a
+ * whole-genome dotplot axis — each one then ends up with a single lone number
+ * jammed against the next chromosome's refName, and the axis reads as scattered
+ * repeats of the same "500M".
+ *
+ * One coordinate conveys no scale on its own: it gives a reader no spacing to
+ * read a distance off, and sitting alone in a chromosome's span it reads as
+ * marking that span rather than a position inside it. Needing two means narrow
+ * regions show just their refName, and only regions with room for a real ruler
+ * get numbers.
+ */
+export declare const MIN_TICK_LABELS_PER_BLOCK = 2;
+/** Whether a run of `count` coordinate labels in one region is worth drawing. */
+export declare function tickLabelsWorthDrawing(count: number): boolean;
+/**
+ * Drop the labels of every region left with too few of them to read, keeping
+ * those of regions that have a real ruler.
+ *
+ * For a caller holding one flat list across several regions, where the count
+ * has to be taken per region before anything can be decided. A caller that
+ * already works a region at a time wants `tickLabelsWorthDrawing` on its own
+ * length instead.
+ *
+ * `regionOf` returns whatever identifies a region to the caller — an index, a
+ * refName, a block key. A group's labels are dropped together, so that identity
+ * has to separate two regions that can sit side by side on one axis: an axis
+ * may carry the same refName twice (a read-vs-ref dotplot builds one from
+ * gatherOverlaps, so a read aligned twice to a chromosome yields two regions on
+ * it), and keying those together would let one lend the other its quorum.
+ */
+export declare function dropLoneTickLabels<T>(labels: T[], regionOf: (label: T) => unknown): T[];

package/esm/util/tickLabels.js

@@ -0,0 +1,45 @@
+/**
+ * A region needs at least this many coordinate labels to be worth numbering.
+ *
+ * Tick pitch comes from the bpPerPx of the whole displayed-region set, so a
+ * region much narrower than that pitch still catches a tick or two. With every
+ * chromosome displayed at once — a whole-genome overview scalebar, a
+ * whole-genome dotplot axis — each one then ends up with a single lone number
+ * jammed against the next chromosome's refName, and the axis reads as scattered
+ * repeats of the same "500M".
+ *
+ * One coordinate conveys no scale on its own: it gives a reader no spacing to
+ * read a distance off, and sitting alone in a chromosome's span it reads as
+ * marking that span rather than a position inside it. Needing two means narrow
+ * regions show just their refName, and only regions with room for a real ruler
+ * get numbers.
+ */
+export const MIN_TICK_LABELS_PER_BLOCK = 2;
+/** Whether a run of `count` coordinate labels in one region is worth drawing. */
+export function tickLabelsWorthDrawing(count) {
+    return count >= MIN_TICK_LABELS_PER_BLOCK;
+}
+/**
+ * Drop the labels of every region left with too few of them to read, keeping
+ * those of regions that have a real ruler.
+ *
+ * For a caller holding one flat list across several regions, where the count
+ * has to be taken per region before anything can be decided. A caller that
+ * already works a region at a time wants `tickLabelsWorthDrawing` on its own
+ * length instead.
+ *
+ * `regionOf` returns whatever identifies a region to the caller — an index, a
+ * refName, a block key. A group's labels are dropped together, so that identity
+ * has to separate two regions that can sit side by side on one axis: an axis
+ * may carry the same refName twice (a read-vs-ref dotplot builds one from
+ * gatherOverlaps, so a read aligned twice to a chromosome yields two regions on
+ * it), and keying those together would let one lend the other its quorum.
+ */
+export function dropLoneTickLabels(labels, regionOf) {
+    const counts = new Map();
+    for (const label of labels) {
+        const region = regionOf(label);
+        counts.set(region, (counts.get(region) ?? 0) + 1);
+    }
+    return labels.filter(label => tickLabelsWorthDrawing(counts.get(regionOf(label))));
+}

package/esm/util/timeGate.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A wall-clock gate for a callback invoked once per item in a long synchronous
+ * loop: `due(intervalMs)` returns true at most once per `intervalMs`, without
+ * calling `Date.now()` on every invocation.
+ *
+ * `Date.now()` costs ~40ns, invisible until the loop is a 666k-read pileup —
+ * there it measured ~28ms per gated callsite, and the alignments worker has two
+ * of them (the progress emit in `createProgressReporter` and the stop-token
+ * check in `checkStopTokenThrottled`). Both previously read the clock per call, on the
+ * documented reasoning that it was negligible next to the per-item work; at
+ * this item count it measurably isn't.
+ *
+ * The stride between clock reads is **learned from the observed call rate**,
+ * never fixed. A fixed stride is what regressed this before: a phase with few
+ * but heavy items (a multi-sample VCF region — a few hundred sites, thousands
+ * of samples each) never reached the count, so its progress bar froze at 0% and
+ * its cancellation never fired. A learned stride makes exactly those loops
+ * measure a low rate and hold a stride of 1, gating on time alone as before,
+ * while a millions-of-calls loop thins itself out.
+ *
+ * `intervalMs` is per call rather than fixed at construction: it was added for
+ * `checkStopTokenThrottled`, whose (since-deleted) sync-XHR probe backed off
+ * linearly over a long loop. Both current callers pass a constant.
+ */
+export declare function createTimeGate(): (intervalMs: number) => boolean;
+export type TimeGate = ReturnType<typeof createTimeGate>;

package/esm/util/timeGate.js

@@ -0,0 +1,79 @@
+// Target number of `Date.now()` reads per interval. Above 1 so the fire itself
+// doesn't drift late when the call rate rises between two fires: the gate
+// notices the interval has elapsed within ~1/this of it.
+const CLOCK_READS_PER_INTERVAL = 8;
+// Ceiling on the learned stride. The stride is only ever an extrapolation from
+// the last observed call rate, and the gate is blind between clock reads — if
+// per-item cost jumps mid-loop the next read arrives late in wall-clock terms.
+// This caps how blind it can get: a 10x mid-loop slowdown at a stride this size
+// costs about one extra interval, which for a progress emit or a cancellation
+// check is immaterial. At the rates that motivate a gate at all (hundreds of
+// calls per ms) it is never the binding constraint.
+const MAX_STRIDE = 8192;
+// The stride is re-aimed on every clock read, including ones taken part-way
+// through an interval — otherwise the whole first interval runs at stride 1,
+// which for a 666k-call loop is 33k clock reads before the gate learns
+// anything. Those early samples span a short window, so cap how fast the stride
+// may grow: the ramp still reaches MAX_STRIDE in five reads, but one
+// unrepresentatively fast millisecond can't launch the gate straight to blind.
+const STRIDE_GROWTH_LIMIT = 8;
+/**
+ * A wall-clock gate for a callback invoked once per item in a long synchronous
+ * loop: `due(intervalMs)` returns true at most once per `intervalMs`, without
+ * calling `Date.now()` on every invocation.
+ *
+ * `Date.now()` costs ~40ns, invisible until the loop is a 666k-read pileup —
+ * there it measured ~28ms per gated callsite, and the alignments worker has two
+ * of them (the progress emit in `createProgressReporter` and the stop-token
+ * check in `checkStopTokenThrottled`). Both previously read the clock per call, on the
+ * documented reasoning that it was negligible next to the per-item work; at
+ * this item count it measurably isn't.
+ *
+ * The stride between clock reads is **learned from the observed call rate**,
+ * never fixed. A fixed stride is what regressed this before: a phase with few
+ * but heavy items (a multi-sample VCF region — a few hundred sites, thousands
+ * of samples each) never reached the count, so its progress bar froze at 0% and
+ * its cancellation never fired. A learned stride makes exactly those loops
+ * measure a low rate and hold a stride of 1, gating on time alone as before,
+ * while a millions-of-calls loop thins itself out.
+ *
+ * `intervalMs` is per call rather than fixed at construction: it was added for
+ * `checkStopTokenThrottled`, whose (since-deleted) sync-XHR probe backed off
+ * linearly over a long loop. Both current callers pass a constant.
+ */
+export function createTimeGate() {
+    let stride = 1;
+    let sinceClockRead = 0;
+    let callsSinceFire = 0;
+    let lastFire = 0;
+    return (intervalMs) => {
+        callsSinceFire++;
+        if (++sinceClockRead < stride) {
+            return false;
+        }
+        sinceClockRead = 0;
+        const now = Date.now();
+        // lastFire 0 is the first call ever — `now - 0` is the epoch, not an
+        // elapsed time, and there is no rate to measure yet. Fire (so an initial
+        // 0% tick is never swallowed) and start the window here.
+        if (lastFire === 0) {
+            lastFire = now;
+            callsSinceFire = 0;
+            return true;
+        }
+        const elapsed = now - lastFire;
+        // elapsed 0 means the window fell inside one clock tick, which measures
+        // nothing. Shrinking is unbounded (an estimate below the current stride
+        // takes effect at once) so a slowdown is corrected on the next read.
+        if (elapsed > 0) {
+            stride = Math.min(MAX_STRIDE, stride * STRIDE_GROWTH_LIMIT, Math.max(1, Math.floor((callsSinceFire * intervalMs) /
+                (elapsed * CLOCK_READS_PER_INTERVAL))));
+        }
+        if (elapsed < intervalMs) {
+            return false;
+        }
+        lastFire = now;
+        callsSinceFire = 0;
+        return true;
+    };
+}

package/esm/util/trackConfigDelta.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Track-config override deltas.
+ *
+ * A non-admin's track-menu / Settings edits are stored as a *delta* against the
+ * admin-owned base config (jbrowse.tracks entry), not as a full copy. The delta
+ * records only the slots the user changed; everything else resolves from the
+ * live base, so a later admin change to an untouched field (e.g. a corrected
+ * adapter URL) still flows through instead of being masked by a pinned full
+ * snapshot.
+ *
+ * Two operations, inverse of each other on the realistic edit path:
+ *   - `diffTrackConfig(base, edited)` — the minimal delta
+ *   - `mergeTrackConfig(base, delta)` — reconstruct the effective config
+ *
+ * Deliberate limitation (no tombstones): a delta records adds/changes only, not
+ * deletions. If a user *resets* a slot the admin had customized (base has it,
+ * edited omits it), the delta can't express "drop below the admin value", so the
+ * field keeps following the base across a reload. This keeps the merge trivial
+ * and the shared JSON free of deletion sentinels, and following the admin value
+ * is a defensible outcome.
+ *
+ * What it is NOT free to conflate is a removal with a reset. Both diff to an
+ * empty delta, and `SessionTracks.updateTrackConfiguration` used to read that as
+ * "the edit netted back to the base" and revert the track's working copy — which
+ * undid a removal on screen 400ms after it landed. Promotable slots made that
+ * reachable rather than rare: the promoted-default snackbar's "Override N
+ * customized tracks" exists to unset a slot, and an admin config is free to set
+ * one. That branch now keeps the working copy; see the comment there.
+ *
+ * `displays` is merged by `displayId` so an edit to one display doesn't pin the
+ * others. Nested config objects (e.g. `adapter`) recurse. Any other array (value
+ * arrays like `jexlFilters`, `assemblyNames`) is replaced wholesale when changed.
+ *
+ * Subtlety worth not "optimizing": when the base has NO `displays` array but the
+ * edited snapshot does (common — a track config that omits displays gets a stub
+ * per compatible display type injected by `baseTrackConfig.preProcessSnapshot`
+ * when it hydrates), the whole edited array lands in the delta, including
+ * seemingly content-free `{type, displayId}` stubs. Do not strip those stubs to
+ * shrink the delta: the array order defines the default display (`displays[0]`),
+ * and re-injection on the next hydrate would append them in a different order,
+ * silently changing which display opens by default.
+ */
+type Json = string | number | boolean | null | undefined | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Minimal delta of `edited` against `base`. Both are plain config snapshots
+ * (post-stripDefault). Records adds/changes only; see the module note on the
+ * no-tombstone limitation. Always retains `trackId` so the delta is
+ * self-identifying.
+ */
+export declare function diffTrackConfig(base: Record<string, unknown>, edited: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Reconstruct the effective config by layering `delta` over the live `base`.
+ * Inverse of `diffTrackConfig` on the add/change path (see module note).
+ */
+export declare function mergeTrackConfig(base: Record<string, unknown>, delta: Record<string, unknown>): Record<string, unknown>;
+/** A single overridden slot: the dotted `path`, its base `from` and edited `to`. */
+export interface TrackConfigChange {
+    /**
+     * Where the setting lives, and — for a row a UI can revert — its **address**:
+     * `resetPreferenceChange` parses a promoted display-type default's path back
+     * into the type and slot it clears. So a producer that wants a friendlier
+     * heading sets `label` and leaves this alone.
+     */
+    path: string[];
+    from: Json;
+    to: Json;
+    /**
+     * What to head the row with, when the path is an address rather than
+     * something to read. `SettingsChangesTable` falls back to the joined path,
+     * which is what every delta row still wants — a config path IS the readable
+     * thing there.
+     */
+    label?: string;
+}
+/**
+ * Flatten a stored track-config `delta` (see {@link diffTrackConfig}) into a
+ * list of changed slots paired with their `base` values, so the UI can show a
+ * user exactly which settings they've overridden and what the default was.
+ * Displays are addressed by type/displayId; identity keys are omitted.
+ */
+export declare function flattenTrackConfigDelta(base: Record<string, unknown>, delta: Record<string, unknown>): TrackConfigChange[];
+export {};