@jbrowse/core 5.0.0-beta.4 → 5.0.0-beta.8

package/README.md

@@ -25,6 +25,22 @@ Apache-2.0 © Evolutionary Software Foundation
 
 Auto-generated from `#api` JSDoc tags in this package. Do not edit by hand.
 
+### AggregateOp
+
+One summary over a group: `count` needs no field; `sum`, `mean`, `min` and `max`
+read one, skipping values that are not numbers. The output field is `as`, else
+`count` or `<op>_<field>`.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### AggregateStep
+
+One feature per distinct `groupby` value set (one for the whole region with
+none), spanning its members' extent, carrying the group's fields and every `ops`
+entry.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### Band
 
 One band of a display's vertical stack — a coverage histogram, an arc strip, a
@@ -37,6 +53,15 @@ historically drifted.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandLayout.ts)
 
+### BinStep
+
+Snap every feature to the genome-aligned bin of `step` bp its `field` (`start`
+by default) falls in, writing the bin's edges over the fields `as` names —
+`start` and `end` by default, so an `aggregate` grouped by those counts per bin
+and the bar spans the bin.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### boundBandHeight
 
 Bound a band height to its legal range — a config value, a menu choice, or a
@@ -113,6 +138,26 @@ 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)
 
+### 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.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### ChannelReader
+
+A channel read per feature: the compiled form of a FieldRef, and what a
+display's own worker method hands the encoder for a channel no field name can
+say — a join against a second adapter, a lookup table, a rule over two fields.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
 ### clampBandHeight
 
 Clamp one _resize_ of a drag-resizable band: boundBandHeight, plus the one rule
@@ -140,27 +185,136 @@ lands before React re-renders.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandHeight.ts)
 
-### clearPromotedDefaults
+### 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.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### colorEvaluator
+
+A CSS colour or `jexl:` colour expression as a per-feature packed ABGR — the
+unscaled arm of ColorEncoding, on its own for a display that carries a plain
+`color` slot.
+
+```js
+// type signature
+(color: string, jexl: JexlInstance | undefined) => (feature: Feature) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### ColorScaleTable
+
+The scale a colour channel was resolved through, as the legend reads it — the
+same table the colours in the payload came from, so the key cannot disagree with
+the painting.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### CoverageStep
+
+Replace the features with runs of constant depth: how many of them overlap each
+stretch of the region, in a field `as` (`coverage` by default), with the
+stretches nothing overlaps left out.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### EncodeContext
+
+What surrounds an encode: the jexl instance a `jexl:` channel compiles against —
+a caller whose channels are all readers or field names passes none — and a
+progress reporter.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### Encoded
 
-Clear the named promoted defaults for this display type, so every track
-following one reverts to its own config value. Backs the badge's "clear session
-default" action, which passes the slots it actually listed
-(`getDisplayTypeDefaultChanges`).
+EncodedChannels with the lanes in `L` present — what `encodeFeatures` answers a
+caller that named them.
 
-**`slots` is required, and an all-slots default is not the convenience it looks
-like.** It reaches further than any list a dialog can have shown: a promoted
-default the track _customized_ over is `inherited: false` and so appears in no
-row, yet still governs sibling tracks — so clearing it from a dialog that never
-showed it moves tracks other than the one whose badge was clicked. Clearing
-every promoted default at once is a preferences-scope action, and Preferences →
-"Reset to defaults" is where it lives (`clearPreferenceOverrides`).
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### EncodedChannels
+
+One encoding's channels over one region's features, dense and index-aligned:
+instance `i` of every array is the same feature, and `featureIndex[i]` says
+which one of the input list it was. A lane is present when the caller asked for
+it (LaneName); Encoded is this type with a known lane set required.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### encodedChannelTransferables
+
+The buffers an EncodedChannels owns, for `rpcResult`'s transfer list.
 
 ```js
 // type signature
-(self: ResolvableDisplay, slots: Iterable<string>) => void
+(c: EncodedChannels) => ArrayBufferLike[]
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
+
+### EncodedFeaturesResult
+
+What `CoreEncodeFeatures` answers for one region: `layers[i]` is the request's
+`layers[i]` over the region's features, so a display's mark list indexes
+straight into it.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### encodeFeatures
+
+Evaluate one encoding over a feature list into dense channel arrays for the
+lanes named, the scale table each scaled channel came from, the `y` extremes and
+— when `index` is among the lanes — a hit index.
+
+A feature whose `x`, `x2` or (declared and asked-for) `y` is not finite is
+skipped and counted in `skipped`, so every array stays index-aligned with the
+Flatbush. Pure: the RPC around it owns the adapter, the filters and the
+transferables.
+
+```js
+// type signature
+<L extends LaneName>(features: readonly Feature[], 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)
+
+### 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.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### FilterStep
+
+Keep the features a `jexl:` expression over `feature` admits.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### FlattenStep
+
+Fan each feature out into one feature per element of an array-valued field —
+`subfeatures`, so a gene answers its transcripts and a transcript its exons.
+Each answer reads the element's own fields first and the feature it came from
+for everything else, so an exon still knows its gene's name and strand. A
+feature whose field holds no array drops out unless `keepEmpty` says otherwise.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### FormulaStep
+
+Write a `jexl:` expression's value over `feature` into the field `as` of every
+feature.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
 ### getAssemblyHost
 
@@ -191,12 +345,6 @@ check, so reaching for the other one does not get a typo past tsc. It does not
 consult the session and has no per-slot behavior; what you read is what the
 track stores.
 
-A `promotable` slot read this way therefore yields the raw stored value,
-`undefined` included — that `undefined` is the cascade's inherit sentinel, and
-`resolveConf` is what turns it into a real value. The read type keeps the
-`undefined` on purpose, so reaching for the wrong reader is a compile error
-rather than a silent one.
-
 ```js
 // type signature
 { (model: {…}): ModelSnapshotType<…>; <…>(model: {…}, slotPath: SLOT, args?: Record<…> | undefined): SLOT extends string ? ConfigurationSlotValue<…> : any; }
@@ -204,30 +352,6 @@ rather than a silent one.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
 
-### getConfigSnapshotWithPromotables
-
-The display's full config snapshot with every `promotable` slot overwritten by
-its resolved value in place. For building a worker payload: a promotable slot
-serializes as its raw inherit sentinel (`undefined`, since they're all `maybe*`
-types), which the worker can't interpret — it has no session to resolve against.
-This hands it concrete values instead, with no per-slot bookkeeping, so adding a
-promotable worker-consumed slot needs no rpcProps change and can't silently ship
-a sentinel. Main-thread only (the cascade consults the session). Display-only
-promotable slots the worker never reads (e.g. displayMode) are still excluded by
-the caller — resolving them here is a harmless no-op since they're dropped
-anyway.
-
-The return type is branded (`ResolvedConfigSnapshot`) so a payload builder can
-demand a snapshot that has been through here. The assertion below is the one
-place the brand is applied, and it sits on the line after the resolve.
-
-```js
-// type signature
-(self: ResolvableDisplay) => ResolvedConfigSnapshot
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
-
 ### getContainingDisplay
 
 Returns the display model that contains the given node. Throws if the node has
@@ -275,19 +399,6 @@ Where a display puts a dialog it cannot mount itself.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/sessionServices.ts)
 
-### getDisplayTypeDefaultChanges
-
-Effective differences a track following the default inherits from session-wide
-defaults, one per promotable slot whose inherited value differs from its schema
-default. Drives the track-selector "affected by a session default" badge.
-
-```js
-// type signature
-(self: ResolvableDisplay) => TrackConfigChange[]
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
-
 ### getEnv
 
 Returns the MST environment for a node, which carries the `pluginManager`.
@@ -369,16 +480,31 @@ module actually uses.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/sessionServices.ts)
 
-### getTrackConfigWithPromotables
+### GLYPH_CODES
 
-See TrackConfigWithPromotables.
+The `point` shape's glyph code for each name an encoding can say.
 
 ```js
 // type signature
-(session: PromotedDefaultStore, trackConfig: ModelInstanceTypeProps<…> & {…} & IStateTreeNode<…>) => TrackConfigWithPromotables
+Record<GlyphName, number>
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/glyphNames.ts)
+
+### GlyphEncoding
+
+A GlyphName, a `jexl:` expression over `feature` returning one, or a field bound
+to a categorical scale whose `range` lists the glyph names handed out — the
+three glyphs, in order, when absent.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
+### GlyphScaleTable
+
+The scale a glyph channel was resolved through: which glyph each value of the
+field took.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
 ### hydrateTrackConfig
 
@@ -387,7 +513,7 @@ to find the schema. `session.tracks` holds `types.frozen` plain objects until
 something references a track (ADR-031), so a caller handed one of those has a
 config that reads nothing but what was literally authored: a slot at its schema
 default is absent, `preProcessSnapshot` has not run, and nothing that walks a
-live node — the promotable cascade above all — applies to it.
+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"
@@ -414,25 +540,15 @@ needs; `CopyConfigEntryPoints.test.ts` pins both halves.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/configurationSchema.ts)
 
-### isSlotCustomized
-
-Whether this track has customized the slot (holds a non-default value of its
-own) rather than following the display type's default. The correct "reset to
-default" predicate for a promotable slot: comparing the resolved value to the
-base instead reads as at-default for a track merely _following_ a non-base
-promoted default, so the reset control lights up on a no-op.
+### LaneName
 
-`SLOT` is constrained the way `getConf`'s is, and a widened `self` switches the
-check off (`HostChecksSlotNames`). A slot name the schema does not declare
-throws at the first read (`getSlotDefinition`), and a declared but
-non-promotable one throws in `resolveSlotIn`.
+The lanes a caller asks the encoder to fill, beyond `x`, `x2` and
+`featureIndex`, which every payload carries: a shape's channels, and `index` for
+the Flatbush a hover reads. A lane not asked for is neither allocated nor
+transferred, and a caller that never hovers declines the index, which is most of
+the encoder's cost after the walk.
 
-```js
-// type signature
-<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT) => boolean
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
 ### launchOrReplaceView
 
@@ -446,99 +562,48 @@ synchronous `addOrReplaceView` requires it loaded already.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/mstUtils.ts)
 
-### makePin
+### LayerRequest
 
-The pin on a radio or slider row: "apply this value to every open track of this
-display type", and — via the snackbar it raises — "keep it as the default for
-the ones opened later".
+One layer of a `CoreEncodeFeatures` request: the encoding to evaluate and the
+lanes the display's shape reads.
 
-`value` chooses between the subsystem's two meanings, which are otherwise
-identical:
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
-- **Give it** for a per-value pin — "make _compact_ the default" — independent
-  of what the track currently shows. Use on an always-visible pin so it can
-  never promote a meaningless value, and so two rows sharing one slot (sashimi
-  `'down'` vs `'auto'`) stay independent.
-- **Omit it** for "whatever I'm showing", resolved through the cascade. Use for
-  a continuous setting where no fixed on-value makes sense (wiggle point size,
-  arc line width).
+### MarkEncoding
 
-A checkbox row takes neither: makeTogglePin.
+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.
 
-One function with an optional argument, rather than the two exported builders it
-replaces — a per-value one and a `…CurrentValue…` one, the second of which was
-exactly the first applied to `resolveSlot(self, slot).value`. The pair was one
-function plus a doc section explaining which name to reach for; omitting the
-argument now says what the longer name said.
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
-```js
-// type signature
-<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<…>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT, ...value: [] | [...]) => ValuePin
-```
+### MarkEncodingInput
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+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.
 
-### makeTogglePin
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
-The pin on a checkbox row: the row's own checkbox, acting on every open track of
-the display type. `active` mirrors the row, so the pin draws filled exactly when
-the box is ticked; a click flips the row's state on every open track and offers
-the new state as the display type's default. It never clears a default the way
-makePin's filled pin does — flipping back and taking the offer promotes the
-other value, and promoting the base value clears the default
-(`applyAndOfferDefault`).
+### NO_VALUE_LABEL
 
-Replaces a symmetric `makePin(self, slot)` on these rows, which carried the
-row's current state: beside an unchecked box that applied _off_ everywhere and
-visibly did nothing. It also replaces the per-value `makePin` a checkbox row
-over a shared enum slot used to carry, which gave two checkbox rows in one
-submenu two different pins: one filled when its value was promoted and clearing
-on a second click, the other filled when the box was ticked and flipping. With
-`states`, a checkbox row is always the toggle kind.
+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.
 
 ```js
 // type signature
-<…>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT, ...states: ConfigurationSlotValueResolved<...> extends boolean ? [] | [...] : [...]) => TogglePin
+'(no value)'
 ```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
-
-### openPromotableDisplays
-
-Every display on an open track, across all open views — the reach of anything
-that acts on "the tracks the user is looking at": a promoted default's "apply to
-open tracks", and the share/export bake. One walk so those can't drift apart.
-
-Recurses into composite views. A display nested in one resolves the cascade like
-any other but was invisible to both callers, so the share/export bake didn't
-bake its inherited values and a shared session containing a breakpoint-split or
-synteny view rendered differently for the recipient. `LGVSyntenyDisplay` is only
-ever reached through this branch, so don't flatten the recursion away.
-`hasChildViews` names the one composite shape it does not cover.
-
-A view holding neither (e.g. spreadsheet) drops out via the structural guards. A
-view whose displays declare no promotable slot (e.g. dotplot, which does hold
-tracks) is walked and contributes nothing — harmless, and cheaper than asking
-each display whether it has anything to promote.
-
-```js
-// type signature
-(session: AbstractSessionModel) => ResolvableDisplay[]
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/openDisplays.ts)
-
-### Pin
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
-The "apply this to every open track of this type" affordance on a menu row — the
-trailing `PushPin`, bundled so the row consumes it as one prop.
+### RampRef
 
-`kind` is what the adornment words itself from and what the row builders check:
-a checkbox row takes a TogglePin, a radio or slider row a ValuePin. The two used
-to be told apart by `typeof onValue === 'boolean'`, which let a value pin over a
-boolean slot compile and read as a toggle while clearing on its second click.
+The ramp a continuous colour scale samples: a named ramp, or evenly spaced CSS
+colour stops.
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotablePin.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
 ### readConfObject
 
@@ -622,57 +687,6 @@ bound) stated height when on. This is the single spelling of "off spends 0 px".
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/bandLayout.ts)
 
-### resolveConf
-
-Reads a `promotable` slot through the display-type-default cascade — the track's
-own value, else the session-wide promoted default for this display type, else
-the slot's `promotedBase`. Always yields a real value, never the `undefined`
-inherit sentinel, so a display's value getter is
-`get displayMode(): DisplayMode { return resolveConf(self, 'displayMode') }`
-with no post-guard and no cast.
-
-Separate from `getConf` rather than folded into it, deliberately: resolution
-consults the session, so it is main-thread only and throws on a detached node.
-Folding it in was built and reverted — ADR-046.
-
-Throws if `slot` isn't promotable — the cascade has nothing to say about a plain
-slot, and `getConf` is what you want there.
-
-Takes no jexl `args`, unlike `getConf`: a promotable slot cannot hold a callback
-(see `SlotResolution`), so there is no per-feature context to supply.
-
-```js
-// type signature
-<…>(model: ResolvableDisplay<...>, slot: SLOT) => ConfigurationSlotValueResolved<...>
-```
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/getConf.ts)
-
-### ResolvedConfigSnapshot
-
-A display config snapshot whose promotable slots hold RESOLVED values rather
-than the inherit sentinel — what a worker payload has to be built from.
-
-The brand is required and unforgeable, so a plain `Record<string, unknown>` is
-not assignable to it and neither is `getSnapshot(self.configuration)`. That is
-the whole point. Everything downstream of the resolve is an ERASED container — a
-snapshot is `Record<string, unknown>`, and the payload it becomes is an
-`as`-asserted interface — so a payload builder handed the RAW snapshot instead
-typechecks, ships `undefined` for every promotable slot, and types it as the
-resolved value. That was measured, not supposed: the raw spelling in
-`LinearBasicDisplay`'s `rpcProps()` passed `pnpm typecheck` and every suite in
-`plugins/canvas`, `packages/core/src/configuration` and `products/jbrowse-web`,
-while sending the worker `undefined` for chevrons, subfeature labels and feature
-height.
-
-The rest of this subsystem's guarantees are carried by types that stay connected
-to the schema: a raw read of a promotable `maybe*` slot is `T | undefined` (see
-`ConfigurationSlotValue`), so `getConf` where `resolveConf` was meant is a
-compile error at any typed consumer. The brand is that guarantee re-established
-at the point where the connection is cut.
-
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
-
 ### runLazyAfterAttach
 
 Run a display's `afterAttach` body from a module loaded on demand, so the
@@ -691,6 +705,19 @@ displays hand-rolled this IIFE and each drew the lines differently.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/lazyAfterAttach.ts)
 
+### runTransforms
+
+Run the transform steps over a feature list, in order, in the worker. The list a
+step answers is what the next one reads, and the last one is what the encoder
+walks.
+
+```js
+// type signature
+(features: readonly Feature[], steps: readonly TransformStep[], jexl?: JexlInstance | undefined) => readonly Feature[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/featureTransforms.ts)
+
 ### sampleColorRamp
 
 The color at `t` in `[0, 1]` across a list of EVENLY SPACED stops, linearly
@@ -704,6 +731,12 @@ than an extrapolation past them, and a one-stop ramp is that stop everywhere.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
+### ScaleTable
+
+Any channel's scale table; the kind names the channel.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
+
 ### SessionPaletteProvider
 
 Make JBrowse follow the host's light/dark state — the whole of it, in one mount:
@@ -760,9 +793,9 @@ cast names a concrete schema instead (`ConfigModelForFields`, or the base schema
 when the slot is the base's), and `HostChecksSlotNames` pins each one.
 
 A wrong _value_ type still throws at runtime (MST type-checks the assignment)
-rather than at compile time. `value` is deliberately `unknown` because the
-inherit sentinel (`undefined`/`null`) is a legitimate write on every promotable
-slot, which the declared slot value type doesn't include.
+rather than at compile time. `value` is deliberately `unknown` because
+`undefined` is a legitimate write — it resets a slot to its schema default — and
+the declared slot value type doesn't include it.
 
 ```js
 // type signature
@@ -790,72 +823,67 @@ 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
 table — the same 256×1 RGBA array `uploadColorRampLut` hands the GPU and the
-Canvas2D fillStyle LUTs index — formatted for `SvgGradientLegend`. It holds one
+Canvas2D fillStyle LUTs index — as the stops of a `RampScale`. It holds one
 claim by construction: the swatch at bar fraction `t` is byte-identical to the
 ramp entry at `t` on both backends. Alpha rides `opacity` (the juicebox fade),
 never baked into the color string.
 
 ```js
 // type signature
-(lut: Uint8Array<ArrayBufferLike>, n: number) => GradientStop[]
+(lut: Uint8Array<ArrayBufferLike>, n: number) => RampStop[]
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/colorRamp.ts)
 
-### TogglePin
+### TransformStep
 
-The pin on a checkbox row, built by makeTogglePin: the row's own checkbox over
-every open track of the display type. `active` mirrors the row, `onValue` is the
-state a click applies (the row's opposite), and `toggle` applies it everywhere
-and offers it as the default. It never clears a default on its own — promoting
-the slot's base value is what clears one.
+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/configuration/promotablePin.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
-### TrackConfigWithPromotables
+### ValueEncoding
 
-A track config snapshot with every display's `promotable` slots resolved, plus
-the list of values that came from a session-wide default rather than from the
-config itself.
+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.
 
-For handing a track's config to somewhere that leaves the cascade for good — the
-About dialog's "Copy config", whose output a user pastes into a `config.json`. A
-raw `getSnapshot` records a slot a track merely _follows_ as absent
-(`stripDefault` collapsed it), so the copied config renders differently from the
-track it was copied from. This is `getComputedStyle` at that boundary, and
-`fromDisplayTypeDefaults` is what lets the UI say so rather than silently
-materializing a session preference into a track config.
+`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.
 
-Resolves from the display _config_ alone, whether or not the track is open.
-Everything the cascade takes is on the config node: it is the same node an open
-display's `configuration` points at (the hydration cache makes it stable), its
-`type` is the display type the session-wide tier is keyed on (every display
-schema is `explicitlyTyped` under the display type's own name), and the session
-is passed in. So an unopened track — which has no display state at all — still
-has an answer to "what would this render as", by the same code path.
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncodingTypes.ts)
 
-**Writes every promotable slot, including the ones sitting at `promotedBase`,
-and that is the decision — don't "align" it with the share bake.** A pasted
-`config.json` is read by a mechanism with no cascade in it at all, so writing
-only the inherited values would leave every other slot to pick up whatever the
-reader has promoted in their own browser. Pinned by
-`products/jbrowse-web/src/tests/CopyConfigPromotedDefaults.test.ts`.
+### valueField
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
+The field a `y` declaration reads, whichever of its two forms it is written in.
 
-### ValuePin
-
-The pin on a radio or slider row, built by makePin: `onValue` is the row's own
-value, `active` means that value is the display type's promoted default, and
-`toggle` on an outline pin applies the value to every open track and offers it
-as the default, while on a filled pin it clears that default and touches no
-track (`applyAndOfferDefault` / `clearDefault`).
+```js
+// type signature
+(y: ValueEncoding) => string
+```
 
-[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotablePin.ts)
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/markEncoding.ts)
 
 ### VIRIDIS_STOPS