@jbrowse/plugin-linear-genome-view 5.0.0-beta.15 → 5.0.0-beta.17

package/esm/LinearGenomeView/model.d.ts

@@ -55,7 +55,7 @@ export interface HighlightRegion {
  *   views: [
  *     {
  *       type: 'LinearGenomeView',
- *       colorByCDS: true,
+ *       colorByFrame: true,
  *       assembly: 'hg38',
  *       loc: 'chr1:1,000,000-1,100,000',
  *       tracks: ['genes', 'alignments'],
@@ -65,7 +65,7 @@ export interface HighlightRegion {
  * ```
  * `assembly`, `loc`, `tracks`, `tracklist`, `nav` and `highlight` need
  * on-attach resolution and are captured into the `launch` property below;
- * `colorByCDS`, `showAminoAcids`, `showCenterLine` and `trackLabels` are plain
+ * `colorByFrame`, `showAminoAcids`, `showCenterLine` and `trackLabels` are plain
  * view props MST restores natively. Both are written the same way.
  * At runtime the same model is driven imperatively — every property and action
  * below is reachable on `viewState.session.views[0]`:
@@ -80,7 +80,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     displayName: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
     minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
-}, "colorByCDS" | "displayedRegions" | "hideHeader" | "hideHeaderOverview" | "hideNoTracksActive" | "id" | "launch" | "legacyBpPerPx" | "scalebarOnly" | "showAminoAcids" | "showCenterLine" | "showCytobands" | "showGridlines" | "showTrackOutlines" | "trackLabels" | "trackSelectorType" | "tracks" | "type" | "windowStartBp" | "windowWidthBp"> & {
+}, "axis" | "colorByFrame" | "displayedRegions" | "hideHeader" | "hideHeaderOverview" | "hideNoTracksActive" | "id" | "launch" | "legacyBpPerPx" | "scalebarOnly" | "showAminoAcids" | "showCenterLine" | "showCytobands" | "showTrackOutlines" | "trackLabels" | "trackSelectorType" | "tracks" | "type" | "windowStartBp" | "windowWidthBp"> & {
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     type: import("@jbrowse/mobx-state-tree").IType<string | undefined, string, string>;
     windowStartBp: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
@@ -95,8 +95,14 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     showCenterLine: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     showCytobands: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     trackLabels: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
-    showGridlines: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
-    colorByCDS: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    axis: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly grid: {
+            type: "boolean";
+        } & {
+            defaultValue: boolean;
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined, undefined, import("@jbrowse/core/configuration").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>, [undefined]>;
+    colorByFrame: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     showAminoAcids: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     showTrackOutlines: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     scalebarOnly: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
@@ -184,6 +190,11 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      */
     volatileGuides: VolatileGuide[];
 } & {
+    /**
+     * #getter
+     * `axis.grid`: whether the ruler's ticks run down through the tracks.
+     */
+    readonly axisGrid: boolean;
     /**
      * #getter
      * the launch state that still has something to apply — the gate every
@@ -612,8 +623,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>) | undefined;
     /**
      * #getter
-     * What the loading screen says while `showLoading`, read off the
-     * assembly whose load is the wait; undefined otherwise.
+     * The loading screen's text while `showLoading`, taken from the
+     * assembly being waited on; undefined otherwise.
      */
     readonly loading: import("@jbrowse/core/util/viewStatus").ViewLoading | undefined;
     /**
@@ -655,12 +666,12 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * `width`/`staticBlocks` throw by design before the view has been
      * measured and navigated.
      *
-     * **Not `initialized`**, which is the trap this getter exists to close.
+     * Use this getter rather than `initialized`.
      * That one answers "have the assembly's regions loaded", which is only
      * the first of two async steps: navigating then populates
      * `displayedRegions`, and in the window between the two `initialized` is
      * already true while there is still nothing on screen. `showLoading`
-     * folds in `awaitingInitNavigation`, the getter that exists for exactly
+     * folds in `awaitingInitNavigation`, the getter for exactly
      * that gap.
      *
      * `error` is the third outcome and is why this is not a bare
@@ -710,7 +721,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     readonly headerHeight: number;
     /**
      * #method
-     * rendered height of a single track, collapsing to a fixed height when
+     * rendered height of a single track, using a fixed height when
      * minimized. Shared by trackHeights and getTrackYOffset so the two can't
      * disagree. Reads `activeDisplay` — the display TrackContainer actually
      * mounts — rather than re-picking `displays[0]`, so the view's height math
@@ -789,8 +800,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * or 0 for a standalone view, a mode that is off, and a stack that cannot
      * answer yet.
      *
-     * Pulled rather than pushed down into a volatile: the number is a
-     * function of every row's fit, all of which move on a resize, and a
+     * A getter rather than a volatile the container writes: the number is a
+     * function of every row's fit, all of which change on a resize, and a
      * stored copy would be stale by the next layout.
      */
     readonly sharedFitBpPerPx: number;
@@ -857,7 +868,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #action
      */
-    setColorByCDS(flag: boolean): void;
+    setColorByFrame(flag: boolean): void;
     /**
      * #action
      */
@@ -916,7 +927,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #action
      */
-    setShowGridlines(b: boolean): void;
+    setAxisGrid(grid: boolean): void;
     /**
      * #action
      * set temporary vertical guides (e.g., for LD display hover)
@@ -1033,7 +1044,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #method
      * Helper method for the fetchSequence.
-     * Retrieves the corresponding regions that were selected by the
+     * Returns the regions the user selected with the
      * rubberband
      *
      * @param leftOffset - `object as {start, end, index, offset}`, offset = start
@@ -1080,15 +1091,15 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * #getter
      * an ideogram only reads correctly against an entire chromosome: on a
      * sub-region it is a meaningless slice of bands, and the centromere shows
-     * up as a lone half-triangle. The chromosome needs bands of its own too:
-     * a cytoband file often lists only the main chromosomes, not chrM or the
+     * up as a lone half-triangle. The chromosome also needs bands: a cytoband
+     * file often lists only the main chromosomes, not chrM or the
      * unplaced scaffolds
      */
     readonly canShowCytobands: boolean;
     /**
      * #getter
      * the `showCytobands` setting gated by whether cytobands can be shown at
-     * all (whole chromosome with bands of its own) and by the header
+     * all (whole chromosome with bands in the cytoband file) and by the header
      * overview they draw in being on, which the SVG export follows too
      */
     readonly effectiveShowCytobands: boolean;
@@ -1141,9 +1152,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #getter
      * dynamic blocks represent the exact coordinates of the currently
-     * visible genome regions on the screen. they are similar to static
-     * blocks, but static blocks can go offscreen while dynamic blocks
-     * represent exactly what is on screen
+     * visible genome regions on the screen. Static blocks can go
+     * offscreen, while dynamic blocks represent exactly what is on screen
      */
     readonly dynamicBlocks: BlockSet;
     /**
@@ -1175,12 +1185,10 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * The frame exists because those three are laid out across every
      * displayed region rather than across the viewport — it overhangs on
      * both sides — so their `x` values are stable under a scroll and only
-     * this number moves. `scalebarRefNameLabels` is the exception and says
-     * so: its `transform` is already a screen x, because a sticky label's
+     * this number moves. `scalebarRefNameLabels` is the exception: its `transform` is already a screen x, because a sticky label's
      * position is a function of the scroll rather than of block geometry.
      *
-     * **The subtraction must happen here, in float64, and that is the
-     * load-bearing part.** `offsetPx` is a whole-genome pixel coordinate —
+     * **The subtraction must happen here, in float64.** `offsetPx` is a whole-genome pixel coordinate —
      * hg38 chr1 at base resolution is already past 1e10 — and a length that
      * size does not survive the trip through CSS: the transform matrix is
      * float32 by the time it reaches the compositor, where consecutive
@@ -1192,13 +1200,12 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * assemblies at high zoom, which is not where anyone tests. Both
      * operands here are large and their difference is bounded by the
      * overhang (a block or two), so what reaches CSS is small and exact.
-     * Same rule as the GPU side, one layer up —
+     * This applies the GPU side's rule one layer up; see
      * `agent-docs/reference/BP_PRECISION.md`.
      *
      * Published because it is the one piece of coordinate arithmetic a host
      * drawing its own chrome would otherwise have to know, and because
-     * having it written out at each call site is how the two in-tree copies
-     * came to disagree about rounding. Round it where the content is text
+     * copies written out at each call site disagree about rounding. Round it where the content is text
      * (a fractional offset blurs a label); leave it alone for paths and
      * boxes.
      */
@@ -1241,11 +1248,11 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * sticky, transform, maxWidth, paddingLeft, text}` each. One per run of
      * same-refName regions, plus a "sticky" one pinned to the viewport's
      * left edge naming the refName under it, so panning into a chromosome
-     * does not scroll its own name off the screen.
+     * does not scroll the chromosome's name off the screen.
      *
-     * Three rules live in here that a host drawing region names will
-     * otherwise rediscover the hard way, and two of them are invisible until
-     * the data is awkward:
+     * This getter applies three rules that a host drawing region names would
+     * otherwise have to rediscover, and two of them are invisible until the
+     * data is awkward:
      *
      * - the sticky label rides the rightmost run that has scrolled off the
      *   left, not the region's first block — that one is gone from
@@ -1257,7 +1264,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      *   is fitted to the whole run, and `displayedRegionIndex` /
      *   `lastDisplayedRegionIndex` bracket what it stands for.
      * - a name is drawn whole or not at all, measured against the space its
-     *   run leaves. Clipped to its own width, `chr16` reads as `chr1` —
+     *   run leaves. Clipped to that space, `chr16` reads as `chr1` —
      *   a different chromosome rather than a shortened name, which is why
      *   this is a fit test rather than an ellipsis.
      *
@@ -1277,7 +1284,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * pins to its right edge rather than the viewport's, and the coordinate
      * numbers stay out from under it. The SVG export deliberately
      * calls `getScalebarRefNameLabels` itself with no prefix rather than
-     * reading this, since it draws its own assembly name above the ruler.
+     * reading this, since it draws the assembly name itself above the ruler.
      */
     readonly scalebarRefNameLabels: {
         labels: import("./util.ts").ScalebarRefNameLabel[];
@@ -1289,7 +1296,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * Every span along the row that is not track data, as plain geometry in
      * the staticBlocks frame — the same frame as gridlineTicks and
      * scalebarLabels, so one `translateX(staticBlocksTranslateX)` places all
-     * three. A host drawing its own chrome needs all three kinds:
+     * three. A host that draws the row's chrome itself needs all three kinds:
      *
      * - `seam`: the 3px bar at a region's right edge. Displayed regions are
      *   laid out **contiguously** (calculateStaticBlocks emits boundary
@@ -1304,11 +1311,11 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      *   but the 24 chromosomes are under a pixel wide), so a host that
      *   skips them leaves that part of the row empty.
      * - `boundary`: past the start of the first region or the end of the
-     *   last. Greying it shows the last region's seam as the edge of a
+     *   last. Greying it makes the last region's seam read as the edge of a
      *   filled area, where it would otherwise look like a line in the
      *   middle of the track.
      *
-     * Elided blocks get no seam even though they carry the flag: at the
+     * Elided blocks get no seam even though they have the flag: at the
      * zoom where regions elide, one bar per region would fill the row solid
      * grey.
      *
@@ -1397,7 +1404,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * array of fresh objects on every pan and zoom frame, so a component
      * that derived this number itself re-rendered on every frame of every
      * gesture — to produce, whenever content fills the track, the unchanged
-     * `trackWidthPx`. Reading the scalar lets MobX's `===` stop the chain at
+     * `trackWidthPx`. A component that reads the scalar lets MobX's `===` stop the chain at
      * this computed instead. Measured over 20 zoom frames: the wiggle
      * family's three body instances fell from 66 renders to 7.
      */
@@ -1483,17 +1490,16 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * as a navigation that didn't happen, and wiggle's autoscale domain is
      * computed over the window the user just left — measured at `[0,200]`
      * against a correct `[0,300]` when a 40bp coarse window survived a jump to
-     * 4040bp on screen. Only the per-region fetch moving to the leading edge
-     * made that reachable: at 600ms the data never landed inside the hole.
+     * 4040bp on screen.
      *
-     * **The continuous paths deliberately do not come through here.** The
+     * **The continuous paths do not call this.** The
      * spring zoom writes through `zoomTo` per frame and a drag through
      * `scrollTo`, so this adds no per-frame work; the settle is idempotent
      * (`setCoarseDynamicBlocks` compares block keys), so the debounced
-     * autorun's own follow-up run costs nothing.
+     * autorun's follow-up run costs nothing.
      *
-     * Every placer calls it, and `placersSettleCoarseBlocks.test.ts` is what
-     * makes that true of the next one — it scans this file for the writes and
+     * Every placer calls it, and `placersSettleCoarseBlocks.test.ts` enforces
+     * that for the next one: it scans this file for the writes and
      * fails on a placer that reaches neither the settle nor its named list of
      * continuous paths. Two passes by hand missed four.
      */
@@ -1519,8 +1525,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     moveTo(start?: BpOffset, end?: BpOffset): void;
     /**
      * #action
-     * Place the viewport by the pair of PIXEL quantities it used to be stored
-     * as. Prefer `setWindow`: pixels mean nothing without the width they were
+     * Place the viewport by `bpPerPx` and `offsetPx`, the pixel pair the view
+     * stored before it stored the window. Prefer `setWindow`: pixels mean nothing without the width they were
      * measured at, so a round trip through here is only exact while the width
      * holds still. Kept for callers that genuinely have pixels — a wheel
      * gesture, a rubberband.
@@ -1529,7 +1535,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #action
      * Place the viewport by the pair it is actually STORED as: the window's
-     * width and left edge, both in bp. `setNewView`'s bp-space twin, and the
+     * width and left edge, both in bp. The bp-space counterpart of `setNewView`, and the
      * right one for anything that captures a viewport and puts it back later
      * (an Undo, a saved location) — those two moments can be a window resize
      * apart, and this pair survives one where a pixel pair does not.
@@ -1551,8 +1557,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     setWindowFrame(windowWidthBp: number, windowStartBp: number): void;
     /**
      * #action
-     * The worst jump of them to leave unsettled: the coarse blocks are keyed
-     * by `displayedRegionIndex`, so a set that outlives the region list has a
+     * Settles the coarse blocks, since this is the worst jump to leave
+     * unsettled: they are keyed by `displayedRegionIndex`, so a set that outlives the region list has a
      * consumer reading one contig's data against another's blocks.
      */
     setDisplayedRegions(regions: Region[]): void;
@@ -1787,7 +1793,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #method
      * returns menu items for a highlight context menu. plugins can extend
-     * this via Core-extendPluggableElement to add their own items
+     * this via Core-extendPluggableElement to add items
      */
     highlightMenuItems(_highlight: HighlightType): MenuItem[];
 } & {
@@ -1813,7 +1819,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     displayName: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
     minimized: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
-}, "colorByCDS" | "displayedRegions" | "hideHeader" | "hideHeaderOverview" | "hideNoTracksActive" | "id" | "launch" | "legacyBpPerPx" | "scalebarOnly" | "showAminoAcids" | "showCenterLine" | "showCytobands" | "showGridlines" | "showTrackOutlines" | "trackLabels" | "trackSelectorType" | "tracks" | "type" | "windowStartBp" | "windowWidthBp"> & {
+}, "axis" | "colorByFrame" | "displayedRegions" | "hideHeader" | "hideHeaderOverview" | "hideNoTracksActive" | "id" | "launch" | "legacyBpPerPx" | "scalebarOnly" | "showAminoAcids" | "showCenterLine" | "showCytobands" | "showTrackOutlines" | "trackLabels" | "trackSelectorType" | "tracks" | "type" | "windowStartBp" | "windowWidthBp"> & {
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     type: import("@jbrowse/mobx-state-tree").IType<string | undefined, string, string>;
     windowStartBp: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
@@ -1828,8 +1834,14 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     showCenterLine: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     showCytobands: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     trackLabels: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
-    showGridlines: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
-    colorByCDS: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
+    axis: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly grid: {
+            type: "boolean";
+        } & {
+            defaultValue: boolean;
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined, undefined, import("@jbrowse/core/configuration").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>, [undefined]>;
+    colorByFrame: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     showAminoAcids: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     showTrackOutlines: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
     scalebarOnly: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>, [undefined]>;
@@ -1917,6 +1929,11 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      */
     volatileGuides: VolatileGuide[];
 } & {
+    /**
+     * #getter
+     * `axis.grid`: whether the ruler's ticks run down through the tracks.
+     */
+    readonly axisGrid: boolean;
     /**
      * #getter
      * the launch state that still has something to apply — the gate every
@@ -2345,8 +2362,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>) | undefined;
     /**
      * #getter
-     * What the loading screen says while `showLoading`, read off the
-     * assembly whose load is the wait; undefined otherwise.
+     * The loading screen's text while `showLoading`, taken from the
+     * assembly being waited on; undefined otherwise.
      */
     readonly loading: import("@jbrowse/core/util/viewStatus").ViewLoading | undefined;
     /**
@@ -2388,12 +2405,12 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * `width`/`staticBlocks` throw by design before the view has been
      * measured and navigated.
      *
-     * **Not `initialized`**, which is the trap this getter exists to close.
+     * Use this getter rather than `initialized`.
      * That one answers "have the assembly's regions loaded", which is only
      * the first of two async steps: navigating then populates
      * `displayedRegions`, and in the window between the two `initialized` is
      * already true while there is still nothing on screen. `showLoading`
-     * folds in `awaitingInitNavigation`, the getter that exists for exactly
+     * folds in `awaitingInitNavigation`, the getter for exactly
      * that gap.
      *
      * `error` is the third outcome and is why this is not a bare
@@ -2443,7 +2460,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     readonly headerHeight: number;
     /**
      * #method
-     * rendered height of a single track, collapsing to a fixed height when
+     * rendered height of a single track, using a fixed height when
      * minimized. Shared by trackHeights and getTrackYOffset so the two can't
      * disagree. Reads `activeDisplay` — the display TrackContainer actually
      * mounts — rather than re-picking `displays[0]`, so the view's height math
@@ -2522,8 +2539,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * or 0 for a standalone view, a mode that is off, and a stack that cannot
      * answer yet.
      *
-     * Pulled rather than pushed down into a volatile: the number is a
-     * function of every row's fit, all of which move on a resize, and a
+     * A getter rather than a volatile the container writes: the number is a
+     * function of every row's fit, all of which change on a resize, and a
      * stored copy would be stale by the next layout.
      */
     readonly sharedFitBpPerPx: number;
@@ -2590,7 +2607,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #action
      */
-    setColorByCDS(flag: boolean): void;
+    setColorByFrame(flag: boolean): void;
     /**
      * #action
      */
@@ -2649,7 +2666,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #action
      */
-    setShowGridlines(b: boolean): void;
+    setAxisGrid(grid: boolean): void;
     /**
      * #action
      * set temporary vertical guides (e.g., for LD display hover)
@@ -2766,7 +2783,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #method
      * Helper method for the fetchSequence.
-     * Retrieves the corresponding regions that were selected by the
+     * Returns the regions the user selected with the
      * rubberband
      *
      * @param leftOffset - `object as {start, end, index, offset}`, offset = start
@@ -2813,15 +2830,15 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * #getter
      * an ideogram only reads correctly against an entire chromosome: on a
      * sub-region it is a meaningless slice of bands, and the centromere shows
-     * up as a lone half-triangle. The chromosome needs bands of its own too:
-     * a cytoband file often lists only the main chromosomes, not chrM or the
+     * up as a lone half-triangle. The chromosome also needs bands: a cytoband
+     * file often lists only the main chromosomes, not chrM or the
      * unplaced scaffolds
      */
     readonly canShowCytobands: boolean;
     /**
      * #getter
      * the `showCytobands` setting gated by whether cytobands can be shown at
-     * all (whole chromosome with bands of its own) and by the header
+     * all (whole chromosome with bands in the cytoband file) and by the header
      * overview they draw in being on, which the SVG export follows too
      */
     readonly effectiveShowCytobands: boolean;
@@ -2874,9 +2891,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #getter
      * dynamic blocks represent the exact coordinates of the currently
-     * visible genome regions on the screen. they are similar to static
-     * blocks, but static blocks can go offscreen while dynamic blocks
-     * represent exactly what is on screen
+     * visible genome regions on the screen. Static blocks can go
+     * offscreen, while dynamic blocks represent exactly what is on screen
      */
     readonly dynamicBlocks: BlockSet;
     /**
@@ -2908,12 +2924,10 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * The frame exists because those three are laid out across every
      * displayed region rather than across the viewport — it overhangs on
      * both sides — so their `x` values are stable under a scroll and only
-     * this number moves. `scalebarRefNameLabels` is the exception and says
-     * so: its `transform` is already a screen x, because a sticky label's
+     * this number moves. `scalebarRefNameLabels` is the exception: its `transform` is already a screen x, because a sticky label's
      * position is a function of the scroll rather than of block geometry.
      *
-     * **The subtraction must happen here, in float64, and that is the
-     * load-bearing part.** `offsetPx` is a whole-genome pixel coordinate —
+     * **The subtraction must happen here, in float64.** `offsetPx` is a whole-genome pixel coordinate —
      * hg38 chr1 at base resolution is already past 1e10 — and a length that
      * size does not survive the trip through CSS: the transform matrix is
      * float32 by the time it reaches the compositor, where consecutive
@@ -2925,13 +2939,12 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * assemblies at high zoom, which is not where anyone tests. Both
      * operands here are large and their difference is bounded by the
      * overhang (a block or two), so what reaches CSS is small and exact.
-     * Same rule as the GPU side, one layer up —
+     * This applies the GPU side's rule one layer up; see
      * `agent-docs/reference/BP_PRECISION.md`.
      *
      * Published because it is the one piece of coordinate arithmetic a host
      * drawing its own chrome would otherwise have to know, and because
-     * having it written out at each call site is how the two in-tree copies
-     * came to disagree about rounding. Round it where the content is text
+     * copies written out at each call site disagree about rounding. Round it where the content is text
      * (a fractional offset blurs a label); leave it alone for paths and
      * boxes.
      */
@@ -2974,11 +2987,11 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * sticky, transform, maxWidth, paddingLeft, text}` each. One per run of
      * same-refName regions, plus a "sticky" one pinned to the viewport's
      * left edge naming the refName under it, so panning into a chromosome
-     * does not scroll its own name off the screen.
+     * does not scroll the chromosome's name off the screen.
      *
-     * Three rules live in here that a host drawing region names will
-     * otherwise rediscover the hard way, and two of them are invisible until
-     * the data is awkward:
+     * This getter applies three rules that a host drawing region names would
+     * otherwise have to rediscover, and two of them are invisible until the
+     * data is awkward:
      *
      * - the sticky label rides the rightmost run that has scrolled off the
      *   left, not the region's first block — that one is gone from
@@ -2990,7 +3003,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      *   is fitted to the whole run, and `displayedRegionIndex` /
      *   `lastDisplayedRegionIndex` bracket what it stands for.
      * - a name is drawn whole or not at all, measured against the space its
-     *   run leaves. Clipped to its own width, `chr16` reads as `chr1` —
+     *   run leaves. Clipped to that space, `chr16` reads as `chr1` —
      *   a different chromosome rather than a shortened name, which is why
      *   this is a fit test rather than an ellipsis.
      *
@@ -3010,7 +3023,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * pins to its right edge rather than the viewport's, and the coordinate
      * numbers stay out from under it. The SVG export deliberately
      * calls `getScalebarRefNameLabels` itself with no prefix rather than
-     * reading this, since it draws its own assembly name above the ruler.
+     * reading this, since it draws the assembly name itself above the ruler.
      */
     readonly scalebarRefNameLabels: {
         labels: import("./util.ts").ScalebarRefNameLabel[];
@@ -3022,7 +3035,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * Every span along the row that is not track data, as plain geometry in
      * the staticBlocks frame — the same frame as gridlineTicks and
      * scalebarLabels, so one `translateX(staticBlocksTranslateX)` places all
-     * three. A host drawing its own chrome needs all three kinds:
+     * three. A host that draws the row's chrome itself needs all three kinds:
      *
      * - `seam`: the 3px bar at a region's right edge. Displayed regions are
      *   laid out **contiguously** (calculateStaticBlocks emits boundary
@@ -3037,11 +3050,11 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      *   but the 24 chromosomes are under a pixel wide), so a host that
      *   skips them leaves that part of the row empty.
      * - `boundary`: past the start of the first region or the end of the
-     *   last. Greying it shows the last region's seam as the edge of a
+     *   last. Greying it makes the last region's seam read as the edge of a
      *   filled area, where it would otherwise look like a line in the
      *   middle of the track.
      *
-     * Elided blocks get no seam even though they carry the flag: at the
+     * Elided blocks get no seam even though they have the flag: at the
      * zoom where regions elide, one bar per region would fill the row solid
      * grey.
      *
@@ -3130,7 +3143,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * array of fresh objects on every pan and zoom frame, so a component
      * that derived this number itself re-rendered on every frame of every
      * gesture — to produce, whenever content fills the track, the unchanged
-     * `trackWidthPx`. Reading the scalar lets MobX's `===` stop the chain at
+     * `trackWidthPx`. A component that reads the scalar lets MobX's `===` stop the chain at
      * this computed instead. Measured over 20 zoom frames: the wiggle
      * family's three body instances fell from 66 renders to 7.
      */
@@ -3216,17 +3229,16 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
      * as a navigation that didn't happen, and wiggle's autoscale domain is
      * computed over the window the user just left — measured at `[0,200]`
      * against a correct `[0,300]` when a 40bp coarse window survived a jump to
-     * 4040bp on screen. Only the per-region fetch moving to the leading edge
-     * made that reachable: at 600ms the data never landed inside the hole.
+     * 4040bp on screen.
      *
-     * **The continuous paths deliberately do not come through here.** The
+     * **The continuous paths do not call this.** The
      * spring zoom writes through `zoomTo` per frame and a drag through
      * `scrollTo`, so this adds no per-frame work; the settle is idempotent
      * (`setCoarseDynamicBlocks` compares block keys), so the debounced
-     * autorun's own follow-up run costs nothing.
+     * autorun's follow-up run costs nothing.
      *
-     * Every placer calls it, and `placersSettleCoarseBlocks.test.ts` is what
-     * makes that true of the next one — it scans this file for the writes and
+     * Every placer calls it, and `placersSettleCoarseBlocks.test.ts` enforces
+     * that for the next one: it scans this file for the writes and
      * fails on a placer that reaches neither the settle nor its named list of
      * continuous paths. Two passes by hand missed four.
      */
@@ -3252,8 +3264,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     moveTo(start?: BpOffset, end?: BpOffset): void;
     /**
      * #action
-     * Place the viewport by the pair of PIXEL quantities it used to be stored
-     * as. Prefer `setWindow`: pixels mean nothing without the width they were
+     * Place the viewport by `bpPerPx` and `offsetPx`, the pixel pair the view
+     * stored before it stored the window. Prefer `setWindow`: pixels mean nothing without the width they were
      * measured at, so a round trip through here is only exact while the width
      * holds still. Kept for callers that genuinely have pixels — a wheel
      * gesture, a rubberband.
@@ -3262,7 +3274,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #action
      * Place the viewport by the pair it is actually STORED as: the window's
-     * width and left edge, both in bp. `setNewView`'s bp-space twin, and the
+     * width and left edge, both in bp. The bp-space counterpart of `setNewView`, and the
      * right one for anything that captures a viewport and puts it back later
      * (an Undo, a saved location) — those two moments can be a window resize
      * apart, and this pair survives one where a pixel pair does not.
@@ -3284,8 +3296,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     setWindowFrame(windowWidthBp: number, windowStartBp: number): void;
     /**
      * #action
-     * The worst jump of them to leave unsettled: the coarse blocks are keyed
-     * by `displayedRegionIndex`, so a set that outlives the region list has a
+     * Settles the coarse blocks, since this is the worst jump to leave
+     * unsettled: they are keyed by `displayedRegionIndex`, so a set that outlives the region list has a
      * consumer reading one contig's data against another's blocks.
      */
     setDisplayedRegions(regions: Region[]): void;
@@ -3520,7 +3532,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     /**
      * #method
      * returns menu items for a highlight context menu. plugins can extend
-     * this via Core-extendPluggableElement to add their own items
+     * this via Core-extendPluggableElement to add items
      */
     highlightMenuItems(_highlight: HighlightType): MenuItem[];
 } & {
@@ -3542,7 +3554,7 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
 } & {
     afterCreate(): void;
     afterAttach(): void;
-}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, InitState, "bpPerPx" | "offsetPx" | "showCytobandsSetting">, {
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, InitState, "bpPerPx" | "colorByCDS" | "offsetPx" | "showCytobandsSetting">, {
     displayName: string | undefined;
     minimized: boolean;
     id: string;
@@ -3558,8 +3570,8 @@ export declare function stateModelFactory(pluginManager: PluginManager): import(
     trackSelectorType: "hierarchical";
     showCytobands: boolean;
     trackLabels: string;
-    showGridlines: boolean;
-    colorByCDS: boolean;
+    axis: import("@jbrowse/mobx-state-tree").ModelSnapshotType<Record<string, any>>;
+    colorByFrame: boolean;
     showAminoAcids: boolean;
     showTrackOutlines: boolean;
     scalebarOnly: boolean;