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

package/esm/util/tabix.js

@@ -1,6 +1,5 @@
 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.
@@ -18,15 +17,15 @@ function extractType(line) {
  * 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
+ * The signal 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) {
+export function readTabixLines(gff, refName, start, end, statusCallback, signal) {
     const lines = [];
-    return withStopTokenSignal(stopToken, signal => downloadStatus('Downloading features', statusCallback, onProgress => gff.getLines(refName, start, end, {
+    return downloadStatus('Downloading features', statusCallback, onProgress => gff.getLines(refName, start, end, {
         lineCallback: (line, offset, s, e) => {
             lines.push({
                 line,
@@ -38,15 +37,21 @@ export function readTabixLines(gff, refName, start, end, statusCallback, stopTok
         },
         onProgress,
         signal,
-    }))).then(() => lines);
+    })).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. Types in `dontRedispatchSet` are
- * excluded from the bounds, so one chromosome-spanning record can't force a
- * whole-chromosome refetch.
+ * 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
@@ -74,13 +79,13 @@ export function readTabixLines(gff, refName, start, end, statusCallback, stopTok
 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, dontRedispatchSet, opts = {}) {
-    const { statusCallback, stopToken } = opts;
+query, expands, opts = {}) {
+    const { statusCallback, signal } = 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 read = (start, end, cb) => readTabixLines(file, query.refName, start, end, cb, signal);
     const lines = await read(query.start, query.end, statusCallback);
-    const redispatch = calculateRedispatchRange(lines, dontRedispatchSet, query.start, query.end);
+    const redispatch = calculateRedispatchRange(lines, expands, query.start, query.end);
     if (redispatch) {
         const slot = createStatusFanOut(statusCallback);
         const flanks = await Promise.all([
@@ -138,6 +143,6 @@ function mergeTabixLines(...groups) {
  * 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();
+export function readTabixHeaderLines(file, opts) {
+    return file.getHeaderLines(opts);
 }

package/esm/util/thresholdScale.d.ts

@@ -0,0 +1,91 @@
+import type { CategoricalScale } from '../ui/colorScale.ts';
+import type { CategoricalField } from './categoricalField.ts';
+/**
+ * #api
+ * A domain written as strings — the shared `domain` slot is a `stringArray` —
+ * read back as the numbers it names. A member that is not a number reads NaN,
+ * which every comparison against it declines.
+ */
+export declare function numericDomain(domain: readonly (string | number)[]): number[];
+/**
+ * #api
+ * A threshold scale's cut points as {@link thresholdIndex} walks them: the
+ * numbers the domain names, ascending. Cuts written high to low, as p-value
+ * thresholds often are, left the middle interval unreachable, the walk stopping
+ * at the first cut a value is under.
+ */
+export declare function thresholdCuts(domain: readonly (string | number)[]): number[];
+/**
+ * #api
+ * The bin a value falls in: how many of the ascending cut points it is at or
+ * past, so a palette with one more entry than the domain paints it as
+ * `palette[thresholdIndex(value, domain)]`. A value that is not a number is
+ * in no bin and answers -1; an infinite one takes the end bin on its side, as
+ * d3's threshold scale places it, so a `-log10` of a zero p-value lands in
+ * the top bin.
+ */
+export declare function thresholdIndex(value: unknown, domain: readonly number[]): number;
+/**
+ * #api
+ * The colour of each interval, in order: the declared palette, and the
+ * default categorical palette where it runs out.
+ */
+export declare function thresholdPalette(bins: number, palette?: readonly string[]): string[];
+/**
+ * #api
+ * What a threshold scale's bins are called in a key, one label per palette
+ * entry: `< a` below the first cut, `a – b` between two, `≥ b` past the last.
+ */
+export declare function thresholdLabels(domain: readonly number[]): string[];
+/**
+ * #api
+ * The key a value holding text that is no number files under on a threshold
+ * scale, painted the misconfiguration grey rather than passing for a missing
+ * value.
+ */
+export declare const NOT_A_NUMBER_LABEL = "(not a number)";
+/**
+ * #api
+ * A threshold key's rows: every interval, painted or not, since the bins are
+ * the whole domain, then the not-a-number and no-value rows where a feature
+ * took one, in the order `thresholdField` sorts them.
+ */
+export declare function thresholdKeyEntries(cuts: readonly number[], range: readonly string[] | undefined, met: {
+    missing?: boolean;
+    notNumber?: boolean;
+}, names?: readonly string[]): {
+    value: string;
+    label: string;
+    color: string;
+    missing?: true;
+}[];
+/**
+ * #api
+ * The rows a ramp's key lists beside its bar once a feature painted one: the
+ * not-a-number and no-value rows a threshold's key ends with. Empty while
+ * neither painted.
+ */
+export declare function rampGapScales(id: string, met: {
+    missing?: boolean;
+    notNumber?: boolean;
+}): CategoricalScale[];
+/**
+ * #api
+ * Whether a field holds no value at all, as against text that fails to parse:
+ * absent, empty, or a VCF's `AF=.`, which arrives as `[undefined]`.
+ */
+export declare function isMissing(value: unknown): boolean;
+/**
+ * #api
+ * A threshold scale read the way every categorical channel reads its field: a
+ * value files under the label of the bin it falls in, a feature with no value
+ * under `''`, and text that is no number under {@link NOT_A_NUMBER_LABEL}.
+ * The bins are the whole domain, so a key lists each one. `labels` names the
+ * bins in a key, one each from the lowest, where a config spells them for a
+ * reader; a bin's key stays its interval.
+ */
+export declare function thresholdField(field: string, { domain, range, labels: names, }?: {
+    domain?: readonly string[];
+    range?: readonly string[];
+    labels?: readonly string[];
+}): CategoricalField;

package/esm/util/thresholdScale.js

@@ -0,0 +1,166 @@
+import { categoricalPalette } from '../ui/colors.js';
+import { NO_VALUE_LABEL, keyNames } from './categoricalField.js';
+import { MISCONFIGURED_COLOR, NO_CATEGORY_COLOR } from './color/index.js';
+import { groupKeyComparator, valueText } from './groupKeys.js';
+import { numericValue } from './numericValue.js';
+/**
+ * #api
+ * A domain written as strings — the shared `domain` slot is a `stringArray` —
+ * read back as the numbers it names. A member that is not a number reads NaN,
+ * which every comparison against it declines.
+ */
+export function numericDomain(domain) {
+    return domain.map(Number);
+}
+/**
+ * #api
+ * A threshold scale's cut points as {@link thresholdIndex} walks them: the
+ * numbers the domain names, ascending. Cuts written high to low, as p-value
+ * thresholds often are, left the middle interval unreachable, the walk stopping
+ * at the first cut a value is under.
+ */
+export function thresholdCuts(domain) {
+    return numericDomain(domain)
+        .filter(cut => Number.isFinite(cut))
+        .sort((a, b) => a - b);
+}
+/**
+ * #api
+ * The bin a value falls in: how many of the ascending cut points it is at or
+ * past, so a palette with one more entry than the domain paints it as
+ * `palette[thresholdIndex(value, domain)]`. A value that is not a number is
+ * in no bin and answers -1; an infinite one takes the end bin on its side, as
+ * d3's threshold scale places it, so a `-log10` of a zero p-value lands in
+ * the top bin.
+ */
+export function thresholdIndex(value, domain) {
+    const v = numericValue(value);
+    if (Number.isNaN(v)) {
+        return -1;
+    }
+    let i = 0;
+    while (i < domain.length && v >= domain[i]) {
+        i++;
+    }
+    return i;
+}
+/**
+ * #api
+ * The colour of each interval, in order: the declared palette, and the
+ * default categorical palette where it runs out.
+ */
+export function thresholdPalette(bins, palette = []) {
+    return Array.from({ length: bins }, (_, i) => palette[i] ?? categoricalPalette[i % categoricalPalette.length]);
+}
+/**
+ * #api
+ * What a threshold scale's bins are called in a key, one label per palette
+ * entry: `< a` below the first cut, `a – b` between two, `≥ b` past the last.
+ */
+export function thresholdLabels(domain) {
+    if (domain.length === 0) {
+        return ['any value'];
+    }
+    return [
+        `< ${domain[0]}`,
+        ...domain.slice(1).map((cut, i) => `${domain[i]} – ${cut}`),
+        `≥ ${domain.at(-1)}`,
+    ];
+}
+/**
+ * #api
+ * The key a value holding text that is no number files under on a threshold
+ * scale, painted the misconfiguration grey rather than passing for a missing
+ * value.
+ */
+export const NOT_A_NUMBER_LABEL = '(not a number)';
+/**
+ * #api
+ * A threshold key's rows: every interval, painted or not, since the bins are
+ * the whole domain, then the not-a-number and no-value rows where a feature
+ * took one, in the order `thresholdField` sorts them.
+ */
+export function thresholdKeyEntries(cuts, range, met, names = []) {
+    const labels = thresholdLabels(cuts);
+    const colors = thresholdPalette(labels.length, range);
+    return [
+        ...labels.map((label, i) => ({
+            value: label,
+            label: names[i] ?? label,
+            color: colors[i],
+        })),
+        ...(met.notNumber
+            ? [
+                {
+                    value: NOT_A_NUMBER_LABEL,
+                    label: NOT_A_NUMBER_LABEL,
+                    color: MISCONFIGURED_COLOR,
+                },
+            ]
+            : []),
+        ...(met.missing
+            ? [
+                {
+                    value: '',
+                    label: NO_VALUE_LABEL,
+                    color: NO_CATEGORY_COLOR,
+                    missing: true,
+                },
+            ]
+            : []),
+    ];
+}
+/**
+ * #api
+ * The rows a ramp's key lists beside its bar once a feature painted one: the
+ * not-a-number and no-value rows a threshold's key ends with. Empty while
+ * neither painted.
+ */
+export function rampGapScales(id, met) {
+    const entries = thresholdKeyEntries([], undefined, met).slice(1);
+    return entries.length > 0 ? [{ kind: 'categorical', id, entries }] : [];
+}
+/**
+ * #api
+ * Whether a field holds no value at all, as against text that fails to parse:
+ * absent, empty, or a VCF's `AF=.`, which arrives as `[undefined]`.
+ */
+export function isMissing(value) {
+    return Array.isArray(value)
+        ? value.every(v => v === undefined || v === null)
+        : valueText(value) === '';
+}
+/**
+ * #api
+ * A threshold scale read the way every categorical channel reads its field: a
+ * value files under the label of the bin it falls in, a feature with no value
+ * under `''`, and text that is no number under {@link NOT_A_NUMBER_LABEL}.
+ * The bins are the whole domain, so a key lists each one. `labels` names the
+ * bins in a key, one each from the lowest, where a config spells them for a
+ * reader; a bin's key stays its interval.
+ */
+export function thresholdField(field, { domain = [], range = [], labels: names = [], } = {}) {
+    const cuts = thresholdCuts(domain);
+    const labels = thresholdLabels(cuts);
+    const named = keyNames(labels, names);
+    const palette = thresholdPalette(labels.length, range);
+    const colorOf = new Map(labels.map((label, i) => [label, palette[i]]));
+    return {
+        field,
+        domain: labels,
+        closed: true,
+        key: value => {
+            if (isMissing(value)) {
+                return '';
+            }
+            const bin = thresholdIndex(value, cuts);
+            return bin < 0 ? NOT_A_NUMBER_LABEL : labels[bin];
+        },
+        compare: groupKeyComparator([...labels, NOT_A_NUMBER_LABEL]),
+        label: key => (key === '' ? NO_VALUE_LABEL : (named.get(key) ?? key)),
+        sectionLabel: key => `${field}: ${key === '' ? 'none' : key}`,
+        color: key => key === ''
+            ? NO_CATEGORY_COLOR
+            : (colorOf.get(key) ?? MISCONFIGURED_COLOR),
+    };
+}

package/esm/util/timeGate.d.ts

@@ -5,8 +5,8 @@
  *
  * `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
+ * of them (the progress emit in `createProgressReporter` and the yield in
+ * `createAbortBreakpoint`). 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.
  *
@@ -18,9 +18,8 @@
  * 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.
+ * `intervalMs` is per call rather than fixed at construction; both current
+ * callers pass a constant.
  */
 export declare function createTimeGate(): (intervalMs: number) => boolean;
 export type TimeGate = ReturnType<typeof createTimeGate>;

package/esm/util/timeGate.js

@@ -24,8 +24,8 @@ const STRIDE_GROWTH_LIMIT = 8;
  *
  * `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
+ * of them (the progress emit in `createProgressReporter` and the yield in
+ * `createAbortBreakpoint`). 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.
  *
@@ -37,9 +37,8 @@ const STRIDE_GROWTH_LIMIT = 8;
  * 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.
+ * `intervalMs` is per call rather than fixed at construction; both current
+ * callers pass a constant.
  */
 export function createTimeGate() {
     let stride = 1;

package/esm/util/trackConfigDelta.d.ts

@@ -12,24 +12,22 @@
  *   - `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.
+ * A delta is a JSON Merge Patch (RFC 7396) over the base, so a `null` member is
+ * a reset: the merge removes the member and the schema's default applies. That
+ * is ADR-146's spelling of a reset, and the diff writes one wherever the base
+ * sets a member the edited config lacks — a slot put back to its default, or a
+ * list emptied, since `stripDefault` drops both from a snapshot. Where the edit
+ * left a whole namespace at its default, the nulls land on the members the base
+ * set inside it rather than on the namespace, so a member the admin adds there
+ * later still flows through. The inference
+ * is exact only because both sides are post-`stripDefault` snapshots: a member
+ * the admin wrote at its default is absent from both, where a `null` for it
+ * would block a later admin value. As in RFC 7396, a delta cannot set a member
+ * to a literal `null`; null and absent are one state.
  *
  * `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.
+ * others, and by `type` where the base has no display of that id. Nested config objects (e.g. `adapter`) recurse. Any other array (value
+ * arrays like `filter`, `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
@@ -44,24 +42,26 @@ 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.
+ * Minimal delta of `edited` against `base`, both post-stripDefault snapshots. A
+ * member `base` sets and `edited` lacks is a `null` (see the module note).
+ * 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).
+ * A `null` removes the member it names, and one naming something the base no
+ * longer has is dropped, so no `null` member reaches the config a track
+ * hydrates from.
  */
 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`. */
+/**
+ * A single overridden slot: the dotted `path`, its base `from` and edited `to`,
+ * which is `undefined` for a reset.
+ */
 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.
+     * Where the setting lives. A producer that wants a friendlier heading sets
+     * `label` and leaves this alone.
      */
     path: string[];
     from: Json;

package/esm/util/trackConfigDelta.js

@@ -12,24 +12,22 @@
  *   - `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.
+ * A delta is a JSON Merge Patch (RFC 7396) over the base, so a `null` member is
+ * a reset: the merge removes the member and the schema's default applies. That
+ * is ADR-146's spelling of a reset, and the diff writes one wherever the base
+ * sets a member the edited config lacks — a slot put back to its default, or a
+ * list emptied, since `stripDefault` drops both from a snapshot. Where the edit
+ * left a whole namespace at its default, the nulls land on the members the base
+ * set inside it rather than on the namespace, so a member the admin adds there
+ * later still flows through. The inference
+ * is exact only because both sides are post-`stripDefault` snapshots: a member
+ * the admin wrote at its default is absent from both, where a `null` for it
+ * would block a later admin value. As in RFC 7396, a delta cannot set a member
+ * to a literal `null`; null and absent are one state.
  *
  * `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.
+ * others, and by `type` where the base has no display of that id. Nested config objects (e.g. `adapter`) recurse. Any other array (value
+ * arrays like `filter`, `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
@@ -51,10 +49,14 @@ function isDisplayArray(v) {
         v.length > 0 &&
         v.every(e => isPlainObject(e) && typeof e.displayId === 'string'));
 }
-// Sentinel returned by diffValue when a value is unchanged, so callers can tell
-// "no delta" apart from a legitimate `undefined` slot value.
 const UNCHANGED = Symbol('unchanged');
 function diffValue(base, edited) {
+    if (edited == null) {
+        if (base == null) {
+            return UNCHANGED;
+        }
+        return isPlainObject(base) ? diffValue(base, {}) : null;
+    }
     if (deepEqual(base, edited)) {
         return UNCHANGED;
     }
@@ -67,13 +69,10 @@ function diffValue(base, edited) {
             if (baseDisplay) {
                 const d = diffValue(baseDisplay, editedDisplay);
                 if (d !== UNCHANGED) {
-                    // always re-key the delta entry by displayId so merge can realign it
                     out.push({ ...d, displayId: id });
                 }
             }
             else {
-                // a display present only in the edited config (e.g. an added display):
-                // carry it whole
                 out.push(editedDisplay);
             }
         }
@@ -81,25 +80,20 @@ function diffValue(base, edited) {
     }
     if (isPlainObject(edited) && isPlainObject(base)) {
         const out = {};
-        for (const [k, v] of Object.entries(edited)) {
-            const d = diffValue(base[k], v);
+        for (const k of new Set([...Object.keys(base), ...Object.keys(edited)])) {
+            const d = diffValue(base[k], edited[k]);
             if (d !== UNCHANGED) {
                 out[k] = d;
             }
         }
-        // an object whose only difference from base is dropped keys (a reset the
-        // delta can't express, see module note) yields no adds/changes: treat it as
-        // unchanged rather than emitting a content-free entry
         return Object.keys(out).length > 0 ? out : UNCHANGED;
     }
-    // scalar, or an object/array replacing a scalar (or a value array): replace
     return edited;
 }
 /**
- * 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.
+ * Minimal delta of `edited` against `base`, both post-stripDefault snapshots. A
+ * member `base` sets and `edited` lacks is a `null` (see the module note).
+ * Always retains `trackId` so the delta is self-identifying.
  */
 export function diffTrackConfig(base, edited) {
     const d = diffValue(base, edited);
@@ -107,35 +101,57 @@ export function diffTrackConfig(base, edited) {
     const trackId = (edited.trackId ?? base.trackId);
     return { ...delta, trackId };
 }
+// A delta display naming an id the base lacks lands on the base display of its
+// type, keeping the base's id: a track holds one display per type, and a
+// migrated session addresses the display by the id its old type minted.
 function mergeValue(base, delta) {
-    if (isDisplayArray(delta) && isDisplayArray(base)) {
-        const deltaById = new Map(delta.map(d => [d.displayId, d]));
-        const merged = base.map(baseDisplay => {
-            const d = deltaById.get(baseDisplay.displayId);
-            return d ? mergeValue(baseDisplay, d) : baseDisplay;
-        });
-        // displays present only in the delta (added by the user) append after base
-        const baseIds = new Set(base.map(d => d.displayId));
+    if (isDisplayArray(delta)) {
+        const baseDisplays = isDisplayArray(base) ? base : [];
+        const baseIds = new Set(baseDisplays.map(d => d.displayId));
+        const deltaByBaseId = new Map();
+        const added = [];
         for (const d of delta) {
-            if (!baseIds.has(d.displayId)) {
-                merged.push(d);
+            const byType = baseIds.has(d.displayId)
+                ? undefined
+                : baseDisplays.find(b => d.type !== undefined && b.type === d.type);
+            const id = (byType?.displayId ?? d.displayId);
+            if (baseIds.has(id)) {
+                const onId = { ...d, displayId: id };
+                const earlier = deltaByBaseId.get(id);
+                deltaByBaseId.set(id, earlier ? mergeValue(earlier, onId) : onId);
+            }
+            else {
+                added.push(d);
             }
         }
+        const merged = baseDisplays.map(baseDisplay => {
+            const d = deltaByBaseId.get(baseDisplay.displayId);
+            return d ? mergeValue(baseDisplay, d) : baseDisplay;
+        });
+        for (const d of added) {
+            merged.push(mergeValue(undefined, d));
+        }
         return merged;
     }
-    if (isPlainObject(delta) && isPlainObject(base)) {
-        const out = { ...base };
+    if (isPlainObject(delta)) {
+        const out = isPlainObject(base) ? { ...base } : {};
         for (const [k, v] of Object.entries(delta)) {
-            out[k] = mergeValue(base[k], v);
+            if (v === null) {
+                delete out[k];
+            }
+            else {
+                out[k] = mergeValue(out[k], v);
+            }
         }
         return out;
     }
-    // scalar / value array / type mismatch: delta wins
     return delta;
 }
 /**
  * Reconstruct the effective config by layering `delta` over the live `base`.
- * Inverse of `diffTrackConfig` on the add/change path (see module note).
+ * A `null` removes the member it names, and one naming something the base no
+ * longer has is dropped, so no `null` member reaches the config a track
+ * hydrates from.
  */
 export function mergeTrackConfig(base, delta) {
     return mergeValue(base, delta);
@@ -174,7 +190,7 @@ function walkDelta(base, delta, path, out, identityKeys = IDENTITY_KEYS) {
         }
     }
     else {
-        out.push({ path, from: base, to: delta });
+        out.push({ path, from: base, to: delta ?? undefined });
     }
 }
 /**