@mosaicajs/deck 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/basemap.d.ts

@@ -2,19 +2,17 @@ import type { Layer } from '@deck.gl/core';
 import { type Rgba, type Store, type ViewInfo } from '@mosaicajs/client';
 import type { DensityCamera } from './density-counter.js';
 /**
- * What is drawn under the points of one view:
+ * What to draw under the points of a view:
  *
- * - `'world'`: land, coastlines and country borders from the server's world outline
- *   (`GET /v1/basemaps/world`), projected as the view's positions were. Only on a view whose
- *   projection is not `none`.
+ * - `'world'`: land, coastlines and country borders from the server's world outline, projected as
+ *   the view's points are. Only for a view with a map projection.
  * - `'none'`: nothing.
- * - `{tiles, attribution}`: raster tiles from `tiles`, a URL template with `{z}`, `{x}` and `{y}`,
- *   composed at the camera's depth. `attribution` is the credit the tile server asks for. Only on a
- *   view with a {@link ViewInfo.tileScheme}. There is no default server.
- * - `{image, bounds}`: one image stretched over `bounds`, `[x0, y0, x1, y1]` in the view's own
- *   coordinates (longitude and latitude in degrees on a geographic view, whose corners are
- *   projected; x and y otherwise), or over the whole frame where `bounds` is left out. The image is
- *   not reprojected.
+ * - `{tiles, attribution}`: raster map tiles. `tiles` is the tile server's URL template, with
+ *   `{z}`, `{x}` and `{y}`, and `attribution` the credit the tile server asks for. Only for a view
+ *   with a {@link ViewInfo.tileScheme}. There is no default tile server.
+ * - `{image, bounds}`: one image, stretched over `bounds` without reprojection. `bounds` is
+ *   `[x0, y0, x1, y1]` in the view's own coordinates: longitude and latitude in degrees on a
+ *   geographic view, x and y otherwise. Leave it out to cover the whole frame.
  *
  * @category Basemaps
  */
@@ -43,15 +41,15 @@ export type WorldColours = {
  */
 export type BasemapOptions = {
     /**
-     * The ground the map draws on. The world outline is a little darker than a light ground and a
-     * little lighter than a dark one. Defaults to `light`.
+     * The map's background, `light` or `dark`. The world outline is drawn a little darker than a
+     * light background and a little lighter than a dark one. Defaults to `light`.
      */
     scheme?: 'light' | 'dark';
-    /** Colours in place of the world outline's own for `scheme`. */
+    /** Colours for the world outline in place of the defaults for `scheme`. */
     colours?: Partial<WorldColours>;
     /**
-     * The camera, for tiles: they are composed for the box it shows at its depth. Without it the
-     * whole frame is composed at a coarse depth.
+     * The current camera. Map tiles are fetched for the area it shows, at its zoom. Without it, tiles
+     * for the whole frame are fetched at a coarse zoom.
      */
     camera?: DensityCamera;
 };
@@ -103,29 +101,28 @@ export declare function isSingle(value: object): boolean;
  */
 export declare function withoutUndefined<T>(value: T): T;
 /**
- * Why `value` cannot be drawn under `view`, in a sentence that says what to write instead, or
- * `null` where it can: the world outline needs a map projection, and tiles a
+ * Why `value` cannot be drawn under `view`, as a sentence that says what to use instead, or `null`
+ * if it can. The world outline needs a view with a map projection, and map tiles need a view with a
  * {@link ViewInfo.tileScheme}.
  *
  * @category Basemaps
  */
 export declare function basemapMisfit(view: ViewInfo, value: BasemapValue): string | null;
 /**
- * The deck.gl layers that draw `value` under `view`, in the 512-unit world {@link MosaicaLayer}
- * draws in: put them before it in the `Deck`'s `layers`. `'none'` is no layers. The code that
- * draws a basemap is loaded the first time this is called, so a page that draws none does not load
- * it.
+ * The deck.gl layers that draw `value` under `view`. Put them before the {@link MosaicaLayer} in
+ * the `Deck`'s `layers`. For `'none'` the list is empty. The code that draws basemaps is loaded the
+ * first time you call this, so a page without a basemap never loads it.
  *
- * The world outline is fetched once per server ({@link Store.basemapWorld}) and placed once per
- * frame. Each call returns new layer instances over the geometry already placed, so deck.gl keeps
- * its buffers and every map gets layers of its own; for tiles, a camera that still shows the same
- * tiles draws the image already composed.
+ * For map tiles, call it again with the new `camera` when the camera moves. Repeated calls are
+ * cheap: the world outline is fetched once per server, and a camera that still shows the same
+ * tiles reuses the image already drawn.
  *
- * @param store - The store whose server serves the world outline.
+ * @param store - The store, whose server serves the world outline.
  * @param view - The view drawn, from `meta.views`.
  * @param value - What to draw.
- * @throws `Error` where `value` is not one of the forms or does not fit `view` ({@link basemapMisfit}), and where the world
- *   outline does not load or is in a format this client does not read.
+ * @param options - The background, colours and camera.
+ * @returns The layers. Rejects with `Error` if `value` is not a valid basemap or does not suit
+ *   `view` (see {@link basemapMisfit}), or if the world outline fails to load.
  *
  * @category Basemaps
  */

package/dist/basemap.js

@@ -115,8 +115,8 @@ const FORMS = [
     ]
 ];
 /**
- * Why `value` cannot be drawn under `view`, in a sentence that says what to write instead, or
- * `null` where it can: the world outline needs a map projection, and tiles a
+ * Why `value` cannot be drawn under `view`, as a sentence that says what to use instead, or `null`
+ * if it can. The world outline needs a view with a map projection, and map tiles need a view with a
  * {@link ViewInfo.tileScheme}.
  *
  * @category Basemaps
@@ -132,21 +132,20 @@ export function basemapMisfit(view, value) {
     return null;
 }
 /**
- * The deck.gl layers that draw `value` under `view`, in the 512-unit world {@link MosaicaLayer}
- * draws in: put them before it in the `Deck`'s `layers`. `'none'` is no layers. The code that
- * draws a basemap is loaded the first time this is called, so a page that draws none does not load
- * it.
+ * The deck.gl layers that draw `value` under `view`. Put them before the {@link MosaicaLayer} in
+ * the `Deck`'s `layers`. For `'none'` the list is empty. The code that draws basemaps is loaded the
+ * first time you call this, so a page without a basemap never loads it.
  *
- * The world outline is fetched once per server ({@link Store.basemapWorld}) and placed once per
- * frame. Each call returns new layer instances over the geometry already placed, so deck.gl keeps
- * its buffers and every map gets layers of its own; for tiles, a camera that still shows the same
- * tiles draws the image already composed.
+ * For map tiles, call it again with the new `camera` when the camera moves. Repeated calls are
+ * cheap: the world outline is fetched once per server, and a camera that still shows the same
+ * tiles reuses the image already drawn.
  *
- * @param store - The store whose server serves the world outline.
+ * @param store - The store, whose server serves the world outline.
  * @param view - The view drawn, from `meta.views`.
  * @param value - What to draw.
- * @throws `Error` where `value` is not one of the forms or does not fit `view` ({@link basemapMisfit}), and where the world
- *   outline does not load or is in a format this client does not read.
+ * @param options - The background, colours and camera.
+ * @returns The layers. Rejects with `Error` if `value` is not a valid basemap or does not suit
+ *   `view` (see {@link basemapMisfit}), or if the world outline fails to load.
  *
  * @category Basemaps
  */

package/dist/camera.d.ts

@@ -7,26 +7,26 @@ export type OrthographicCamera = {
     zoom: number;
 };
 /**
- * Converts a deck.gl `OrthographicView` camera over the 512-unit world into the input
- * `store.setView` takes: the box the canvas covers, clamped to the world and converted to data
- * coordinates through the store's frame, the camera's zoom, and the canvas size.
+ * Converts a deck.gl `OrthographicView` camera into the {@link ViewInput} that the store's
+ * `setView` takes. Call it whenever the view state or the canvas size changes. The box the canvas
+ * shows is clamped to the world and converted to the current view's data coordinates.
  *
- * @param store - The store whose frame converts world units to data coordinates.
+ * @param store - The store, which converts world units to data coordinates.
  * @param camera - The view state's `target` and `zoom`.
  * @param width - The canvas width in CSS pixels.
  * @param height - The canvas height in CSS pixels.
- * @returns The view input, or `null` before `meta` has arrived, when the store has no frame.
+ * @returns The view input, or `null` until the store has `/v1/meta`.
  */
 export declare function viewInputOf(store: Pick<Store, 'frame' | 'dataXY'>, camera: OrthographicCamera, width: number, height: number): ViewInput | null;
 /**
- * The camera that fits a box of the 512-unit world into a canvas: centred on the box, at the zoom
- * where the box takes `fill` of the canvas along whichever side limits it, and at most
- * {@link MAX_DEPTH}. The rest of the canvas is the margin round the box.
+ * The deck.gl camera that fits a box of the world into a canvas. It centres the box and zooms until
+ * the box fills `fill` of the canvas's width or height, whichever it reaches first, up to a zoom of
+ * {@link MAX_DEPTH}. Spread the result into the `OrthographicView` view state.
  *
  * @param box - `[x0, y0, x1, y1]` in world units, as {@link frameMatches} gives it.
  * @param width - The canvas width in CSS pixels.
  * @param height - The canvas height in CSS pixels.
- * @param fill - The share of the canvas the box takes, 0.92 unless given.
+ * @param fill - The share of the canvas the box fills.
  */
 export declare function cameraFitting(box: readonly [number, number, number, number], width: number, height: number, fill?: number): {
     target: [number, number, number];

package/dist/camera.js

@@ -1,15 +1,15 @@
 import { MAX_DEPTH } from '@mosaicajs/client';
 import { worldBbox } from '@mosaicajs/client/internal';
 /**
- * Converts a deck.gl `OrthographicView` camera over the 512-unit world into the input
- * `store.setView` takes: the box the canvas covers, clamped to the world and converted to data
- * coordinates through the store's frame, the camera's zoom, and the canvas size.
+ * Converts a deck.gl `OrthographicView` camera into the {@link ViewInput} that the store's
+ * `setView` takes. Call it whenever the view state or the canvas size changes. The box the canvas
+ * shows is clamped to the world and converted to the current view's data coordinates.
  *
- * @param store - The store whose frame converts world units to data coordinates.
+ * @param store - The store, which converts world units to data coordinates.
  * @param camera - The view state's `target` and `zoom`.
  * @param width - The canvas width in CSS pixels.
  * @param height - The canvas height in CSS pixels.
- * @returns The view input, or `null` before `meta` has arrived, when the store has no frame.
+ * @returns The view input, or `null` until the store has `/v1/meta`.
  */
 export function viewInputOf(store, camera, width, height) {
     if (!store.frame())
@@ -20,14 +20,14 @@ export function viewInputOf(store, camera, width, height) {
     return { bbox: [x0, y0, x1, y1], zoom: camera.zoom, width, height };
 }
 /**
- * The camera that fits a box of the 512-unit world into a canvas: centred on the box, at the zoom
- * where the box takes `fill` of the canvas along whichever side limits it, and at most
- * {@link MAX_DEPTH}. The rest of the canvas is the margin round the box.
+ * The deck.gl camera that fits a box of the world into a canvas. It centres the box and zooms until
+ * the box fills `fill` of the canvas's width or height, whichever it reaches first, up to a zoom of
+ * {@link MAX_DEPTH}. Spread the result into the `OrthographicView` view state.
  *
  * @param box - `[x0, y0, x1, y1]` in world units, as {@link frameMatches} gives it.
  * @param width - The canvas width in CSS pixels.
  * @param height - The canvas height in CSS pixels.
- * @param fill - The share of the canvas the box takes, 0.92 unless given.
+ * @param fill - The share of the canvas the box fills.
  */
 export function cameraFitting(box, width, height, fill = 0.92) {
     const across = Math.abs(box[2] - box[0]) || 1;

package/dist/colour.d.ts

@@ -28,8 +28,7 @@ export declare const UNMAPPED: Rgba;
  */
 export type CategoryPaletteName = 'tableau10' | 'okabe-ito' | 'set2' | 'dark2';
 /**
- * A qualitative palette: its title, whether it stays distinguishable under the common colour-vision
- * deficiencies, and its colours in rank order.
+ * A qualitative palette, for colouring a category column.
  *
  * @category Colour
  */
@@ -42,9 +41,9 @@ export type CategoryPalette = {
     colours: readonly Rgb[];
 };
 /**
- * The qualitative palettes, by name. A value's colour is the palette's entry at its rank among the
- * values drawn, ordered by frequency; a value ranked past the palette's end is drawn in
- * {@link UNMAPPED} and listed as "Other".
+ * The qualitative palettes, by name. The most frequent category values among the marks drawn take
+ * the palette's colours in order, and a value keeps its colour as the camera moves. Values past the
+ * end of the palette are drawn grey.
  *
  * @category Colour
  */
@@ -58,8 +57,8 @@ export declare const CATEGORY_PALETTES: Readonly<Record<CategoryPaletteName, Cat
  */
 export type RampName = 'viridis' | 'cividis' | 'magma' | 'greys' | 'red-blue';
 /**
- * A colour ramp: its title, whether it diverges from a midpoint, and its stops from the low end to
- * the high end, interpolated linearly in RGB.
+ * A colour ramp, for colouring a number column. Colours between its stops are interpolated
+ * linearly in RGB.
  *
  * @category Colour
  */
@@ -67,8 +66,8 @@ export type Ramp = {
     /** The ramp's name as a menu shows it. */
     title: string;
     /**
-     * Whether the ramp diverges from a midpoint: zero where the range spans zero, else the middle of
-     * the range. The midpoint takes the ramp's middle colour.
+     * Whether the ramp diverges from a midpoint, which takes the ramp's middle colour. The midpoint
+     * is zero if the range spans zero, and the middle of the range otherwise.
      */
     diverging: boolean;
     /** The stops from the low end to the high end. */
@@ -81,38 +80,38 @@ export type Ramp = {
  */
 export declare const RAMPS: Readonly<Record<RampName, Ramp>>;
 /**
- * How a number is placed on a ramp: `linear` in the value, or `log`, which places
- * `log(1 + (v − min))` so that a long tail does not push most values into one colour. On a
- * diverging ramp, `log` applies either side of the midpoint.
+ * How a number is placed on a ramp: `linear`, in proportion to the value, or `log`, in proportion
+ * to `log(1 + (v − min))`, so that a long tail does not push most values into one colour. On a
+ * diverging ramp, `log` applies on each side of the midpoint.
  *
  * @category Colour
  */
 export type RampScale = 'linear' | 'log';
 /**
- * The colour choices for a column: the palette for a category, the ramp for a number, and colours
- * chosen for single category values. The same choices colour the marks and the legend.
+ * How to colour marks by a column: a palette for a category column, a ramp for a number column,
+ * and any colours you choose for single category values. The same choices colour the legend.
  *
  * @category Colour
  */
 export type Colouring = {
-    /** The palette a category column's values take in order of rank. */
+    /** The palette for a category column. */
     palette: CategoryPaletteName;
-    /** The ramp a number column's values are placed on. */
+    /** The ramp for a number column. */
     ramp: RampName;
     /** How a number is placed on the ramp. */
     scale: RampScale;
     /** Whether the ramp runs from its high end to its low end. */
     reverse: boolean;
     /**
-     * Colours chosen for single category values, per column, per category key, as `#rrggbb`. A value
-     * named here takes this colour in place of its palette colour. A key that is not a drawn value of
-     * the column colours nothing.
+     * Colours you choose for single category values, as `#rrggbb`, keyed by column and then by
+     * category key. A chosen colour replaces the value's palette colour. A key that is not among the
+     * column's drawn values has no effect.
      */
     values: Readonly<Record<string, Readonly<Record<string, string>>>>;
 };
 /**
- * The colouring with nothing chosen: Tableau 10, Viridis on a linear scale, and no value's colour
- * chosen.
+ * The default colouring: Tableau 10 for categories, Viridis on a linear scale for numbers, and no
+ * chosen colours.
  *
  * @category Colour
  */

package/dist/colour.js

@@ -10,9 +10,9 @@ export const UNIFORM = [120, 190, 255, ALPHA];
 export const UNMAPPED = [110, 118, 132, ALPHA];
 const hex = (h) => [parseInt(h.slice(1, 3), 16), parseInt(h.slice(3, 5), 16), parseInt(h.slice(5, 7), 16)];
 /**
- * The qualitative palettes, by name. A value's colour is the palette's entry at its rank among the
- * values drawn, ordered by frequency; a value ranked past the palette's end is drawn in
- * {@link UNMAPPED} and listed as "Other".
+ * The qualitative palettes, by name. The most frequent category values among the marks drawn take
+ * the palette's colours in order, and a value keeps its colour as the camera moves. Values past the
+ * end of the palette are drawn grey.
  *
  * @category Colour
  */
@@ -55,8 +55,8 @@ export const RAMPS = {
     'red-blue': { title: 'Red–Blue, diverging', diverging: true, stops: ['#b2182b', '#ef8a62', '#f7f7f7', '#67a9cf', '#2166ac'].map(hex) }
 };
 /**
- * The colouring with nothing chosen: Tableau 10, Viridis on a linear scale, and no value's colour
- * chosen.
+ * The default colouring: Tableau 10 for categories, Viridis on a linear scale for numbers, and no
+ * chosen colours.
  *
  * @category Colour
  */

package/dist/density-counter.d.ts

@@ -1,26 +1,25 @@
 import { type Store } from '@mosaicajs/client';
 import { type DensityCounts } from './density.js';
 /**
- * The cell sizes on screen density's resolution is chosen from, in CSS pixels, coarse to fine.
+ * The cell sizes on screen that density can be drawn at, in CSS pixels, from coarse to fine.
  *
  * @category Colour
  */
 export declare const DENSITY_CELL_SIZES: readonly number[];
 /**
- * The cell size density is drawn at until one is chosen, in CSS pixels.
+ * The cell size density is drawn at by default, in CSS pixels.
  *
  * @category Colour
  */
 export declare const DEFAULT_DENSITY_CELL_PX = 12;
 /**
- * How long the camera rests before {@link DensityCounter} asks for counts, in milliseconds.
+ * How long the camera must rest before {@link DensityCounter} fetches counts, in milliseconds.
  *
  * @category Colour
  */
 export declare const DENSITY_SETTLE_MS = 200;
 /**
- * A camera over the 512-unit world, as deck's `OrthographicView` view state holds it, with the
- * canvas size.
+ * A deck.gl `OrthographicView` camera over the 512-unit world, with the canvas size.
  *
  * @category Colour
  */
@@ -35,79 +34,67 @@ export type DensityCamera = {
     height: number;
 };
 /**
- * One resolution stop: its cell size on screen, the depth whose cells come closest to it at the
- * camera's zoom, and whether that depth's cells over the asked area fit
- * `selection.maxAggregateCells`.
+ * One cell size density can be drawn at, at the current camera. A menu of resolutions can disable
+ * the stops that are not `enabled`.
  *
  * @category Colour
  */
 export type ResolutionStop = {
     /** The cell size on screen, in CSS pixels. */
     px: number;
-    /** The depth whose cells are nearest that size at the camera's zoom. */
+    /** The depth of the cells fetched for this size at the camera's zoom (see {@link DensityCounts}). */
     depth: number;
-    /** Whether that depth's cells over the area asked for number at most `selection.maxAggregateCells`. */
+    /** Whether the server's `selection.maxAggregateCells` allows this many cells over the area fetched. */
     enabled: boolean;
 };
 /**
- * What {@link DensityCounter} asks for.
+ * The settings {@link DensityCounter.set} takes.
  *
  * @category Colour
  */
 export type DensitySettings = {
-    /** Whether density is drawn. Off, nothing is asked for and nothing is held. */
+    /** Whether density is drawn. While it is off, the counter fetches nothing and holds nothing. */
     on: boolean;
-    /** The cell size on screen, in CSS pixels, taken as the nearest of {@link DENSITY_CELL_SIZES}. */
+    /** The cell size on screen in CSS pixels, rounded to the nearest of {@link DENSITY_CELL_SIZES}. */
     cellPx: number;
 };
 /**
- * The depth whose cells are closest to `cellPx` across on screen at `zoom`, nearest on a log scale.
- * A cell at depth `d` is `WORLD_SIZE · 2^zoom / 2^d` pixels wide.
+ * The depth whose cells are closest to `cellPx` wide on screen at `zoom`, measured on a log scale.
+ * A cell at depth `d` is `512 · 2^zoom / 2^d` pixels wide.
  *
  * @category Colour
  */
 export declare function cellDepth(zoom: number, cellPx: number): number;
 /**
- * The stops of {@link DENSITY_CELL_SIZES} at `camera`, each with the depth it asks for and whether
- * that depth fits `limit` cells over the area asked for.
+ * Each size in {@link DENSITY_CELL_SIZES} at `camera`, with its depth and whether its cells over
+ * the area fetched number at most `limit`, the server's `selection.maxAggregateCells`.
  *
  * @category Colour
  */
 export declare function resolutionStops(camera: DensityCamera, limit: number): ResolutionStop[];
 /**
- * The stop of {@link DENSITY_CELL_SIZES} nearest `px` on a log scale.
+ * The size in {@link DENSITY_CELL_SIZES} nearest `px`, measured on a log scale.
  *
  * @category Colour
  */
 export declare function nearestStop(px: number): number;
 /**
- * Keeps the counts density is drawn from for a camera: one `POST /v1/aggregate` grouping of cells,
- * registered with the store, which sends its filters and its highlight with it and asks again when
- * either changes. The counts are the highlighted items' under a highlight and the filtered items'
- * otherwise.
+ * Fetches the counts that density is drawn from, for the area around a camera. It registers an
+ * aggregate with the store, so the counts cover only what the viewer may see under the store's
+ * filters, and it fetches again when the filters, the highlight or the store's view (coordinate
+ * system) change. While a
+ * highlight is set, it counts the highlighted items.
  *
- * A camera change asks nothing while the camera moves. {@link DENSITY_SETTLE_MS} after the last
- * one, the counter works out the depth whose cells are nearest the chosen size on screen and asks
- * for that depth over the viewport and a margin, unless the counts asked for last are at that depth
- * and their area holds the viewport. The same request asks for up to {@link RINGS} coarser levels,
- * each a depth coarser over twice the reach, as the points' ring is fetched coarser further out. A
- * move that leaves the finest area asked for drops the registration at once, so a filter changed
- * during the move asks nothing for an area no longer shown. The counts held are drawn at their own
- * world positions until the next answer lands, so a zoom scales them with the map and a pan within
- * the margin asks nothing: the finest level held whose area holds the viewport is drawn, so a zoom
- * out draws the coarser levels' counts to the edges, and where no level holds it the widest is
- * drawn. A view switch asks again at once.
+ * Tell it where the camera is with `look` and what to draw with `set`. Once the camera has rested
+ * for {@link DENSITY_SETTLE_MS}, it fetches cells of about the chosen size on screen over the
+ * viewport and a margin round it, so a short pan needs no new request. Until the first answer for
+ * the view arrives, or after the server refuses one, `counts` returns the coarser counts that come
+ * with the map's tiles. After that it returns the last answer until the next one arrives.
+ * `onChange` is called whenever the counts to draw change.
  *
- * A depth whose cells over the area would pass `selection.maxAggregateCells` is never asked for.
- * Where the server refuses a request with `422` anyway, the counter asks one depth coarser, up to
- * three times. After any other refusal it drops the answer it held, so density is drawn from the
- * frame's tile counts as below, and it asks again at the camera's next rest.
- *
- * Until an answer is held for the view, density is drawn from the counts the frame's tiles carry,
- * which land with each viewport response ahead of its points. They count the same items, at the
- * tiles' coarser cells, and are not drawn once an answer is held.
- *
- * `onChange` is called when the counts to draw change.
+ * A {@link MosaicaLayer} with a `store` keeps a counter of its own. Make one yourself and pass it
+ * as the layer's `densityCounter` if your own code also needs the counts, as `<mosaica-map>` does
+ * for its density key.
  *
  * @category Colour
  */
@@ -128,23 +115,31 @@ export declare class DensityCounter {
     /** The tiles projection last read, and the counts derived from it. */
     private tiles;
     private readonly unsubscribe;
+    /**
+     * @param store - The store to fetch through.
+     * @param onChange - Called whenever the counts to draw change.
+     * @param settleMs - How long the camera must rest before counts are fetched, in milliseconds.
+     */
     constructor(store: Store, onChange: () => void, settleMs?: number);
-    /** The camera moved or the canvas was resized. Counts are asked for once it has rested. */
+    /** Tell the counter the camera has moved or the canvas has been resized. */
     look(camera: DensityCamera): void;
-    /** What to draw. Off drops the registration and the counts held at once. */
+    /** Turn density on or off and choose the cell size. Turning it off drops the counts held. */
     set(settings: DensitySettings): void;
     /**
-     * The counts to draw: the last answer, while it was counted in the store's current view, and
-     * until there is one the frame's tile counts. Nothing while density is off.
+     * The counts to draw, or `null` while density is off or there are none. Until the first answer
+     * for the current view arrives, these are the coarser counts that come with the map's tiles.
      */
     counts(): DensityCounts | null;
     /** The finest level held whose area holds the viewport, else the widest; null where none is held for the view. */
     private answered;
     /** The frame's tile counts at its depth, derived once per tiles projection; null where none. */
     private tileCounts;
-    /** The resolution stops at the camera as it stands; every stop is enabled before a camera and `meta`. */
+    /**
+     * The cell sizes density can be drawn at for the current camera. Every stop is enabled until the
+     * counter has a camera and the store has `meta`.
+     */
     stops(): ResolutionStop[];
-    /** Drop the registration and stop following the store. */
+    /** Stop fetching counts and unsubscribe from the store. */
     dispose(): void;
     private schedule;
     /** Ask for the counts at the camera, unless what was asked for last holds the viewport; `force` asks regardless. */