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

package/esm/pluggableElementTypes/models/BaseDisplayModel.js

@@ -1,5 +1,6 @@
 import { hasParent, isAlive, types } from '@jbrowse/mobx-state-tree';
-import { applyConfSettings, getConf } from '../../configuration/index.js';
+import { applyConfSettings, getConfigurationSchemaMetadata, getConf, setConf, } from '../../configuration/index.js';
+import { liftPlot as liftPlotDraft, plotKeysOf, plotOf, plotWrites as plotWritesOf, schemaPlotProblems, } from '../../configuration/plot.js';
 import { getContainingTrack, getEnv, statusFraction, statusMessageText, } from '../../util/index.js';
 import { ElementId } from '../../util/types/mst.js';
 import { displaySetterName } from '../../util/unknownSnapshotKeys.js';
@@ -198,7 +199,7 @@ function stateModelFactory() {
          * `installClearHoverOnViewportChange` calls.
          *
          * A display that STORES its hover owes an override; one that derives it
-         * from the live pointer (MAF, Hi-C, LD) owes nothing, and the default
+         * from the live pointer (Hi-C, LD) owes nothing, and the default
          * costs it nothing. Declared here so the clear can be installed for every
          * display rather than remembered per display — forgetting it is the
          * failure ARCHITECTURE.md's stored-hover section is about, and it used to
@@ -272,6 +273,87 @@ function stateModelFactory() {
             }
             return { applied, unapplied, failed };
         },
+    }))
+        .views(self => ({
+        /**
+         * #getter
+         * The grammar settings this display's config declares, by slot name
+         * (`PLOT_VOCABULARY`): what "Edit plot..." edits. Empty on a display
+         * with none, which then offers no editor.
+         */
+        get plotKeys() {
+            return plotKeysOf(self.configuration);
+        },
+        /**
+         * #getter
+         * Those settings as declared, defaults left off and a shorthand written
+         * as a config file writes it. An agent edits a `structuredClone` of it,
+         * checks it with `plotProblems` and hands it to `applyPlot`.
+         */
+        get plot() {
+            return plotOf(self.configuration);
+        },
+        /**
+         * #getter
+         * The worked examples this display type declares, which "Edit plot..."
+         * offers as buttons.
+         */
+        get plotExamples() {
+            const { pluginManager } = getEnv(self);
+            return pluginManager.getDisplayType(self.type).plotExamples;
+        },
+        /**
+         * #getter
+         * This display type's page in the config reference, which lists every
+         * setting it takes.
+         */
+        get configDocsUrl() {
+            const name = getConfigurationSchemaMetadata(self.configuration)?.name;
+            return name
+                ? `https://jbrowse.org/jb2/docs/config/${name.toLowerCase()}/`
+                : 'https://jbrowse.org/jb2/docs/config_guide/';
+        },
+        /**
+         * #method
+         * A draft as the config would hold it, merged over `plot`, throwing what
+         * a config file would be refused for. Nothing on the display changes.
+         */
+        liftPlot(draft) {
+            return liftPlotDraft(self.configuration, draft);
+        },
+        /**
+         * #method
+         * What a draft would report once applied, throwing a refusal as
+         * `liftPlot` does: what its colour objects and `scales.y` say together
+         * that cannot be drawn as written. A display with a rule list over its
+         * settings overrides it; the draft still applies, and draws what it can.
+         */
+        plotProblems(draft) {
+            return schemaPlotProblems(liftPlotDraft(self.configuration, draft));
+        },
+        /**
+         * #method
+         * What applying a draft would write, by setting: the lifted value where
+         * it differs from `plot`, `null` where it resets one. Throws a refusal.
+         */
+        plotWrites(draft) {
+            return plotWritesOf(self.configuration, draft);
+        },
+    }))
+        .actions(self => ({
+        /**
+         * #action
+         * Write a draft over `plot`: each setting it changes is replaced whole,
+         * so a member left out of an object goes back to its default, and `null`
+         * resets the setting. A draft the schema refuses, or naming a setting
+         * outside the plot, throws before anything is written.
+         */
+        applyPlot(draft) {
+            const { configuration } = self;
+            for (const [key, value] of Object.entries(self.plotWrites(draft))) {
+                setConf(configuration, key, value);
+            }
+        },
     }));
 }
 export const BaseDisplay = stateModelFactory();

package/esm/pluggableElementTypes/models/BaseTrackModel.d.ts

@@ -200,10 +200,8 @@ export declare function createBaseTrackModel(pm: PluginManager, trackType: strin
      * completely untouched ones — `reaction` only fires on an actual change.
      *
      * `equals: compareStructural` is load-bearing, not an optimization:
-     * `self.configuration` is a re-resolving reference, and persisting a save
-     * can swap the resolved node identity (the delta path reconciles in place
-     * but still churns once, and a session without deltas replaces the frozen
-     * `jbrowse.tracks` entry, rehydrating a brand-new MST node every write).
+     * `self.configuration` is a re-resolving reference, and an undo or a
+     * session restore swaps the resolved node for a new working copy.
      * Referential comparison would treat every such swap as a fresh change
      * and re-fire the save, an unbounded debounced loop. Structural
      * comparison settles once the content stops changing.

package/esm/pluggableElementTypes/models/BaseTrackModel.js

@@ -324,10 +324,8 @@ export function createBaseTrackModel(pm, trackType, baseTrackConfig) {
              * completely untouched ones — `reaction` only fires on an actual change.
              *
              * `equals: compareStructural` is load-bearing, not an optimization:
-             * `self.configuration` is a re-resolving reference, and persisting a save
-             * can swap the resolved node identity (the delta path reconciles in place
-             * but still churns once, and a session without deltas replaces the frozen
-             * `jbrowse.tracks` entry, rehydrating a brand-new MST node every write).
+             * `self.configuration` is a re-resolving reference, and an undo or a
+             * session restore swaps the resolved node for a new working copy.
              * Referential comparison would treat every such swap as a fresh change
              * and re-fire the save, an unbounded debounced loop. Structural
              * comparison settles once the content stops changing.

package/esm/pluggableElementTypes/models/BaseViewModel.d.ts

@@ -29,7 +29,7 @@ declare const BaseViewModel: import("@jbrowse/mobx-state-tree").IModelType<{
      *
      * `ViewContainer` mounts a view's body only while an IntersectionObserver
      * says it is on screen, to hold the app under the WebGL2 context ceiling
-     * (`reference/GPU_CONTEXT_BUDGET.md`). A view below the fold therefore has
+     * (`reference/GPU_PORTABILITY.md`). A view below the fold therefore has
      * no canvas, so nothing ever calls `markCanvasDrawn` and the pre-first-paint
      * term of `displayPhase` pins every display in it at `loading` with nothing
      * left to resolve it — which parks `[data-app-phase="ready"]` for the whole
@@ -169,7 +169,7 @@ export declare const BaseViewModelWithDisplayedRegions: import("@jbrowse/mobx-st
      *
      * `ViewContainer` mounts a view's body only while an IntersectionObserver
      * says it is on screen, to hold the app under the WebGL2 context ceiling
-     * (`reference/GPU_CONTEXT_BUDGET.md`). A view below the fold therefore has
+     * (`reference/GPU_PORTABILITY.md`). A view below the fold therefore has
      * no canvas, so nothing ever calls `markCanvasDrawn` and the pre-first-paint
      * term of `displayPhase` pins every display in it at `loading` with nothing
      * left to resolve it — which parks `[data-app-phase="ready"]` for the whole

package/esm/pluggableElementTypes/models/BaseViewModel.js

@@ -54,7 +54,7 @@ const BaseViewModel = types
      *
      * `ViewContainer` mounts a view's body only while an IntersectionObserver
      * says it is on screen, to hold the app under the WebGL2 context ceiling
-     * (`reference/GPU_CONTEXT_BUDGET.md`). A view below the fold therefore has
+     * (`reference/GPU_PORTABILITY.md`). A view below the fold therefore has
      * no canvas, so nothing ever calls `markCanvasDrawn` and the pre-first-paint
      * term of `displayPhase` pins every display in it at `loading` with nothing
      * left to resolve it — which parks `[data-app-phase="ready"]` for the whole

package/esm/pluggableElementTypes/models/baseTrackConfig.js

@@ -177,6 +177,7 @@ export function createBaseTrackConfig(pluginManager) {
                 type: 'stringArray',
                 description: 'list of which feature attributes to index for text searching',
                 defaultValue: ['Name', 'ID', 'symbol'],
+                advanced: true,
             },
             /**
              * #slot textSearching.indexingFeatureTypesToExclude
@@ -185,6 +186,7 @@ export function createBaseTrackConfig(pluginManager) {
                 type: 'stringArray',
                 description: 'list of feature types to exclude in text search index',
                 defaultValue: ['CDS', 'exon'],
+                advanced: true,
             },
             /**
              * #slot textSearching.indexingFeatureTypesToInclude
@@ -207,6 +209,7 @@ export function createBaseTrackConfig(pluginManager) {
                 type: 'stringArray',
                 description: 'the only feature types to index; empty means index every type not excluded',
                 defaultValue: [],
+                advanced: true,
             },
             /**
              * #slot textSearching.textSearchAdapter

package/esm/rpc/RpcRegistry.d.ts

@@ -100,9 +100,10 @@ export interface RpcRegistry {
         args: Record<string, unknown>;
         return: void;
     };
-    CoreLoadAdapterCode: {
+    CoreLoadTrackCode: {
         args: {
             adapterTypes: string[];
+            rpcMethods: string[];
         };
         return: void;
     };

package/esm/rpc/byteBudget.d.ts

@@ -33,6 +33,13 @@ export interface RegionTooLargeResult {
     partial?: boolean;
 }
 export declare function isRegionRefused(result: unknown): result is RegionTooLargeResult;
+/**
+ * The thrown form of the same refusal, for an adapter whose limit only a fetch
+ * can find, such as a graph's node count. Marked by an own `regionTooLarge`
+ * property, which crosses the worker boundary, so an adapter's own error class
+ * opts in without importing anything.
+ */
+export declare function isRegionTooLargeError(error: unknown): error is Error;
 /** Undefined, never 0, when no region could be measured. */
 export declare function largestRegionBytes(perRegion: (number | undefined)[]): number | undefined;
 /** A non-positive declared limit means "no opinion" (htsget reports 0). */

package/esm/rpc/byteBudget.js

@@ -3,6 +3,16 @@ import { updateStatus } from '../util/progress.js';
 export function isRegionRefused(result) {
     return (typeof result === 'object' && result !== null && 'regionTooLarge' in result);
 }
+/**
+ * The thrown form of the same refusal, for an adapter whose limit only a fetch
+ * can find, such as a graph's node count. Marked by an own `regionTooLarge`
+ * property, which crosses the worker boundary, so an adapter's own error class
+ * opts in without importing anything.
+ */
+export function isRegionTooLargeError(error) {
+    return (error instanceof Error &&
+        error.regionTooLarge === true);
+}
 /** Undefined, never 0, when no region could be measured. */
 export function largestRegionBytes(perRegion) {
     let largest;

package/esm/rpc/coreRpcMethods.d.ts

@@ -6,7 +6,7 @@ export { default as CoreGetEncodedLayers } from './methods/CoreGetEncodedLayers.
 export { default as CoreGetEncodedFeature } from './methods/CoreGetEncodedFeature.ts';
 export { default as CoreGetSequence } from './methods/CoreGetSequence.ts';
 export { default as CoreFreeResources } from './methods/CoreFreeResources.ts';
-export { default as CoreLoadAdapterCode } from './methods/CoreLoadAdapterCode.ts';
+export { default as CoreLoadTrackCode } from './methods/CoreLoadTrackCode.ts';
 export { default as CoreGetRegionByteEstimate } from './methods/CoreGetRegionByteEstimate.ts';
 export { default as CoreGetFeatureDensity } from './methods/CoreGetFeatureDensity.ts';
 export { default as CoreGetRegions } from './methods/CoreGetRegions.ts';

package/esm/rpc/coreRpcMethods.js

@@ -6,7 +6,7 @@ export { default as CoreGetEncodedLayers } from './methods/CoreGetEncodedLayers.
 export { default as CoreGetEncodedFeature } from './methods/CoreGetEncodedFeature.js';
 export { default as CoreGetSequence } from './methods/CoreGetSequence.js';
 export { default as CoreFreeResources } from './methods/CoreFreeResources.js';
-export { default as CoreLoadAdapterCode } from './methods/CoreLoadAdapterCode.js';
+export { default as CoreLoadTrackCode } from './methods/CoreLoadTrackCode.js';
 export { default as CoreGetRegionByteEstimate } from './methods/CoreGetRegionByteEstimate.js';
 export { default as CoreGetFeatureDensity } from './methods/CoreGetFeatureDensity.js';
 export { default as CoreGetRegions } from './methods/CoreGetRegions.js';

package/esm/rpc/explainTransferError.js

@@ -14,9 +14,9 @@
 // sentence this appends to.
 //
 // Only runs on the error path.
-// The deepest RPC result in the tree is the regular multi-sample variant one:
-// `perRegionCellData.0.featureGenotypeMap.<featureId>.genotypeCodes` — four
-// containers down. The alignments result is three (`groups.3.data.mismatchStarts`),
+// The deepest RPC result in the tree is the multi-sample variant one:
+// `perRegionCellData.0.featureInfo.<index>.genotypeCodes` — four containers
+// down. The alignments result is three (`groups.3.data.mismatchStarts`),
 // synteny two (`instanceData.bp1`, `attributes.identity`) and most are one. The
 // walk is capped rather than unbounded because a payload also carries plain data
 // — a featureIds array of half a million strings — and there is no reason to

package/esm/rpc/methods/CoreLoadTrackCode.d.ts

@@ -0,0 +1,17 @@
+import RpcMethodType from '../../pluggableElementTypes/RpcMethodType.ts';
+import type { RpcExecuteArgs } from '../RpcRegistry.ts';
+/**
+ * Load the code a track's first request runs in the worker it is about to use:
+ * its adapter classes and the RPC methods its display names. Each arrives by
+ * dynamic import on that request otherwise, after the view lays out, the
+ * assembly loads and the request's refNames resolve.
+ *
+ * At launch rather than at worker boot: until `parallelizeChunkLoading` is
+ * installed a classic worker loads chunks by serial `importScripts`, and an
+ * import there delayed the first data request 360ms at 80ms RTT.
+ */
+export default class CoreLoadTrackCode extends RpcMethodType<'CoreLoadTrackCode'> {
+    name: 'CoreLoadTrackCode';
+    execute({ adapterTypes, rpcMethods, }: RpcExecuteArgs<'CoreLoadTrackCode'>): Promise<void>;
+    serializeArguments(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/esm/rpc/methods/CoreLoadTrackCode.js

@@ -0,0 +1,24 @@
+import RpcMethodType from '../../pluggableElementTypes/RpcMethodType.js';
+/**
+ * Load the code a track's first request runs in the worker it is about to use:
+ * its adapter classes and the RPC methods its display names. Each arrives by
+ * dynamic import on that request otherwise, after the view lays out, the
+ * assembly loads and the request's refNames resolve.
+ *
+ * At launch rather than at worker boot: until `parallelizeChunkLoading` is
+ * installed a classic worker loads chunks by serial `importScripts`, and an
+ * import there delayed the first data request 360ms at 80ms RTT.
+ */
+export default class CoreLoadTrackCode extends RpcMethodType {
+    name = 'CoreLoadTrackCode';
+    async execute({ adapterTypes, rpcMethods, }) {
+        const { pluginManager } = this;
+        await Promise.all([
+            ...adapterTypes.map(type => pluginManager.getAdapterType(type).getAdapterClass()),
+            ...rpcMethods.map(name => pluginManager.getRpcMethodType(name).preload()),
+        ]);
+    }
+    async serializeArguments(args) {
+        return args;
+    }
+}

package/esm/ui/AppLogo.js

@@ -1,10 +1,50 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
 import { observer } from 'mobx-react';
 import { readConfObject } from '../configuration/index.js';
+import { isUriLocation } from '../util/types/data.js';
 import { LogoFull } from './Logo.js';
+function resolvedUri(location) {
+    return location.baseUri
+        ? new URL(location.uri, location.baseUri).href
+        : location.uri;
+}
+// A URI goes straight to the <img>, which needs no CORS; a local path, a
+// blob or a file handle is read into an object URL.
+function useLogoSrc(location) {
+    const [objectUrl, setObjectUrl] = useState();
+    useEffect(() => {
+        if (!location || isUriLocation(location)) {
+            return;
+        }
+        let url;
+        let cancelled = false;
+        import('../util/io/index.js')
+            .then(({ openLocation }) => openLocation(location).readFile())
+            .then(bytes => {
+            if (!cancelled) {
+                url = URL.createObjectURL(new Blob([bytes]));
+                setObjectUrl(url);
+            }
+        })
+            .catch((e) => {
+            console.error(e);
+        });
+        return () => {
+            cancelled = true;
+            if (url) {
+                URL.revokeObjectURL(url);
+            }
+        };
+    }, [location]);
+    return location && isUriLocation(location)
+        ? resolvedUri(location)
+        : location
+            ? objectUrl
+            : undefined;
+}
 const Logo = observer(function Logo({ session, }) {
-    const { configuration } = session;
-    const logoPath = readConfObject(configuration, 'logoPath');
-    return logoPath?.uri ? (_jsx("img", { src: logoPath.uri, alt: "Custom logo" })) : (_jsx(LogoFull, { variant: "white" }));
+    const src = useLogoSrc(readConfObject(session.configuration, 'logoPath'));
+    return src ? (_jsx("img", { src: src, alt: "Custom logo" })) : (_jsx(LogoFull, { variant: "white" }));
 });
 export default Logo;

package/esm/ui/JexlFilterDialog.d.ts

@@ -7,7 +7,7 @@ export interface JexlFilterExample {
 }
 /**
  * Editor for a display's jexl feature filters, for any display implementing
- * the two-tier {@link JexlFilterModel} contract. The Conditions tab shows each
+ * the {@link JexlFilterModel} contract. The Conditions tab shows each
  * line as rows of field, operator and value where it can, and as text where it
  * cannot; the Text tab is every line as text.
  *

package/esm/ui/JexlFilterDialog.js

@@ -6,7 +6,6 @@ import { Button, ListItemText, MenuItem, Tab, Tabs, TextField, } from '@mui/mate
 import { observer } from 'mobx-react';
 import { readConfObject } from '../configuration/readConfObject.js';
 import { addRow, describedColumns, readFilterRows, removeRow, replaceRow, resolveFields, stripJexlPrefix, writeFilterRows, } from '../util/jexlFilterRows.js';
-import { activeJexlFilters } from '../util/jexlFilters.js';
 import { ensureJexlPrefix } from '../util/jexlStrings.js';
 import { getContainingTrack } from '../util/mstUtils.js';
 import { makeStyles } from '../util/tss-react/index.js';
@@ -100,7 +99,7 @@ function withOneRow(state) {
 }
 /**
  * Editor for a display's jexl feature filters, for any display implementing
- * the two-tier {@link JexlFilterModel} contract. The Conditions tab shows each
+ * the {@link JexlFilterModel} contract. The Conditions tab shows each
  * line as rows of field, operator and value where it can, and as text where it
  * cannot; the Text tab is every line as text.
  *
@@ -116,7 +115,7 @@ const JexlFilterDialog = observer(function JexlFilterDialog({ model, handleClose
     const fieldList = fields instanceof Promise ? use(fields) : fields;
     const described = metadata && use(metadata);
     const [choices] = useState(() => resolveFields([...fieldList, ...describedColumns(described, fieldList)]));
-    const [state, setState] = useState(() => withOneRow(readFilterRows(activeJexlFilters(model), jexl, choices)));
+    const [state, setState] = useState(() => withOneRow(readFilterRows(model.configuredFilters(), jexl, choices)));
     const [tab, setTab] = useState('conditions');
     const [text, setText] = useState({ value: '', shown: '' });
     const textEdited = text.value !== text.shown;

package/esm/ui/buildExtraTrackMenuItems.d.ts

@@ -1,10 +1,10 @@
 import type PluginManager from '../PluginManager.ts';
-import type { AnyConfigurationModel } from '../configuration/index.ts';
+import type { AnyTrackConfig } from '../configuration/index.ts';
 import type { AbstractSessionModel, TrackActionView } from '../util/types/index.ts';
 import type { MenuItem } from './MenuTypes.ts';
 export interface ExtraTrackMenuItemsProps {
     session: AbstractSessionModel;
-    config: AnyConfigurationModel;
+    config: AnyTrackConfig;
     view?: TrackActionView;
 }
 /** Return the items to add, or nothing when the track isn't yours. */

package/esm/ui/colors.d.ts

@@ -15,11 +15,9 @@ export declare const paletteColors: {
  * The wide qualitative palette: every scheme above, in order, deduped and with
  * the neutrals dropped. ~40 entries.
  *
- * One list, because "give each row a distinct color" is one question this repo
- * answers in two places — the multi-row painter handing colors out by row
- * index, and the arrangement dialog's palette-by-attribute — and two lists
- * would mean a track's automatic colors and the colors it takes when a user
- * palettes it by hand were different palettes for no reason a reader could see.
+ * A feature's categorical colour deals from it; a row's deals from
+ * `rowPaletteColorAt`, which re-lights tableau10 rather than reaching for
+ * another scheme's hues.
  *
  * `tableau10` leads because its hues are the most evenly separated, so a track
  * with a handful of rows spends only that. The tail is what makes the 26
@@ -31,21 +29,16 @@ export declare const paletteColors: {
  * re-palettes), while a by-position painter has no value to hash and wraps.
  *
  * **It holds 14 pairs `similarColors` calls the same** — five schemes' blues,
- * oranges, greens, reds and pinks — and deduping it at construction is the
- * wrong reading of that, measured on the 38 GENCODE gene biotypes. Hashed,
- * which is what a track with no `colorDomain` does, 30 of them land on 22
- * colors and 38 on 26; the loss is the birthday collision on 40 slots, not the
- * near-twins, and only 3 of the pairs they land on read alike. Pruning to the
- * 30 distinct entries makes that 23 and 24, so it costs ten colors and buys
- * nothing.
+ * oranges, greens, reds and pinks. A dealt scale (`categoricalScale`'s `held`)
+ * steps over a twin of a color already dealt, so they cost a track only once
+ * it has more values than the 30 distinct entries.
  *
- * The near-twins bite the PINNED case instead, where a `domain` spends the
- * list in order: 30 listed values take 30 colors today and 7 of those pairs
- * read alike. Ordering the distinct 30 first and the twins behind them fixes
- * that outright (0 pairs at 30 listed values, 11 at 38 where the twins are
- * reached anyway) and costs no colors — but it moves every hashed color in
- * marks, GWAS, canvas, multi-row and the arrangement dialog, so it is a pass
- * with a figure refresh in it.
+ * The near-twins bite a `domain` instead, which spends the list in order: 30
+ * listed values take 30 colors and 7 of those pairs read alike. Ordering the
+ * distinct 30 first and the twins behind them fixes that outright (0 pairs at
+ * 30 listed values, 11 at 38 where the twins are reached anyway) and costs no
+ * colors — but it moves every hashed color in marks, GWAS, canvas, multi-row
+ * and the arrangement dialog, so it is a pass with a figure refresh in it.
  */
 export declare const categoricalPalette: string[];
 /**
@@ -60,18 +53,30 @@ export declare const categoricalPalette: string[];
 export declare function categoricalValueColor(value: string): string;
 export declare function categoricalValueColor<T>(value: string, palette: readonly T[]): T;
 /**
- * The categorical rule every scaled channel resolves through. With no
- * `domain` a value takes `categoricalValueColor`'s slot in `range`. With one,
- * the listed values take `range` in order, continuing into the `fallback`
- * entries `range` lacks past its end, and any other value takes a slot of the
- * whole list derived from itself that no listed value holds, nor one
- * `isNear` calls the same. A value's entry depends only on the value and the
- * declaration, so every region agrees on it, and adding a listed value moves
- * only the unlisted values on the slots it takes.
+ * The slots a categorical scale has dealt the values it met that its `domain`
+ * does not list, each recorded on first sight and never dealt again. The
+ * caller owns it and hands the same one to every scale that should agree.
  */
-export declare function categoricalScale<T>(domain: readonly (string | number)[] | undefined, range: readonly T[], { fallback, isNear, }?: {
+export type HeldSlots = Map<string, number>;
+/**
+ * The categorical rule every scaled channel resolves through. The values
+ * `domain` lists take `range` in order, continuing into the `fallback`
+ * entries `range` lacks past its end. Any other value takes the slot derived
+ * from itself (`categoricalValueColor`'s, with no `domain`) unless a listed
+ * value holds it or one `isNear` calls the same, and then another slot derived
+ * from itself.
+ *
+ * With `held`, a value is dealt once, on first sight: its slot avoids every
+ * slot `held` already records and their near twins as well, so values met
+ * together never share an entry while the list has room, and the slot is
+ * recorded so the value keeps it as others arrive. A value nothing else
+ * collides with keeps the entry it takes without `held`. With no `domain`, the
+ * deal spends `range` before spilling into the `fallback` entries it lacks.
+ */
+export declare function categoricalScale<T>(domain: readonly (string | number)[] | undefined, range: readonly T[], { fallback, isNear, held, }?: {
     fallback?: readonly T[];
     isNear?: (a: T, b: T) => boolean;
+    held?: HeldSlots;
 }): (value: string) => T;
 /**
  * Whether two CSS colors read as one: under 0.05 apart in OKLab, where the
@@ -81,9 +86,10 @@ export declare function similarColors(a: string, b: string): boolean;
 /**
  * `categoricalScale` for a color channel: `palette` (the wide palette when
  * empty) spent in `domain` order and continued into the wide palette, and an
- * unlisted value never on a listed value's color or one that reads the same.
+ * unlisted value never on a listed value's color or one that reads the same,
+ * nor, with `held`, on the color of a value met before it.
  */
-export declare function categoricalColorScale(domain: readonly (string | number)[] | undefined, palette?: readonly string[]): (value: string) => string;
+export declare function categoricalColorScale(domain: readonly (string | number)[] | undefined, palette?: readonly string[], held?: HeldSlots): (value: string) => string;
 /**
  * The color one value of a categorical color channel paints, by
  * `categoricalColorScale`. A value-less feature is neutral grey, and an array
@@ -104,6 +110,11 @@ export declare function hashString(str: string): number;
 export declare function getQueryColor(queryName: string): string;
 /** The palette color for a chromosome at `position` in its assembly. */
 export declare function refNamePaletteColorAt(position: number): string;
+/**
+ * The colour the row palette deals the row or value at `position`: tableau10
+ * less its grey, then re-lit laps of it, as a karyotype's are.
+ */
+export declare function rowPaletteColorAt(position: number): string;
 /**
  * The color a refName paints, BY POSITION IN THE ASSEMBLY where the caller
  * knows its chromosome order.