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

package/README.md

@@ -235,11 +235,13 @@ a refName.
 ### categoricalField
 
 `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.
+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.
 
 ```js
 // type signature
-(field: string, {…}?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; labels?: readonly string[] | undefined; }) => CategoricalField
+(field: string, {…}?: {…}) => CategoricalField
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
@@ -250,7 +252,9 @@ One categorical field as every channel reads it — a facet's sections, a color'
 range entries, a key's rows. `key` files a value, `compare` 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.
+color depends only on the key and the 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.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
 
@@ -343,7 +347,9 @@ matplotlib's perceptual ramps, dark at the low end; `juicebox` fades from
 transparent to red, as Juicebox paints contacts; `fall` runs white through
 yellow and red to black, as HiGlass does; `reds` and `blues` are ColorBrewer's,
 from white; `redblue` and `purpleorange` diverge through white, ColorBrewer's
-RdBu and PuOr.
+RdBu and PuOr; `redgreyblue` diverges through a grey middle, which stays visible
+on a white page where a white middle would not, as the MAF display's identity
+ramp paints it.
 
 ```js
 // type signature
@@ -357,7 +363,8 @@ readonly[
   'reds',
   'blues',
   'redblue',
-  'purpleorange')
+  'purpleorange',
+  'redgreyblue')
 ]
 ```
 
@@ -492,7 +499,9 @@ ramp is `range`'s CSS colours, evenly spaced, where it lists any, else the named
 
 Replace the features with runs of constant depth: how many of them overlap each
 stretch of the region, in a field `as` (`coverage` by default), with the
-stretches nothing overlaps left out.
+stretches nothing overlaps left out. A read counts across its whole span,
+deletions and introns included; gap-aware depth stays the alignments display's
+(ADR-118).
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
@@ -503,11 +512,24 @@ siblings do, juicebox, fall, reds and blues do not.
 
 ```js
 // type signature
-(scheme: "blues" | "cividis" | "fall" | "inferno" | "juicebox" | "magma" | "purpleorange" | "redblue" | "reds" | "viridis") => boolean
+(scheme: "blues" | "cividis" | "fall" | "inferno" | "juicebox" | "magma" | "purpleorange" | "redblue" | "redgreyblue" | "reds" | "viridis") => boolean
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
+### dealKeyColors
+
+Deals `keys` their colours in `field.compare` order, so the colours 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.
+
+```js
+// type signature
+(field: CategoricalField, keys: Iterable<string>) => void
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
 ### DEFAULT_COLOR_SCHEME
 
 The ramp a continuous scale samples while it names no `range` and no `scheme`,
@@ -523,6 +545,7 @@ so a declaration spelling it out and one leaving it unset resolve alike.
   'magma' |
   'purpleorange' |
   'redblue' |
+  'redgreyblue' |
   'reds' |
   'viridis'
 ```
@@ -596,6 +619,18 @@ categorical over a `category` column per label.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
+### evaluateForFeature
+
+A config value as `feature` reads it: a `jexl:` callback evaluated against the
+feature, anything else as written.
+
+```js
+// type signature
+(value: unknown, feature: Feature, jexl: JexlInstance) => unknown
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
+
 ### FacetedLayer
 
 One layer of a faceted request: its rows in section order, and the stacked row
@@ -660,6 +695,23 @@ the hover.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
 
+### fenceOutliers
+
+Where a value axis's open ends stand below a `domainQuantile` of 1: at the
+`extremes`, unless one would stretch the axis past twice the span the
+quantileExtent ends `quantiles` draw, 0 included where the axis reaches it
+(`zero`); that end stops at the fence. So a plot with no spike shows every value
+and cuts none, and a spike leaves the values under it at least half the axis.
+Quantiles that meet span their own size, as a flat domain widens in
+`getNiceDomain`.
+
+```js
+// type signature
+({ extremes, quantiles, zero, }: { extremes: readonly [number, number]; quantiles: readonly [number, number]; zero: boolean; }) => [number, number]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
 ### fieldReader
 
 What a channel reads off a feature: a field by name, a dotted path into a
@@ -756,15 +808,8 @@ mate must drop both rather than treat `<DEL>` as a refName.
 
 ### getConf
 
-Reads a configuration value from a state model that has a `.configuration`
-member (a track or display state model). For a raw configuration model, use
-`readConfObject` instead.
-
-**This is exactly `readConfObject(model.configuration, path)`** — sugar for the
-`.configuration` hop, and nothing more. The two readers carry the same slot-name
-check, so reaching for the other one does not get a typo past tsc. It does not
-consult the session and has no per-slot behavior; what you read is what the
-track stores.
+Reads a configuration value from a track or display state model: exactly
+`readConfObject(model.configuration, path)`, with the same slot-name check.
 
 ```js
 // type signature
@@ -901,6 +946,18 @@ module actually uses.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/sessionServices.ts)
 
+### heldSlotsOf
+
+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.
+
+```js
+// type signature
+(owner: object, key: string) => HeldSlots
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
 ### HitIndexed
 
 An encoded payload as a display stores it: the hit index the worker built with
@@ -922,27 +979,15 @@ at 0 for a mark with no value.
 
 ### hydrateTrackConfig
 
-Hydrate a plain track config into a live config node, dispatching on its `type`
-to find the schema. `session.tracks` holds `types.frozen` plain objects until
-something references a track (ADR-031). One of those holds only what was
-literally authored: a slot at its schema default is absent, `preProcessSnapshot`
-has not run, and nothing that walks a live node applies to it.
+Hydrate a plain track config, such as a `session.tracks` entry, into a live
+config node, dispatching on its `type` to find the schema. A plain entry holds
+only what was authored: a slot at its default is absent and `preProcessSnapshot`
+has not run.
 
-Use it where a caller needs the resolved config and may be handed either form.
-The About dialog's "Copy config" is reached from two menus, and one of them
-passes a `session.tracks` entry.
-
-Returns **undefined** when the config names a track type no plugin registered,
-or when `create` rejects it as invalid. An un-hydrated config has never been
-validated, so the dialog opening over it should not throw. Callers fall back to
-using the plain object.
-
-Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating the
-same entry twice returns the same node, and in an admin session a track opened
-later resolves to that same node. A non-admin's open track resolves to the
-session's private working copy (ADR-032), and this function returns the pristine
-mirror beside it. The two have the same content; `CopyConfigEntryPoints.test.ts`
-tests both cases.
+Returns **undefined** when no plugin registered the type or `create` rejects the
+config, which has never been validated; callers fall back to the plain object.
+Hydrating one entry twice returns one node. A shown track resolves to the
+session's working copy instead (ADR-032), which has the same content.
 
 ```js
 // type signature
@@ -1384,6 +1429,11 @@ it itself. Under 0.5 reads as 0.5, where the ends meet rather than cross.
 `scales.y.domainQuantile` and a colour's `domainQuantile` both name it.
 `[Infinity, -Infinity]` where nothing is finite.
 
+Nearest rank keeps ties: where one value holds the rank, as on a segmented
+copy-number track, a ramp clipped below 1 paints nearly every value one colour.
+A value axis fences instead (fenceOutliers); a ramp takes the same fence once a
+colour default below 1 meets tied data.
+
 ```js
 // type signature
 (values: ArrayLike<number>, count: number, quantile?: number) => [number, number]
@@ -1466,20 +1516,13 @@ widened domain with no table baked again.
 
 ### readConfObject
 
-Given a configuration model (an instance of a ConfigurationSchema), read the
-configuration value at the given path. Use this when you hold the configuration
-model directly, e.g. an entry from `session.tracks`.
-
-Wants a **live config node**, not a snapshot of one, and passing a snapshot is a
-type error. Slots are built with `types.stripDefault`, so a slot sitting at its
-default is absent from a snapshot — "unset" and "at its default" are
-indistinguishable there, and a read off one reports a default as missing.
+Read the value at a path of a live config node, such as a track's
+`configuration`, evaluating a `jexl:` callback with `args`.
 
-That is enforced in the types only, deliberately: it can't be a runtime check.
-`generateHierarchy` reads slots straight off the **un-hydrated frozen** entries
-of `jbrowse.tracks` on purpose, because hydrating every track to answer the
-track selector is what `types.frozen` exists to avoid — and those reads are
-indistinguishable at runtime from the broken spelling.
+A snapshot is refused by the types, since a slot at its default is absent from
+one. A `session.tracks` entry is one (`TrackConfigEntry`): read its `trackId`
+and `type` directly, and a slot through a helper that supplies the default, such
+as `getConfAssemblyNamesOrNone`.
 
 ```js
 // type signature
@@ -1761,32 +1804,11 @@ array naming a sub-schema's member at any depth —
 `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
 model, or a config node directly.
 
-**The path length says what the write replaces.** A path ending on a slot writes
-that slot and leaves the object around it alone; a path ending on a sub-schema
-replaces the whole object, which is how a channel whose members move together —
-a facet's field and the domain that field's values order — gets written without
-a stale member surviving underneath.
-
-**Prefer this over a bare `self.configuration.setSlot('x', v)`.** The constraint
-here mirrors `getConf`'s, so on a model with a concrete schema an unknown slot
-name is a compile error. `setSlot` itself stays untyped on purpose — the config
-editor's slot facade routes dynamic slot names through it
-(`configurationSchema.ts`) — and guards the name at runtime instead (ADR-052),
-so a misspelled write is diagnosed one way or the other.
-
-**The read is the half with no diagnostic at all.** `getConf` for a name the
-schema doesn't declare returns `undefined` and reports nothing, at any layer, so
-the slot keeps reading as its default forever. Which makes the compile-time
-constraint worth keeping _reachable_: it is only as good as the schema of the
-holder handed in, and a holder widened to `AnyConfigurationModel` switches it
-off entirely — the trap a mixin casting to reach its host walks into. Every such
-cast names a concrete schema instead (`ConfigModelForFields`, or the base schema
-when the slot is the base's), and `HostChecksSlotNames` pins each one.
-
-A wrong _value_ type still throws at runtime (MST type-checks the assignment)
-rather than at compile time. `value` is deliberately `unknown` because
-`undefined` is a legitimate write — it resets a slot to its schema default — and
-the declared slot value type doesn't include it.
+A path ending on a slot writes that slot; one ending on a sub-schema replaces
+the whole object, so a channel's members (a facet's field and its domain) move
+together. On a concrete schema an unknown slot name is a compile error, and
+`setSlot` refuses one at runtime (ADR-052). A wrong value type throws at
+runtime; `null` or `undefined` resets the slot to its default (ADR-146).
 
 ```js
 // type signature

package/esm/BaseFeatureWidget/BaseFeatureDetail/Attributes.d.ts

@@ -1,4 +1,7 @@
 import type { Descriptors, FeatureFormatter, FieldActions } from '../types.tsx';
+export declare function withoutLocations(attributes: Record<string, unknown>): Record<string, unknown>;
+/** Whether `Attributes` given these `attributes` and `omit` draws any row. */
+export declare function hasAttributeRows(attributes: Record<string, unknown>, omit?: string[]): boolean;
 export default function Attributes(props: {
     attributes: Record<string, unknown>;
     omit?: string[];

package/esm/BaseFeatureWidget/BaseFeatureDetail/Attributes.js

@@ -51,7 +51,7 @@ function isLocation(value) {
 }
 // hideUris prunes the data rather than each render branch checking: an array
 // of objects reaches the data grid and ArrayValue, which print locations too
-function withoutLocations(attributes) {
+export function withoutLocations(attributes) {
     return Object.fromEntries(Object.entries(attributes)
         .filter(([, value]) => !isLocation(value))
         .map(([key, value]) => [key, valueWithoutLocations(value)]));
@@ -103,6 +103,19 @@ function measureLabels(attributes, opts) {
     }
     return widest;
 }
+/** Whether `Attributes` given these `attributes` and `omit` draws any row. */
+export function hasAttributeRows(attributes, omit = []) {
+    const omits = new Set([...omit, ...globalOmit]);
+    return Object.entries(attributes).some(([key, value]) => value == null || omits.has(key)
+        ? false
+        : Array.isArray(value)
+            ? isHomogeneousObjectArray(value) ||
+                !isObjectArray(value) ||
+                value.some(entry => hasAttributeRows(entry))
+            : isObject(value)
+                ? isUriLocation(value) || hasAttributeRows(value, omit)
+                : true);
+}
 function widestLabel(attributes, opts) {
     return Math.ceil(measureLabels(attributes, opts)) + FIELD_NAME_PADDING;
 }

package/esm/BaseFeatureWidget/SequenceFeatureDetails/SequenceFeatureDetails.d.ts

@@ -1,4 +1,5 @@
 import type { AbstractSessionModel, SimpleFeatureSerialized } from '../../util/index.ts';
+import type { CanonicalTranscripts } from '../../util/isoformRank.ts';
 import type { SequenceFeatureDetailsModel, SequenceHoverTarget } from './model.ts';
 interface SequenceFeatureDetailsProps {
     model: SequenceFeatureDetailsModel;
@@ -7,6 +8,7 @@ interface SequenceFeatureDetailsProps {
     feature: SimpleFeatureSerialized;
     hoverTarget?: SequenceHoverTarget;
     showOpenInDialog?: boolean;
+    canonicalTranscripts?: CanonicalTranscripts;
 }
 declare function SequenceFeatureDetails(props: SequenceFeatureDetailsProps): import("react").JSX.Element;
 export default SequenceFeatureDetails;

package/esm/BaseFeatureWidget/SequenceFeatureDetails/SequenceFeatureDetails.js

@@ -10,15 +10,15 @@ import { useSequenceFetch } from './useSequenceFetch.js';
 // lazies
 const SequenceBody = lazy(() => import('./SequenceBody.js'));
 const SequenceDialog = lazy(() => import('./dialogs/SequenceDialog.js'));
-const SequenceFeatureDetailsPanel = observer(function SequenceFeatureDetailsPanel({ model, session, assemblyName, feature, hoverTarget, showOpenInDialog = true, }) {
+const SequenceFeatureDetailsPanel = observer(function SequenceFeatureDetailsPanel({ model, session, assemblyName, feature, hoverTarget, showOpenInDialog = true, canonicalTranscripts, }) {
     const { upDownBp } = model;
     const seqPanelRef = useRef(null);
     // A container feature (e.g. a gene) has no CDS/exon of its own — one of its
-    // transcript children does. Default to the longest-coding transcript so CDS
-    // and Protein sequence types work without an extra click into Subfeatures,
-    // with a selector to switch transcripts when the gene has more than one.
+    // transcript children does. Default to the transcript the track draws first
+    // so CDS and Protein sequence types work without an extra click into
+    // Subfeatures, with a selector to switch when the gene has more than one.
     const transcripts = getTranscripts(feature);
-    const [transcriptIndex, setTranscriptIndex] = useState(() => pickDefaultTranscriptIndex(transcripts));
+    const [transcriptIndex, setTranscriptIndex] = useState(() => pickDefaultTranscriptIndex(transcripts, canonicalTranscripts));
     const effectiveFeature = transcripts[transcriptIndex] ?? feature;
     // mode and revcomp are per-panel state, not on the shared model, so each
     // subfeature panel (e.g. coding vs noncoding transcripts of one gene) picks

package/esm/BaseFeatureWidget/SequenceFeatureDetails/SequenceFeaturePanel.js

@@ -38,6 +38,6 @@ const SequenceFeaturePanel = observer(function SequenceFeaturePanel({ model, fea
                         feature,
                         viewAssemblyNames: model.view?.assemblyNames,
                         assemblyManager: getSession(model).assemblyManager,
-                    }), feature: feature, hoverTarget: model }) })) : null] }));
+                    }), feature: feature, hoverTarget: model, canonicalTranscripts: model.canonicalTranscripts }) })) : null] }));
 });
 export default SequenceFeaturePanel;

package/esm/BaseFeatureWidget/SequenceFeatureDetails/dialogs/FeatureSequenceDialog.d.ts

@@ -1,11 +1,13 @@
 import type { AbstractSessionModel, SimpleFeatureSerialized } from '../../../util/index.ts';
+import type { CanonicalTranscripts } from '../../../util/isoformRank.ts';
 import type { SequenceHoverTarget } from '../model.ts';
-declare const FeatureSequenceDialog: ({ feature, error, session, assemblyName, hoverTarget, handleClose, }: {
+declare const FeatureSequenceDialog: ({ feature, error, session, assemblyName, hoverTarget, canonicalTranscripts, handleClose, }: {
     feature: SimpleFeatureSerialized | undefined;
     error?: unknown;
     session: AbstractSessionModel;
     assemblyName: string | undefined;
     hoverTarget?: SequenceHoverTarget;
+    canonicalTranscripts?: CanonicalTranscripts;
     handleClose: () => void;
 }) => import("react").JSX.Element;
 export default FeatureSequenceDialog;

package/esm/BaseFeatureWidget/SequenceFeatureDetails/dialogs/FeatureSequenceDialog.js

@@ -17,13 +17,13 @@ const useStyles = makeStyles()({
 // The settings model lives for as long as the dialog does: it holds no
 // snapshot and reads no tree, so nothing has to carry one around on the chance
 // a sequence panel is opened.
-const FeatureSequenceDialog = observer(function FeatureSequenceDialog({ feature, error, session, assemblyName, hoverTarget, handleClose, }) {
+const FeatureSequenceDialog = observer(function FeatureSequenceDialog({ feature, error, session, assemblyName, hoverTarget, canonicalTranscripts, handleClose, }) {
     const { classes } = useStyles();
     const [model] = useState(() => SequenceFeatureDetailsF().create());
     return (_jsx(InfoDialog, { maxWidth: "xl", open: true, title: feature
             ? `Feature sequence - ${feature.name || feature.id || feature.type}`
             : 'Feature sequence', onClose: () => {
             handleClose();
-        }, children: _jsx("div", { className: classes.content, children: error ? (_jsx(ErrorBanner, { error: error })) : feature ? (_jsx(SequenceFeatureDetails, { model: model, session: session, assemblyName: assemblyName, feature: feature, hoverTarget: hoverTarget, showOpenInDialog: false })) : (_jsx(LoadingEllipses, { message: "Loading feature" })) }) }));
+        }, children: _jsx("div", { className: classes.content, children: error ? (_jsx(ErrorBanner, { error: error })) : feature ? (_jsx(SequenceFeatureDetails, { model: model, session: session, assemblyName: assemblyName, feature: feature, hoverTarget: hoverTarget, showOpenInDialog: false, canonicalTranscripts: canonicalTranscripts })) : (_jsx(LoadingEllipses, { message: "Loading feature" })) }) }));
 });
 export default FeatureSequenceDialog;

package/esm/BaseFeatureWidget/SequenceFeatureDetails/featureTypeUtil.d.ts

@@ -1,10 +1,11 @@
 import type { SimpleFeatureSerialized, SimpleFeatureSerializedNoId } from '../../util/index.ts';
+import type { CanonicalTranscripts } from '../../util/isoformRank.ts';
 import type { SequenceDisplayMode, ShowCoordinatesMode } from './model.ts';
 export declare function featureHasCDS(feature: SimpleFeatureSerializedNoId): boolean;
 export declare function featureHasExon(feature: SimpleFeatureSerializedNoId): boolean;
 export declare function featureHasExonOrCDS(feature: SimpleFeatureSerializedNoId): boolean;
 export declare function getTranscripts(feature: SimpleFeatureSerialized): SimpleFeatureSerialized[];
-export declare function pickDefaultTranscriptIndex(transcripts: SimpleFeatureSerialized[]): number;
+export declare function pickDefaultTranscriptIndex(transcripts: SimpleFeatureSerialized[], canonical?: CanonicalTranscripts): number;
 export declare function getDefaultMode(feature: SimpleFeatureSerializedNoId): SequenceDisplayMode;
 export declare function modeHasUpDownstream(mode: SequenceDisplayMode): boolean;
 export declare function modeSupportsRevcomp(mode: SequenceDisplayMode): boolean;

package/esm/BaseFeatureWidget/SequenceFeatureDetails/featureTypeUtil.js

@@ -1,3 +1,4 @@
+import { DEFAULT_CANONICAL_TRANSCRIPTS, isoformScorer, rankIsoforms, serializedIsoformReader, } from '../../util/isoformRank.js';
 // these predicates only ever read type/subfeatures, so they accept a bare
 // subfeature (no guaranteed uniqueId) as readily as a full feature
 export function featureHasCDS(feature) {
@@ -30,20 +31,12 @@ export function getTranscripts(feature) {
         uniqueId: `${feature.uniqueId}_${idx}`,
     })) ?? []);
 }
-// index of the transcript the gene glyph itself would collapse to in
-// 'longestCoding' mode (RenderFeatureDataRPC/glyphs/subfeatures.ts): prefer a
-// coding transcript, then the longest span — so the sequence panel's default
-// matches what the track already drew. A feature that is itself a transcript
-// (clicked directly, not via its container gene) has no nested transcripts to
-// autopick from.
-export function pickDefaultTranscriptIndex(transcripts) {
-    if (transcripts.length === 0) {
-        return 0;
-    }
-    const coding = transcripts.filter(t => featureHasCDS(t));
-    const candidates = coding.length > 0 ? coding : transcripts;
-    const longest = candidates.reduce((a, b) => b.end - b.start > a.end - a.start ? b : a);
-    return transcripts.indexOf(longest);
+// The isoform the canvas gene glyph draws first, so the panel opens on the
+// transcript the track showed. A feature that is itself a transcript has no
+// nested transcripts to pick from.
+export function pickDefaultTranscriptIndex(transcripts, canonical = DEFAULT_CANONICAL_TRANSCRIPTS) {
+    const [best] = rankIsoforms(transcripts, isoformScorer(serializedIsoformReader, canonical));
+    return best ? transcripts.indexOf(best) : 0;
 }
 export function getDefaultMode(feature) {
     return featureHasCDS(feature)

package/esm/BaseFeatureWidget/SequenceFeatureDetails/seqtypes/CDNASequence.js

@@ -51,9 +51,9 @@ const CDNASequence = observer(function CDNASequence({ cds, exons, sequence, upst
     }
     // The stretches of the feature its own exons do not reach. Real annotations
     // produce them: CAT/liftoff emits a transcript spanning the source alignment
-    // with exons only where the CDS is supported, so KCNT2 in
-    // `hprc_cfhr_HG00099.1.genes.gff3.gz` runs 10,207 bp past its first exon and
-    // 28 of that corpus's 438 transcripts do the same.
+    // with exons only where the CDS is supported, so KCNT2 in HG00099.1's HPRC CAT
+    // annotation runs 10,207 bp past its first exon, and 28 of the 438 transcripts
+    // around CFH do the same.
     //
     // Uncolored, like the inter-exon gaps they are — the annotation does not call
     // them exonic, so stretching the first and last exon over them (which is what

package/esm/BaseFeatureWidget/stateModelFactory.d.ts

@@ -1,6 +1,7 @@
 import type PluginManager from '../PluginManager.ts';
 import type { AnyConfigurationModel } from '../configuration/index.ts';
 import type { ParentFeatureSummary, SimpleFeatureSerialized } from '../util/index.ts';
+import type { CanonicalTranscripts } from '../util/isoformRank.ts';
 import type { SequenceHoverPosition } from './SequenceFeatureDetails/model.ts';
 import type { FormatDetailsTiers } from './formatDetails.ts';
 import type { Descriptors, MaybeSerializedFeat } from './types.tsx';
@@ -88,6 +89,12 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
         feature?: SimpleFeatureSerialized;
         error?: Error;
     };
+    /**
+     * #getter
+     * the isoform tags the open track's display ranks by, so the sequence
+     * panel opens on the transcript the track draws first
+     */
+    readonly canonicalTranscripts: CanonicalTranscripts;
     /**
      * #getter
      * levels of subfeature card the panel renders; unset means no limit

package/esm/BaseFeatureWidget/stateModelFactory.js

@@ -1,6 +1,7 @@
 import { getEnv, isStateTreeNode, types } from '@jbrowse/mobx-state-tree';
 import { hydrateTrackConfig } from '../configuration/index.js';
 import { getSession } from '../util/index.js';
+import { DEFAULT_CANONICAL_TRANSCRIPTS, isCanonicalTranscriptsHost, } from '../util/isoformRank.js';
 import { ElementId } from '../util/types/mst.js';
 import { SequenceFeatureDetailsF } from './SequenceFeatureDetails/model.js';
 import { applyFormatDetails, formatDetailsNumber } from './formatDetails.js';
@@ -116,6 +117,16 @@ export function stateModelFactory(pluginManager) {
                 return { error };
             }
         },
+        /**
+         * #getter
+         * the isoform tags the open track's display ranks by, so the sequence
+         * panel opens on the transcript the track draws first
+         */
+        get canonicalTranscripts() {
+            const track = self.track;
+            return (track?.displays.find(isCanonicalTranscriptsHost)
+                ?.canonicalTranscripts ?? DEFAULT_CANONICAL_TRANSCRIPTS);
+        },
         /**
          * #getter
          * levels of subfeature card the panel renders; unset means no limit

package/esm/BaseFeatureWidget/types.d.ts

@@ -1,4 +1,5 @@
 import type { MenuItem } from '../ui/MenuTypes.ts';
+import type { CanonicalTranscripts } from '../util/isoformRank.ts';
 import type { SimpleFeatureSerialized } from '../util/simpleFeature.ts';
 import type { SequenceFeatureDetailsModel, SequenceHoverTarget } from './SequenceFeatureDetails/model.ts';
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
@@ -9,6 +10,7 @@ export interface FeatureDetailsModel extends IStateTreeNode, SequenceHoverTarget
     view: {
         assemblyNames: string[];
     } | undefined;
+    canonicalTranscripts?: CanonicalTranscripts;
 }
 export interface Descriptors {
     [key: string]: React.ReactNode | Descriptors;

package/esm/PluginManager.d.ts

@@ -375,9 +375,12 @@ export default class PluginManager {
      * frozen object, so a hit can only ever come from this same instance and this
      * same track type. See ADR-031.
      *
-     * The node is never mutated: admin edits replace the frozen entry (new
-     * identity drops the WeakMap entry), and a non-admin's edits go to a private
-     * session working copy, not here (ADR-032). Both levels are `WeakMap`s so
+     * The node is never mutated: every edit goes to a private session working
+     * copy, not here, and is stored as a delta whose merged config is a new
+     * object (ADR-032). In a session composing `SessionTracksManagerSessionMixin`,
+     * which every product does, `track.configuration` resolves to that working
+     * copy, so this memo serves `hydrateTrackConfig` and sessions without the
+     * mixin. Both levels are `WeakMap`s so
      * entries collect normally — no manual invalidation needed, which is why this
      * is a memo and not a cache with a lifecycle to expose.
      */

package/esm/PluginManager.js

@@ -155,9 +155,12 @@ export default class PluginManager {
      * frozen object, so a hit can only ever come from this same instance and this
      * same track type. See ADR-031.
      *
-     * The node is never mutated: admin edits replace the frozen entry (new
-     * identity drops the WeakMap entry), and a non-admin's edits go to a private
-     * session working copy, not here (ADR-032). Both levels are `WeakMap`s so
+     * The node is never mutated: every edit goes to a private session working
+     * copy, not here, and is stored as a delta whose merged config is a new
+     * object (ADR-032). In a session composing `SessionTracksManagerSessionMixin`,
+     * which every product does, `track.configuration` resolves to that working
+     * copy, so this memo serves `hydrateTrackConfig` and sessions without the
+     * mixin. Both levels are `WeakMap`s so
      * entries collect normally — no manual invalidation needed, which is why this
      * is a memo and not a cache with a lifecycle to expose.
      */