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

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/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))) }
+        : {},
+};

package/esm/util/locString.js

@@ -36,12 +36,12 @@ export function parseLocStringOneBased(locString, isValidRefName) {
         throw new Error('no location string provided, could not parse');
     }
     // handle reverse strand notation e.g. "chr1:1-100[rev]"
+    locString = locString.replaceAll(/\s/g, '');
     let reversed = false;
     if (locString.endsWith('[rev]')) {
         reversed = true;
         locString = locString.slice(0, -5);
     }
-    locString = locString.replaceAll(/\s/g, '');
     // extract optional assembly name in braces e.g. "{hg19}chr1:1-100"
     const assemblyMatch = ASSEMBLY_REGEX.exec(locString);
     if (!assemblyMatch) {
@@ -174,7 +174,10 @@ function assembleLocStringWith(region, cb = (n) => n) {
     }
     let endString;
     if (end !== undefined) {
-        endString = start !== undefined && start + 1 === end ? '' : `..${cb(end)}`;
+        endString =
+            start !== undefined && (start + 1 === end || start === end)
+                ? ''
+                : `..${cb(end)}`;
     }
     else {
         endString = start !== undefined ? '..' : '';

package/esm/util/markEncoding.js

@@ -51,6 +51,22 @@ function channelReader(table, ref, jexl) {
     const read = fieldReader(ref, jexl);
     return i => read(table.row(i));
 }
+// A text channel's reader, printing a float32 lane's value at the digits the
+// lane holds rather than the double it widens to: 0.3865, not 0.3865000009.
+function textChannelReader(table, ref, jexl) {
+    const read = channelReader(table, ref, jexl);
+    const column = typeof ref !== 'function' && isPlainFieldRef(ref)
+        ? table.column(ref)
+        : undefined;
+    return column?.kind === 'number' && column.values instanceof Float32Array
+        ? i => {
+            const v = read(i);
+            return typeof v === 'number' && !Number.isInteger(v)
+                ? String(Number(v.toPrecision(7)))
+                : valueText(v);
+        }
+        : i => valueText(read(i));
+}
 function numberChannelReader(table, ref, jexl) {
     if (typeof ref !== 'function' && isPlainFieldRef(ref)) {
         return numberReaderOf(table.column(ref));
@@ -457,10 +473,10 @@ export function encodeFeatures(input, encoding, lanes, ctx = {}) {
             text.fill('');
         }
         else {
-            const read = channelReader(table, textEncoding, jexl);
+            const read = textChannelReader(table, textEncoding, jexl);
             for (let k = 0; k < count; k++) {
                 report?.(k);
-                text[k] = valueText(read(rowAt(k)));
+                text[k] = read(rowAt(k));
             }
         }
     }
@@ -519,30 +535,47 @@ export function encodeFeatures(input, encoding, lanes, ctx = {}) {
             ? y
             : new Float32Array(count)
         : undefined;
-    const paintsColor = has('color') && !colorValue;
+    const colorKey = declaredScale?.scale === 'categorical' && has('colorKey')
+        ? new Uint32Array(count)
+        : undefined;
+    const paintsColor = has('color') && !colorValue && !colorKey;
     const unscaled = paintsColor && declaredScale?.scale !== 'categorical' && !quantitative
         ? unscaledColor(table, colorEncoding, jexl)
         : undefined;
     const color = paintsColor && typeof unscaled !== 'number'
         ? new Uint32Array(count)
         : undefined;
-    const scaled = paintsColor || colorValue ? declaredScale : undefined;
+    const scaled = paintsColor || colorValue || colorKey ? declaredScale : undefined;
+    const categoryLane = colorKey ?? color;
     let scale;
     let missingMet = false;
     let notNumberMet = false;
-    if (scaled?.scale === 'categorical' && color) {
+    if (scaled?.scale === 'categorical' && categoryLane) {
         const colorField = categoricalField(scaled.field, {
             domain: scaled.domain?.map(String),
             range: scaled.range,
         });
-        const entries = paintCategories(table, scaled.field, jexl, colorField, { kept, count, report }, color, key => cssColorToABGR(colorField.color(key)), abgr => abgr);
+        let resolved = 0;
+        const entries = paintCategories(table, scaled.field, jexl, colorField, { kept, count, report }, categoryLane, key => ({
+            color: cssColorToABGR(colorField.color(key)),
+            order: resolved++,
+        }), entry => (colorKey ? entry.order : entry.color));
+        if (colorKey) {
+            const position = new Uint32Array(resolved);
+            for (const [i, e] of entries.entries()) {
+                position[e.entry.order] = i;
+            }
+            for (let k = 0; k < count; k++) {
+                colorKey[k] = position[colorKey[k]];
+            }
+        }
         scale = {
             kind: 'categorical',
             field: scaled.field,
             domain: [...colorField.domain],
             ...(scaled.range ? { range: [...scaled.range] } : {}),
             ...(keysAreNumeric(entries) ? { numericKeys: true } : {}),
-            entries: entries.map(e => ({ value: e.value, color: e.entry })),
+            entries: entries.map(e => ({ value: e.value, color: e.entry.color })),
         };
     }
     else if (scaled && quantitative) {
@@ -570,10 +603,13 @@ export function encodeFeatures(input, encoding, lanes, ctx = {}) {
             const cuts = thresholdCuts(thresholdEncoding.domain ?? []);
             if (color) {
                 const binColors = Uint32Array.from(thresholdPalette(cuts.length + 1, thresholdEncoding.range), c => cssColorToABGR(c));
+                // in float32 on both sides, as the shader and the key compare, so a
+                // value off a float32 lane sits at a cut like 0.7 rather than under it
+                const cuts32 = cuts.map(cut => Math.fround(cut));
                 for (let k = 0; k < count; k++) {
                     report?.(k);
                     const v = read(rowAt(k));
-                    const bin = thresholdIndex(v, cuts);
+                    const bin = thresholdIndex(Math.fround(numericValue(v)), cuts32);
                     if (bin >= 0) {
                         color[k] = binColors[bin];
                     }
@@ -656,6 +692,9 @@ export function encodeFeatures(input, encoding, lanes, ctx = {}) {
         // the y view itself where the colour reads y, so a reader can tell
         encoded.colorValue = colorValue;
     }
+    if (colorKey) {
+        encoded.colorKey = colorKey;
+    }
     if (glyph) {
         encoded.glyph = glyph;
     }
@@ -830,6 +869,7 @@ export function encodedChannelTransferables(c) {
         c.row,
         typeof c.color === 'number' ? undefined : c.color,
         c.colorValue,
+        c.colorKey,
         c.glyph,
         c.size,
         c.x2Ref,

package/esm/util/markEncodingTypes.d.ts

@@ -149,7 +149,7 @@ export interface MarkEncoding {
  * allocated nor transferred, and a caller that never hovers declines the
  * index, which is most of the encoder's cost after the walk.
  */
-export type LaneName = 'y' | 'color' | 'colorValue' | 'glyph' | 'row' | 'text' | 'size' | 'x2Ref' | 'index';
+export type LaneName = 'y' | 'color' | 'colorValue' | 'colorKey' | 'glyph' | 'row' | 'text' | 'size' | 'x2Ref' | 'index';
 /**
  * #api
  * The scale a colour channel was resolved through, as the legend reads it —
@@ -318,6 +318,13 @@ export interface EncodedChannels {
      * colour reads the field `y` plots, this IS the `y` array, not a copy.
      */
     colorValue?: Float32Array;
+    /**
+     * Each instance's index into `scale.entries` under a categorical colour, for
+     * a caller that named the `colorKey` lane in place of `color`: the display
+     * then paints each key through its own `domain` and `range`, which never
+     * reach the worker.
+     */
+    colorKey?: Uint32Array;
     /** The point painter's code for each feature's `shape`. */
     glyph?: Uint8Array;
     row?: Uint32Array;