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

package/README.md

@@ -58,6 +58,8 @@ 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
+import { applyConfSettings } from '@jbrowse/core/configuration'
+
 // type signature
 (target: AnyConfigurationModel | { configuration: AnyConfigurationModel; }, settings: Record<string, unknown>) => ConfSettingsReport
 ```
@@ -70,6 +72,8 @@ The `ConfigurationSchemaUnion` an array slot's entries answer to, read off the
 slot's MST type, or undefined for any other slot.
 
 ```js
+import { arraySlotUnion } from '@jbrowse/core/configuration'
+
 // type signature
 (slotType: IAnyType) => ConfigurationSchemaUnionMetadata | undefined
 ```
@@ -81,6 +85,8 @@ slot's MST type, or undefined for any other slot.
 A table over a feature list, or the table itself.
 
 ```js
+import { asTable } from '@jbrowse/core/util/featureTable'
+
 // type signature
 (input: readonly Feature[] | FeatureTable) => FeatureTable
 ```
@@ -106,6 +112,8 @@ this the reader's" compares against: the config.json's, or the one a track the
 session owns was added with; empty in a session that keeps no base.
 
 ```js
+import { baseDisplayConfig } from '@jbrowse/core/util/baseDisplayConfig'
+
 // type signature
 (self: object) => Record<string, unknown>
 ```
@@ -147,6 +155,8 @@ rather than each band re-deriving the reasoning — that is how the two
 this rule and a doc comment claiming to be the whole of it.
 
 ```js
+import { boundBandHeight } from '@jbrowse/core/util/bandHeight'
+
 // type signature
 (n: number, { min, max }?: BandBounds) => number
 ```
@@ -174,6 +184,8 @@ Split out of `parseSvAlt` because a consumer holding an already-parsed
 polarity — the shape that produced 78bb7b84f9.
 
 ```js
+import { breakendKeepsDirections } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (bnd: Breakend) => { mateDirection: number; joinDirection: number; }
 ```
@@ -192,6 +204,8 @@ 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
+import { buildColorRampLut } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 (stops: readonly ColorRampStop[]) => Uint8Array<ArrayBuffer>
 ```
@@ -226,6 +240,8 @@ and a caller reading an untyped `frozen` slot must first check that the value is
 a refName.
 
 ```js
+import { canonicalizeViewRefName } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode, refName: string) => string
 ```
@@ -235,11 +251,15 @@ a refName.
 ### categoricalField
 
 `labels` names the `domain`'s values in a key, one each in order, where a config
-spells them for a reader rather than as the data does.
+spells them for a reader rather than as the data does. `held` deals each key the
+domain does not list a color of its own on first sight (`categoricalScale`); the
+caller keeps it for as long as the colors should hold.
 
 ```js
+import { categoricalField } from '@jbrowse/core/util/categoricalField'
+
 // type signature
-(field: string, {…}?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; labels?: readonly string[] | undefined; }) => CategoricalField
+(field: string, { domain, range, labels, held, }?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; labels?: readonly string[] | undefined; held?: HeldSlots | undefined; }) => CategoricalField
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
@@ -250,14 +270,16 @@ One categorical field as every channel reads it — a facet's sections, a color'
 range entries, a key's rows. `key` files a value, `compare` orders keys (the
 `domain` first, the rest by `compareGroupKeys`, `''` after them), `label` names
 a key in a legend, `sectionLabel` on a chip, and `color` paints it. A key's
-color depends only on the key and the declaration, so every region agrees on it.
+color depends only on the key and the declaration, so every region agrees on it,
+except that a field dealing its colors (`categoricalField`'s `held`) also steps
+a key off the colors of the keys met before it.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
 
 ### 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
+channel's `range` — a color 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
@@ -310,6 +332,8 @@ component computing the target from a rendered height drops every tick that
 lands before React re-renders.
 
 ```js
+import { clampBandHeight } from '@jbrowse/core/util/bandHeight'
+
 // type signature
 (current: number, target: number, bounds?: BandBounds) => number
 ```
@@ -322,6 +346,8 @@ The quantile a clip toggle writes: a scale's declared default where that clips,
 below 1, else DEFAULT_CLIP_QUANTILE.
 
 ```js
+import { clipQuantileOf } from '@jbrowse/core/util/quantileExtent'
+
 // type signature
 (declaredDefault: unknown) => number
 ```
@@ -336,16 +362,21 @@ Codes into a list of labels, one per row.
 
 ### 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.
+The named ramps a continuous color 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; `redgreyblue`
+diverges through a grey middle, which stays visible on a white page where a
+white middle would not, as `identity` paints; `blueyellowred` is ColorBrewer's
+RdYlBu turned round, so low reads cool and high hot through a pale yellow
+middle, as `dnds` paints.
 
 ```js
+import { COLOR_SCHEMES } from '@jbrowse/core/util/colorSchemes'
+
 // type signature
 readonly[
   ('viridis',
@@ -357,7 +388,9 @@ readonly[
   'reds',
   'blues',
   'redblue',
-  'purpleorange')
+  'purpleorange',
+  'redgreyblue',
+  'blueyellowred')
 ]
 ```
 
@@ -365,10 +398,12 @@ readonly[
 
 ### 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.
+The packed color instance `i` of `channels` paints: `color[i]`, or `color`
+itself where the color is a constant and so shipped as one number.
 
 ```js
+import { colorAt } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 (channels: Pick<EncodedChannels, "color">, i: number) => number | undefined
 ```
@@ -377,7 +412,7 @@ itself where the colour is a constant and so shipped as one number.
 
 ### ColorEncoding
 
-How a mark's `color` channel resolves. A CSS colour or a `jexl:` expression
+How a mark's `color` channel resolves. A CSS color 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.
 
@@ -385,11 +420,13 @@ a scale, which a legend can describe, and share the config's member names.
 
 ### colorEvaluator
 
-A CSS colour or `jexl:` colour expression as a per-feature packed ABGR — the
+A CSS color or `jexl:` color 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
+import { colorEvaluator } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 (color: string, jexl: JexlInstance | undefined) => (feature: Feature) => number
 ```
@@ -398,11 +435,13 @@ unscaled arm of ColorEncoding, on its own for a display that carries a plain
 
 ### 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`.
+The stops a continuous color scale samples: `range`'s CSS colors where it lists
+any, else the named `scheme`, viridis while that is unset, turned round under
+`reverse`.
 
 ```js
+import { colorRampStops } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 ({ range, scheme, reverse, }: RampDeclaration) => readonly ColorRampStop[]
 ```
@@ -411,8 +450,8 @@ under `reverse`.
 
 ### 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 scale a color channel was resolved through, as the legend reads it — the
+same table the colors 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)
@@ -438,6 +477,8 @@ A table an adapter answers from the typed arrays it already holds, where
 row's id. A row's hover JSON is every field it holds.
 
 ```js
+import { ColumnTable } from '@jbrowse/core/util/featureTable'
+
 // type signature
 typeof ColumnTable
 ```
@@ -452,10 +493,12 @@ A list entry that is one of several configuration schemas, each keyed by the
 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.
+its key, so a key belonging to another member is named on a load and refused on
+a write rather than dropped; one that is not throws here.
 
 ```js
+import { ConfigurationSchemaUnion } from '@jbrowse/core/configuration'
+
 // type signature
 <const MEMBERS extends Record<string, AnyConfigurationSchemaType>>(name: string, members: MEMBERS) => ConfigurationSchemaUnionType<MEMBERS>
 ```
@@ -464,14 +507,16 @@ one that is not throws here.
 
 ### continuousColorScale
 
-A continuous colour scale over `extent`, the values it met: the domain its
+A continuous color 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.
+where its middle stop sits, and the packed color 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 color whoever paints it.
 
 ```js
+import { continuousColorScale } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 (encoding: ContinuousRef, extent: readonly [number, number]) => { domain: [number, number]; lut: Uint8Array<ArrayBufferLike>; midNorm: number; colorOf: (value: number) => number; }
 ```
@@ -482,8 +527,8 @@ ramp itself read it, so a value takes one colour whoever paints it.
 
 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
+where unset, so pinning both keeps colors consistent across a whole view. The
+ramp is `range`'s CSS colors, 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)
@@ -492,7 +537,9 @@ ramp is `range`'s CSS colours, evenly spaced, where it lists any, else the named
 
 Replace the features with runs of constant depth: how many of them overlap each
 stretch of the region, in a field `as` (`coverage` by default), with the
-stretches nothing overlaps left out.
+stretches nothing overlaps left out. A read counts across its whole span,
+deletions and introns included; gap-aware depth stays the alignments display's
+(ADR-118).
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
@@ -502,20 +549,55 @@ 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
+import { darkAtLowEnd } from '@jbrowse/core/util/colorRamp'
+
 // type signature
-(scheme: "blues" | "cividis" | "fall" | "inferno" | "juicebox" | "magma" | "purpleorange" | "redblue" | "reds" | "viridis") => boolean
+(scheme: "blues" | "blueyellowred" | "cividis" | "fall" | "inferno" | "juicebox" | "magma" | "purpleorange" | "redblue" | "redgreyblue" | "reds" | "viridis") => boolean
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
+### dealKeyColors
+
+Deals `keys` their colors in `field.compare` order, so the colors a set of keys
+first seen together takes do not depend on the order they arrive in. A no-op for
+a field that deals nothing.
+
+```js
+import { dealKeyColors } from '@jbrowse/core/util/categoricalField'
+
+// type signature
+(field: CategoricalField, keys: Iterable<string>) => void
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
+### declaredSnapshot
+
+A snapshot as `type` lifts it, without the keys it does not declare: the config
+half of an entry that carries its owner's keys beside one, as a
+`MultiWiggleAdapter` subadapter carries its row's `name` and `color`.
+
+```js
+import { declaredSnapshot } from '@jbrowse/core/configuration'
+
+// type signature
+(type: IAnyType, snapshot: Record<string, unknown>) => Record<string, unknown>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/snapshotPreprocess.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
+import { DEFAULT_COLOR_SCHEME } from '@jbrowse/core/util/colorSchemes'
+
 // type signature
 ;'blues' |
+  'blueyellowred' |
   'cividis' |
   'fall' |
   'inferno' |
@@ -523,6 +605,7 @@ so a declaration spelling it out and one leaving it unset resolve alike.
   'magma' |
   'purpleorange' |
   'redblue' |
+  'redgreyblue' |
   'reds' |
   'viridis'
 ```
@@ -559,6 +642,8 @@ feature `i` (featureIndexAt). A lane is present when the caller asked for it
 The buffers an EncodedChannels owns, for `rpcResult`'s transfer list.
 
 ```js
+import { encodedChannelTransferables } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 (c: EncodedChannels) => ArrayBufferLike[]
 ```
@@ -590,12 +675,28 @@ its own loop over the admitted rows, a lane straight off a typed column and a
 categorical over a `category` column per label.
 
 ```js
+import { encodeFeatures } from '@jbrowse/core/util/markEncoding'
+
 // 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)
 
+### evaluateForFeature
+
+A config value as `feature` reads it: a `jexl:` callback evaluated against the
+feature, anything else as written.
+
+```js
+import { evaluateForFeature } from '@jbrowse/core/configuration'
+
+// type signature
+(value: unknown, feature: Feature, jexl: JexlInstance) => unknown
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
+
 ### FacetedLayer
 
 One layer of a faceted request: its rows in section order, and the stacked row
@@ -619,8 +720,10 @@ every step runs once over the ordered rows, keeping section order, and one that
 groups rows groups within a section.
 
 ```js
+import { facetLayers } from '@jbrowse/core/util/featureTransforms'
+
 // type signature
-(input: readonly Feature[] | FeatureTable, facet: FacetSpec, layers: readonly {…}[], jexl?: JexlInstance | undefined) => { ...; }
+(input: readonly Feature[] | FeatureTable, facet: FacetSpec, layers: readonly { transform?: readonly TransformStep[] | undefined; row?: string | undefined; }[], jexl?: JexlInstance | undefined) => { layers: FacetedLayer[]; sections: FacetSection[]; }
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
@@ -646,6 +749,8 @@ The input feature instance `i` of `channels` was: `featureIndex[i]`, or `i`
 itself where the encoder skipped none and so shipped no index.
 
 ```js
+import { featureIndexAt } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 (channels: Pick<EncodedChannels, "featureIndex">, i: number) => number
 ```
@@ -660,6 +765,25 @@ the hover.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTable.ts)
 
+### fenceOutliers
+
+Where a value axis's open ends stand below a `domainQuantile` of 1: at the
+`extremes`, unless one would stretch the axis past twice the span the
+quantileExtent ends `quantiles` draw, 0 included where the axis reaches it
+(`zero`); that end stops at the fence. So a plot with no spike shows every value
+and cuts none, and a spike leaves the values under it at least half the axis.
+Quantiles that meet span their own size, as a flat domain widens in
+`getNiceDomain`.
+
+```js
+import { fenceOutliers } from '@jbrowse/core/util/quantileExtent'
+
+// type signature
+({ extremes, quantiles, zero, }: { extremes: readonly [number, number]; quantiles: readonly [number, number]; zero: boolean; }) => [number, number]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/quantileExtent.ts)
+
 ### fieldReader
 
 What a channel reads off a feature: a field by name, a dotted path into a
@@ -668,6 +792,8 @@ record), or a `jexl:` expression over `feature`. A jexl expression that does not
 compile throws here, once, rather than on every feature.
 
 ```js
+import { fieldReader } from '@jbrowse/core/util/fieldReader'
+
 // type signature
 (ref: string, jexl: JexlInstance | undefined) => (feature: Feature) => unknown
 ```
@@ -695,6 +821,8 @@ The least and greatest finite values of `values[0, count)`,
 `[Infinity, -Infinity]` where none is finite.
 
 ```js
+import { finiteExtremes } from '@jbrowse/core/util/quantileExtent'
+
 // type signature
 (values: ArrayLike<number>, count: number) => [number, number]
 ```
@@ -732,6 +860,8 @@ wanted, and because that cost is the finding: the assembly manager is the one
 thing on `AbstractSessionModel` a third-party host cannot simply implement.
 
 ```js
+import { getAssemblyHost } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => AssemblyHost
 ```
@@ -748,6 +878,8 @@ 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
+import { getBreakendMateLocString } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (breakend?: Breakend | undefined) => string | undefined
 ```
@@ -756,19 +888,15 @@ mate must drop both rather than treat `<DEL>` as a refName.
 
 ### getConf
 
-Reads a configuration value from a state model that has a `.configuration`
-member (a track or display state model). For a raw configuration model, use
-`readConfObject` instead.
-
-**This is exactly `readConfObject(model.configuration, path)`** — sugar for the
-`.configuration` hop, and nothing more. The two readers carry the same slot-name
-check, so reaching for the other one does not get a typo past tsc. It does not
-consult the session and has no per-slot behavior; what you read is what the
-track stores.
+Reads a configuration value from a track or display state model: exactly
+`readConfObject(model.configuration, path)`, with the same slot-name check.
 
 ```js
+import { getConf } from '@jbrowse/core/configuration'
+
 // type signature
-{…}
+(model: { configuration: AnyConfigurationModel; }) => AnyConfigurationSnapshot
+<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: { configuration: CONFMODEL; }, slotPath: SLOT, args?: Record<string, unknown>) => SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
@@ -779,6 +907,8 @@ Returns the display model that contains the given node. Throws if the node has
 no containing display.
 
 ```js
+import { getContainingDisplay } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => AbstractDisplayModel
 ```
@@ -791,6 +921,8 @@ Returns the track model that contains the given node. Throws if the node has no
 containing track.
 
 ```js
+import { getContainingTrack } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => AbstractTrackModel
 ```
@@ -803,6 +935,8 @@ Returns the view model that contains the given node. Throws if the node has no
 containing view.
 
 ```js
+import { getContainingView } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => AbstractViewModel
 ```
@@ -814,6 +948,8 @@ containing view.
 Where a display puts a dialog it cannot mount itself.
 
 ```js
+import { getDialogHost } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => DialogHost
 ```
@@ -825,6 +961,8 @@ Where a display puts a dialog it cannot mount itself.
 Returns the MST environment for a node, which carries the `pluginManager`.
 
 ```js
+import { getEnv } from '@jbrowse/core/util'
+
 // type signature
 (obj: IAnyStateTreeNode) => { pluginManager: PluginManager; }
 ```
@@ -836,6 +974,8 @@ Returns the MST environment for a node, which carries the `pluginManager`.
 Where a display puts a message it cannot draw itself.
 
 ```js
+import { getNotificationSink } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => NotificationSink
 ```
@@ -847,6 +987,8 @@ Where a display puts a message it cannot draw itself.
 The colors to draw with, and the args that rebuild them in a worker.
 
 ```js
+import { getPaletteHost } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => PaletteHost
 ```
@@ -859,6 +1001,8 @@ Everything a display needs of its host in order to draw a region: the
 assemblies, the RPC entry point and the colors.
 
 ```js
+import { getRenderingServices } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => RenderingServices
 ```
@@ -870,6 +1014,8 @@ assemblies, the RPC entry point and the colors.
 The host's RPC entry point, for a module that issues RPCs and nothing else.
 
 ```js
+import { getRpcHost } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => RpcHost
 ```
@@ -882,6 +1028,8 @@ Returns the JBrowse session model for any node in the state tree. Throws if the
 node has no session ancestor.
 
 ```js
+import { getSession } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => AbstractSessionModel
 ```
@@ -895,12 +1043,28 @@ Prefer one of the narrower accessors below, which say which of them the calling
 module actually uses.
 
 ```js
+import { getSessionServices } from '@jbrowse/core/util'
+
 // type signature
 (node: IAnyStateTreeNode) => SessionServices
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/sessionServices.ts)
 
+### heldSlotsOf
+
+The `HeldSlots` `owner` keeps under `key`, made empty on first ask. Lives as
+long as `owner` and is never persisted, so a reload deals afresh.
+
+```js
+import { heldSlotsOf } from '@jbrowse/core/util/categoricalField'
+
+// type signature
+(owner: object, key: string) => HeldSlots
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
+
 ### HitIndexed
 
 An encoded payload as a display stores it: the hit index the worker built with
@@ -914,6 +1078,8 @@ 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
+import { hitIndexOf } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 (x: Uint32Array<ArrayBufferLike>, x2: Uint32Array<ArrayBufferLike>, y: Float32Array<ArrayBufferLike> | undefined, count?: number) => Flatbush
 ```
@@ -922,29 +1088,19 @@ at 0 for a mark with no value.
 
 ### hydrateTrackConfig
 
-Hydrate a plain track config into a live config node, dispatching on its `type`
-to find the schema. `session.tracks` holds `types.frozen` plain objects until
-something references a track (ADR-031). One of those holds only what was
-literally authored: a slot at its schema default is absent, `preProcessSnapshot`
-has not run, and nothing that walks a live node applies to it.
+Hydrate a plain track config, such as a `session.tracks` entry, into a live
+config node, dispatching on its `type` to find the schema. A plain entry holds
+only what was authored: a slot at its default is absent and `preProcessSnapshot`
+has not run.
 
-Use it where a caller needs the resolved config and may be handed either form.
-The About dialog's "Copy config" is reached from two menus, and one of them
-passes a `session.tracks` entry.
-
-Returns **undefined** when the config names a track type no plugin registered,
-or when `create` rejects it as invalid. An un-hydrated config has never been
-validated, so the dialog opening over it should not throw. Callers fall back to
-using the plain object.
-
-Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating the
-same entry twice returns the same node, and in an admin session a track opened
-later resolves to that same node. A non-admin's open track resolves to the
-session's private working copy (ADR-032), and this function returns the pristine
-mirror beside it. The two have the same content; `CopyConfigEntryPoints.test.ts`
-tests both cases.
+Returns **undefined** when no plugin registered the type or `create` rejects the
+config, which has never been validated; callers fall back to the plain object.
+Hydrating one entry twice returns one node. A shown track resolves to the
+session's working copy instead (ADR-032), which has the same content.
 
 ```js
+import { hydrateTrackConfig } from '@jbrowse/core/configuration'
+
 // type signature
 (pluginManager: PluginManager, config: Record<string, unknown>) => AnyConfigurationModel | undefined
 ```
@@ -958,6 +1114,8 @@ breakends (`.A` / `G.`), and the symbolic-mate form (`G<DEL>`, an angle bracket
 past position 0; a leading `<` is a plain symbolic allele).
 
 ```js
+import { isBreakend } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (alt: string) => boolean
 ```
@@ -970,6 +1128,8 @@ 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]`.
 
 ```js
+import { isMissing } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (value: unknown) => boolean
 ```
@@ -983,6 +1143,8 @@ 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
+import { isPlainFieldRef } from '@jbrowse/core/util/fieldReader'
+
 // type signature
 (ref: string) => ref is never
 ```
@@ -1006,6 +1168,8 @@ 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
+import { junctionEnds } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (feature: Feature, alt?: string | undefined, alleleIndex?: number | undefined) => { own: JunctionEnd; mate: JunctionEnd; } | undefined
 ```
@@ -1014,12 +1178,14 @@ for the target, so it names no side.
 
 ### keyNames
 
-What a key names each of `keys`, from a colour object's `labels`: one each in
+What a key names each of `keys`, from a color object's `labels`: one each in
 order, an empty or missing entry leaving that key its own name. Every key that
 takes `labels` reads them through this, so a config means one thing by them
 everywhere.
 
 ```js
+import { keyNames } from '@jbrowse/core/util/categoricalField'
+
 // type signature
 (keys: readonly unknown[], labels?: readonly string[]) => ReadonlyMap<string, string>
 ```
@@ -1042,8 +1208,10 @@ hovers declines the index, which is most of the encoder's cost after the walk.
 synchronous `addOrReplaceView` requires it loaded already.
 
 ```js
+import { launchOrReplaceView } from '@jbrowse/core/util'
+
 // type signature
-(args: { session: AbstractViewContainer; typeName: string; initialState?: Record<string, unknown> | undefined; replacing?: AbstractViewModel | undefined; }) => Promise<...>
+(args: { session: AbstractViewContainer; typeName: string; initialState?: Record<string, unknown> | undefined; replacing?: AbstractViewModel | undefined; }) => Promise<AbstractViewModel>
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/mstUtils.ts)
@@ -1064,8 +1232,10 @@ 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
+import { layerTables } from '@jbrowse/core/util/featureTransforms'
+
 // type signature
-(input: readonly Feature[] | FeatureTable, request: {…}, jexl?: JexlInstance | undefined) => { ...; }
+(input: readonly Feature[] | FeatureTable, request: { transform?: readonly TransformStep[] | undefined; facet?: FacetSpec | undefined; layers: readonly { transform?: readonly TransformStep[] | undefined; row?: string | undefined; }[]; }, jexl?: JexlInstance | undefined) => { layers: { table: FeatureTable; row: string | Uint32Array<ArrayBufferLike> | undefined; }[]; sections: FacetSection[] | undefined; }
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
@@ -1080,6 +1250,8 @@ members off it. The draft is copied first, since MST freezes what it creates
 from.
 
 ```js
+import { liftPlot } from '@jbrowse/core/configuration'
+
 // type signature
 (conf: AnyConfigurationModel, draft: Plot) => AnyConfigurationModel
 ```
@@ -1097,7 +1269,7 @@ name, the name of each entry.
 ### 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.
+and `color` are what the adapter names and colors that row with.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/rowSources.ts)
 
@@ -1106,6 +1278,8 @@ and `color` are what the adapter names and colours that row with.
 Whether an adapter implements RowSourceLister.
 
 ```js
+import { listsRowSources } from '@jbrowse/core/data_adapters/BaseAdapter/rowSources'
+
 // type signature
 (adapter: object) => adapter is RowSourceLister
 ```
@@ -1159,6 +1333,8 @@ whether links are the picture a track wants asks here rather than re-reading the
 fields.
 
 ```js
+import { matedBy } from '@jbrowse/core/util/featureTransforms'
+
 // type signature
 (f: Feature) => "alt" | "mate" | "pair" | undefined
 ```
@@ -1180,11 +1356,13 @@ ends answer once.
 
 ### MISCONFIGURED_ABGR
 
-The misconfiguration grey packed as the encoder paints it: a `jexl:` colour that
+The misconfiguration grey packed as the encoder paints it: a `jexl:` color that
 answered no string, a ramp value that is no number, text a threshold cannot
 read.
 
 ```js
+import { MISCONFIGURED_ABGR } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 number
 ```
@@ -1197,6 +1375,8 @@ The no-value grey packed as the encoder paints it: a feature with nothing in the
 field a threshold reads.
 
 ```js
+import { NO_VALUE_ABGR } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 number
 ```
@@ -1209,8 +1389,10 @@ 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
+import { NO_VALUE_LABEL } from '@jbrowse/core/util/markEncoding'
+
 // type signature
-'(no value)'
+;('(no value)')
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
@@ -1221,8 +1403,10 @@ 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
+import { NOT_A_NUMBER_LABEL } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
-'(not a number)'
+;('(not a number)')
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
@@ -1239,6 +1423,8 @@ readerOf as the number a quantitative channel or step reads, `NaN` where a row
 holds none, by `numericValue`'s rules.
 
 ```js
+import { numberReaderOf } from '@jbrowse/core/util/featureTable'
+
 // type signature
 (column: Column) => (i: number) => number
 ```
@@ -1252,6 +1438,8 @@ back as the numbers it names. A member that is not a number reads NaN, which
 every comparison against it declines.
 
 ```js
+import { numericDomain } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (domain: readonly (string | number)[]) => number[]
 ```
@@ -1264,6 +1452,8 @@ The text as a plot, refusing a key the display's plot does not hold. The schema
 is the parser past this point.
 
 ```js
+import { parsePlot } from '@jbrowse/core/configuration'
+
 // type signature
 (text: string, keys: readonly string[]) => Plot
 ```
@@ -1278,12 +1468,38 @@ 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
+import { parseSvAlt } from '@jbrowse/core/util/svAlt'
+
 // type signature
-(feature: Feature, alt?: string | undefined, alleleIndex?: number) => {…} | undefined
+(feature: Feature, alt?: string | undefined, alleleIndex?: number) => { mateRefName: string; matePos: number; mateDirection?: number | undefined; joinDirection?: number | undefined; } | undefined
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/svAlt.ts)
 
+### pathSeries
+
+A path layer's table in series order, as PathSpec defines a series, with each
+row's series beside it and the stretch past which a series breaks. `steps` are
+every step the layer's rows went through, which a `window` among them reads the
+default break from.
+
+```js
+// type signature
+(table: FeatureTable, row: RowEncoding, path: PathSpec, steps: readonly TransformStep[], jexl?: JexlInstance | undefined) => { table: FeatureTable; row: RowEncoding; series: Uint32Array<ArrayBuffer>; gapBp: number | undefined; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/pathSeries.ts)
+
+### PathSpec
+
+A path's series, as Vega-Lite draws a line: one per row and, within a row, one
+per distinct value of `by`, a categorical color's field, each in start order.
+`gapBp` breaks a series where the next instance's middle lies further on than
+that; absent, a `window` step among the layer's steps sets it to the bases a
+frame spans at the median row, and with none a series is one run.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### PileupStep
 
 Assign every feature the lowest row on which it overlaps nothing already there —
@@ -1310,6 +1526,8 @@ and what each holds: what "Edit plot..." shows and an agent reads as a display's
 `plot`. A display's plot is the ones its config declares (`plotKeysOf`).
 
 ```js
+import { PLOT_VOCABULARY } from '@jbrowse/core/configuration'
+
 // type signature
 Readonly<Record<string, string>>
 ```
@@ -1328,6 +1546,8 @@ what it does.
 The plot keys a display config declares.
 
 ```js
+import { plotKeysOf } from '@jbrowse/core/configuration'
+
 // type signature
 (conf: AnyConfigurationModel) => string[]
 ```
@@ -1341,6 +1561,8 @@ shares with no other display, a default plot's marks, shows its entries, since
 they are what is drawn.
 
 ```js
+import { plotOf } from '@jbrowse/core/configuration'
+
 // type signature
 (conf: AnyConfigurationModel) => Plot
 ```
@@ -1355,6 +1577,8 @@ way but lifting to the same setting writes nothing. Throws a refusal before
 anything is written.
 
 ```js
+import { plotWrites } from '@jbrowse/core/configuration'
+
 // type signature
 (conf: AnyConfigurationModel, draft: Plot) => Record<string, unknown>
 ```
@@ -1363,11 +1587,13 @@ anything is written.
 
 ### 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.
+A snapshot as a write to `type` admits it: the lift and checks `setConf`
+applies, so a dialog or a validator refuses what an edit cannot hold, an
+undeclared key included. Throws what the schema's `preProcessSnapshot` throws.
 
 ```js
+import { preProcessConfigSnapshot } from '@jbrowse/core/configuration'
+
 // type signature
 (type: IAnyType, snapshot: unknown) => Record<string, unknown>
 ```
@@ -1381,10 +1607,17 @@ What the open ends of a scale follow over `values[0, count)`: at a `quantile` of
 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.
+`scales.y.domainQuantile` and a color's `domainQuantile` both name it.
 `[Infinity, -Infinity]` where nothing is finite.
 
+Nearest rank keeps ties: where one value holds the rank, as on a segmented
+copy-number track, a ramp clipped below 1 paints nearly every value one color. A
+value axis fences instead (fenceOutliers); a ramp takes the same fence once a
+color default below 1 meets tied data.
+
 ```js
+import { quantileExtent } from '@jbrowse/core/util/quantileExtent'
+
 // type signature
 (values: ArrayLike<number>, count: number, quantile?: number) => [number, number]
 ```
@@ -1398,6 +1631,8 @@ of them sit at or below, so a handful of values clips at their maximum. Permutes
 `a`; 0 where `n` is.
 
 ```js
+import { quantileOf } from '@jbrowse/core/util/quantileExtent'
+
 // type signature
 (a: Float32Array<ArrayBufferLike>, n: number, quantile: number) => number
 ```
@@ -1406,18 +1641,20 @@ of them sit at or below, so a handful of values clips at their maximum. Permutes
 
 ### RampDeclaration
 
-A continuous colour scale's ramp as a config declares it.
+A continuous color scale's ramp as a config declares it.
 
 [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 domain a continuous color 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
+import { rampDomain } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 (min: number | undefined, max: number | undefined, extent: readonly [number, number]) => [number, number]
 ```
@@ -1431,6 +1668,8 @@ not-a-number and no-value rows a threshold's key ends with. Empty while neither
 painted.
 
 ```js
+import { rampGapScales } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (id: string, met: { missing?: boolean | undefined; notNumber?: boolean | undefined; }) => CategoricalScale[]
 ```
@@ -1444,6 +1683,8 @@ 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.
 
 ```js
+import { rampLutOf } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 (ramp: RampDeclaration) => Uint8Array<ArrayBufferLike>
 ```
@@ -1458,32 +1699,30 @@ The table stays straight and `domainMid` a value, so the middle stop follows the
 widened domain with no table baked again.
 
 ```js
+import { rampOverExtent } from '@jbrowse/core/util/markEncoding'
+
 // type signature
-(table: {…}, extent: [...]) => { ...; }
+(table: {…}, extent: [number, number]) => { kind: "ramp"; field: string; scale: "linear" | "log"; domain: [number, number]; pinned: [boolean, boolean]; domainMid?: number | undefined; range?: string[] | undefined; scheme?: "blues" | "blueyellowred" | "cividis" | "fall" | "inferno" | "juicebox" | "magma" | "purpleorange" | "redblue" | "redgreyblue" | "reds" | "viridis" | undefined; reverse?: boolean | undefined; extent: [number, number]; quantile?: number | undefined; lut: Uint8Array<…>; missing?: boolean | undefined; notNumber?: boolean | undefined; }
 ```
 
 [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
-configuration value at the given path. Use this when you hold the configuration
-model directly, e.g. an entry from `session.tracks`.
-
-Wants a **live config node**, not a snapshot of one, and passing a snapshot is a
-type error. Slots are built with `types.stripDefault`, so a slot sitting at its
-default is absent from a snapshot — "unset" and "at its default" are
-indistinguishable there, and a read off one reports a default as missing.
+Read the value at a path of a live config node, such as a track's
+`configuration`, evaluating a `jexl:` callback with `args`.
 
-That is enforced in the types only, deliberately: it can't be a runtime check.
-`generateHierarchy` reads slots straight off the **un-hydrated frozen** entries
-of `jbrowse.tracks` on purpose, because hydrating every track to answer the
-track selector is what `types.frozen` exists to avoid — and those reads are
-indistinguishable at runtime from the broken spelling.
+A snapshot is refused by the types, since a slot at its default is absent from
+one. A `session.tracks` entry is one (`TrackConfigEntry`): read its `trackId`
+and `type` directly, and a slot through a helper that supplies the default, such
+as `getConfAssemblyNamesOrNone`.
 
 ```js
+import { readConfObject } from '@jbrowse/core/configuration'
+
 // type signature
-{…}
+(confObject: AnyConfigurationModel) => AnyConfigurationSnapshot
+<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>) => SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/readConfObject.ts)
@@ -1494,6 +1733,8 @@ 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.
 
 ```js
+import { readerOf } from '@jbrowse/core/util/featureTable'
+
 // type signature
 (column: Column) => (i: number) => unknown
 ```
@@ -1512,12 +1753,30 @@ other adapter keys on its config alone: a synteny adapter is fetched from each
 of its assemblies and reads no reference.
 
 ```js
+import { READS_REFERENCE } from '@jbrowse/core/data_adapters/dataAdapterCache'
+
 // type signature
-'readsReference'
+;('readsReference')
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/dataAdapterCache.ts)
 
+### refusingUndeclaredKeys
+
+Runs `write` as a write: a `closed` schema created inside it refuses a key it
+does not declare, at any depth, where a config loading only names the key on the
+console. `setConf`, a settings bag and a plot draft write this way, so a typo in
+an edit is an error and a config written for another version still draws.
+
+```js
+import { refusingUndeclaredKeys } from '@jbrowse/core/configuration'
+
+// type signature
+<T>(write: () => T) => T
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/snapshotPreprocess.ts)
+
 ### relight
 
 Move a color's OKLCH lightness by `lightnessShift` and scale its chroma, holding
@@ -1539,6 +1798,8 @@ same coefficient moves a yellow and a blue by visibly different amounts: a lap
 has to read as one tone across the whole palette or it reads as noise.
 
 ```js
+import { relight } from '@jbrowse/core/util/color'
+
 // type signature
 (color: string, lightnessShift: number, chromaScale?: number) => string
 ```
@@ -1553,6 +1814,8 @@ 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
+import { requirementProblems } from '@jbrowse/core/configuration'
+
 // type signature
 (type: IAnyType, snapshot: Record<string, unknown>) => RequirementProblem[]
 ```
@@ -1565,6 +1828,8 @@ The pixels a band takes from the plot below it: 0 when off, the (optionally
 bound) stated height when on. This is the single spelling of "off spends 0 px".
 
 ```js
+import { reservedPx } from '@jbrowse/core/util/bandLayout'
+
 // type signature
 (band: Band) => number
 ```
@@ -1581,7 +1846,7 @@ files, a MAF its species.
 ### 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.
+a row display gives a row with nothing in view its place, label and color.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/data_adapters/BaseAdapter/rowSources.ts)
 
@@ -1597,6 +1862,8 @@ 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
+import { runLazyAfterAttach } from '@jbrowse/core/util/lazyAfterAttach'
+
 // type signature
 <Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>) => void
 ```
@@ -1610,6 +1877,8 @@ The table a step answers is what the next one reads, and the last one is what
 the encoder walks.
 
 ```js
+import { runTransforms } from '@jbrowse/core/util/featureTransforms'
+
 // type signature
 (input: readonly Feature[] | FeatureTable, steps: readonly TransformStep[], jexl?: JexlInstance | undefined) => FeatureTable
 ```
@@ -1622,6 +1891,8 @@ parseBreakend, honoring its `Breakend | undefined` signature. ALT strings are
 user data and malformed breakends do occur;
 
 ```js
+import { safeParseBreakend } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (alt: string) => Breakend | undefined
 ```
@@ -1635,6 +1906,8 @@ interpolated per channel. `t` is clamped, so the ends are the end stops rather
 than an extrapolation past them, and a one-stop ramp is that stop everywhere.
 
 ```js
+import { sampleColorRamp } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 (stops: readonly ColorRampStop[], t: number) => ColorRampStop
 ```
@@ -1651,6 +1924,8 @@ clampBandHeight rule). Whole pixels, rounded by largest remainder, so the stack
 moves by exactly the rounded distance.
 
 ```js
+import { scaleBandHeights } from '@jbrowse/core/util/bandHeight'
+
 // type signature
 (heights: number[], distance: number, floor?: number) => number[]
 ```
@@ -1665,6 +1940,8 @@ met there would floor the domain at 1 and fold a domain below 1 flat.
 `[Infinity, -Infinity]` where the scale reads nothing.
 
 ```js
+import { scaleExtent } from '@jbrowse/core/util/quantileExtent'
+
 // type signature
 (values: ArrayLike<number>, count: number, scale: string, quantile?: number) => [number, number]
 ```
@@ -1673,7 +1950,7 @@ met there would floor the domain at 1 and fold a domain below 1 flat.
 
 ### ScaleTable
 
-The table behind a channel a key is drawn from: a colour's, whose `kind` names
+The table behind a channel a key is drawn from: a color's, whose `kind` names
 the scale it resolved through, or a shape's. A `size` channel's (SizeScaleTable)
 draws no key and stands outside.
 
@@ -1689,8 +1966,10 @@ and the worker answers the entry of `layer`'s list that the instance's
 steps made. A second click aborts the first.
 
 ```js
+import { selectEncodedFeature } from '@jbrowse/core/util/selectEncodedFeature'
+
 // type signature
-(self: IStateTreeNode<IAnyType>, rotation: { begin(): ActiveFetch; cancel: () => void; dispose(): void; }, args: Omit<CoreGetEncodedLayersArgs, "byteLimit"> & { ...; }) => void
+(self: IStateTreeNode<IAnyType>, rotation: { begin(): ActiveFetch; cancel: () => void; dispose(): void; }, args: Omit<CoreGetEncodedLayersArgs, "byteLimit"> & { layer: number; featureIndex: number; }) => void
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/selectEncodedFeature.ts)
@@ -1703,6 +1982,8 @@ a sort of 4.5M counts measured ~1s. Median-of-three because Hi-C contacts arrive
 nearly sorted.
 
 ```js
+import { selectNth } from '@jbrowse/core/util/quantileExtent'
+
 // type signature
 (a: Float32Array<ArrayBufferLike>, n: number, k: number) => number
 ```
@@ -1716,6 +1997,8 @@ 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
+import { selectRows } from '@jbrowse/core/util/featureTable'
+
 // type signature
 (table: FeatureTable, rows: Uint32Array<ArrayBufferLike>) => FeatureTable
 ```
@@ -1734,7 +2017,8 @@ Make JBrowse follow the host's light/dark state — the whole of it, in one moun
 
 `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.
+session and nothing else. A page that declares `light dark` follows the OS, and
+a page that declares nothing stays light.
 
 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
@@ -1748,6 +2032,8 @@ The session is the only thing that resolves a palette here, so a host supplying
 colors of its own mounts `PaletteProvider` directly instead.
 
 ```js
+import { SessionPaletteProvider } from '@jbrowse/core/ui/PaletteContext'
+
 // type signature
 ({ session, mode, children, }: { session: ThemeModeSession; mode?: "dark" | "light" | undefined; children: ReactNode; }) => Element
 ```
@@ -1761,36 +2047,17 @@ array naming a sub-schema's member at any depth —
 `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
 model, or a config node directly.
 
-**The path length says what the write replaces.** A path ending on a slot writes
-that slot and leaves the object around it alone; a path ending on a sub-schema
-replaces the whole object, which is how a channel whose members move together —
-a facet's field and the domain that field's values order — gets written without
-a stale member surviving underneath.
-
-**Prefer this over a bare `self.configuration.setSlot('x', v)`.** The constraint
-here mirrors `getConf`'s, so on a model with a concrete schema an unknown slot
-name is a compile error. `setSlot` itself stays untyped on purpose — the config
-editor's slot facade routes dynamic slot names through it
-(`configurationSchema.ts`) — and guards the name at runtime instead (ADR-052),
-so a misspelled write is diagnosed one way or the other.
-
-**The read is the half with no diagnostic at all.** `getConf` for a name the
-schema doesn't declare returns `undefined` and reports nothing, at any layer, so
-the slot keeps reading as its default forever. Which makes the compile-time
-constraint worth keeping _reachable_: it is only as good as the schema of the
-holder handed in, and a holder widened to `AnyConfigurationModel` switches it
-off entirely — the trap a mixin casting to reach its host walks into. Every such
-cast names a concrete schema instead (`ConfigModelForFields`, or the base schema
-when the slot is the base's), and `HostChecksSlotNames` pins each one.
-
-A wrong _value_ type still throws at runtime (MST type-checks the assignment)
-rather than at compile time. `value` is deliberately `unknown` because
-`undefined` is a legitimate write — it resets a slot to its schema default — and
-the declared slot value type doesn't include it.
+A path ending on a slot writes that slot; one ending on a sub-schema replaces
+the whole object, so a channel's members (a facet's field and its domain) move
+together. On a concrete schema an unknown slot name is a compile error, and
+`setSlot` refuses one at runtime (ADR-052). A wrong value type throws at
+runtime; `null` or `undefined` resets the slot to its default (ADR-146).
 
 ```js
+import { setConf } from '@jbrowse/core/configuration'
+
 // type signature
-<…>(target: CONFMODEL | { ...; }, slotPath: SLOT, value: unknown) => void
+<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(target: CONFMODEL | { configuration: CONFMODEL; }, slotPath: SLOT, value: unknown) => void
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
@@ -1800,6 +2067,8 @@ the declared slot value type doesn't include it.
 The `point` mark's painter code for each shape an encoding can name.
 
 ```js
+import { SHAPE_CODES } from '@jbrowse/core/util/shapeNames'
+
 // type signature
 Record<ShapeName, number>
 ```
@@ -1834,7 +2103,7 @@ binds the field to a scale.
 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
+extremes where unset, as a color 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)
@@ -1860,6 +2129,8 @@ projected to the screen, and a band drawn outside its reservation (an overlay)
 carries its own draw rect beside the stack.
 
 ```js
+import { stackBands } from '@jbrowse/core/util/bandLayout'
+
 // type signature
 <K extends string>(order: readonly K[], bands: Record<K, Band>) => BandStack<K>
 ```
@@ -1877,6 +2148,8 @@ ramp entry both backends read at `t`, through the ramp's middle stop at
 into the color string.
 
 ```js
+import { stopsFromRampLut } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 (lut: Uint8Array<ArrayBufferLike>, n: number, midNorm?: number) => RampStop[]
 ```
@@ -1886,8 +2159,10 @@ into the color string.
 ### STRAND_FIELD
 
 ```js
+import { STRAND_FIELD } from '@jbrowse/core/util/categoricalField'
+
 // type signature
-'strand'
+;('strand')
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
@@ -1897,6 +2172,8 @@ into the color string.
 The conventional size floor for calling a sequence indel structural.
 
 ```js
+import { SV_MIN_LENGTH } from '@jbrowse/core/util/svAlt'
+
 // type signature
 50
 ```
@@ -1909,8 +2186,10 @@ 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
+import { SV_TYPE_FIELD } from '@jbrowse/core/util/categoricalField'
+
 // type signature
-'svType'
+;('svType')
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/categoricalField.ts)
@@ -1922,6 +2201,8 @@ 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
+import { svClassOf } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (feature: Feature) => string
 ```
@@ -1937,6 +2218,8 @@ than BND, and a sequence allele is an insertion or deletion by its length
 against REF, else its `SVTYPE`'s class.
 
 ```js
+import { svClassOfAlt } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (alt: string, { ref, info, alleleIndex, }?: { ref?: string | undefined; info?: Record<string, unknown> | undefined; alleleIndex?: number | undefined; }) => string
 ```
@@ -1953,6 +2236,8 @@ none is a deletion and two or more a duplication. `''` for an empty or missing
 token.
 
 ```js
+import { svClassOfToken } from '@jbrowse/core/util/svAlt'
+
 // type signature
 (raw: string) => string
 ```
@@ -1975,6 +2260,8 @@ are, left the middle interval unreachable, the walk stopping at the first cut a
 value is under.
 
 ```js
+import { thresholdCuts } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (domain: readonly (string | number)[]) => number[]
 ```
@@ -1991,8 +2278,10 @@ each from the lowest, where a config spells them for a reader; a bin's key stays
 its interval.
 
 ```js
+import { thresholdField } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
-(field: string, {…}?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; labels?: readonly string[] | undefined; }) => CategoricalField
+(field: string, { domain, range, labels: names, }?: { 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)
@@ -2006,6 +2295,8 @@ 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
+import { thresholdIndex } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (value: unknown, domain: readonly number[]) => number
 ```
@@ -2019,8 +2310,10 @@ whole domain, then the not-a-number and no-value rows where a feature took one,
 in the order `thresholdField` sorts them.
 
 ```js
+import { thresholdKeyEntries } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
-(cuts: readonly number[], range: readonly string[] | undefined, met: {…}, names?: readonly string[]) => {…}[]
+(cuts: readonly number[], range: readonly string[] | undefined, met: { missing?: boolean | undefined; notNumber?: boolean | undefined; }, names?: readonly string[]) => { value: string; label: string; color: string; missing?: true | undefined; }[]
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/thresholdScale.ts)
@@ -2031,6 +2324,8 @@ 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
+import { thresholdLabels } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (domain: readonly number[]) => string[]
 ```
@@ -2039,10 +2334,12 @@ What a threshold scale's bins are called in a key, one label per palette entry:
 
 ### thresholdPalette
 
-The colour of each interval, in order: the declared palette, and the default
+The color of each interval, in order: the declared palette, and the default
 categorical palette where it runs out.
 
 ```js
+import { thresholdPalette } from '@jbrowse/core/util/thresholdScale'
+
 // type signature
 (bins: number, palette?: readonly string[]) => string[]
 ```
@@ -2052,7 +2349,7 @@ categorical palette where it runs out.
 ### 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
+`range` holds one color 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)
@@ -2070,6 +2367,8 @@ the last answered.
 A column's value at a row, whatever its kind: for a loop that reads few rows.
 
 ```js
+import { valueAt } from '@jbrowse/core/util/featureTable'
+
 // type signature
 (column: Column, i: number) => unknown
 ```
@@ -2082,18 +2381,35 @@ The 256 viridis stops, fully opaque. Feed them to buildColorRampLut for the
 texture/fillStyle form, or to sampleColorRamp for legend stops.
 
 ```js
+import { VIRIDIS_STOPS } from '@jbrowse/core/util/colorRamp'
+
 // type signature
 readonly ColorRampStop[]
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
+### WindowStep
+
+Every row kept, each written with `ops` summarized over the rows of its group
+around it, Vega-Lite's window transform: a group is a distinct `groupby` value
+set within a section, its rows taken in `start` order, and `frame` counts rows
+before and after the current one, `null` running to the group's end.
+`[-10, 10]`, the default, is a moving average over 21 rows, whatever bases they
+span; `[null, 0]` a running total. A frame cut off at a group's end summarizes
+the rows it has. The rows come out grouped, each group in `start` order, so a
+`line` walks one group at a time.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### withColumns
 
 The table's rows with `written` beside them, in the order `rows` names where it
 names one.
 
 ```js
+import { withColumns } from '@jbrowse/core/util/featureTable'
+
 // type signature
 (table: FeatureTable, written: ReadonlyMap<string, Column>, rows?: Uint32Array<ArrayBufferLike> | undefined) => FeatureTable
 ```
@@ -2105,6 +2421,8 @@ names one.
 HitIndexed over what the worker shipped.
 
 ```js
+import { withHitIndex } from '@jbrowse/core/util/markEncoding'
+
 // type signature
 <T extends EncodedChannels>(channels: T) => HitIndexed<T>
 ```