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

package/README.md

@@ -25,6 +25,68 @@ Apache-2.0 © Evolutionary Software Foundation
 
 Auto-generated from `#api` JSDoc tags in this package. Do not edit by hand.
 
+### AggregateOp
+
+One summary over a group: `count` needs no field; `sum`, `mean`, `min` and `max`
+read one, skipping values that are not numbers. The output field is `as`, else
+`count` or `<op>_<field>`.
+
+`weight` names a field each row counts by: `count` is then the sum of the
+weights, `sum` the sum of value times weight, and `mean` that over the sum of
+the weights, a row whose weight is not a number counting for nothing. A weight
+moves no minimum or maximum, so `min` and `max` read none.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### AggregateStep
+
+One feature per distinct `groupby` value set (one for the whole region with
+none), spanning its members' extent, carrying the group's fields and every `ops`
+entry.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### applyConfSettings
+
+Write a settings bag — a session spec's track entry, a share link, an agent call
+— onto a config. Each key names a member: a slot or a channel is written whole,
+as `setConf` writes it, so `null` resets it (ADR-146); a namespace's object
+names members inside it, at any depth, and the ones it leaves out keep their
+values. The config's own lift and checks run over the bag first, and each
+namespace's over its part, so a shorthand or a legacy key reads the same here as
+in `config.json`. A key the config does not declare is reported for the caller
+to route or refuse, and a declared key whose write throws costs that key alone.
+
+```js
+// type signature
+(target: AnyConfigurationModel | { configuration: AnyConfigurationModel; }, settings: Record<string, unknown>) => ConfSettingsReport
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
+
+### arraySlotUnion
+
+The `ConfigurationSchemaUnion` an array slot's entries answer to, read off the
+slot's MST type, or undefined for any other slot.
+
+```js
+// type signature
+(slotType: IAnyType) => ConfigurationSchemaUnionMetadata | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/configurationSchemaUnion.ts)
+
+### asTable
+
+A table over a feature list, or the table itself.
+
+```js
+// type signature
+(input: readonly Feature[] | FeatureTable) => FeatureTable
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
 ### Band
 
 One band of a display's vertical stack — a coverage histogram, an arc strip, a
@@ -37,6 +99,23 @@ historically drifted.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandLayout.ts)
 
+### BinStep
+
+Place every feature in a genome-aligned bin of `step` bp, writing the bin's
+edges over the fields `as` names — `start` and `end` by default, so an
+`aggregate` grouped by those counts per bin and the bar spans the bin.
+
+With `field` (`start` by default) a feature lands in the one bin that field
+falls in. With `fields`, an interval's start and end, it is cut at the bin edges
+into one piece per bin it overlaps, each piece writing `overlap`, the bases of
+the interval inside its bin; a zero-length interval (an insertion) is one piece
+of overlap 0 in the bin holding its position, and one whose ends are not numbers
+is none. A piece is its feature with those fields beside it, so its id and hover
+are the feature's, and an `aggregate` over the pieces weighted by `overlap` is a
+mean per base.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### boundBandHeight
 
 Bound a band height to its legal range — a config value, a menu choice, or a
@@ -61,6 +140,33 @@ this rule and a doc comment claiming to be the whole of it.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandHeight.ts)
 
+### breakendKeepsDirections
+
+Which way the sequence each end of a breakend KEEPS runs from its breakpoint, as
+`+1 = right` / `-1 = left` — the convention `StarFusionAdapter`'s
+`tickDirection` states and the one every producer in the tree emits.
+
+The two halves read their strings with OPPOSITE polarity, which is the whole
+reason to state them together. `Join: 'right'` says the mate piece is joined to
+the RIGHT of the ref base, so this end keeps the sequence to its left: negated.
+`MateDirection: 'right'` says the mate's own piece extends to the right of the
+mate position, which is already the direction it keeps: taken as read. So
+`N[chr2:2000[` is `{ joinDirection: -1, mateDirection: 1 }`, and that is the
+same pair `StarFusionAdapter` emits for the fusion it describes — the donor
+keeps the sequence below its breakpoint (-1) and the acceptor the sequence above
+its own (+1).
+
+Split out of `parseSvAlt` because a consumer holding an already-parsed
+`Breakend` was re-deriving it by hand, in two adjacent ternaries of opposite
+polarity — the shape that produced 78bb7b84f9.
+
+```js
+// type signature
+(bnd: Breakend) => { mateDirection: number; joinDirection: number; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
 ### buildColorRampLut
 
 An RGBA lookup table over sampleColorRamp, laid out as the Nx1 texture both GPU
@@ -68,6 +174,10 @@ backends upload and the Canvas2D twins index — entry `i` is the color at
 `t = i / (N - 1)`. N comes off the shader that samples it, so the table and
 `rampColor`'s texel mapping cannot disagree.
 
+The table is always straight. A diverging ramp whose middle belongs at a value
+off the centre of the domain reads it through `rampMidT`, the shader's rule and
+its generated twin, so the middle follows a moving domain without a new table.
+
 ```js
 // type signature
 (stops: readonly ColorRampStop[]) => Uint8Array<ArrayBuffer>
@@ -78,33 +188,29 @@ backends upload and the Canvas2D twins index — entry `i` is the color at
 ### canonicalizeViewRefName
 
 Resolve user-authored refName text against the assembly of the view containing
-`node` — the one normalization layer, which resolves aliases and casing
-together. Falls back to the input when the assembly is absent or its aliases
-have not loaded.
+`node`, resolving aliases and casing together. Falls back to the input when the
+assembly is absent or its aliases have not loaded.
 
-Keyed off the VIEW's assembly rather than the track's, because the view is what
-the comparison is against: displayed regions, loaded regions and blocks all
-carry the refNames the view laid out.
+Uses the view's assembly, not the track's, because displayed regions, loaded
+regions and blocks all carry the refNames the view laid out.
 
-Reach for this wherever a refName a _person_ wrote is about to be compared
-against regions, features or blocks, which carry the assembly's canonical name.
-A refName a display copied off a region is canonical already and needs nothing;
-one that arrived in a session spec, a config slot or a URL is whatever the
-author read out of the location box.
+Call it wherever a refName a _person_ wrote is about to be compared against
+regions, features or blocks, which carry the assembly's canonical name. A
+refName a display copied off a region is already canonical. One from a session
+spec, a config slot or a URL is whatever the author typed.
 
-Skipping it fails silently and, worse, assembly-dependently: `chr12` matches on
-an assembly canonicalized `chr12` and matches nothing on one canonicalized `12`,
-so the same spec key works on one config and quietly does nothing on the next,
-with no error for anyone to act on.
+Without it, matching depends on the assembly: `chr12` matches on an assembly
+canonicalized `chr12` and matches nothing on one canonicalized `12`. The same
+spec key works on one config and does nothing on the next, with no error.
 
-Resolves through `getCanonicalRefName2`, whose fallback is what keeps a spec
-read before the alias file has loaded from throwing — and the getters that read
-user specs do run from the first render.
+Resolves through `getCanonicalRefName2`, which falls back to the input instead
+of throwing when a spec is read before the alias file has loaded. The getters
+that read user specs run from the first render.
 
-Takes a refName, not a spec that might hold one: the resolver reads
-`refName.toLowerCase()`, so anything else throws once the aliases are there, and
-a caller reading an untyped `frozen` slot has to establish that it names a
-refName at all before this is the right question to ask of it.
+Takes a refName, not a spec that might hold one. The resolver calls
+`refName.toLowerCase()`, so any other value throws once the aliases have loaded,
+and a caller reading an untyped `frozen` slot must first check that the value is
+a refName.
 
 ```js
 // type signature
@@ -113,6 +219,63 @@ refName at all before this is the right question to ask of it.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/mstUtils.ts)
 
+### 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.
+
+```js
+// type signature
+(field: string, {…}?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; labels?: readonly string[] | undefined; }) => CategoricalField
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### CategoricalField
+
+One categorical field as every channel reads it — a facet's sections, a color's
+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.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### CategoricalRef
+
+A field bound to a categorical scale: each distinct value takes one entry of the
+channel's `range` — a colour for `color`, a shape name for `shape`. Every value
+derives its entry from itself (an integer takes the slot it names, anything else
+hashes in), so every region agrees on a value it shares with another at the cost
+of an occasional collision. A `domain` spends the range deliberately: the listed
+values take it in order, and a value the domain leaves out never takes a listed
+value's entry. The domain orders and spends; it never adds a value the data
+lacks.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### CellsStep
+
+Replace each aligned row with its cells against the reference: one feature per
+run of columns in one `state` — `match`, `mismatch` or `gap` — on the row's own
+reference span, a mismatch run carrying its `base` and a match or mismatch run
+`match` as 1 or 0, and one interbase feature per `insertion`, standing at the
+reference base it precedes with the inserted bases in `base` and their count in
+`length`. The row's `field` (`seq`) is the aligned text, and the reference's is
+the same field on the feature the row was fanned out of, so a `flatten` over a
+MAF block's `alignments` stands in front. A gap run reaching either end of the
+row is no cell, and a feature with no parent answers none.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### ChannelReader
+
+A channel read per feature: the compiled form of a FieldRef, and what a
+display's own worker method hands the encoder for a channel no field name can
+say — a join against a second adapter, a lookup table, a rule over two fields.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
 ### clampBandHeight
 
 Clamp one _resize_ of a drag-resizable band: boundBandHeight, plus the one rule
@@ -140,28 +303,410 @@ lands before React re-renders.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandHeight.ts)
 
-### clearPromotedDefaults
+### clipQuantileOf
+
+The quantile a clip toggle writes: a scale's declared default where that clips,
+below 1, else DEFAULT_CLIP_QUANTILE.
+
+```js
+// type signature
+(declaredDefault: unknown) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
+### CodeLane
+
+Codes into a list of labels, one per row.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### COLOR_SCHEMES
+
+The named ramps a continuous colour scale's `scheme` takes, each one a stop
+table in `colorRamp.ts` that every ramp baker reads, so no display can name a
+scheme nothing bakes. `viridis`, `magma`, `inferno` and `cividis` are
+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.
+
+```js
+// type signature
+readonly[
+  ('viridis',
+  'magma',
+  'inferno',
+  'cividis',
+  'juicebox',
+  'fall',
+  'reds',
+  'blues',
+  'redblue',
+  'purpleorange')
+]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorSchemes.ts)
+
+### colorAt
+
+The packed colour instance `i` of `channels` paints: `color[i]`, or `color`
+itself where the colour is a constant and so shipped as one number.
+
+```js
+// type signature
+(channels: Pick<EncodedChannels, "color">, i: number) => number | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### ColorEncoding
+
+How a mark's `color` channel resolves. A CSS colour or a `jexl:` expression
+returning one paints per feature with no scale; the object forms bind a field to
+a scale, which a legend can describe, and share the config's member names.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### colorEvaluator
+
+A CSS colour or `jexl:` colour expression as a per-feature packed ABGR — the
+unscaled arm of ColorEncoding, on its own for a display that carries a plain
+`color` slot.
+
+```js
+// type signature
+(color: string, jexl: JexlInstance | undefined) => (feature: Feature) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### colorRampStops
+
+The stops a continuous colour scale samples: `range`'s CSS colours where it
+lists any, else the named `scheme`, viridis while that is unset, turned round
+under `reverse`.
+
+```js
+// type signature
+({ range, scheme, reverse, }: RampDeclaration) => readonly ColorRampStop[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
+
+### ColorScaleTable
+
+The scale a colour channel was resolved through, as the legend reads it — the
+same table the colours in the payload came from, so the key cannot disagree with
+the painting.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### ColorSchemeName
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorSchemes.ts)
+
+### Column
+
+A field's values over a table's rows, resolved once per step so the loop reading
+it is chosen before the loop runs: a lane a step wrote, codes into labels, a
+field read off the parser's own features, text or lists an adapter holds typed,
+or a value a step computes per row. `at` is the row each of the table's rows
+reads, where the lane or the features belong to a table this one stands on.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### ColumnTable
+
+A table an adapter answers from the typed arrays it already holds, where
+`getFeaturesArray` would make an object per row: a column per field, and each
+row's id. A row's hover JSON is every field it holds.
+
+```js
+// type signature
+typeof ColumnTable
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### ConfigurationSchemaUnion
+
+A list entry that is one of several configuration schemas, each keyed by the
+`type` it answers to:
+`types.array(ConfigurationSchemaUnion('Step', { filter, bin }))`. The keys are
+the vocabulary, the snapshot's `type` picks the member, and a `type` naming no
+member is refused in every build — where a bare `types.union` would load it as
+its first member. Each member is an `explicitlyTyped`, `closed` schema named by
+its key, so a key belonging to another member is refused rather than dropped;
+one that is not throws here.
+
+```js
+// type signature
+<const MEMBERS extends Record<string, AnyConfigurationSchemaType>>(name: string, members: MEMBERS) => ConfigurationSchemaUnionType<MEMBERS>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/configurationSchemaUnion.ts)
+
+### continuousColorScale
+
+A continuous colour scale over `extent`, the values it met: the domain its
+declared ends and the extent make, the straight table its stops bake to and
+where its middle stop sits, and the packed colour a value paints through them:
+an infinity the end on its side, as a threshold places it, and NaN, text that is
+no number, the misconfiguration grey. The encoder and every display painting a
+ramp itself read it, so a value takes one colour whoever paints it.
+
+```js
+// type signature
+(encoding: ContinuousRef, extent: readonly [number, number]) => { domain: [number, number]; lut: Uint8Array<ArrayBufferLike>; midNorm: number; colorOf: (value: number) => number; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### ContinuousRef
+
+A numeric field read through a linear or log scale into a ramp. Each end of the
+domain is pinned by `domainMin` or `domainMax`, or is the region's own extreme
+where unset, so pinning both keeps colours consistent across a whole view. The
+ramp is `range`'s CSS colours, evenly spaced, where it lists any, else the named
+`scheme`; `reverse` turns it round.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### CoverageStep
+
+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.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### darkAtLowEnd
+
+Whether a named ramp runs dark at its low end, drawn over white: viridis and its
+siblings do, juicebox, fall, reds and blues do not.
+
+```js
+// type signature
+(scheme: "blues" | "cividis" | "fall" | "inferno" | "juicebox" | "magma" | "purpleorange" | "redblue" | "reds" | "viridis") => boolean
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
+
+### DEFAULT_COLOR_SCHEME
+
+The ramp a continuous scale samples while it names no `range` and no `scheme`,
+so a declaration spelling it out and one leaving it unset resolve alike.
+
+```js
+// type signature
+;'blues' |
+  'cividis' |
+  'fall' |
+  'inferno' |
+  'juicebox' |
+  'magma' |
+  'purpleorange' |
+  'redblue' |
+  'reds' |
+  'viridis'
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorSchemes.ts)
+
+### EncodeContext
+
+What surrounds an encode: the jexl instance a `jexl:` channel compiles against —
+a caller whose channels are all readers or field names passes none — and a
+progress reporter.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### Encoded
+
+EncodedChannels with the lanes in `L` present — what `encodeFeatures` answers a
+caller that named them.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### EncodedChannels
+
+One encoding's channels over one region's features, dense and index-aligned:
+instance `i` of every array is the same feature, and `featureIndex[i]` says
+which one of the input list it was, or it is absent where instance `i` is
+feature `i` (featureIndexAt). A lane is present when the caller asked for it
+(LaneName); Encoded is this type with a known lane set required.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### encodedChannelTransferables
+
+The buffers an EncodedChannels owns, for `rpcResult`'s transfer list.
+
+```js
+// type signature
+(c: EncodedChannels) => ArrayBufferLike[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### EncodedLayersResult
+
+What `CoreGetEncodedLayers` answers for one region: `layers[i]` is the request's
+`layers[i]` over the region's features, so a display's mark list indexes
+straight into it.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### encodeFeatures
+
+Evaluate one encoding over a feature list into dense channel arrays for the
+lanes named, the scale table each scaled channel came from, the `y` extremes and
+— when `index` is among the lanes — a hit index.
+
+A feature whose `x`, `x2` or (declared and asked-for) `y` is not finite is
+skipped and counted in `skipped`, so every array stays index-aligned with the
+Flatbush. Pure: the RPC around it owns the adapter, the filters and the
+transferables.
+
+Columnar: one pass admits the rows over `x`, `x2` and `y` alone, and none runs
+where all three are lanes of whole numbers; every other lane is then filled in
+its own loop over the admitted rows, a lane straight off a typed column and a
+categorical over a `category` column per label.
+
+```js
+// type signature
+<L extends LaneName>(input: readonly Feature[] | FeatureTable, encoding: MarkEncodingInput, lanes: readonly L[], ctx?: EncodeContext) => Encoded<L>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### FacetedLayer
+
+One layer of a faceted request: its rows in section order, and the stacked row
+of each, index for index.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
+
+### facetLayers
+
+A faceted request's layers: the rows split on the facet's field, the facet's own
+steps and then each layer's run over each section alone, and the sections
+stacked — a section's rows start where the one above it ends, and it is as tall
+as the tallest layer packed it. Every layer's rows come back in section order
+beside their stacked rows, so a faceted display is the unfaceted one drawn once
+per section, and a row is handed on as its steps left it. A layer naming no
+`row` field stands on each section's first row, the answer the unfaceted encoder
+gives it.
+
+The split is a counting sort into section order rather than a list per section:
+every step runs once over the ordered rows, keeping section order, and one that
+groups rows groups within a section.
+
+```js
+// type signature
+(input: readonly Feature[] | FeatureTable, facet: FacetSpec, layers: readonly {…}[], jexl?: JexlInstance | undefined) => { ...; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
 
-Clear the named promoted defaults for this display type, so every track
-following one reverts to its own config value. Backs the badge's "clear session
-default" action, which passes the slots it actually listed
-(`getDisplayTypeDefaultChanges`).
+### FacetSection
 
-**`slots` is required, and an all-slots default is not the convenience it looks
-like.** It reaches further than any list a dialog can have shown: a promoted
-default the track _customized_ over, or one promoted to a value equal to
-`promotedBase`, is `inherited: false` and so appears in no row, yet still
-governs sibling tracks — so clearing it from a dialog that never showed it moves
-tracks other than the one whose badge was clicked. Clearing every promoted
-default at once is a preferences-scope action, and Preferences → "Reset to
-defaults" is where it lives (`clearPreferenceOverrides`).
+One faceted section as the worker stacked it: its key, the row it starts on and
+how many rows it holds.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### FacetSpec
+
+A row facet: split the features on `field`'s value, run `transform` and then
+every layer's own steps over each section alone, and stack the sections, each
+starting on the row after the one above it ends.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### featureIndexAt
+
+The input feature instance `i` of `channels` was: `featureIndex[i]`, or `i`
+itself where the encoder skipped none and so shipped no index.
+
+```js
+// type signature
+(channels: Pick<EncodedChannels, "featureIndex">, i: number) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### FeatureTable
+
+The rows one step of a mark's declaration hands the next: a column per field and
+a view of one row as a `Feature`, for a `jexl:` expression, a channel reader and
+the hover.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### fieldReader
+
+What a channel reads off a feature: a field by name, a dotted path into a
+structured field where no field carries the whole name (`INFO.SVTYPE` on a VCF
+record), or a `jexl:` expression over `feature`. A jexl expression that does not
+compile throws here, once, rather than on every feature.
 
 ```js
 // type signature
-(self: ResolvableDisplay, slots: Iterable<string>) => void
+(ref: string, jexl: JexlInstance | undefined) => (feature: Feature) => unknown
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/fieldReader.ts)
+
+### FieldRef
+
+Where a channel's value comes from: a feature field name, read natively
+(`feature.get(name)`), or a `jexl:` expression over `feature` — the opt-in
+escape, measured at 1.5x to 2.0x native per feature (MARK_ENCODING.md "The jexl
+channel, measured").
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### FilterStep
+
+Keep the features a `jexl:` expression over `feature` admits.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### finiteExtremes
+
+The least and greatest finite values of `values[0, count)`,
+`[Infinity, -Infinity]` where none is finite.
+
+```js
+// type signature
+(values: ArrayLike<number>, count: number) => [number, number]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
+### FlattenStep
+
+Fan each feature out into one feature per element of an array-valued field —
+`subfeatures`, so a gene answers its transcripts and a transcript its exons — or
+per entry of a record keyed by name, so a VCF record answers one feature per
+sample and a MAF block one per species, each with its key in `key`. Each answer
+reads the element's own fields first and the feature it came from for everything
+else, so an exon still knows its gene's name and strand and a species row its
+block's reference span. A feature whose field holds no array and no record drops
+out unless `keepEmpty` says otherwise.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### FormulaStep
+
+Write a `jexl:` expression's value over `feature` into the field `as` of every
+feature.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
 ### getAssemblyHost
 
@@ -180,6 +725,22 @@ thing on `AbstractSessionModel` a third-party host cannot simply implement.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/mstUtils.ts)
 
+### getBreakendMateLocString
+
+The mate locString ("chr2:100") of a parsed breakend, or undefined when it names
+no navigable position. Two ALT forms reach here without one: a single breakend
+(`.A` / `G.`) has no mate at all, and the symbolic-mate forms (`G<DEL>`,
+`<DEL>G`) get a placeholder `<DEL>:1` from parseBreakend, which puts a symbolic
+allele id where a contig name belongs. Callers that navigate or split-view a
+mate must drop both rather than treat `<DEL>` as a refName.
+
+```js
+// type signature
+(breakend?: Breakend | undefined) => string | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
 ### getConf
 
 Reads a configuration value from a state model that has a `.configuration`
@@ -192,43 +753,13 @@ 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.
 
-A `promotable` slot read this way therefore yields the raw stored value,
-`undefined` included — that `undefined` is the cascade's inherit sentinel, and
-`resolveConf` is what turns it into a real value. The read type keeps the
-`undefined` on purpose, so reaching for the wrong reader is a compile error
-rather than a silent one.
-
 ```js
 // type signature
-{ (model: {…}): ModelSnapshotType<…>; <…>(model: {…}, slotPath: SLOT, args?: Record<…> | undefined): SLOT extends string ? ConfigurationSlotValue<…> : any; }
+{…}
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
 
-### getConfigSnapshotWithPromotables
-
-The display's full config snapshot with every `promotable` slot overwritten by
-its resolved value in place. For building a worker payload: a promotable slot
-serializes as its raw inherit sentinel (`undefined`, since they're all `maybe*`
-types), which the worker can't interpret — it has no session to resolve against.
-This hands it concrete values instead, with no per-slot bookkeeping, so adding a
-promotable worker-consumed slot needs no rpcProps change and can't silently ship
-a sentinel. Main-thread only (the cascade consults the session). Display-only
-promotable slots the worker never reads (e.g. displayMode) are still excluded by
-the caller — resolving them here is a harmless no-op since they're dropped
-anyway.
-
-The return type is branded (`ResolvedConfigSnapshot`) so a payload builder can
-demand a snapshot that has been through here. The assertion below is the one
-place the brand is applied, and it sits on the line after the resolve.
-
-```js
-// type signature
-(self: ResolvableDisplay) => ResolvedConfigSnapshot
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
-
 ### getContainingDisplay
 
 Returns the display model that contains the given node. Throws if the node has
@@ -276,19 +807,6 @@ Where a display puts a dialog it cannot mount itself.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/sessionServices.ts)
 
-### getDisplayTypeDefaultChanges
-
-Effective differences a track following the default inherits from session-wide
-defaults, one per promotable slot whose inherited value differs from its schema
-default. Drives the track-selector "affected by a session default" badge.
-
-```js
-// type signature
-(self: ResolvableDisplay) => TrackConfigChange[]
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
-
 ### getEnv
 
 Returns the MST environment for a node, which carries the `pluginManager`.
@@ -370,150 +888,473 @@ module actually uses.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/sessionServices.ts)
 
-### getTrackConfigWithPromotables
+### HitIndexed
+
+An encoded payload as a display stores it: the hit index the worker built with
+hitIndexOf, wrapped once where the payload lands.
 
-See TrackConfigWithPromotables.
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### hitIndexOf
+
+The hit index over `count` instances: each a box from `x` to `x2` at its `y`, or
+at 0 for a mark with no value.
 
 ```js
 // type signature
-(session: PromotedDefaultStore, trackConfig: ModelInstanceTypeProps<…> & {…} & IStateTreeNode<…>) => TrackConfigWithPromotables
+(x: Uint32Array<ArrayBufferLike>, x2: Uint32Array<ArrayBufferLike>, y: Float32Array<ArrayBufferLike> | undefined, count?: number) => Flatbush
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
 ### 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), so a caller handed one of those has a
-config that reads nothing but what was literally authored: a slot at its schema
-default is absent, `preProcessSnapshot` has not run, and nothing that walks a
-live node — the promotable cascade above all — applies to it.
-
-For the callers that need the resolved answer rather than the authored one and
-cannot know which of the two they were handed. The About dialog's "Copy config"
-is the case this exists for: it is reached from two menus, and one of them
+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.
+
+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** rather than throwing when the config names a track type no
-plugin registered, or when it is invalid enough that `create` rejects it — an
-un-hydrated config has never been validated, so a dialog that opens over it must
-not be the thing that discovers this. Callers fall back to treating it as the
-plain object it is.
+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 a track that gets opened later reuses
-it.
+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.
 
 ```js
 // type signature
-(pluginManager: PluginManager, config: Record<string, unknown>) => (ModelInstanceTypeProps<Record<string, any>> & { ...; } & IStateTreeNode<...>) | undefined
+(pluginManager: PluginManager, config: Record<string, unknown>) => AnyConfigurationModel | undefined
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/configurationSchema.ts)
 
-### isSlotCustomized
-
-Whether this track has customized the slot (holds a non-default value of its
-own) rather than following the display type's default. The correct "reset to
-default" predicate for a promotable slot: comparing the resolved value to the
-base instead reads as at-default for a track merely _following_ a non-base
-promoted default, so the reset control lights up on a no-op.
+### isBreakend
 
-`SLOT` is constrained the way `getConf`'s is. A pin or a reset over a slot name
-the schema does not declare is inert and silent — `resolveSlot` answers about
-nothing, so the control draws outline forever — and a widened `self` switches
-the check off (`HostChecksSlotNames`).
+Breakend notation, without parsing it: bracket forms (`G[chr2:100[`), single
+breakends (`.A` / `G.`), and the symbolic-mate form (`G<DEL>`, an angle bracket
+past position 0; a leading `<` is a plain symbolic allele).
 
 ```js
 // type signature
-<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT) => boolean
+(alt: string) => boolean
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
 
-### makePin
+### isMissing
 
-The pin for one promotable slot: "apply this value to every open track of this
-display type", and — via the snackbar it raises — "keep it as the default for
-the ones opened later".
+Whether a field holds no value at all, as against text that fails to parse:
+absent, empty, or a VCF's `AF=.`, which arrives as `[undefined]`.
 
-`value` chooses between the subsystem's two meanings, which are otherwise
-identical:
+```js
+// type signature
+(value: unknown) => boolean
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### isPlainFieldRef
+
+Whether a field ref is a bare name: what `feature.get` answers on its own, with
+no path to walk and no expression to evaluate. A loop over a plain name keeps
+the direct call, and only a config that writes a path pays for one.
+
+```js
+// type signature
+(ref: string) => ref is never
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/fieldReader.ts)
+
+### junctionEnds
+
+Where a paired record's junction is at each of its two ends, and which side of
+it each end keeps — the one answer every launcher, the row menu and the chain
+walk take, whether the record is a VCF breakend, a symbolic SV or a paired
+adapter's row (BEDPE, STAR-Fusion). Refnames are as the record spells them.
+`undefined` for a record naming no other end. A VCF record is read through
+`alt`, its first ALT unless the caller names another.
+
+A VCF end is its own position. A paired adapter's end is a block, and the
+junction is the block's edge on the side the end keeps: stated by
+`mateDirection` where the adapter knows it, read off the strands where the
+record states one for each end as BEDPE does, and with neither the two blocks
+face each other. A PAF row's strand is the query's orientation and states none
+for the target, so it names no side.
+
+```js
+// type signature
+(feature: Feature, alt?: string | undefined, alleleIndex?: number | undefined) => { own: JunctionEnd; mate: JunctionEnd; } | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
+### keyNames
+
+What a key names each of `keys`, from a colour 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.
+
+```js
+// type signature
+(keys: readonly unknown[], labels?: readonly string[]) => ReadonlyMap<string, string>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### LaneName
+
+The lanes a caller asks the encoder to fill, beyond `x` and `x2`, which every
+payload carries, and `featureIndex`, which one carries where a feature was
+skipped: a mark's channels, and `index` for the Flatbush a hover reads. A lane
+not asked for is neither allocated nor transferred, and a caller that never
+hovers declines the index, which is most of the encoder's cost after the walk.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### launchOrReplaceView
+
+`addOrReplaceView` for view types whose state model may be lazily loaded; the
+synchronous `addOrReplaceView` requires it loaded already.
+
+```js
+// type signature
+(args: { session: AbstractViewContainer; typeName: string; initialState?: Record<string, unknown> | undefined; replacing?: AbstractViewModel | undefined; }) => Promise<...>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/mstUtils.ts)
+
+### LayerRequest
+
+One layer of a `CoreGetEncodedLayers` request: the encoding to evaluate and the
+lanes the display's mark reads.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### layerTables
+
+A layered request's rows: the shared steps, the facet's split where it names
+one, and each layer's own steps, with the row each layer's rows stand in — the
+field it names, or under a facet each row's stacked row. The split comes as
+early as it can: after the last shared step that must see every row, so the
+steps that follow it read the rows already in section order.
+
+```js
+// type signature
+(input: readonly Feature[] | FeatureTable, request: {…}, jexl?: JexlInstance | undefined) => { ...; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
+
+### ListColumn
+
+A list of rows per row: row `i`'s entries are the rows of `entries` from
+`start[i]` up to `start[i + 1]`, and `keys`, where the list is a record keyed by
+name, the name of each entry.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### ListedRowSource
+
+One row an adapter lists: `name` is a value of the listing's field, and `label`
+and `color` are what the adapter names and colours that row with.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/rowSources.ts)
+
+### listsRowSources
+
+Whether an adapter implements RowSourceLister.
+
+```js
+// type signature
+(adapter: object) => adapter is RowSourceLister
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/rowSources.ts)
+
+### LocusRef
+
+A position that may lie on another sequence: the field holding its refName and
+the field holding its 0-based coordinate, as a paired record states its mate
+(`{ chrom: 'mate.refName', pos: 'mate.start' }`). Spelt the way GenomeSpy spells
+a genomic position over two columns.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### MadeRows
+
+A table whose rows a step made, which answers each row's identity, its hover
+JSON and the feature it hangs from.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### MarkEncoding
+
+The declared mapping from a feature's fields to a mark's channels. Every
+positional channel is a field: `x` defaults to `start` and `x2` to `end`, a mark
+that plots no value leaves `y` off, and the scale `y` is read through belongs to
+the display rather than to the encoding. `shape` is read by the `point` mark
+alone, `row` — an integer field, 0 where missing — by every mark, which stands a
+feature in the band it names.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### MarkEncodingInput
+
+What `encodeFeatures` takes: a MarkEncoding, any channel of which may be a
+ChannelReader in place of its declared form, and `row` the values themselves,
+one per input feature, where the caller computed them — a facet's stacked rows.
+The declared form is what crosses the wire; a reader or a value list is built in
+the worker.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### matedBy
+
+How a record states its other end, or undefined where it states none: the `mate`
+a paired adapter fills (BEDPE, STAR-Fusion), or an `ALT` the breakend and
+symbolic-SV readers resolve. The `mate` step admits exactly the features this
+names one for, so a caller deciding whether links are the picture a track wants
+asks here rather than re-reading the fields.
+
+```js
+// type signature
+(f: Feature) => "alt" | "mate" | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
+
+### MateStep
+
+One feature per other end a record states: the `mate` a paired adapter fills in
+(BEDPE, STAR-Fusion), or each VCF `ALT` naming a locus, a breakend's mate or a
+symbolic allele's `END` on `CHR2` or its own sequence. Each answer carries
+`mate` (`refName`, `start`, `end`, 0-based and half-open, and the far end's
+`mateDirection`), its own end's `mateDirection`, the `alt` it came from and
+`svType`, the structural class the allele states (`svClassOfAlt`). A record
+naming no other end drops out, and two records or alleles stating one pair of
+ends answer once.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### MISCONFIGURED_ABGR
+
+The misconfiguration grey packed as the encoder paints it: a `jexl:` colour that
+answered no string, a ramp value that is no number, text a threshold cannot
+read.
+
+```js
+// type signature
+number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### NO_VALUE_ABGR
+
+The no-value grey packed as the encoder paints it: a feature with nothing in the
+field a threshold reads.
+
+```js
+// type signature
+number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### NO_VALUE_LABEL
+
+The row a feature with nothing in a categorical field lands on, so a key says
+why a mark is grey rather than listing a blank value.
+
+```js
+// type signature
+'(no value)'
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### NOT_A_NUMBER_LABEL
+
+The key a value holding text that is no number files under on a threshold scale,
+painted the misconfiguration grey rather than passing for a missing value.
+
+```js
+// type signature
+'(not a number)'
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### NumberLane
+
+A typed lane a step wrote, one number per row.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### numberReaderOf
+
+readerOf as the number a quantitative channel or step reads, `NaN` where a row
+holds none, by `numericValue`'s rules.
+
+```js
+// type signature
+(column: Column) => (i: number) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### numericDomain
+
+A domain written as strings — the shared `domain` slot is a `stringArray` — read
+back as the numbers it names. A member that is not a number reads NaN, which
+every comparison against it declines.
+
+```js
+// type signature
+(domain: readonly (string | number)[]) => number[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### parseSvAlt
+
+Parse raw (non-assembly-resolved) mate coordinates from a VCF SV feature+alt.
+Returns undefined when no mate coordinate info is found. `alleleIndex` is the
+alt's place in `ALT`, which a record repeating one symbolic allele with several
+lengths needs; it defaults to the first place `alt` appears.
+
+```js
+// type signature
+(feature: Feature, alt?: string | undefined, alleleIndex?: number) => {…} | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
+### PileupStep
+
+Assign every feature the lowest row on which it overlaps nothing already there —
+greedy first fit in start order, the packing a pileup is — and write it to the
+field `as` (`row`). `fields` names the interval read (`start`, `end`); `padding`
+is bp of clearance kept between two features sharing a row. The answer is the
+input in start order, so a `span` encoding `row` stacks it. Under a facet it
+packs each section on its own.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### preProcessConfigSnapshot
+
+A snapshot as `type` admits it: the same lift and checks `type.create` applies,
+so a dialog or a validator refuses exactly what a config file cannot hold.
+Throws what the schema's `preProcessSnapshot` throws.
+
+```js
+// type signature
+(type: IAnyType, snapshot: unknown) => Record<string, unknown>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/snapshotPreprocess.ts)
+
+### quantileExtent
+
+What the open ends of a scale follow over `values[0, count)`: at a `quantile` of
+1 their finite extremes, and below it each end clipped at that quantile of the
+values on its side of 0, so one spike takes neither the axis nor the ramp, and a
+sparse tail of the other sign keeps its own end. An axis that starts at 0 adds
+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.
+
+```js
+// type signature
+(values: ArrayLike<number>, count: number, quantile?: number) => [number, number]
+```
 
-- **Give it** for a per-value pin — "make _arcs_ the default" — independent of
-  what the track currently shows. Use on an always-visible pin so it can never
-  promote a meaningless value, and so two rows sharing one slot (arcs `'arc'` vs
-  read cloud `'cloud'`; sashimi `'down'` vs `'auto'`) stay independent.
-- **Omit it** for "whatever I'm showing", resolved through the cascade. Use for
-  a symmetric or continuous setting where no fixed on-value makes sense (wiggle
-  point size, arc line width, `mismatchAlpha`).
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
 
-One function with an optional argument, rather than the two exported builders it
-replaces — a per-value one and a `…CurrentValue…` one, the second of which was
-exactly the first applied to `resolveSlot(self, slot).value`. The pair was one
-function plus a doc section explaining which name to reach for; omitting the
-argument now says what the longer name said.
+### quantileOf
+
+The nearest-rank `quantile` of `a[0, n)`: the smallest value at least that share
+of them sit at or below, so a handful of values clips at their maximum. Permutes
+`a`; 0 where `n` is.
 
 ```js
 // type signature
-<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<…>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT, ...value: [] | [...]) => Pin
+(a: Float32Array<ArrayBufferLike>, n: number, quantile: number) => number
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
+### RampDeclaration
+
+A continuous colour scale's ramp as a config declares it.
 
-### openPromotableDisplays
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
+
+### rampDomain
+
+The domain a continuous colour scale spans: each end `min` or `max` pins, else
+the extent's, ascending, since a span has no direction and `reverse` is the
+ramp's. An open end stops at a pinned one rather than crossing it, and an extent
+holding no value (`[Infinity, -Infinity]`) spans [0, 1].
+
+```js
+// type signature
+(min: number | undefined, max: number | undefined, extent: readonly [number, number]) => [number, number]
+```
 
-Every display on an open track, across all open views — the reach of anything
-that acts on "the tracks the user is looking at": a promoted default's "apply to
-open tracks", and the share/export bake. One walk so those can't drift apart.
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
-Recurses into composite views. A display nested in one resolves the cascade like
-any other but was invisible to both callers, so the share/export bake didn't
-bake its inherited values and a shared session containing a breakpoint-split or
-synteny view rendered differently for the recipient. `LGVSyntenyDisplay` is only
-ever reached through this branch, so don't flatten the recursion away.
-`hasChildViews` names the one composite shape it does not cover.
+### rampGapScales
 
-A view holding neither (e.g. spreadsheet) drops out via the structural guards. A
-view whose displays declare no promotable slot (e.g. dotplot, which does hold
-tracks) is walked and contributes nothing — harmless, and cheaper than asking
-each display whether it has anything to promote.
+The rows a ramp's key lists beside its bar once a feature painted one: the
+not-a-number and no-value rows a threshold's key ends with. Empty while neither
+painted.
 
 ```js
 // type signature
-(session: AbstractSessionModel) => ResolvableDisplay[]
+(id: string, met: { missing?: boolean | undefined; notNumber?: boolean | undefined; }) => CategoricalScale[]
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/openDisplays.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
 
-### Pin
+### rampLutOf
 
-The "apply this to every open track of this type" affordance on a menu row — the
-trailing `PushPin`, bundled so the row consumes it as one prop. Built by
-makePin.
+The buildColorRampLut table a ramp declaration asks for, the same `Uint8Array`
+for the same declaration, since a GPU backend re-uploads its ramp texture when
+the identity changes and a render state is rebuilt far more often than its ramp.
 
-`active` = this value is currently the session default (a filled pin), which is
-the state, not the click. `toggle` **applies the value to every open track of
-the display type** and raises a snackbar whose one action promotes it to the
-display type's default; on an already-promoted value it clears that default
-instead, touching no track (see `applyPinClick`).
+```js
+// type signature
+(ramp: RampDeclaration) => Uint8Array<ArrayBufferLike>
+```
 
-**`toggle` rather than an `apply`/`clear` pair**, which was tried and dropped:
-the sole renderer is a MUI `ToggleButton` whose `onChange` means exactly "flip",
-so splitting it adds a member _and_ a branch at the one call site that never
-needed one. `active` is already public for a caller that wants to state a
-direction. (The house preference for explicit setters over toggles is about MST
-actions, where a toggle destroys the ability to set a known state; nothing here
-stores a value.)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
-Lives here, alone and with no imports, rather than beside `makePin` in
-`promotableDefaults.ts`: the menu types describe a pin without building one, and
-`MenuTypes.ts` taking this one interface from that module gave a React-free type
-file a type closure of 374 files. See
-`agent-docs/ideas/barrels-block-extraction.md` and `scripts/moduleClosure.ts`.
+### rampOverExtent
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotablePin.ts)
+A ramp table over `extent`, the union a display took across the regions it
+loaded: each open end of the domain moved to the union's, the pinned ends kept.
+The table stays straight and `domainMid` a value, so the middle stop follows the
+widened domain with no table baked again.
+
+```js
+// type signature
+(table: {…}, extent: [...]) => { ...; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
 ### readConfObject
 
@@ -539,24 +1380,35 @@ indistinguishable at runtime from the broken spelling.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
 
-### readConfSlot
+### readerOf
+
+A reader of a column's values by row, its kind resolved here once. A `number`
+lane with no index reads straight off the lane.
 
-Read a single config slot from a config that may be **either** a live MST node
-or a plain snapshot object, evaluating the value if it is a `jexl:` expression.
-For the dialogs and panels that are handed a track config without knowing which
-of the two they got. An About panel gets a hydrated track config from the
-session and a bare object from an embedded caller.
+```js
+// type signature
+(column: Column) => (i: number) => unknown
+```
 
-Reach for `readConfObject` or `readConfigValue` when the shape is known: this
-one decides at runtime, and the plain branch inherits the snapshot caveat (a
-slot at its default is absent from a snapshot, so it reads `undefined`).
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### READS_REFERENCE
+
+The `adapterCapabilities` entry of an adapter that reads the reference sequence
+of the assembly it is displayed against: BAM and SAM for mismatches without an
+MD tag, CRAM to rebuild bases, GC content and the reference scans for everything
+they answer. Such an adapter is built with that reference and keyed on it as
+well as on its config, so one config shown on two genomes is two instances, each
+reading its own, and an instance never changes reference for its life. Every
+other adapter keys on its config alone: a synteny adapter is fetched from each
+of its assemblies and reads no reference.
 
 ```js
 // type signature
-<…>(config: Record<…> | (ModelInstanceTypeProps<…> & {…} & IStateTreeNode<…>), slotPath: string | string[], args?: Record<…>, jexl?: JexlInstance | undefined) => T
+'readsReference'
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/dataAdapterCache.ts)
 
 ### relight
 
@@ -585,6 +1437,20 @@ has to read as one tone across the whole palette or it reads as noise.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/color/index.ts)
 
+### requirementProblems
+
+The `requires` entries of a configuration schema that `snapshot` does not meet,
+as a config file or `getSnapshot` spells it: a slot left off reads as its
+default, so a `when` value that is the default fires for an absent slot, which
+is what the generated JSON Schema's `if` does.
+
+```js
+// type signature
+(type: IAnyType, snapshot: Record<string, unknown>) => RequirementProblem[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/requirements.ts)
+
 ### reservedPx
 
 The pixels a band takes from the plot below it: 0 when off, the (optionally
@@ -597,56 +1463,62 @@ bound) stated height when on. This is the single spelling of "off spends 0 px".
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandLayout.ts)
 
-### resolveConf
+### RowSourceLister
+
+An adapter that lists its rows without reading a region: a multi-BigWig its
+files, a MAF its species.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/rowSources.ts)
+
+### RowSourceListing
+
+Every row an adapter has, in its own order, whatever the loaded regions hold, so
+a row display gives a row with nothing in view its place, label and colour.
 
-Reads a `promotable` slot through the display-type-default cascade — the track's
-own value, else the session-wide promoted default for this display type, else
-the slot's `promotedBase`. Always yields a real value, never the `undefined`
-inherit sentinel, so a display's value getter is
-`get displayMode(): DisplayMode { return resolveConf(self, 'displayMode') }`
-with no post-guard and no cast.
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/rowSources.ts)
 
-Separate from `getConf` rather than folded into it, deliberately: resolution
-consults the session, so it is main-thread only and throws on a detached node.
-Folding it in was built and reverted — ADR-046.
+### runLazyAfterAttach
 
-Throws if `slot` isn't promotable — the cascade has nothing to say about a plain
-slot, and `getConf` is what you want there.
+Run a display's `afterAttach` body from a module loaded on demand, so the
+autorun installers stay out of the display's eager bundle.
 
-Takes no jexl `args`, unlike `getConf`: a promotable slot cannot hold a callback
-(see `SlotResolution`), so there is no per-feature context to supply.
+One policy for the gap the `await` opens: a node torn down before the module
+lands installs nothing, and a module that fails to load is reported where the
+user can see it rather than onto the display's own error slot — that slot is
+what `reload()` clears, and nothing would re-run the install behind it. Three
+displays hand-rolled this IIFE and each drew the lines differently.
 
 ```js
 // type signature
-<…>(model: ResolvableDisplay<...>, slot: SLOT) => ConfigurationSlotValueResolved<...>
+<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>) => void
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/lazyAfterAttach.ts)
+
+### runTransforms
+
+Run the transform steps over a feature list or a table, in order, in the worker.
+The table a step answers is what the next one reads, and the last one is what
+the encoder walks.
+
+```js
+// type signature
+(input: readonly Feature[] | FeatureTable, steps: readonly TransformStep[], jexl?: JexlInstance | undefined) => FeatureTable
+```
 
-### ResolvedConfigSnapshot
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
 
-A display config snapshot whose promotable slots hold RESOLVED values rather
-than the inherit sentinel — what a worker payload has to be built from.
+### safeParseBreakend
 
-The brand is required and unforgeable, so a plain `Record<string, unknown>` is
-not assignable to it and neither is `getSnapshot(self.configuration)`. That is
-the whole point. Everything downstream of the resolve is an ERASED container — a
-snapshot is `Record<string, unknown>`, and the payload it becomes is an
-`as`-asserted interface — so a payload builder handed the RAW snapshot instead
-typechecks, ships `undefined` for every promotable slot, and types it as the
-resolved value. That was measured, not supposed: the raw spelling in
-`LinearBasicDisplay`'s `rpcProps()` passed `pnpm typecheck` and every suite in
-`plugins/canvas`, `packages/core/src/configuration` and `products/jbrowse-web`,
-while sending the worker `undefined` for chevrons, subfeature labels and feature
-height.
+parseBreakend, honoring its `Breakend | undefined` signature. ALT strings are
+user data and malformed breakends do occur;
 
-The rest of this subsystem's guarantees are carried by types that stay connected
-to the schema: a raw read of a promotable `maybe*` slot is `T | undefined` (see
-`ConfigurationSlotValue`), so `getConf` where `resolveConf` was meant is a
-compile error at any typed consumer. The brand is that guarantee re-established
-at the point where the connection is cut.
+```js
+// type signature
+(alt: string) => Breakend | undefined
+```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
 
 ### sampleColorRamp
 
@@ -661,6 +1533,87 @@ than an extrapolation past them, and a one-stop ramp is that stop everywhere.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
+### scaleBandHeights
+
+Heights after growing or shrinking a stack of bands by `distance` px in all: the
+one rule every whole-stack resize uses. Each band takes its share of the height
+it has above `floor`, so the tall bands give and take the most, and none goes
+below `floor`, or below its own height if it already sits under it (the
+clampBandHeight rule). Whole pixels, rounded by largest remainder, so the stack
+moves by exactly the rounded distance.
+
+```js
+// type signature
+(heights: number[], distance: number, floor?: number) => number[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandHeight.ts)
+
+### scaleExtent
+
+quantileExtent as a scale's open ends read it: over every finite value on a
+linear scale, and on a log scale over the positive ones, since a 0 or a negative
+met there would floor the domain at 1 and fold a domain below 1 flat.
+`[Infinity, -Infinity]` where the scale reads nothing.
+
+```js
+// type signature
+(values: ArrayLike<number>, count: number, scale: string, quantile?: number) => [number, number]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
+### ScaleTable
+
+The table behind a channel a key is drawn from: a colour's, whose `kind` names
+the scale it resolved through, or a shape's. A `size` channel's (SizeScaleTable)
+draws no key and stands outside.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### selectEncodedFeature
+
+Open the feature widget on the feature behind one instance of a
+`CoreGetEncodedLayers` answer. A display holds channels, not records, so it
+sends `CoreGetEncodedFeature` the request the instance's region came back under,
+and the worker answers the entry of `layer`'s list that the instance's
+`featureIndex` names: the record as the adapter wrote it, or the bin or run the
+steps made. A second click aborts the first.
+
+```js
+// type signature
+(self: IStateTreeNode<IAnyType>, rotation: { begin(): ActiveFetch; cancel: () => void; dispose(): void; }, args: Omit<CoreGetEncodedLayersArgs, "byteLimit"> & { ...; }) => void
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/selectEncodedFeature.ts)
+
+### selectNth
+
+The `k`th smallest of `a[0, n)`, permuting `a` in place. Exact, where a
+histogram collapses skewed contact counts into its bottom bucket, and O(n) where
+a sort of 4.5M counts measured ~1s. Median-of-three because Hi-C contacts arrive
+nearly sorted.
+
+```js
+// type signature
+(a: Float32Array<ArrayBufferLike>, n: number, k: number) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
+### selectRows
+
+The table's rows `rows` names, in that order: over an adapter's features, a
+source table over those features again, so every field still reads straight off
+them; over rows a step made, a table standing on them.
+
+```js
+// type signature
+(table: FeatureTable, rows: Uint32Array<ArrayBufferLike>) => FeatureTable
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
 ### SessionPaletteProvider
 
 Make JBrowse follow the host's light/dark state — the whole of it, in one mount:
@@ -671,6 +1624,10 @@ Make JBrowse follow the host's light/dark state — the whole of it, in one moun
 </SessionPaletteProvider>
 ```
 
+`mode` is optional. Left out, JBrowse follows the page's declared `color-scheme`
+— so a host whose dark-mode toggle sets it, as most do, mounts this with a
+session and nothing else — and the OS preference where the page declares none.
+
 A component rather than a documented pair of calls because the pair has a half
 that can be left out with nothing to show for it. `PaletteProvider` is the name
 a host reaches for, and it colors the React side alone; the session write is
@@ -684,15 +1641,23 @@ colors of its own mounts `PaletteProvider` directly instead.
 
 ```js
 // type signature
-({ session, mode, children, }: { session: ThemeModeSession; mode: "dark" | "light"; children: ReactNode; }) => Element
+({ session, mode, children, }: { session: ThemeModeSession; mode?: "dark" | "light" | undefined; children: ReactNode; }) => Element
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/ui/PaletteContext.tsx)
 
 ### setConf
 
-Write counterpart to `getConf`: sets a slot on a state model that has a
-`.configuration` member (a track or display state model).
+Write counterpart to `getConf`, and it takes the same path: a slot name, or an
+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
@@ -711,26 +1676,78 @@ 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 the
-inherit sentinel (`undefined`/`null`) is a legitimate write on every promotable
-slot, which the declared slot value type doesn't include.
+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.
 
 ```js
 // type signature
-<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<…> = ConfigurationSlotName<…>>(model: { ...; }, slotName: SLOT, value: unknown) => void
+<…>(target: CONFMODEL | { ...; }, slotPath: SLOT, value: unknown) => void
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
 
+### SHAPE_CODES
+
+The `point` mark's painter code for each shape an encoding can name.
+
+```js
+// type signature
+Record<ShapeName, number>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/shapeNames.ts)
+
+### ShapeEncoding
+
+A ShapeName, a `jexl:` expression over `feature` returning one, or a field bound
+to a categorical scale whose `range` lists the shape names handed out — the
+three shapes, in order, when absent.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### ShapeScaleTable
+
+The scale a shape channel was resolved through: which shape each value of the
+field took.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### SizeEncoding
+
+How a mark's `size` channel resolves: a number is a constant width in CSS px for
+every instance, a field name is `{ field }` with the defaults, and the object
+binds the field to a scale.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### SizeRef
+
+A numeric field read through a linear or log scale into a width in CSS px:
+`range` is the px at each end of the domain (1 to 6 unset), and each end of the
+domain is pinned by `domainMin` or `domainMax` or follows the loaded regions'
+extremes where unset, as a colour ramp's does. A feature holding no number takes
+the range's first px.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### SizeScaleTable
+
+The scale a size channel is read through: the `size` lane holds the raw values
+and the shape maps them to px through this, so a display unions `extent` over
+its loaded regions into the open ends of `domain` and every region strokes the
+same value at the same width.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### stackBands
 
 Fold an ordered set of bands into tops and a bottom. The order is the argument,
-so a display states its band order exactly once; reserve, paint and pick all
-read the same fold, which is what keeps "the reserver and the painter read one
-function" true by construction rather than by prose.
+so a display states its band order exactly once. Reserve, paint and pick all
+call this function, so the reserved and painted positions cannot disagree.
 
-Only the fold is shared. What varies per display stays there: per-lane iteration
-runs this once per lane, sticky-vs-scrolling is a property of how the result is
+Only the fold is shared; the rest stays in each display. Per-lane iteration runs
+this once per lane, sticky-vs-scrolling is a property of how the result is
 projected to the screen, and a band drawn outside its reservation (an overlay)
 carries its own draw rect beside the stack.
 
@@ -745,48 +1762,211 @@ carries its own draw rect beside the stack.
 
 `n` evenly spaced legend stops read straight out of a buildColorRampLut byte
 table — the same 256×1 RGBA array `uploadColorRampLut` hands the GPU and the
-Canvas2D fillStyle LUTs index — formatted for `SvgGradientLegend`. It holds one
+Canvas2D fillStyle LUTs index — as the stops of a `RampScale`. It holds one
 claim by construction: the swatch at bar fraction `t` is byte-identical to the
-ramp entry at `t` on both backends. Alpha rides `opacity` (the juicebox fade),
-never baked into the color string.
+ramp entry both backends read at `t`, through the ramp's middle stop at
+`midNorm` (`rampMidT`). Alpha rides `opacity` (the juicebox fade), never baked
+into the color string.
 
 ```js
 // type signature
-(lut: Uint8Array<ArrayBufferLike>, n: number) => GradientStop[]
+(lut: Uint8Array<ArrayBufferLike>, n: number, midNorm?: number) => RampStop[]
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
-### TrackConfigWithPromotables
-
-A track config snapshot with every display's `promotable` slots resolved, plus
-the list of values that came from a session-wide default rather than from the
-config itself.
-
-For handing a track's config to somewhere that leaves the cascade for good — the
-About dialog's "Copy config", whose output a user pastes into a `config.json`. A
-raw `getSnapshot` records a slot a track merely _follows_ as absent
-(`stripDefault` collapsed it), so the copied config renders differently from the
-track it was copied from. This is `getComputedStyle` at that boundary, and
-`fromDisplayTypeDefaults` is what lets the UI say so rather than silently
-materializing a session preference into a track config.
-
-Resolves from the display _config_ alone, whether or not the track is open.
-Everything the cascade takes is on the config node: it is the same node an open
-display's `configuration` points at (the hydration cache makes it stable), its
-`type` is the display type the session-wide tier is keyed on (every display
-schema is `explicitlyTyped` under the display type's own name), and the session
-is passed in. So an unopened track — which has no display state at all — still
-has an answer to "what would this render as", by the same code path.
-
-**Writes every promotable slot, including the ones sitting at `promotedBase`,
-and that is the decision — don't "align" it with the share bake.** A pasted
-`config.json` is read by a mechanism with no cascade in it at all, so writing
-only the inherited values would leave every other slot to pick up whatever the
-reader has promoted in their own browser. Pinned by
-`products/jbrowse-web/src/tests/CopyConfigPromotedDefaults.test.ts`.
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+### STRAND_FIELD
+
+```js
+// type signature
+'strand'
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### SV_MIN_LENGTH
+
+The conventional size floor for calling a sequence indel structural.
+
+```js
+// type signature
+50
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
+### SV_TYPE_FIELD
+
+The structural-variant class `svClassOf` names. A VCF record and a BEDPE row
+carry it, and the mark display's `mate` step writes it per allele.
+
+```js
+// type signature
+'svType'
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### svClassOf
+
+The structural-variant class of a VCF record as a whole: the one class its
+alleles state, CNV where they are losses and gains of one segment, OTHER where
+they otherwise disagree, and `''` for a record with no structural allele.
+
+```js
+// type signature
+(feature: Feature) => string
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
+### svClassOfAlt
+
+The structural-variant class one ALT allele states, `''` for one that is not
+structural. A symbolic allele's own id wins. Otherwise VCF 4.4's `EVENTTYPE`
+does; then a breakend is the class its `SVTYPE` declares where that says more
+than BND, and a sequence allele is an insertion or deletion by its length
+against REF, else its `SVTYPE`'s class.
+
+```js
+// type signature
+(alt: string, { ref, info, alleleIndex, }?: { ref?: string | undefined; info?: Record<string, unknown> | undefined; alleleIndex?: number | undefined; }) => string
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
+### svClassOfToken
+
+The class a symbolic allele id, `SVTYPE` or `EVENTTYPE` names. A subtype folds
+into its first level (`DEL:ME:ALU` is DEL, `DUP:TANDEM` DUP), except the tandem
+repeats VCF 4.4 spells `CNV:TR` and ExpansionHunter `STRn`, and the inverted
+duplication `INV:DUP`. 1000 Genomes' `CNn` counts one haplotype's copies, so
+none is a deletion and two or more a duplication. `''` for an empty or missing
+token.
+
+```js
+// type signature
+(raw: string) => string
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
+
+### TextColumn
+
+Text held as bytes, one per character: row `i`'s is `length[i]` bytes of `bytes`
+from `offset[i]`, so many rows share one buffer, as an adapter's arena holds
+them.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### thresholdCuts
+
+A threshold scale's cut points as thresholdIndex walks them: the numbers the
+domain names, ascending. Cuts written high to low, as p-value thresholds often
+are, left the middle interval unreachable, the walk stopping at the first cut a
+value is under.
+
+```js
+// type signature
+(domain: readonly (string | number)[]) => number[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### thresholdField
+
+A threshold scale read the way every categorical channel reads its field: a
+value files under the label of the bin it falls in, a feature with no value
+under `''`, and text that is no number under NOT_A_NUMBER_LABEL. The bins are
+the whole domain, so a key lists each one. `labels` names the bins in a key, one
+each from the lowest, where a config spells them for a reader; a bin's key stays
+its interval.
+
+```js
+// type signature
+(field: string, {…}?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; labels?: readonly string[] | undefined; }) => CategoricalField
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### thresholdIndex
+
+The bin a value falls in: how many of the ascending cut points it is at or past,
+so a palette with one more entry than the domain paints it as
+`palette[thresholdIndex(value, domain)]`. A value that is not a number is in no
+bin and answers -1; an infinite one takes the end bin on its side, as d3's
+threshold scale places it, so a `-log10` of a zero p-value lands in the top bin.
+
+```js
+// type signature
+(value: unknown, domain: readonly number[]) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### thresholdKeyEntries
+
+A threshold key's rows: every interval, painted or not, since the bins are the
+whole domain, then the not-a-number and no-value rows where a feature took one,
+in the order `thresholdField` sorts them.
+
+```js
+// type signature
+(cuts: readonly number[], range: readonly string[] | undefined, met: {…}, names?: readonly string[]) => {…}[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### thresholdLabels
+
+What a threshold scale's bins are called in a key, one label per palette entry:
+`< a` below the first cut, `a – b` between two, `≥ b` past the last.
+
+```js
+// type signature
+(domain: readonly number[]) => string[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### thresholdPalette
+
+The colour of each interval, in order: the declared palette, and the default
+categorical palette where it runs out.
+
+```js
+// type signature
+(bins: number, palette?: readonly string[]) => string[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
+
+### ThresholdRef
+
+A numeric field cut into intervals: `domain` is the ascending cut points and
+`range` holds one colour more, so a value paints the entry for the number of cut
+points it is at or past. A value that is not a number belongs to no interval.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### TransformStep
+
+One step over the features before a layer is encoded, named by `type` the way
+GenomeSpy spells a transform; every step runs in order and the next reads what
+the last answered.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### valueAt
+
+A column's value at a row, whatever its kind: for a loop that reads few rows.
+
+```js
+// type signature
+(column: Column, i: number) => unknown
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
 
 ### VIRIDIS_STOPS
 
@@ -800,4 +1980,35 @@ readonly ColorRampStop[]
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
+### withColumns
+
+The table's rows with `written` beside them, in the order `rows` names where it
+names one.
+
+```js
+// type signature
+(table: FeatureTable, written: ReadonlyMap<string, Column>, rows?: Uint32Array<ArrayBufferLike> | undefined) => FeatureTable
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
+
+### withHitIndex
+
+HitIndexed over what the worker shipped.
+
+```js
+// type signature
+<T extends EncodedChannels>(channels: T) => HitIndexed<T>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### ZoomRange
+
+The bp/px interval, `[minBpPerPx, maxBpPerPx)`, over which an adapter with zoom
+levels answers a fetch from the same level it answered `opts.bpPerPx` from. A
+display holding the answer refetches when the view leaves it.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/zoomRange.ts)
+
 <!-- API_DOCS_END -->