@jbrowse/core 5.0.0-beta.7 → 5.0.0-beta.9

package/README.md

@@ -41,6 +41,18 @@ entry.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.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)
+
 ### Band
 
 One band of a display's vertical stack — a coverage histogram, an arc strip, a
@@ -93,9 +105,15 @@ 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.
 
+`mid` is where the stop list's own midpoint lands in the table, so a diverging
+ramp whose middle colour belongs at a value off the centre of the domain is
+baked into the bytes. Every reader — the shader, the Canvas2D fillStyle table,
+the legend bar — then samples one evenly spaced table and cannot disagree about
+the warp.
+
 ```js
 // type signature
-(stops: readonly ColorRampStop[]) => Uint8Array<ArrayBuffer>
+(stops: readonly ColorRampStop[], mid?: number) => Uint8Array<ArrayBuffer>
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
@@ -103,33 +121,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
@@ -138,15 +152,35 @@ 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
+
+```js
+// type signature
+(field: string, { domain, range, }?: { domain?: readonly string[] | undefined; range?: 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 palette entry for `color`, a glyph name for `glyph`. With a
-`domain`, the listed values take the range in that order and whatever else the
-region meets follows, sorted; without one each 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, and `domain` is the way to spend the range deliberately.
+channel's `range` — a colour for `color`, a glyph name for `glyph`. 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)
 
@@ -185,13 +219,24 @@ lands before React re-renders.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandHeight.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.
+
+```js
+// type signature
+readonly['viridis']
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorSchemes.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 two object forms bind a
-field to a scale, which is what a legend can describe. A continuous scale reads
-the field through `domain` (the region's own extremes when absent) into `ramp`,
-and there a listed `domain` is what pins the answer across a whole view.
+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)
 
@@ -208,6 +253,19 @@ unscaled arm of ColorEncoding, on its own for a display that carries a plain
 
 [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, }: { range?: readonly string[] | undefined; scheme?: "viridis" | undefined; reverse?: boolean | undefined; }) => 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
@@ -216,6 +274,38 @@ 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)
+
+### 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)
+
+### 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
@@ -285,11 +375,64 @@ transferables.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
+### FacetedLayer
+
+One layer of a faceted request: its features 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 features split on `field`'s key, each layer's
+own steps 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 features come back in section order beside their
+stacked rows, so a faceted display is the unfaceted one drawn once per section,
+and a feature is handed on as its steps left it.
+
+```js
+// type signature
+(features: readonly Feature[], field: string, layers: readonly {…}[], jexl?: JexlInstance | undefined) => { ...; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
+
+### FacetSection
+
+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 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)
+
+### 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
+(ref: string, jexl: JexlInstance | undefined) => (feature: Feature) => unknown
+```
+
+[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, three orders of magnitude slower per feature.
+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)
 
@@ -347,7 +490,7 @@ track stores.
 
 ```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)
@@ -506,40 +649,62 @@ field took.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.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
+(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/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 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 in admin/embedded sessions a track
-opened later resolves to that same node. A non-admin's open track does not: it
-resolves to the session's private working copy (ADR-032) and this is the
-pristine mirror beside it. The two agree in content, which is what the caller
-needs; `CopyConfigEntryPoints.test.ts` pins both halves.
+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)
 
+### 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)
+
 ### LaneName
 
 The lanes a caller asks the encoder to fill, beyond `x`, `x2` and
@@ -571,40 +736,119 @@ lanes the display's shape reads.
 
 ### MarkEncoding
 
-The declared mapping from a feature's fields to a mark's channels. `x` defaults
-to `start` and `x2` to `end`; a mark that plots no value leaves `y` off. `glyph`
-is read by the `point` shape alone, `row` — an integer field, 0 where missing —
-by the `span` shape, which stacks a feature on the band it names.
+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. `glyph` is read by the `point` shape
+alone, `row` — an integer field, 0 where missing — by every shape, 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. The declared form is what crosses
-the wire; a reader is built in the worker.
+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)
 
 ### NO_VALUE_LABEL
 
-The key row a feature with nothing in a categorical field lands on, so the
-legend says why a mark is grey, or a disc, rather than listing a blank value.
+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/markEncoding.ts)
+[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)
+
+### 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[]
+```
 
-### RampRef
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
 
-The ramp a continuous colour scale samples: a named ramp, or evenly spaced CSS
-colour stops.
+### 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)
+
+### 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]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
+
+### rampOverExtent
+
+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,
+and the table baked again where a `domainMid` places its middle stop by that
+domain. Each region baked its own, so keeping the first region's put the middle
+colour at a value none of them declared.
+
+One table per stop list and middle position, so a display asking again over an
+extent that has not moved gets the bytes it already uploaded: a backend
+re-uploads a ramp on identity.
+
+```js
+// type signature
+(table: {…}, extent: [...]) => { ...; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
 ### readConfObject
 
 Given a configuration model (an instance of a ConfigurationSchema), read the
@@ -629,25 +873,6 @@ indistinguishable at runtime from the broken spelling.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
 
-### readConfSlot
-
-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.
-
-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`).
-
-```js
-// type signature
-<…>(config: Record<…> | (ModelInstanceTypeProps<…> & {…} & IStateTreeNode<…>), slotPath: string | string[], args?: Record<…>, jexl?: JexlInstance | undefined) => T
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
-
 ### relight
 
 Move a color's OKLCH lightness by `lightnessShift` and scale its chroma, holding
@@ -675,6 +900,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
@@ -747,11 +986,9 @@ Make JBrowse follow the host's light/dark state — the whole of it, in one moun
 </SessionPaletteProvider>
 ```
 
-`mode` is optional. Left out, JBrowse follows `prefers-color-scheme` and
-re-themes when the OS preference changes, through the same session write an
-explicit mode takes — so a host whose dark mode _is_ the OS preference mounts
-this with a session and nothing else. Pass a mode as soon as the host has a
-toggle of its own, since the media query cannot see it.
+`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
@@ -773,8 +1010,16 @@ colors of its own mounts `PaletteProvider` directly instead.
 
 ### 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
@@ -799,7 +1044,7 @@ 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)
@@ -807,12 +1052,11 @@ the declared slot value type doesn't include it.
 ### 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.
 
@@ -823,17 +1067,6 @@ carries its own draw rect beside the stack.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandLayout.ts)
 
-### StackStep
-
-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; `groupby` packs each
-distinct value set on its own rows, each numbered from 0. The answer is the
-input in start order, so a `span` encoding `row` stacks it.
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
-
 ### stopsFromRampLut
 
 `n` evenly spaced legend stops read straight out of a buildColorRampLut byte
@@ -850,40 +1083,96 @@ never baked into the color string.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
-### TransformStep
+### STRAND_FIELD
 
-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.
+```js
+// type signature
+'strand'
+```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.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[]
+```
 
-### ValueEncoding
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
 
-How a mark's `y` channel resolves: a feature field (or `jexl:` expression) read
-on a linear scale over the loaded regions' extremes, or the same field with the
-scale spelled out — `log` to read the domain logarithmically, `domain` to pin
-`[min, max]` instead of autoscaling. The declaration is the one owner: the
-display's axis, its ticks and the shader's placement are all resolved from it.
+### thresholdField
 
-`resolve` is which axis the mark reads. `shared` — the default — folds it into
-the display's one y domain with every other mark. `independent` gives it a
-domain folded from its layers alone and a second axis on the right, so a
-coverage run and the raw features can share a plot; one mark per display may ask
-for it.
+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.
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+```js
+// type signature
+(field: string, { domain, range, }?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; }) => CategoricalField
+```
 
-### valueField
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
 
-The field a `y` declaration reads, whichever of its two forms it is written in.
+### 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 finite number is
+in no bin and answers -1.
 
 ```js
 // type signature
-(y: ValueEncoding) => string
+(value: unknown, domain: readonly number[]) => number
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+[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)
 
 ### VIRIDIS_STOPS
 
@@ -897,4 +1186,12 @@ readonly ColorRampStop[]
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.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 -->