@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/colorSwatchStyle.js

@@ -0,0 +1,11 @@
+// Shared clickable color-swatch button style, used by ColorPicker's preset grid
+// and PopoverPicker's trigger swatch.
+export const swatchStyle = {
+    width: 24,
+    height: 24,
+    margin: 4,
+    border: 'none',
+    padding: 0,
+    cursor: 'pointer',
+    outline: 'none',
+};

package/esm/ui/colors.d.ts

@@ -1,10 +1,127 @@
 declare const category10: string[];
-declare const dark2: string[];
 declare const set1: string[];
-declare const set2: string[];
-declare const tableau10: string[];
-declare const ggplot2Colors6: string[];
-declare const ggplot2Colors5: string[];
-declare const ggplot2Colors4: string[];
-declare const ggplot2Colors3: string[];
-export { category10, dark2, ggplot2Colors3, ggplot2Colors4, ggplot2Colors5, ggplot2Colors6, set1, set2, tableau10, };
+export declare const paletteColors: {
+    category10: string[];
+    dark2: string[];
+    ggplot2Colors3: string[];
+    ggplot2Colors4: string[];
+    ggplot2Colors5: string[];
+    ggplot2Colors6: string[];
+    set1: string[];
+    set2: string[];
+    tableau10: string[];
+};
+/**
+ * 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.
+ *
+ * `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
+ * 1000-Genomes population codes, or a repeat painting's classes, all get a
+ * curated color instead of falling out to `randomColor`.
+ *
+ * Past the end is the caller's problem, and the two callers answer differently
+ * on purpose: an attribute palette-by hashes the VALUE (stable across
+ * 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.
+ *
+ * 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.
+ */
+export declare const categoricalPalette: string[];
+/**
+ * The palette color a categorical value paints, derived from the value rather
+ * than from the order it was met: values stream in as regions load, and a
+ * discovery-order slot would let one region paint `chr2` blue and the next
+ * paint it pink. A non-negative integer takes the slot it names, anchored at
+ * 1, so `1`, `2`, `3` walk the palette in order and stay distinct; anything
+ * else hashes in, stable for the same reason at the cost of an occasional
+ * collision. `categoricalScale` is the same rule with a domain.
+ */
+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.
+ */
+export declare function categoricalScale<T>(domain: readonly (string | number)[] | undefined, range: readonly T[], { fallback, isNear, }?: {
+    fallback?: readonly T[];
+    isNear?: (a: T, b: T) => boolean;
+}): (value: string) => T;
+/**
+ * Whether two CSS colors read as one: under 0.05 apart in OKLab, where the
+ * wide palette's tableau and category10 oranges sit 0.003 apart.
+ */
+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.
+ */
+export declare function categoricalColorScale(domain: readonly (string | number)[] | undefined, palette?: readonly string[]): (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
+ * value joins the way a group key does.
+ */
+export declare function categoricalColor(value: unknown, domain?: readonly string[], palette?: readonly string[]): string;
+/**
+ * Deterministic non-negative 32-bit hash of a string.
+ */
+export declare function hashString(str: string): number;
+/**
+ * Stable category10 color for a sequence name, via `hashString`.
+ *
+ * Kept as a published export; in-tree, prefer {@link refNameColor}, which hands
+ * the palette out by position where the caller knows the assembly's chromosome
+ * order and only hashes where it does not.
+ */
+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 color a refName paints, BY POSITION IN THE ASSEMBLY where the caller
+ * knows its chromosome order.
+ *
+ * Handing the palette out rather than hashing into it is what stops a genome
+ * painting two of its own chromosomes the same color: nine slots means ten or
+ * more chromosomes re-use one, and by the birthday bound long before that. On
+ * hg38 the hash puts chr1, chr12, chr21 and chrY on one color.
+ *
+ * `position` is undefined for the case the order genuinely is not available —
+ * an assembly still loading, or a refName the assembly does not list (a
+ * scaffold under an alias). There a stable arbitrary color beats no color, so
+ * it falls back to the hash.
+ */
+export declare function refNameColor(name: string, position: number | undefined): string;
+/**
+ * A palette named in `namedPalettes`, or a comma-separated list of CSS
+ * colours; undefined, with a warning, for anything else.
+ */
+export declare function paletteFromSpec(spec: unknown): readonly string[] | undefined;
+export { category10, set1 };

package/esm/ui/colors.js

@@ -1,3 +1,8 @@
+import * as convert from '../util/color-bits/convert.js';
+import { NO_CATEGORY_COLOR, relight } from '../util/color/index.js';
+import { cssColorToNormalizedRgb } from '../util/colorBits.js';
+import { isCssColor } from '../util/cssColorParse.js';
+import { valueText } from '../util/groupKeys.js';
 const category10 = [
     '#1f77b4',
     '#ff7f0e',
@@ -64,4 +69,362 @@ const ggplot2Colors6 = [
 const ggplot2Colors5 = ['#F8766D', '#A3A500', '#00BF7D', '#00B0F6', '#E76BF3'];
 const ggplot2Colors4 = ['#F8766D', '#7CAE00', '#00BFC4', '#C77CFF'];
 const ggplot2Colors3 = ['#F8766D', '#00BA38', '#619CFF'];
-export { category10, dark2, ggplot2Colors3, ggplot2Colors4, ggplot2Colors5, ggplot2Colors6, set1, set2, tableau10, };
+// A neutral has no place in a categorical palette that paints FILLS. Grey reads
+// as "uncolored / no value" — it is what `randomColor` hands a value-less
+// feature, what a synteny ribbon defaults to, what alignments paint a read with
+// no tag — so a category landing on one says the opposite of what the palette
+// is for. `refNameColorHexes` below drops category10's grey for this reason and
+// has since it was written; this is the same rule applied to every scheme at
+// once.
+const NEUTRALS = new Set([
+    '#bab0ab',
+    '#999999',
+    '#666666',
+    '#b3b3b3',
+    '#7f7f7f',
+]);
+export const paletteColors = {
+    category10,
+    dark2,
+    ggplot2Colors3,
+    ggplot2Colors4,
+    ggplot2Colors5,
+    ggplot2Colors6,
+    set1,
+    set2,
+    tableau10,
+};
+/**
+ * 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.
+ *
+ * `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
+ * 1000-Genomes population codes, or a repeat painting's classes, all get a
+ * curated color instead of falling out to `randomColor`.
+ *
+ * Past the end is the caller's problem, and the two callers answer differently
+ * on purpose: an attribute palette-by hashes the VALUE (stable across
+ * 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.
+ *
+ * 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.
+ */
+export const categoricalPalette = [
+    ...new Set([...tableau10, ...set1, ...dark2, ...set2, ...category10].filter(hex => !NEUTRALS.has(hex.toLowerCase()))),
+];
+export function categoricalValueColor(value, palette = categoricalPalette) {
+    return palette[valueSlot(value, palette.length)];
+}
+function valueSlot(value, n) {
+    const num = Number(value);
+    return value !== '' && Number.isInteger(num) && num >= 0
+        ? (num + n - 1) % n
+        : hashString(value) % n;
+}
+function entryKey(entry) {
+    return typeof entry === 'string' ? entry.toLowerCase() : entry;
+}
+// The first slot derived from the value that `taken` does not hold, trying
+// rehashes before walking, so the values landing on a taken slot spread over
+// the free ones instead of piling onto the next.
+function freeSlot(value, size, taken) {
+    let slot = valueSlot(value, size);
+    for (let salt = 1; taken.has(slot) && salt <= size; salt++) {
+        slot = hashString(`${salt}:${value}`) % size;
+    }
+    for (let step = 0; taken.has(slot) && step < size; step++) {
+        slot = (slot + 1) % size;
+    }
+    return slot;
+}
+/**
+ * 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.
+ */
+export function categoricalScale(domain, range, { fallback = [], isNear, } = {}) {
+    const base = range.length ? range : fallback;
+    const listed = [...new Set((domain ?? []).map(String))].filter(v => v !== '');
+    if (listed.length === 0) {
+        return value => base[valueSlot(value, base.length)];
+    }
+    const seen = new Set(base.map(entryKey));
+    const entries = [
+        ...base,
+        ...fallback.filter(entry => {
+            const key = entryKey(entry);
+            return seen.has(key) ? false : (seen.add(key), true);
+        }),
+    ];
+    const size = entries.length;
+    const rank = new Map(listed.map((value, i) => [value, i]));
+    const listedSlots = new Set(listed.map((_, i) => i % size));
+    const taken = new Set(entries.flatMap((entry, i) => listedSlots.has(i) ||
+        (isNear && [...listedSlots].some(j => isNear(entries[j], entry)))
+        ? [i]
+        : []));
+    return value => {
+        const i = rank.get(value);
+        return entries[i !== undefined
+            ? i % size
+            : taken.size < size
+                ? freeSlot(value, size, taken)
+                : valueSlot(value, size)];
+    };
+}
+const oklabByColor = new Map();
+function oklabOf(color) {
+    let lab = oklabByColor.get(color);
+    if (lab === undefined) {
+        lab = convert.xyzd65ToOklab(...convert.xyzd50ToD65(...convert.srgbToXyzd50(...cssColorToNormalizedRgb(color))));
+        oklabByColor.set(color, lab);
+    }
+    return lab;
+}
+/**
+ * Whether two CSS colors read as one: under 0.05 apart in OKLab, where the
+ * wide palette's tableau and category10 oranges sit 0.003 apart.
+ */
+export function similarColors(a, b) {
+    const [l1, a1, b1] = oklabOf(a);
+    const [l2, a2, b2] = oklabOf(b);
+    return Math.hypot(l1 - l2, a1 - a2, b1 - b2) < 0.05;
+}
+/**
+ * `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.
+ */
+export function categoricalColorScale(domain, palette = []) {
+    return categoricalScale(domain, palette, {
+        fallback: categoricalPalette,
+        isNear: similarColors,
+    });
+}
+const MAX_CACHED_SCALES = 16;
+const scaleCache = new Map();
+function cachedColorScale(domain, palette) {
+    const key = `${domain.join('\u001F')}\u001E${palette.join('\u001F')}`;
+    let scale = scaleCache.get(key);
+    if (scale === undefined) {
+        if (scaleCache.size >= MAX_CACHED_SCALES) {
+            scaleCache.delete(scaleCache.keys().next().value);
+        }
+        scale = categoricalColorScale(domain, palette);
+        scaleCache.set(key, scale);
+    }
+    return scale;
+}
+/**
+ * The color one value of a categorical color channel paints, by
+ * `categoricalColorScale`. A value-less feature is neutral grey, and an array
+ * value joins the way a group key does.
+ */
+export function categoricalColor(value, domain = [], palette = []) {
+    const label = valueText(value);
+    if (label === '') {
+        return NO_CATEGORY_COLOR;
+    }
+    return domain.length === 0 && palette.length === 0
+        ? categoricalValueColor(label)
+        : cachedColorScale(domain, palette)(label);
+}
+// only category10 and set1 are imported by name; the rest are reached through
+// paletteColors above
+/**
+ * Deterministic non-negative 32-bit hash of a string.
+ */
+export function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}
+/**
+ * Stable category10 color for a sequence name, via `hashString`.
+ *
+ * Kept as a published export; in-tree, prefer {@link refNameColor}, which hands
+ * the palette out by position where the caller knows the assembly's chromosome
+ * order and only hashes where it does not.
+ */
+export function getQueryColor(queryName) {
+    return category10[hashString(queryName) % category10.length];
+}
+// The by-refName painting palette: category10 with its grey dropped, since a
+// grey chromosome reads as "uncolored/broken" (see NEUTRALS).
+//
+// category10 rather than the wide `categoricalPalette` — a karyotype wants nine
+// hues it can re-light into tones a reader can compare, not forty unrelated
+// ones, and `PALETTE_LAP_TONES` below is what that costs.
+const refNameColorHexes = category10.filter(hex => !NEUTRALS.has(hex));
+// Nine do not cover a karyotype, so each LAP around the list re-lights the same
+// hues: chromosome 10 is a deep version of chromosome 1's blue, chromosome 19 a
+// pale one. Three laps is 27 colors, past every karyotype these figures anchor
+// on (human 24, rice 12, bread wheat 21), and a fourth lap starts the tones
+// again rather than fading to nothing — a repeat 27 positions away is one no
+// reader is comparing.
+//
+// THE COLORS ARE THE PALETTE'S, not a ramp's. This spent a round as the next hue
+// on the golden angle at a fixed HSL 70%/50%, which is collision-free for any
+// karyotype and was rejected on sight by figure review ("the previous palette is
+// better"): an even hue circle at one saturation is a rainbow, and a five-genome
+// synteny figure drawn in one is a hundred thousand ribbons of pure red, green,
+// blue and magenta. category10's nine are uneven on purpose — that is what makes
+// them read as a set.
+//
+// It is not the weaker option for distinguishability either, which is what the
+// ramp was reached for. Closest pair in OKLab over 24 positions: 0.077 for these
+// laps, 0.019 for the golden angle at HSL 70%/50% — an even hue circle is even
+// in HSL's hue, and HSL's hue is not perceptually even.
+const PALETTE_LAP_TONES = [
+    // lap 0 is the palette color itself, untouched
+    undefined,
+    // deep before pale, because these are drawn at a low alpha over white (the
+    // OrthoFinder figures run at 0.06) and a pale color at 0.06 is a color a
+    // reader cannot see. Chroma held, and the gamut takes what it must down here.
+    { lightnessShift: -0.17, chromaScale: 1 },
+    // pale. Chroma comes down with lightness: held at full, the light lap's reds
+    // and pinks all pin against the top of the sRGB gamut and converge there.
+    { lightnessShift: 0.18, chromaScale: 0.8 },
+];
+/** The palette color for a chromosome at `position` in its assembly. */
+export function refNamePaletteColorAt(position) {
+    const hex = refNameColorHexes[position % refNameColorHexes.length];
+    const lap = PALETTE_LAP_TONES[Math.floor(position / refNameColorHexes.length) % PALETTE_LAP_TONES.length];
+    return lap ? relight(hex, lap.lightnessShift, lap.chromaScale) : hex;
+}
+/**
+ * The color a refName paints, BY POSITION IN THE ASSEMBLY where the caller
+ * knows its chromosome order.
+ *
+ * Handing the palette out rather than hashing into it is what stops a genome
+ * painting two of its own chromosomes the same color: nine slots means ten or
+ * more chromosomes re-use one, and by the birthday bound long before that. On
+ * hg38 the hash puts chr1, chr12, chr21 and chrY on one color.
+ *
+ * `position` is undefined for the case the order genuinely is not available —
+ * an assembly still loading, or a refName the assembly does not list (a
+ * scaffold under an alias). There a stable arbitrary color beats no color, so
+ * it falls back to the hash.
+ */
+export function refNameColor(name, position) {
+    return position === undefined
+        ? refNameColorHexes[hashString(name) % refNameColorHexes.length]
+        : refNamePaletteColorAt(position);
+}
+// The four below are as their sources publish them less the black or grey,
+// which reads as "no value" on a fill (see NEUTRALS).
+// Okabe & Ito, "Color Universal Design" (2008), jfly.uni-koeln.de/color
+const okabeIto = [
+    '#e69f00',
+    '#56b4e9',
+    '#009e73',
+    '#f0e442',
+    '#0072b2',
+    '#d55e00',
+    '#cc79a7',
+];
+// Paul Tol, "Colour Schemes", SRON/EPS/TN/09-002 (2021), the bright scheme
+const tolBright = [
+    '#4477aa',
+    '#ee6677',
+    '#228833',
+    '#ccbb44',
+    '#66ccee',
+    '#aa3377',
+];
+// Paul Tol, "Colour Schemes", SRON/EPS/TN/09-002 (2021), the muted scheme
+const tolMuted = [
+    '#cc6677',
+    '#332288',
+    '#ddcc77',
+    '#117733',
+    '#88ccee',
+    '#882255',
+    '#44aa99',
+    '#999933',
+    '#aa4499',
+];
+// Tableau 20, Tableau 10.0's paired palette (Maureen Stone, 2016)
+const tableau20 = [
+    '#4e79a7',
+    '#a0cbe8',
+    '#f28e2b',
+    '#ffbe7d',
+    '#59a14f',
+    '#8cd17d',
+    '#b6992d',
+    '#f1ce63',
+    '#499894',
+    '#86bcb6',
+    '#e15759',
+    '#ff9d9a',
+    '#d37295',
+    '#fabfd2',
+    '#b07aa1',
+    '#d4a6c8',
+    '#9d7660',
+    '#d7b5a6',
+];
+/** The palettes a capture run can deal the rows from by name (`paletteFromSpec`). */
+const namedPalettes = {
+    set1: () => set1,
+    categoricalPalette: () => categoricalPalette,
+    tableau10: () => tableau10,
+    // ColorBrewer Set2, which d3-scale-chromatic publishes as schemeSet2
+    schemeSet2: () => set2,
+    okabeIto: () => okabeIto,
+    tolBright: () => tolBright,
+    tolMuted: () => tolMuted,
+    tableau20: () => tableau20,
+    // every lap `refNamePaletteColorAt` re-lights category10 through
+    relit: () => Array.from({ length: refNameColorHexes.length * PALETTE_LAP_TONES.length }, (_, i) => refNamePaletteColorAt(i)),
+};
+/**
+ * A palette named in `namedPalettes`, or a comma-separated list of CSS
+ * colours; undefined, with a warning, for anything else.
+ */
+export function paletteFromSpec(spec) {
+    if (typeof spec !== 'string' || spec === '') {
+        return undefined;
+    }
+    if (Object.hasOwn(namedPalettes, spec)) {
+        return namedPalettes[spec]();
+    }
+    const colors = spec.split(/,(?![^(]*\))/).map(c => c.trim());
+    if (colors.every(isCssColor)) {
+        return colors;
+    }
+    console.warn(`palette "${spec}" is neither one of ${Object.keys(namedPalettes).join(', ')} nor a comma-separated list of CSS colours`);
+    return undefined;
+}
+export { category10, set1 };

package/esm/ui/extensionSelectors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Which tracks a contribution is for. Every track-scoped extension point fires
+ * for every track, so a contribution with no selector applies to all of them.
+ * {@link matchesTrackSelector} is what applies one.
+ */
+export interface TrackSelector {
+    /** track type, e.g. `'VariantTrack'`, usually what "for my tracks" means */
+    trackType?: string | string[];
+    /** track id; a plain string also matches the user's copies of that track */
+    trackId?: string | RegExp | (string | RegExp)[];
+    /** widget model type, e.g. `'AlignmentsFeatureWidget'`, for the slot points */
+    widgetType?: string | string[];
+}
+/** the model fields a declarative selector can match on */
+export interface SelectableModel {
+    type?: string;
+    trackId?: string;
+    trackType?: string;
+}
+/**
+ * What a track-scoped extension point contribution is for: whether the widget
+ * model or track config in `subject` satisfies every field of `select`. Every
+ * field given must match, and an empty selector matches everything.
+ *
+ * Every one of those points fires for every track, so a contribution that does
+ * not call this applies to all of them. Hand-writing `config.trackId === 'x'`
+ * instead is what silently stops applying the first time a user copies the
+ * track: `copyTrackSnapshot` suffixes the id, and this knows that.
+ *
+ * Not to be confused with {@link matchTrackId}, which tests an id against
+ * patterns you supply and so leaves that normalization to you.
+ */
+export declare function matchesTrackSelector(select: TrackSelector | undefined, subject: {
+    /** a widget model, if the point's props carry one */
+    model?: SelectableModel;
+    /** a track config, if they carry that instead — `type` is the track type */
+    config?: Record<string, unknown>;
+}): boolean;

package/esm/ui/extensionSelectors.js

@@ -0,0 +1,49 @@
+import { matchTrackId } from '../util/matchTrackId.js';
+// "Copy track" appends `-${Date.now()}` to the trackId (copyTrackSnapshot), and
+// copying a copy appends again, so a bare id in a selector means "this track,
+// including the user's copies of it". Doing this in the framework is the point:
+// scoping by `trackId ===` is what people write by hand, and it silently stops
+// applying the moment a user copies the track.
+function matchesTrackId(trackId, pattern) {
+    return typeof pattern === 'string'
+        ? trackId === pattern ||
+            (trackId?.startsWith(`${pattern}-`) === true &&
+                trackId
+                    .slice(pattern.length + 1)
+                    .split('-')
+                    .every(part => /^\d+$/.test(part)))
+        : matchTrackId(trackId, [pattern]);
+}
+function matchesOneOf(value, expected) {
+    return typeof expected === 'string'
+        ? value === expected
+        : expected.includes(value ?? '');
+}
+/** Whether `model` satisfies every declarative field of `select`. */
+function selectorMatchesModel(select, model) {
+    const { widgetType, trackType, trackId } = select ?? {};
+    return ((widgetType === undefined || matchesOneOf(model.type, widgetType)) &&
+        (trackType === undefined || matchesOneOf(model.trackType, trackType)) &&
+        (trackId === undefined ||
+            (Array.isArray(trackId) ? trackId : [trackId]).some(pattern => matchesTrackId(model.trackId, pattern))));
+}
+/**
+ * What a track-scoped extension point contribution is for: whether the widget
+ * model or track config in `subject` satisfies every field of `select`. Every
+ * field given must match, and an empty selector matches everything.
+ *
+ * Every one of those points fires for every track, so a contribution that does
+ * not call this applies to all of them. Hand-writing `config.trackId === 'x'`
+ * instead is what silently stops applying the first time a user copies the
+ * track: `copyTrackSnapshot` suffixes the id, and this knows that.
+ *
+ * Not to be confused with {@link matchTrackId}, which tests an id against
+ * patterns you supply and so leaves that normalization to you.
+ */
+export function matchesTrackSelector(select, subject) {
+    const { model, config } = subject;
+    return selectorMatchesModel(select, model ?? {
+        trackId: config?.trackId,
+        trackType: config?.type,
+    });
+}