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

package/esm/util/analytics.js

@@ -1,14 +1,59 @@
 import { effectiveRenderer, getGraphicsCapabilities, } from '@jbrowse/render-core/graphicsCapabilities';
 import { readConfObject } from '../configuration/index.js';
 import { isElectron, rIC } from '../util/index.js';
+import { createSessionActivity, describeSession, tallyTypes, } from './sessionActivity.js';
+import { getConfAssemblyNamesOrNone } from './tracks.js';
+const analyticsUrl = 'https://analytics.jbrowse.org/api/v1';
+// Ties a page load's end reports to its start report. It lives in memory only,
+// so a reload gets a new one and nothing follows a user from load to load.
+let pageLoadId;
+function getPageLoadId() {
+    pageLoadId ??=
+        typeof crypto.randomUUID === 'function'
+            ? crypto.randomUUID()
+            : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    return pageLoadId;
+}
+// Names only, and only JBrowse's own: says whether a load was a link to a
+// location or a set of tracks without saying which. Read when this module
+// loads, because jbrowse-web folds `loc`, `tracks` and `assembly` into a
+// `session` parameter before the report goes out.
+const knownUrlParams = [
+    'assembly',
+    'config',
+    'highlight',
+    'loc',
+    'nav',
+    'session',
+    'sessionName',
+    'sessionTracks',
+    'tracklist',
+    'tracks',
+];
+export function urlParamNames(search) {
+    const params = new URLSearchParams(search);
+    return knownUrlParams.filter(name => params.has(name)).join(',');
+}
+const initialUrlParams = typeof window === 'undefined' ? '' : urlParamNames(window.location.search);
+function sessionTrackTypeCounts(session) {
+    const counts = {};
+    for (const track of session?.sessionTracks ?? []) {
+        const key = `sessionTrack-types-${track.type}`;
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+}
+async function send(stats, init) {
+    const qs = new URLSearchParams(Object.entries(stats).map(([key, value]) => [key, String(value)])).toString();
+    await fetch(`${analyticsUrl}?${qs}`, init);
+}
 // Both writers are fire-and-forget from several call sites, so they swallow
 // their own failures rather than rejecting: a floating rejected promise trips
 // the webpack-dev-server overlay (it listens for unhandledrejection), and an
 // analytics ping is never worth interrupting a session for.
 export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuery) {
     try {
-        const url = 'https://analytics.jbrowse.org/api/v1';
-        const multiAssemblyTracks = rootModel.jbrowse.tracks.filter(track => readConfObject(track, 'assemblyNames').length > 1).length;
+        const multiAssemblyTracks = rootModel.jbrowse.tracks.filter(track => getConfAssemblyNamesOrNone(track).length > 1).length;
         // The rung createGpuHal built where a display has built one by idle time,
         // else the ladder's prediction with any page-wide pin applied — so a
         // session that fell back to Canvas2D is counted as Canvas2D rather than as
@@ -24,8 +69,11 @@ export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuer
         const softwareRendering = capabilities.softwareWebgl ?? 'unknown';
         const { jbrowse: config, session, version: ver } = rootModel;
         const { tracks, assemblies, plugins } = config;
+        const shape = describeSession(session);
         // stats to be recorded in db
         const stats = {
+            event: 'start',
+            sid: getPageLoadId(),
             ver,
             'plugins-count': plugins?.length ?? 0,
             'plugin-names': plugins?.map(p => p.name).join(','),
@@ -33,6 +81,9 @@ export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuer
             'tracks-count': tracks.length,
             'session-tracks-count': session?.sessionTracks.length ?? 0,
             'open-views': session?.views.length ?? 0,
+            'view-types': tallyTypes(shape.viewTypes),
+            'open-track-types': tallyTypes(shape.trackTypes),
+            'url-params': initialUrlParams,
             'synteny-tracks-count': multiAssemblyTracks,
             // No `saved-sessions-count`: it counted localStorage keys matching
             // `localSaved-`, a format nothing has written since autosaved sessions
@@ -61,14 +112,8 @@ export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuer
             const key = `track-types-${track.type}`;
             trackTypeCounts[key] = (trackTypeCounts[key] ?? 0) + 1;
         }
-        const sessionTrackTypeCounts = {};
-        for (const track of session?.sessionTracks ?? []) {
-            const key = `sessionTrack-types-${track.type}`;
-            sessionTrackTypeCounts[key] = (sessionTrackTypeCounts[key] ?? 0) + 1;
-        }
-        Object.assign(stats, trackTypeCounts, sessionTrackTypeCounts);
-        const qs = new URLSearchParams(Object.entries(stats).map(([key, value]) => [key, String(value)])).toString();
-        await fetch(`${url}?${qs}`);
+        Object.assign(stats, trackTypeCounts, sessionTrackTypeCounts(session));
+        await send(stats);
     }
     catch (e) {
         console.warn('Failed to write analytics to AWS.', e);
@@ -108,6 +153,83 @@ export async function writeGAAnalytics(rootModel, initialTimestamp) {
         console.warn('Failed to write analytics to GA.', e);
     }
 }
+// What the page load's sessions held while in use, for the end report.
+const activity = createSessionActivity();
+let latestRootModel;
+let endReportsInstalled = false;
+let endReportsSent = 0;
+let lastEndSignature;
+let visibleMs = 0;
+let visibleSince;
+let visibleMsAtLastEnd = 0;
+const maxEndReports = 10;
+const resendAfterVisibleMs = 60_000;
+// The end report says what a session came to hold: the view, track and widget
+// types open when the tab was hidden and those opened at any point before.
+// A tab is hidden many times before it closes and the close itself is not
+// reliably observable, so each hide sends one, numbered by `seq`, when the
+// session changed or another minute was spent on the page. The last one for a
+// `sid` is the session's end.
+export async function writeAWSSessionEnd() {
+    try {
+        if (!activity.watching || endReportsSent >= maxEndReports) {
+            return;
+        }
+        const seen = activity.stats();
+        const signature = JSON.stringify(seen);
+        if (signature === lastEndSignature &&
+            visibleMs - visibleMsAtLastEnd < resendAfterVisibleMs) {
+            return;
+        }
+        lastEndSignature = signature;
+        visibleMsAtLastEnd = visibleMs;
+        endReportsSent += 1;
+        const stats = {
+            event: 'end',
+            sid: getPageLoadId(),
+            seq: endReportsSent,
+            duration: Math.round(performance.now() / 1000),
+            'visible-time': Math.round(visibleMs / 1000),
+            ...seen,
+            electron: isElectron,
+            jb2: true,
+        };
+        try {
+            const { session, version } = latestRootModel ?? {};
+            stats.ver = version;
+            stats['session-tracks-count'] = session?.sessionTracks.length ?? 0;
+            Object.assign(stats, sessionTrackTypeCounts(session));
+        }
+        catch {
+            // root model left its state tree; the accumulated types still go out
+        }
+        // keepalive lets the request outlive the page it was sent from
+        await send(stats, { keepalive: true });
+    }
+    catch (e) {
+        console.warn('Failed to write analytics to AWS.', e);
+    }
+}
+function installEndReports() {
+    if (!endReportsInstalled) {
+        endReportsInstalled = true;
+        if (document.visibilityState === 'visible') {
+            visibleSince = performance.now();
+        }
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden') {
+                if (visibleSince !== undefined) {
+                    visibleMs += performance.now() - visibleSince;
+                    visibleSince = undefined;
+                }
+                void writeAWSSessionEnd();
+            }
+            else {
+                visibleSince = performance.now();
+            }
+        });
+    }
+}
 // One pageview per page load, not per pluginManager. jbrowse-web rebuilds the
 // whole pluginManager (and rootModel) whenever plugins change, and StrictMode
 // builds it twice on mount — without this guard each rebuild re-pings AWS and
@@ -115,9 +237,19 @@ export async function writeGAAnalytics(rootModel, initialTimestamp) {
 // growing the document on every plugin install.
 let analyticsSent = false;
 export function doAnalytics(rootModel, initialTimestamp, initialSessionQuery) {
-    if (rootModel &&
-        !analyticsSent &&
-        !readConfObject(rootModel.jbrowse.configuration, 'disableAnalytics')) {
+    if (!rootModel) {
+        return;
+    }
+    // a config that opts out stops the end reports too, whichever config or
+    // session started them
+    if (readConfObject(rootModel.jbrowse.configuration, 'disableAnalytics')) {
+        activity.stop();
+        return;
+    }
+    latestRootModel = rootModel;
+    activity.watch(() => rootModel.session);
+    installEndReports();
+    if (!analyticsSent) {
         analyticsSent = true;
         // writeGAAnalytics injects Google's scripts and writeAWSAnalytics probes
         // graphics capabilities, hundreds of ms of main-thread work together. Idle
@@ -138,7 +270,8 @@ export function doAnalytics(rootModel, initialTimestamp, initialSessionQuery) {
 // `[data-app-phase="ready"]`, or a timeout for a page that never shows one
 // (Desktop's start screen)
 function afterAppReady(callback, maxWaitMs = 10_000) {
-    const isReady = () => document.querySelector('[data-app-phase="ready"]') !== null;
+    const doc = document;
+    const isReady = () => doc.querySelector('[data-app-phase="ready"]') !== null;
     if (isReady()) {
         callback();
         return;
@@ -158,7 +291,7 @@ function afterAppReady(callback, maxWaitMs = 10_000) {
         }
     });
     const timer = setTimeout(finish, maxWaitMs);
-    observer.observe(document.body, {
+    observer.observe(doc.body, {
         subtree: true,
         childList: true,
         attributeFilter: ['data-app-phase'],

package/esm/util/bezierConnector.d.ts

@@ -1,5 +1,25 @@
+/**
+ * A symmetric cubic's extreme sits 3/4 of the way from its baseline to its
+ * controls; the sashimi labels solve the same equation in the other direction.
+ */
 export declare const CUBIC_APEX_RATIO = 0.75;
+/**
+ * How far a curve can stray outside the band between its two endpoints, which
+ * a culler pads its viewport test by.
+ */
 export declare const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
+/**
+ * One horizontal-tangent connector curve as an SVG path: the read and
+ * breakpoint connector BreakpointSplitView's AlignmentConnections draws, and
+ * the alignments display draws as render-core's `connector` mark. The
+ * geometry is that shader's own, through its JS twin, so the two views cannot
+ * drift in which way a connection leaves its read.
+ *
+ * A discordant connection dips below its ends instead of bowing up over them,
+ * so the two classes read apart at a glance. How deep is the caller's call:
+ * only it knows the band the ink has to survive in, and `discordantDipPx`
+ * (@jbrowse/sv-core) is the law the two views share.
+ */
 export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dipPx, }: {
     x1: number;
     y1: number;

package/esm/util/bezierConnector.js

@@ -1,101 +1,39 @@
-// One horizontal-tangent "oval" connector curve, shared by the alignments
-// linked-read bezier overlay (PileupBezierOverlay) and BreakpointSplitView's
-// AlignmentConnections so the two renderers draw a connection identically. Both
-// describe the same thing — two read endpoints (from the shared
-// connectionEndpoints rule), each segment's strand, and whether the second end
-// is a split junction's 5' edge — and this owns the curve geometry, so the
-// direction logic can't drift between them.
-// A handle or bow larger than the endpoints' own separation folds the cubic
-// back over itself: the curve leaves along its tangent, overshoots the far
-// endpoint, and has to curl back to arrive — the "loop-de-loop"/squiggle seen
-// on tightly-spaced reads. So every shaping term stays under this fraction of
-// the span the curve actually has to cover. Endpoints that nearly touch
-// therefore get no shaping at all and draw as the straight line they should be.
-const SPAN_FACTOR = 0.3;
-// Ceiling on the control-handle length. The span budget is what actually scales
-// the handle — it resolves below this for any connection whose endpoints are
-// closer than ~667px apart, which is nearly all of them — so this only bites on
-// very wide arcs. There it bounds the fold-back hook that an inversion draws at
-// its leading end: unbounded, that hook grows with the arc, and a full-width
-// inversion flings a ~500px curl back across unrelated reads.
-const MAX_HANDLE_PX = 200;
-// A symmetric cubic's extreme sits 3/4 of the way from its baseline to its
-// control points, so an arc asked to reach a given apex puts its controls 4/3
-// past it. Exported because the sashimi overlay solves the same equation in the
-// other direction, and the two spellings drifting apart would put the insert-
-// size ruler's labels at heights nothing plots at.
-export const CUBIC_APEX_RATIO = 0.75;
-// Vertical bow applied to a connection whose two endpoints share (or nearly
-// share) a row — e.g. a chain whose split segments are all laid out on one
-// pileup row. Without it the horizontal-only handles collapse the cubic to a
-// flat, invisible line lying on the row; the bow lifts the control points so
-// the curve arcs into a visible hump. This is the control-point lift, not the
-// height the curve reaches.
-const MAX_BOW_PX = 30;
-// A discordant connection bows *down* instead of up, so the two classes read
-// apart at a glance. Both renderers follow this: BreakpointSplitView dips its
-// same-level discordant links, and the pileup overlay dips every discordant
-// curve it draws (a normal-orientation pair is a plain line, or bows up over its
-// row where a hidden-segment one would lie on a chain's connecting line). Keep
-// it that way — a renderer that opts out makes "below the reads" mean two
-// different things in two views of the same data.
-//
-// HOW DEEP is the renderer's call, not this file's. Depth is the mark's one free
-// channel, and only the renderer knows the band the ink has to survive in — the
-// pileup clips each section at its band bottom, and the split view bleeds a
-// too-deep dip into the panel below. So callers pass the depth they want and
-// `discordantDipPx` (@jbrowse/sv-core) is the law the two of them share.
-// How far a curve can stray outside the band between its two endpoints. The dip
-// is the deeper of the two shaping terms, so this is a ceiling on it, applied
-// here rather than trusted to a caller: a culler pads its viewport test by this,
-// and the shaping is applied to the *control points*, so a curve whose two
-// endpoints both sit just outside the viewport can still have a visible body.
-export const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
-// Sign (+1/-1) of an endpoint's horizontal control handle. The handle leaves a
-// trailing (3') endpoint along the read's reading direction (`strand`); at a
-// split junction's leading (5') endpoint it flips, so the curve arrives flowing
-// *into* the next segment (a fwd→rev inversion folds back instead of cutting
-// straight across). `reversed` flips screen-x for a reverse-complemented region.
-function tangentSign(strand, leading, reversed) {
-    return strand * (leading ? -1 : 1) * (reversed ? -1 : 1);
-}
-// How much shaping (handle length, bow height) this curve may spend: a fraction
-// of the distance it has to cover.
-function shapingBudget(p1, p2) {
-    return Math.hypot(p2.x - p1.x, p2.y - p1.y) * SPAN_FACTOR;
-}
-// Fades to zero as the endpoints' rows separate, since a cross-row curve
-// already has vertical extent — and via the budget as they close in
-// horizontally, since a short connector is legible without a hump.
-function bowHeight(p1, p2, budget) {
-    return Math.min(budget, Math.max(0, MAX_BOW_PX - Math.abs(p2.y - p1.y)));
-}
-function cubicPath(from, ctrl1, ctrl2, to) {
-    return `M ${from.x} ${from.y} C ${ctrl1.x} ${ctrl1.y} ${ctrl2.x} ${ctrl2.y} ${to.x} ${to.y}`;
-}
+import { connectorBudgetPx, connectorHandlePx, connectorLiftPx, connectorTangent, } from '@jbrowse/render-core/shaders/connectorMark';
+import { CONNECTOR_APEX_RATIO, CONNECTOR_BOW, CONNECTOR_MAX_HANDLE_PX, CONNECTOR_MAX_REACH_PX, } from '@jbrowse/render-core/shaders/connectorMarkConsts';
+/**
+ * A symmetric cubic's extreme sits 3/4 of the way from its baseline to its
+ * controls; the sashimi labels solve the same equation in the other direction.
+ */
+export const CUBIC_APEX_RATIO = CONNECTOR_APEX_RATIO;
+/**
+ * How far a curve can stray outside the band between its two endpoints, which
+ * a culler pads its viewport test by.
+ */
+export const BEZIER_CONNECTOR_MAX_REACH_PX = CONNECTOR_MAX_REACH_PX;
+/**
+ * One horizontal-tangent connector curve as an SVG path: the read and
+ * breakpoint connector BreakpointSplitView's AlignmentConnections draws, and
+ * the alignments display draws as render-core's `connector` mark. The
+ * geometry is that shader's own, through its JS twin, so the two views cannot
+ * drift in which way a connection leaves its read.
+ *
+ * A discordant connection dips below its ends instead of bowing up over them,
+ * so the two classes read apart at a glance. How deep is the caller's call:
+ * only it knows the band the ink has to survive in, and `discordantDipPx`
+ * (@jbrowse/sv-core) is the law the two views share.
+ */
 export function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, 
 // The second endpoint is a split junction's 5' leading edge (its handle flips
 // to fold the curve into the next segment); false for a paired mate's 3' edge.
-leadingEnd2 = false, reversed1 = false, reversed2 = false, maxHandlePx = MAX_HANDLE_PX, 
-// Depth, in px, of the dip a discordant connection draws instead of the bow a
-// concordant one gets — aberrant pair orientation, or a split junction's
-// strand flip, so the two classes are tellable apart by shape alone. It is
-// the depth of the curve's APEX — what a caller can bound by the room it has —
-// and CUBIC_APEX_RATIO converts it to the control-point drop that puts the ink
-// there. Leave it out to bow up.
+leadingEnd2 = false, reversed1 = false, reversed2 = false, maxHandlePx = CONNECTOR_MAX_HANDLE_PX, 
+// Depth, in px, of the APEX of the dip a discordant connection draws instead
+// of the bow a concordant one gets. Leave it out to bow up.
 dipPx, }) {
-    const from = { x: x1, y: y1 };
-    const to = { x: x2, y: y2 };
-    const budget = shapingBudget(from, to);
-    const handle = Math.min(maxHandlePx, budget);
-    // The dip is deliberately not clamped to the budget, unlike the bow. The
-    // budget stops the cubic folding back over itself, and only the horizontal
-    // handles can do that — a vertical offset leaves x(t) monotonic however deep
-    // it goes, so a big event squeezed into a few px draws a narrow trough rather
-    // than a squiggle. Pinned by 'a dipped connection never overshoots its
-    // endpoints in x'.
-    const bow = dipPx === undefined
-        ? bowHeight(from, to, budget)
-        : -Math.min(dipPx, BEZIER_CONNECTOR_MAX_REACH_PX) / CUBIC_APEX_RATIO;
-    return cubicPath(from, { x: x1 + handle * tangentSign(s1, false, reversed1), y: y1 - bow }, { x: x2 + handle * tangentSign(s2, leadingEnd2, reversed2), y: y2 - bow }, to);
+    const dy = y2 - y1;
+    const budget = connectorBudgetPx(x2 - x1, dy);
+    const handle = connectorHandlePx(budget, maxHandlePx);
+    const lift = connectorLiftPx(budget, dy, dipPx ?? CONNECTOR_BOW);
+    const c1x = x1 + handle * connectorTangent(s1, 0, reversed1 ? 1 : 0);
+    const c2x = x2 + handle * connectorTangent(s2, leadingEnd2 ? 1 : 0, reversed2 ? 1 : 0);
+    return `M ${x1} ${y1} C ${c1x} ${y1 - lift} ${c2x} ${y2 - lift} ${x2} ${y2}`;
 }

package/esm/util/cacheBudgets.d.ts

@@ -51,5 +51,8 @@ import { SharedBudget } from '@gmod/shared-read-cache';
  * why this used to be two budgets named for their units: a million records
  * could not be added to bytes, and never bound long-read data either, where a
  * 6 MB slice counted as 37.
+ *
+ * `@jbrowse/tables` lowers the limit for a host such as R, which keeps no
+ * track open to pan (`packages/tables/src/cache.ts`).
  */
 export declare const decompressedBytesBudget: SharedBudget;

package/esm/util/cacheBudgets.js

@@ -51,5 +51,8 @@ import { SharedBudget } from '@gmod/shared-read-cache';
  * why this used to be two budgets named for their units: a million records
  * could not be added to bytes, and never bound long-read data either, where a
  * 6 MB slice counted as 37.
+ *
+ * `@jbrowse/tables` lowers the limit for a host such as R, which keeps no
+ * track open to pan (`packages/tables/src/cache.ts`).
  */
 export const decompressedBytesBudget = new SharedBudget(1024 * 2 ** 20);

package/esm/util/categoricalField.d.ts

@@ -1,3 +1,4 @@
+import type { HeldSlots } from '../ui/colors.ts';
 /** #api */
 export declare const STRAND_FIELD = "strand";
 /**
@@ -19,7 +20,9 @@ export declare const NO_VALUE_LABEL = "(no value)";
  * orders keys (the `domain` first, the rest by `compareGroupKeys`, `''`
  * after them), `label` names a key in a legend, `sectionLabel` on a chip, and
  * `color` paints it. A key's color depends only on the key and the
- * declaration, so every region agrees on it.
+ * declaration, so every region agrees on it, except that a field dealing its
+ * colors (`categoricalField`'s `held`) also steps a key off the colors of the
+ * keys met before it.
  */
 export interface CategoricalField {
     field: string;
@@ -38,7 +41,7 @@ export interface CategoricalField {
 }
 /**
  * #api
- * What a key names each of `keys`, from a colour object's `labels`: one each in
+ * What a key names each of `keys`, from a color object's `labels`: one each in
  * order, an empty or missing entry leaving that key its own name. Every key
  * that takes `labels` reads them through this, so a config means one thing by
  * them everywhere.
@@ -47,10 +50,27 @@ export declare function keyNames(keys: readonly unknown[], labels?: readonly str
 /**
  * #api
  * `labels` names the `domain`'s values in a key, one each in order, where a
- * config spells them for a reader rather than as the data does.
+ * config spells them for a reader rather than as the data does. `held` deals
+ * each key the domain does not list a color of its own on first sight
+ * (`categoricalScale`); the caller keeps it for as long as the colors should
+ * hold.
  */
-export declare function categoricalField(field: string, { domain, range, labels, }?: {
+export declare function categoricalField(field: string, { domain, range, labels, held, }?: {
     domain?: readonly string[];
     range?: readonly string[];
     labels?: readonly string[];
+    held?: HeldSlots;
 }): CategoricalField;
+/**
+ * #api
+ * Deals `keys` their colors in `field.compare` order, so the colors a set
+ * of keys first seen together takes do not depend on the order they arrive
+ * in. A no-op for a field that deals nothing.
+ */
+export declare function dealKeyColors(field: CategoricalField, keys: Iterable<string>): void;
+/**
+ * #api
+ * The `HeldSlots` `owner` keeps under `key`, made empty on first ask. Lives as
+ * long as `owner` and is never persisted, so a reload deals afresh.
+ */
+export declare function heldSlotsOf(owner: object, key: string): HeldSlots;

package/esm/util/categoricalField.js

@@ -18,7 +18,7 @@ export const SV_TYPE_FIELD = 'svType';
 export const NO_VALUE_LABEL = '(no value)';
 /**
  * #api
- * What a key names each of `keys`, from a colour object's `labels`: one each in
+ * What a key names each of `keys`, from a color object's `labels`: one each in
  * order, an empty or missing entry leaving that key its own name. Every key
  * that takes `labels` reads them through this, so a config means one thing by
  * them everywhere.
@@ -37,11 +37,14 @@ export function keyNames(keys, labels = []) {
 /**
  * #api
  * `labels` names the `domain`'s values in a key, one each in order, where a
- * config spells them for a reader rather than as the data does.
+ * config spells them for a reader rather than as the data does. `held` deals
+ * each key the domain does not list a color of its own on first sight
+ * (`categoricalScale`); the caller keeps it for as long as the colors should
+ * hold.
  */
-export function categoricalField(field, { domain = [], range = [], labels = [], } = {}) {
+export function categoricalField(field, { domain = [], range = [], labels = [], held, } = {}) {
     // a field with a vocabulary of its own reads it on every channel, a facet's
-    // sections as well as a colour's key
+    // sections as well as a color's key
     const vocabulary = universalPresetOf(field);
     const ownOrder = vocabulary?.domain ?? [];
     const order = domain.length > 0 ? domain : ownOrder;
@@ -66,8 +69,38 @@ export function categoricalField(field, { domain = [], range = [], labels = [],
             if (key === '') {
                 return NO_CATEGORY_COLOR;
             }
-            colorOf ??= categoricalColorScale(paired, colors);
+            colorOf ??= categoricalColorScale(paired, colors, held);
             return colorOf(key);
         },
     };
 }
+/**
+ * #api
+ * Deals `keys` their colors in `field.compare` order, so the colors a set
+ * of keys first seen together takes do not depend on the order they arrive
+ * in. A no-op for a field that deals nothing.
+ */
+export function dealKeyColors(field, keys) {
+    for (const key of [...new Set(keys)].sort(field.compare)) {
+        field.color(key);
+    }
+}
+const heldByOwner = new WeakMap();
+/**
+ * #api
+ * The `HeldSlots` `owner` keeps under `key`, made empty on first ask. Lives as
+ * long as `owner` and is never persisted, so a reload deals afresh.
+ */
+export function heldSlotsOf(owner, key) {
+    let byKey = heldByOwner.get(owner);
+    if (byKey === undefined) {
+        byKey = new Map();
+        heldByOwner.set(owner, byKey);
+    }
+    let held = byKey.get(key);
+    if (held === undefined) {
+        held = new Map();
+        byKey.set(key, held);
+    }
+    return held;
+}

package/esm/util/cellMatches.js

@@ -1,8 +1,9 @@
 // A `cells` step, the interval `bin` behind it and the `aggregate` of its
 // matches as one walk over the rows' bytes, which `runSteps` in
 // featureTransforms.ts reaches by relative path only.
+import { DASH, SPACE, firstDrawn, isGapByte, lastDrawn, } from './alignedBytes.js';
 import { fusesBinAggregate } from './binnedAggregate.js';
-import { DASH, DEFAULT_CELLS_FIELD, MATCH, MISMATCH, NO_STATE, SPACE, cellState, firstDrawn, isGapByte, lastDrawn, walkedTexts, } from './cellsStep.js';
+import { DEFAULT_CELLS_FIELD, MATCH, NO_STATE, cellState, comparesBase, opensRun, runKey, walkedTexts, } from './cellsStep.js';
 import { numberReaderOf, readerOf } from './featureTable.js';
 import { BIN_OVERLAP_FIELD, DEFAULT_BIN_AS, OpSums, groupKey, madeGroups, } from './stepTables.js';
 const isEdges = (pair) => pair?.length === 2 && pair[0] === 'start' && pair[1] === 'end';
@@ -97,10 +98,10 @@ class SectionBins {
     }
     /**
      * One row's runs as `cells` writes them, each met by its bins as the bin
-     * step cuts it and in the order the lanes hold them: a run when the next
-     * column's state differs, an insertion at the reference base after it,
-     * ahead of the run still open. The bases a run of matches or mismatches
-     * holds are counted in their bins as the walk passes them.
+     * step cuts it and in the order the lanes hold them: a run where the next
+     * column `opensRun`, an insertion at the reference base after it,
+     * ahead of the run still open. The compared bases a run holds are counted
+     * in their bins as the walk passes them.
      */
     walk(r, startPos, size, rowBytes, rowAt, rowLen, refBytes, refAt, refLen) {
         const { matched, compared, low } = this;
@@ -114,7 +115,7 @@ class SectionBins {
         let runOpen = false;
         let runBin = 0;
         let runState = NO_STATE;
-        let runBase = -1;
+        let openKey = -1;
         let inserting = false;
         for (let col = 0; col < refLen; col++) {
             const refByte = refBytes[refAt + col];
@@ -130,22 +131,21 @@ class SectionBins {
                 inserting = false;
             }
             const st = cellState(refByte, rowByte, col >= first && col <= last && col < rowLen);
-            const base = st === MISMATCH ? rowByte : -1;
-            if (st !== runState || base !== runBase) {
+            const key = runKey(st, refByte);
+            if (opensRun(st, key, runState, openKey)) {
                 if (runOpen) {
                     this.touch(runBin, pos > edge - size ? bin : bin - 1, r);
                 }
                 runOpen = st !== NO_STATE;
                 runBin = bin;
                 runState = st;
-                runBase = base;
+                openKey = key;
             }
-            if (st === MATCH) {
-                m++;
-                c++;
-            }
-            else if (st === MISMATCH) {
+            if (comparesBase(st, refByte)) {
                 c++;
+                if (st === MATCH) {
+                    m++;
+                }
             }
             pos++;
             if (pos === edge) {

package/esm/util/cellsStep.d.ts

@@ -2,15 +2,13 @@ import type { FeatureTable, TextColumn } from './featureTable.ts';
 import type { CellsStep } from './markEncodingTypes.ts';
 import type { Staged } from './stepTables.ts';
 export declare const DEFAULT_CELLS_FIELD = "seq";
-export declare const DASH = 45;
-export declare const SPACE = 32;
 export declare const MATCH = 0;
 export declare const MISMATCH = 1;
 export declare const NO_STATE = 255;
-export declare function isGapByte(b: number): b is 32 | 45;
-export declare function firstDrawn(bytes: Uint8Array, at: number, len: number): number;
-export declare function lastDrawn(bytes: Uint8Array, at: number, len: number, first: number): number;
 export declare function cellState(refByte: number, rowByte: number, drawn: boolean): 0 | 1 | 2 | 255;
+export declare function comparesBase(state: number, refByte: number): boolean;
+export declare function runKey(state: number, refByte: number): 0 | 1;
+export declare function opensRun(state: number, key: number, runState: number, openKey: number): boolean;
 /**
  * The texts a `cells` walk reads, by the row of the table it walked: each
  * row's own, and the reference it is read against, which a row fanned out of