@jbrowse/core 5.0.0-beta.10 → 5.0.0-beta.13

package/esm/util/fetchPhases.d.ts

@@ -43,7 +43,7 @@ export interface FetchPhases<TArgs, TResult, TCtx> {
      * gets a dead Retry button — see there.
      *
      * What it must **not** do is move a trigger read of its own under a bail-out.
-     * See reference/FETCH_SKELETON.md §"The global-fetch trigger list must be read
+     * See reference/FETCH_KEYS.md §"The global-fetch trigger list must be read
      * unconditionally".
      */
     prepare: () => TArgs | undefined;

package/esm/util/formatBytes.js

@@ -10,7 +10,7 @@ const units = ['bytes', 'kB', 'MB', 'GB', 'TB'];
 export function formatBytes(bytes) {
     let n = bytes;
     let i = 0;
-    while (n >= 1000 && i < units.length - 1) {
+    while (Number(n.toFixed(1)) >= 1000 && i < units.length - 1) {
         n /= 1000;
         i++;
     }

package/esm/util/formatGuessers.d.ts

@@ -1,7 +1,23 @@
-import type PluginManager from '../PluginManager.ts';
 import type { AdapterConfig } from './tracks.ts';
 import type { FileLocation } from './types/data.ts';
 import type { AdapterSpec } from '@jbrowse/add-track-core';
+/**
+ * creates a new location from the provided location including the appropriate
+ * suffix and location type
+ *
+ * @param location - the FileLocation
+ * @param suffix - the file suffix (e.g. .bam)
+ * @returns the constructed location object from the provided parameters
+ */
+export declare function makeIndex(location: FileLocation, suffix: string): import("./index.ts").BlobLocation | import("./index.ts").FileHandleLocation | {
+    uri: string;
+    locationType: string;
+    baseUri?: string | undefined;
+    localPath?: undefined;
+} | {
+    localPath: string;
+    locationType: string;
+};
 /**
  * The adapter config one format-table entry describes: the data file under the
  * field that format's adapter reads it from, plus wherever that adapter expects
@@ -14,17 +30,12 @@ import type { AdapterSpec } from '@jbrowse/add-track-core';
  */
 export declare function adapterConfigFromSpec(spec: AdapterSpec, file: FileLocation, index?: FileLocation): AdapterConfig | undefined;
 /**
- * Guess every format `@jbrowse/add-track-core`'s table describes — the same
- * table `@jbrowse/cli`'s `add-track` reads, so a file resolves to the same
- * adapter config in the app and on the command line.
- *
- * Whether a build can open a format is decided by `hasAdapterType`, not by the
- * table: guessing `BamAdapter` in a build with no alignments plugin writes a
- * track config that fails at render. A plugin therefore registers its adapters
- * and nothing else — there is no format list to keep in step. ADR-077.
- *
- * `CorePlugin` installs this first, so any `addAdapterGuesser` a plugin
- * registers is later in the chain and wins over the table. That is how a format
- * the table cannot express is added, and how a third-party plugin claims one.
+ * The track the format table makes of a file: its adapter, the track type that
+ * draws it, and the file name as its name. `undefined` for a file no format
+ * claims, which is where `guessTrackConf` throws.
  */
-export declare function installFormatGuessers(pluginManager: PluginManager): void;
+export declare function guessTrackConfFromTable(file: FileLocation, index?: FileLocation, adapterHint?: string): {
+    type: string;
+    name: string;
+    adapter: AdapterConfig;
+} | undefined;

package/esm/util/formatGuessers.js

@@ -1,6 +1,33 @@
 import { matchFormat, resolveIndexType, trackTypeForAdapter, } from '@jbrowse/add-track-core';
 import { getFileName } from './getFileName.js';
-import { addAdapterGuesser, addTrackTypeGuesser, makeIndex } from './tracks.js';
+/**
+ * creates a new location from the provided location including the appropriate
+ * suffix and location type
+ *
+ * @param location - the FileLocation
+ * @param suffix - the file suffix (e.g. .bam)
+ * @returns the constructed location object from the provided parameters
+ */
+export function makeIndex(location, suffix) {
+    if ('uri' in location) {
+        return {
+            uri: location.uri + suffix,
+            locationType: 'UriLocation',
+            // carry the parent's baseUri so a derived sibling index resolves against
+            // the same config location as the file it indexes
+            ...(location.baseUri ? { baseUri: location.baseUri } : {}),
+        };
+    }
+    else if ('localPath' in location) {
+        return {
+            localPath: location.localPath + suffix,
+            locationType: 'LocalPathLocation',
+        };
+    }
+    else {
+        return location;
+    }
+}
 /**
  * The adapter config one format-table entry describes: the data file under the
  * field that format's adapter reads it from, plus wherever that adapter expects
@@ -39,31 +66,19 @@ export function adapterConfigFromSpec(spec, file, index) {
     }
 }
 /**
- * Guess every format `@jbrowse/add-track-core`'s table describes — the same
- * table `@jbrowse/cli`'s `add-track` reads, so a file resolves to the same
- * adapter config in the app and on the command line.
- *
- * Whether a build can open a format is decided by `hasAdapterType`, not by the
- * table: guessing `BamAdapter` in a build with no alignments plugin writes a
- * track config that fails at render. A plugin therefore registers its adapters
- * and nothing else — there is no format list to keep in step. ADR-077.
- *
- * `CorePlugin` installs this first, so any `addAdapterGuesser` a plugin
- * registers is later in the chain and wins over the table. That is how a format
- * the table cannot express is added, and how a third-party plugin claims one.
+ * The track the format table makes of a file: its adapter, the track type that
+ * draws it, and the file name as its name. `undefined` for a file no format
+ * claims, which is where `guessTrackConf` throws.
  */
-// #region installFormatGuessers
-export function installFormatGuessers(pluginManager) {
-    addAdapterGuesser(pluginManager, (file, index, adapterHint) => {
-        const spec = matchFormat(getFileName(file), adapterHint)?.spec;
-        return spec &&
-            'adapterType' in spec &&
-            pluginManager.hasAdapterType(spec.adapterType)
-            ? adapterConfigFromSpec(spec, file, index)
-            : undefined;
-    });
-    addTrackTypeGuesser(pluginManager, (adapterName, file) => pluginManager.hasAdapterType(adapterName)
-        ? trackTypeForAdapter(adapterName, file && getFileName(file))
-        : undefined);
+export function guessTrackConfFromTable(file, index, adapterHint) {
+    const name = getFileName(file);
+    const spec = matchFormat(name, adapterHint)?.spec;
+    const adapter = spec && adapterConfigFromSpec(spec, file, index);
+    return adapter
+        ? {
+            type: trackTypeForAdapter(adapter.type, name) ?? 'FeatureTrack',
+            name,
+            adapter,
+        }
+        : undefined;
 }
-// #endregion

package/esm/util/formatRelativeTime.js

@@ -15,7 +15,7 @@ export function formatRelativeTime(date, now = Date.now()) {
     let duration = (Number(date) - now) / 1000;
     let result = rtf.format(Math.round(duration), 'years');
     for (const { amount, unit } of DIVISIONS) {
-        if (Math.abs(duration) < amount) {
+        if (Math.round(Math.abs(duration)) < amount) {
             result = rtf.format(Math.round(duration), unit);
             break;
         }

package/esm/util/getLocationUri.d.ts

@@ -9,7 +9,8 @@ export declare function resolveUri({ uri, baseUri, }: {
     baseUri?: string;
 }): string;
 /**
- * An address with its query string dropped, which is what makes it safe to put
+ * An address with its query string and any username:password dropped, which is
+ * what makes it safe to put
  * on screen. A presigned S3 or GCS link carries its credential in the query — a
  * few hundred characters of `?X-Amz-Signature=…` — and a notice that renders one
  * puts it in front of whoever is looking at the screen and into every screenshot

package/esm/util/getLocationUri.js

@@ -13,7 +13,8 @@ export function resolveUri({ uri, baseUri = '', }) {
     }
 }
 /**
- * An address with its query string dropped, which is what makes it safe to put
+ * An address with its query string and any username:password dropped, which is
+ * what makes it safe to put
  * on screen. A presigned S3 or GCS link carries its credential in the query — a
  * few hundred characters of `?X-Amz-Signature=…` — and a notice that renders one
  * puts it in front of whoever is looking at the screen and into every screenshot
@@ -25,7 +26,12 @@ export function resolveUri({ uri, baseUri = '', }) {
  * than a typed location.
  */
 export function redactSource(source) {
-    return source.includes('://') ? source.split(/[?#]/)[0] : source;
+    if (!source.includes('://')) {
+        return source;
+    }
+    return source
+        .replace(/^([a-z][a-z\d+.-]*:\/\/)[^/?#]*@/i, '$1')
+        .split(/[?#]/)[0];
 }
 /**
  * Where a location's bytes come from, as an address worth showing someone, or

package/esm/util/groupKeys.d.ts

@@ -46,14 +46,13 @@ export declare function carryGroupDomain<T extends {
 export declare function overflowLabel(count: number): string;
 /**
  * Which section each key stacks into once the cap applies: the first
- * `limit` keys (`MAX_GROUPS` by default) in natural order keep their own and
- * the rest fold into the overflow section; `Infinity` folds none. The
- * catch-all `''` is held out of the merge, since "lacking the value" is an
- * answer users look for. A domain orders the
+ * `MAX_GROUPS` keys in natural order keep their own and the rest fold into
+ * the overflow section. The catch-all `''` is held out of the merge, since
+ * "lacking the value" is an answer users look for. A domain orders the
  * sections and never decides which exist, so reordering them changes no
  * key's section.
  */
-export declare function capGroupKeys(keys: Iterable<string>, limit?: number): {
+export declare function capGroupKeys(keys: Iterable<string>): {
     mergedCount: number;
     sectionOf: (key: string) => string;
 };

package/esm/util/groupKeys.js

@@ -125,18 +125,19 @@ export function overflowLabel(count) {
 }
 /**
  * Which section each key stacks into once the cap applies: the first
- * `limit` keys (`MAX_GROUPS` by default) in natural order keep their own and
- * the rest fold into the overflow section; `Infinity` folds none. The
- * catch-all `''` is held out of the merge, since "lacking the value" is an
- * answer users look for. A domain orders the
+ * `MAX_GROUPS` keys in natural order keep their own and the rest fold into
+ * the overflow section. The catch-all `''` is held out of the merge, since
+ * "lacking the value" is an answer users look for. A domain orders the
  * sections and never decides which exist, so reordering them changes no
  * key's section.
  */
-export function capGroupKeys(keys, limit = MAX_GROUPS) {
+export function capGroupKeys(keys) {
     const ordered = [...new Set(keys)].sort(compareGroupKeys);
     const hasUntagged = ordered.includes('');
     const named = ordered.filter(key => key !== '');
-    const merged = ordered.length > limit ? named.slice(limit - (hasUntagged ? 2 : 1)) : [];
+    const merged = ordered.length > MAX_GROUPS
+        ? named.slice(MAX_GROUPS - (hasUntagged ? 2 : 1))
+        : [];
     const mergedSet = new Set(merged);
     return {
         mergedCount: merged.length,

package/esm/util/intervals.js

@@ -28,10 +28,15 @@ export function mergeIntervals(intervals, padding = 5000) {
  * features. `padding` carries the same per-side meaning.
  */
 export function gatherOverlaps(regions, padding = 5000) {
-    const memo = {};
+    const memo = new Map();
     for (const x of regions) {
-        memo[x.refName] ??= [];
-        memo[x.refName].push(x);
+        const group = memo.get(x.refName);
+        if (group) {
+            group.push(x);
+        }
+        else {
+            memo.set(x.refName, [x]);
+        }
     }
-    return Object.values(memo).flatMap(group => mergeIntervals(group, padding));
+    return [...memo.values()].flatMap(group => mergeIntervals(group, padding));
 }

package/esm/util/io/index.js

@@ -77,7 +77,9 @@ export function openLocation(location, pluginManager) {
         if (!file) {
             throw new Error(`file ("${location.name}") requires permission. Please reopen the file from track settings`);
         }
-        return new CachedFilehandle(new BlobFile(file), `filehandle://${location.handleId}`);
+        // A File is a snapshot: the handle yields a new one once the file changes
+        // on disk, and its chunks must not be the old snapshot's
+        return new CachedFilehandle(new BlobFile(file), `filehandle://${location.handleId}@${file.lastModified}:${file.size}`);
     }
     if (isUriLocation(location)) {
         // Check for empty string

package/esm/util/isoformRank.d.ts

@@ -0,0 +1,39 @@
+import type { Feature, SimpleFeatureSerializedNoId } from './simpleFeature.ts';
+/**
+ * Which isoform of a gene a display shows first: the canvas gene glyph's
+ * `longestCoding` collapse and the sequence panel's default transcript both
+ * rank with this, so the panel opens on the isoform the track drew. Generic
+ * over the feature shape because the worker ranks live `Feature`s and the
+ * panel ranks their serialized form.
+ */
+export interface IsoformReader<T> {
+    type: (feature: T) => string | undefined;
+    start: (feature: T) => number;
+    end: (feature: T) => number;
+    subfeatures: (feature: T) => readonly T[];
+    attribute: (feature: T, field: string) => unknown;
+}
+export declare const featureIsoformReader: IsoformReader<Feature>;
+export declare const serializedIsoformReader: IsoformReader<SimpleFeatureSerializedNoId>;
+/**
+ * The attribute naming a gene's representative isoform, and the values of it
+ * that do, best first. The canvas display's `canonicalTranscriptField` and
+ * `canonicalTranscriptTags` slots default to these.
+ */
+export interface CanonicalTranscripts {
+    field: string;
+    tags: readonly string[];
+}
+export declare const DEFAULT_CANONICAL_TRANSCRIPTS: CanonicalTranscripts;
+export interface IsoformScore {
+    canonical: number;
+    coding: boolean;
+    size: number;
+}
+export declare function isCodingIsoform<T>(read: IsoformReader<T>, feature: T): boolean;
+export declare function isoformScorer<T>(read: IsoformReader<T>, { field, tags }: CanonicalTranscripts): (feature: T) => IsoformScore;
+export declare function rankIsoforms<T>(isoforms: readonly T[], scoreOf: (feature: T) => IsoformScore): T[];
+export interface CanonicalTranscriptsHost {
+    canonicalTranscripts: CanonicalTranscripts;
+}
+export declare function isCanonicalTranscriptsHost(thing: unknown): thing is CanonicalTranscriptsHost;

package/esm/util/isoformRank.js

@@ -0,0 +1,118 @@
+export const featureIsoformReader = {
+    type: f => f.get('type'),
+    start: f => f.get('start'),
+    end: f => f.get('end'),
+    subfeatures: f => f.get('subfeatures') ?? [],
+    attribute: (f, field) => f.get(field),
+};
+export const serializedIsoformReader = {
+    type: f => f.type,
+    start: f => f.start,
+    end: f => f.end,
+    subfeatures: f => f.subfeatures ?? [],
+    attribute: (f, field) => f[field],
+};
+export const DEFAULT_CANONICAL_TRANSCRIPTS = {
+    field: 'tag',
+    tags: [
+        'MANE Select',
+        'MANE_Select',
+        'RefSeq Select',
+        'Ensembl_canonical',
+        'MANE Plus Clinical',
+        'MANE_Plus_Clinical',
+    ],
+};
+function isCDSType(type) {
+    return type?.toLowerCase() === 'cds';
+}
+// The feature itself counts, because an isoform can BE the CDS: a viral
+// polyprotein hangs its cleavage products off its CDS, not off further CDSs.
+export function isCodingIsoform(read, feature) {
+    return (isCDSType(read.type(feature)) ||
+        read.subfeatures(feature).some(sub => isCodingIsoform(read, sub)));
+}
+// "Longest coding" is the longest protein — summed CDS length, not the widest
+// genomic footprint an isoform with a large intron could win. A duplicated CDS
+// row is a real GFF3 quirk that would otherwise inflate one isoform past a
+// genuinely longer protein, so equal spans count once.
+function codingLength(read, feature) {
+    const spans = [];
+    const walk = (f) => {
+        for (const sub of read.subfeatures(f)) {
+            if (isCDSType(read.type(sub))) {
+                spans.push([read.start(sub), read.end(sub)]);
+            }
+            else {
+                walk(sub);
+            }
+        }
+    };
+    walk(feature);
+    if (spans.length === 0) {
+        return isCDSType(read.type(feature))
+            ? read.end(feature) - read.start(feature)
+            : 0;
+    }
+    spans.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    let sum = 0;
+    for (const [i, span] of spans.entries()) {
+        const prev = spans[i - 1];
+        if (!prev || prev[0] !== span[0] || prev[1] !== span[1]) {
+            sum += span[1] - span[0];
+        }
+    }
+    return sum;
+}
+// A position in the tag list rather than a boolean, because the default list
+// holds two tags one gene can carry at once and flattening them to "tagged"
+// leaves the coding-length tiebreak to pick between them. A GFF3 attribute
+// holding a comma list arrives as an array, hence both shapes.
+function canonicalRank(value, wanted) {
+    const values = Array.isArray(value)
+        ? value.map(v => String(v).toLowerCase())
+        : typeof value === 'string'
+            ? [value.toLowerCase()]
+            : [];
+    let best = Infinity;
+    for (const v of values) {
+        const rank = wanted.indexOf(v);
+        if (rank !== -1 && rank < best) {
+            best = rank;
+        }
+    }
+    return best;
+}
+export function isoformScorer(read, { field, tags }) {
+    const wanted = tags.map(t => t.toLowerCase());
+    return (feature) => {
+        const coding = isCodingIsoform(read, feature);
+        return {
+            canonical: wanted.length
+                ? canonicalRank(read.attribute(feature, field), wanted)
+                : Infinity,
+            coding,
+            size: coding
+                ? codingLength(read, feature)
+                : read.end(feature) - read.start(feature),
+        };
+    };
+}
+// Best first. A curated tag outranks every measurement, because for a gene whose
+// longest protein is a minor variant it is the only thing that picks the right
+// isoform. A coding-length tie resolves to the LATER isoform, which a stable
+// sort would break the other way — hence the explicit index term.
+export function rankIsoforms(isoforms, scoreOf) {
+    return isoforms
+        .map((feature, index) => ({ feature, index, ...scoreOf(feature) }))
+        .sort((a, b) => a.canonical - b.canonical ||
+        Number(b.coding) - Number(a.coding) ||
+        b.size - a.size ||
+        b.index - a.index)
+        .map(s => s.feature);
+}
+export function isCanonicalTranscriptsHost(thing) {
+    return (typeof thing === 'object' &&
+        thing !== null &&
+        'canonicalTranscripts' in thing);
+}

package/esm/util/jexlFilters.d.ts

@@ -1,68 +1,50 @@
 import { getConf } from '../configuration/getConf.ts';
+import type { RetiredDisplayState } from '../pluggableElementTypes/DisplayType.ts';
 import type { Reversible } from '../ui/filterMenuItems.ts';
 /**
- * The two-tier feature-filter contract, shared by every display offering a
- * "Filter by..." row. Two tiers because the setting has two authors:
- *
- * - the **`filter` config slot**, which an admin declares in a track config:
- *   `jexlFilterConfigSchemaFields` in display-kit, spread by the canvas base
- *   display schema, the mark display schema and the shared multi-sample
- *   variant schema — the three whose models read it.
- * - the **`filterSetting` display property**, which the dialog writes. Set —
- *   *even to an empty list* — it replaces the config tier entirely, which is
- *   what makes "clear the filters an admin declared" expressible.
- *
- * Both hold `jexl:` expressions and refuse a bare string.
+ * The feature-filter contract, shared by every display offering a "Filter
+ * by..." row: the **`filter` config slot** holds the filters applied, as
+ * `jexl:` expressions (`jexlFilterConfigSchemaFields` in display-kit, spread
+ * by the canvas base display schema, the mark display schema and the shared
+ * multi-sample variant schema). The dialog, a feature's "Filter" actions and
+ * "Edit plot..." all write that slot, and the session keeps the write as it
+ * keeps any track setting, so "Reset track settings" returns it with the
+ * rest.
  */
 export interface JexlFilterSource {
-    /**
-     * The dialog's override. `undefined` means "follow the config slot"; an
-     * empty array means "the user cleared them".
-     */
-    filterSetting?: readonly string[];
-    /**
-     * The config tier — in practice `configuredJexlFilters(self)`. A member rather than a read this module does
-     * itself, so the two things that consume this contract off a **duck-typed**
-     * model — LD's structural menu builder and its shape test — need no live
-     * config node to answer a count with.
-     */
+    /** The slot's filters, in practice `configuredJexlFilters(self)`. */
     configuredFilters: () => string[];
 }
 /**
  * The writing half, for the dialog and the menu's clear row. Separate from
- * {@link JexlFilterSource} because a display declares `activeFilters()` in an
- * earlier `.views()` block than the `.actions()` block declaring its setter, so
- * requiring the setter to *read* the filters would put the two in an order MST
- * cannot satisfy.
+ * {@link JexlFilterSource} because a display declares its readers in an
+ * earlier `.views()` block than the `.actions()` block declaring its setter.
  */
 export interface JexlFilterModel extends JexlFilterSource {
+    /** What the track's config declares, which "Clear all filters" returns to. */
+    baseFilters: () => string[];
+    /** Write the slot; undefined returns it to {@link baseFilters}. */
     setFilter: (filters?: string[]) => void;
 }
-/** The `filterSetting` property, for a display model to declare. */
-export declare const FilterSetting: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>>;
-/**
- * A snapshot's v4 `jexlFiltersSetting` as `filterSetting`, for the
- * `preProcessSnapshot` of the model declaring {@link FilterSetting}.
- */
-export declare function liftRetiredFilterSetting<T>(snap: T): T;
-/** What the `filter` config slot alone declares: a display's `configuredFilters`. */
+/** What the `filter` config slot holds: a display's `configuredFilters`. */
 export declare function configuredJexlFilters(self: Parameters<typeof getConf>[0]): string[];
 /**
- * The filters actually applied — the single source of truth
- * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
- * filters show up and are editable), and for the narrowing count below.
+ * What the track's config declares for this display's `filter`, before the
+ * session wrote any: a display's `baseFilters`. Empty in a session that keeps
+ * no base.
  */
-export declare function activeJexlFilters(self: JexlFilterSource): string[];
+export declare function baseJexlFilters(self: object): string[];
 /**
- * The `Reversible` a display declares for its jexl filters.
- *
- * The count is whether the override **differs from the configured baseline**,
- * not the number of expressions: a filter an admin declared is not something
- * the user narrowed, and "Clear all filters" could not undo it anyway. It
- * counts in both directions when they differ — narrowing further, and (emptied
- * over a slot that declares filters) widening past what the config asked for.
- *
- * No per-item row: a list of jexl expressions has no recovery to name beyond
- * restoring the config default, which the group clear already is.
+ * The `Reversible` a display declares for its jexl filters. The count is
+ * whether the filters differ from what the track's config declares, not the
+ * number of expressions: a filter an admin declared is not something the user
+ * narrowed. It counts in both directions, narrowing further and, emptied over
+ * a config that declares filters, widening past it.
  */
 export declare function jexlFilterNarrowing(self: JexlFilterModel): Reversible;
+/**
+ * A v4 session's display-instance `jexlFiltersSetting`, which is the `filter`
+ * slot now: the retired state the canvas and single-sample variant displays
+ * declare (ADR-168).
+ */
+export declare const retiredFilterState: RetiredDisplayState;

package/esm/util/jexlFilters.js

@@ -1,57 +1,36 @@
 // own module, not the configuration barrel: that barrel re-exports modules
 // which import this one, and a value import back into it is the cycle shape
 // `openFeatureWidget` documents
-import { types } from '@jbrowse/mobx-state-tree';
 import { getConf } from '../configuration/getConf.js';
+import { baseDisplayConfig } from './baseDisplayConfig.js';
 import { ensureJexlPrefix } from './jexlStrings.js';
-import { JexlExpressionString } from './types/mst.js';
-/** The `filterSetting` property, for a display model to declare. */
-export const FilterSetting = types.maybe(types.array(JexlExpressionString));
-/**
- * A snapshot's v4 `jexlFiltersSetting` as `filterSetting`, for the
- * `preProcessSnapshot` of the model declaring {@link FilterSetting}.
- */
-export function liftRetiredFilterSetting(snap) {
-    if (!snap || typeof snap !== 'object' || !('jexlFiltersSetting' in snap)) {
-        return snap;
-    }
-    const { jexlFiltersSetting, ...rest } = snap;
-    return (Array.isArray(jexlFiltersSetting) && !('filterSetting' in rest)
-        ? { ...rest, filterSetting: jexlFiltersSetting.map(ensureJexlPrefix) }
-        : rest);
-}
-/** What the `filter` config slot alone declares: a display's `configuredFilters`. */
+/** What the `filter` config slot holds: a display's `configuredFilters`. */
 export function configuredJexlFilters(self) {
     return getConf(self, 'filter');
 }
 /**
- * The filters actually applied — the single source of truth
- * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
- * filters show up and are editable), and for the narrowing count below.
+ * What the track's config declares for this display's `filter`, before the
+ * session wrote any: a display's `baseFilters`. Empty in a session that keeps
+ * no base.
  */
-export function activeJexlFilters(self) {
-    const { filterSetting } = self;
-    return filterSetting ? [...filterSetting] : self.configuredFilters();
+export function baseJexlFilters(self) {
+    const declared = baseDisplayConfig(self).filter;
+    return Array.isArray(declared)
+        ? declared.map(f => ensureJexlPrefix(String(f)))
+        : [];
 }
 /**
- * The `Reversible` a display declares for its jexl filters.
- *
- * The count is whether the override **differs from the configured baseline**,
- * not the number of expressions: a filter an admin declared is not something
- * the user narrowed, and "Clear all filters" could not undo it anyway. It
- * counts in both directions when they differ — narrowing further, and (emptied
- * over a slot that declares filters) widening past what the config asked for.
- *
- * No per-item row: a list of jexl expressions has no recovery to name beyond
- * restoring the config default, which the group clear already is.
+ * The `Reversible` a display declares for its jexl filters. The count is
+ * whether the filters differ from what the track's config declares, not the
+ * number of expressions: a filter an admin declared is not something the user
+ * narrowed. It counts in both directions, narrowing further and, emptied over
+ * a config that declares filters, widening past it.
  */
 export function jexlFilterNarrowing(self) {
-    const override = self.filterSetting;
-    const configured = self.configuredFilters();
+    const current = self.configuredFilters();
+    const base = self.baseFilters();
     return {
-        count: override !== undefined &&
-            (override.length !== configured.length ||
-                override.some((f, i) => f !== configured[i]))
+        count: current.length !== base.length || current.some((f, i) => f !== base[i])
             ? 1
             : 0,
         clear: () => {
@@ -59,3 +38,14 @@ export function jexlFilterNarrowing(self) {
         },
     };
 }
+/**
+ * A v4 session's display-instance `jexlFiltersSetting`, which is the `filter`
+ * slot now: the retired state the canvas and single-sample variant displays
+ * declare (ADR-168).
+ */
+export const retiredFilterState = {
+    keys: ['jexlFiltersSetting'],
+    lift: ({ jexlFiltersSetting }) => Array.isArray(jexlFiltersSetting)
+        ? { filter: jexlFiltersSetting.map(f => ensureJexlPrefix(String(f))) }
+        : {},
+};