@jax-data-science/sci-image-visualizer 0.3.3 → 0.5.0

package/lib/contracts/spatial-dataset.contract.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Backend-neutral data model for a **spatial-omics dataset**: N observations
+ * (Visium spots, segmented cells, nuclei, …) positioned in the pixel space of a
+ * tissue image, each carrying categorical and continuous annotations, plus an
+ * optional feature (gene) matrix and optional per-observation boundaries.
+ *
+ * DESIGN
+ * ------
+ * 1. **Struct-of-arrays, not object-per-cell.** Real datasets run 10^3 (Visium)
+ *    to 10^6 (Xenium/CosMx) observations. `{x, y}[]` at 500k cells is ~500k
+ *    objects the GC has to walk; two `Float32Array`s are two allocations and
+ *    upload to the GPU without a copy.
+ *
+ * 2. **Metadata is eager, values are lazy.** A dataset advertises *which*
+ *    columns and features exist ({@link SpatialColumnMeta},
+ *    {@link SpatialFeatureMeta}); the vectors themselves are fetched on demand
+ *    through {@link SpatialDataPort}. A Visium table is ~30k genes wide — the
+ *    dense matrix is ~800 MB — so "load the dataset" can never mean "load the
+ *    matrix". Only the handful of columns actually being displayed is resident.
+ *
+ * 3. **Data stays data.** No I/O, no RxJS, no Angular in this file — the same
+ *    rule `plotly-trace-builders.ts` follows. Fetching lives on the port.
+ *
+ * The shape mirrors how the field already stores this (SpatialData/AnnData:
+ * `obs` annotations, `var` features, `obsm/spatial` coordinates, shapes with a
+ * coordinate transform) so an adapter is a projection, not a translation.
+ */
+/**
+ * Observation positions. Every array is length {@link count} and index-aligned:
+ * observation `i` is at `(x[i], y[i])`, and column/feature vectors index the
+ * same way. This shared index is the join key for the whole model.
+ */
+export interface SpatialObservations {
+    /** N — number of observations. */
+    readonly count: number;
+    /** X in the reference image's pixel space (see {@link SpatialImageRef}). */
+    x: Float32Array;
+    /** Y in the reference image's pixel space. */
+    y: Float32Array;
+    /** Z, for serial sections or genuinely 3D assays. Absent for a single plane. */
+    z?: Float32Array;
+    /** Stable per-observation ids (barcodes, cell ids) for tooltips and export.
+     *  Optional — omit for large datasets where the strings cost more than they
+     *  are worth. */
+    ids?: string[];
+    /** Marker RADIUS in image pixels: one value shared by all observations (a
+     *  Visium spot is a fixed 55 µm ⇒ `27.5 / mppX` px), or one per observation
+     *  (segmented cells). Absent ⇒ the renderer picks a display default. */
+    radius?: Float32Array | number;
+}
+/** Fields common to every column descriptor. */
+interface SpatialColumnMetaBase {
+    /** Column name as the user sees it (`leiden`, `total_counts`). */
+    name: string;
+    /** Longer human-readable description for tooltips/menus. */
+    description?: string;
+}
+/**
+ * A discrete annotation — cluster, cell type, region, sample. Rendered as a
+ * palette + legend; a legend click selects the category's observations.
+ */
+export interface CategoricalColumnMeta extends SpatialColumnMetaBase {
+    kind: 'categorical';
+    /** Category labels; a value's label is `categories[codes[i]]`. */
+    categories: string[];
+    /** Authored display colours as `#rrggbb`, index-aligned with
+     *  {@link categories}. Supply these to keep the viewer's palette identical to
+     *  the figures the same analysis produced in R/Python; omit to let the viewer
+     *  derive one. */
+    colors?: string[];
+}
+/**
+ * A continuous measurement — expression, QC metric, area, density. Rendered
+ * through the shared colormap/LUT + contrast window.
+ */
+export interface ContinuousColumnMeta extends SpatialColumnMetaBase {
+    kind: 'continuous';
+    /** Unit for axis/tooltip labels (`counts`, `µm²`). */
+    unit?: string;
+    /** True when the column reads best log-scaled — count data almost always
+     *  does, and a linear scale collapses it against a few bright outliers. */
+    logScaleHint?: boolean;
+    /** Observed extremes, when the producer knows them. Lets the UI seed a
+     *  contrast window and axis range without first scanning the vector. */
+    min?: number;
+    max?: number;
+}
+export type SpatialColumnMeta = CategoricalColumnMeta | ContinuousColumnMeta;
+/**
+ * Code meaning "this observation has no category" (unassigned / filtered out /
+ * not in tissue). Renderers should draw it in the muted background style rather
+ * than as a real category, and it must never index {@link
+ * CategoricalColumnMeta.categories}.
+ */
+export declare const NO_CATEGORY = 65535;
+/** A loaded categorical column: per-observation indices into `meta.categories`,
+ *  or {@link NO_CATEGORY}. */
+export interface CategoricalColumn {
+    meta: CategoricalColumnMeta;
+    /** Length = {@link SpatialObservations.count}. */
+    codes: Uint16Array;
+}
+/** A loaded continuous column. `NaN` marks a missing value. */
+export interface ContinuousColumn {
+    meta: ContinuousColumnMeta;
+    /** Length = {@link SpatialObservations.count}. */
+    values: Float32Array;
+}
+export type SpatialColumn = CategoricalColumn | ContinuousColumn;
+export declare function isCategoricalColumn(c: SpatialColumn): c is CategoricalColumn;
+export declare function isContinuousColumn(c: SpatialColumn): c is ContinuousColumn;
+/**
+ * The feature (gene) matrix, described but never delivered whole. Vectors come
+ * one at a time from {@link SpatialDataPort.getFeatureVector}.
+ */
+export interface SpatialFeatureMeta {
+    /** Number of features available. */
+    count: number;
+    /**
+     * All feature names, when the producer chose to inline them. Present for
+     * targeted panels (Xenium/CosMx ship 300–5,000 genes ⇒ a few dozen KB) and
+     * absent for whole-transcriptome data (Visium ships ~31k ⇒ ~350 KB), where
+     * the UI should use {@link SpatialDataPort.searchFeatures} for typeahead
+     * instead of downloading the list. Consumers must handle both.
+     */
+    names?: string[];
+    /** What a feature value means (`log1p normalized`, `raw counts`). */
+    unit?: string;
+    /** True when feature vectors read best log-scaled (raw counts). */
+    logScaleHint?: boolean;
+}
+/**
+ * Per-observation boundaries (cell/nucleus segmentation, spot outlines) as flat
+ * rings — deliberately NOT GeoJSON objects, which cost one object + one array
+ * per cell and would dominate memory at 10^5 polygons.
+ *
+ * Ring `i` occupies `coords[2*offsets[i] .. 2*offsets[i+1])` as `x0,y0,x1,y1,…`
+ * and is implicitly closed. `offsets` has length `count + 1`.
+ */
+export interface SpatialPolygons {
+    coords: Float32Array;
+    offsets: Uint32Array;
+    /** Number of rings — `offsets.length - 1`. */
+    readonly count: number;
+}
+/** Presence/size of the boundary geometry, without loading it. */
+export interface SpatialPolygonsMeta {
+    count: number;
+}
+/**
+ * How observation coordinates relate to the tissue image they are drawn over.
+ * Applied as `world = coord * scale + translate`, matching the affine that
+ * SpatialData records per coordinate system — and the full-resolution world
+ * convention the napari-js backend already uses so pre-saved regions align on
+ * pyramidal slides.
+ */
+export interface SpatialImageRef {
+    /** Host-defined id of the image these coordinates live in, so the host can
+     *  resolve it to an `IImageInfo`. */
+    imageId?: string;
+    /** Data→world scale. Defaults to `[1, 1]` (coordinates already in
+     *  full-resolution image pixels). */
+    scale?: [number, number];
+    /** Data→world translation, in the same units as {@link scale}'s output. */
+    translate?: [number, number];
+    /** Physical pixel size in µm — drives the scale bar and physical marker
+     *  sizing (a 55 µm Visium spot). */
+    mppX?: number;
+    mppY?: number;
+}
+/**
+ * A spatial-omics dataset: everything cheap enough to hold resident. Column and
+ * feature *values*, and polygon *geometry*, are fetched through
+ * {@link SpatialDataPort} as they are displayed.
+ */
+/**
+ * A precomputed low-dimensional embedding over the SAME observations — UMAP, t-SNE, PCA.
+ *
+ * Announced in the dataset and fetched on demand, exactly like a column or a gene: the
+ * coordinates are another per-observation vector, and a dataset may carry several.
+ */
+export interface SpatialEmbeddingMeta {
+    /** Key as the source names it, e.g. `X_umap`. */
+    name: string;
+    /** Short label for menus; falls back to {@link name}. */
+    label?: string;
+    /** 2 for a plane, 3 for a cloud. */
+    dims: 2 | 3;
+    /**
+     * True when the coordinates were COMPUTED for this bundle rather than published with the
+     * dataset. Worth surfacing: a UMAP recomputed with different parameters is a different picture,
+     * and a reader comparing against a paper's figure needs to know which they are looking at.
+     */
+    derived?: boolean;
+    /**
+     * Fraction of total variance each axis accounts for, index-aligned with the dimensions.
+     *
+     * Only meaningful for a LINEAR embedding — PCA. Its axes are ordered, and each one explains a
+     * measurable share of the variance, which is the whole reason to look at a PCA rather than a
+     * UMAP: "PC1 (23%)" says something, where "UMAP 1" says nothing at all. A UMAP's coordinates
+     * are an arbitrary output of an optimisation with no variance to report, so this stays absent
+     * there rather than being faked.
+     */
+    varianceRatio?: number[];
+    /**
+     * How a derived embedding was computed, in a few words — e.g. "PCA(50) then perplexity 30,
+     * seed 0".
+     *
+     * Not decoration. A t-SNE or UMAP is stochastic, and its picture changes materially with
+     * perplexity or `n_neighbors`; two runs at different settings are different pictures of the same
+     * cells, and neither is more correct. Saying "computed here" without saying HOW leaves a reader
+     * unable to reproduce or compare it. Absent for a published embedding, whose parameters belong
+     * to whoever published it.
+     */
+    params?: string;
+}
+/**
+ * One embedding's coordinates.
+ *
+ * Deliberately shaped like {@link SpatialObservations}' `x`/`y`/`z` rather than an (N, D) matrix:
+ * the point of an embedding here is to be swapped in as the scatter's coordinate source, and
+ * matching that shape means the renderer, the hover hit-test and the selection code need no
+ * variant for it.
+ */
+export interface SpatialEmbedding {
+    meta: SpatialEmbeddingMeta;
+    x: Float32Array;
+    y: Float32Array;
+    z?: Float32Array;
+}
+export interface SpatialDataset {
+    /** Stable id — the key the port's lazy accessors are scoped to. */
+    id: string;
+    /** Human-readable name for menus. */
+    name: string;
+    observations: SpatialObservations;
+    /** Every column available, whether or not its values are loaded. */
+    columns: SpatialColumnMeta[];
+    features?: SpatialFeatureMeta;
+    polygons?: SpatialPolygonsMeta;
+    imageRef?: SpatialImageRef;
+    /** Presence + geometry of a reference volume the observations sit inside. */
+    volume?: SpatialVolumeMeta;
+    /** Embeddings available for these observations, whose coordinates are fetched on demand. */
+    embeddings?: SpatialEmbeddingMeta[];
+    /**
+     * Microns per observation coordinate unit — what makes a scale bar possible.
+     *
+     * The 2D path gets this from `imageRef.mppX`, because there the coordinates are
+     * image pixels. A 3D cloud has no image, so it has to say for itself: `1` means
+     * the coordinates are already microns.
+     *
+     * Absent means the unit is UNKNOWN, and a renderer must then draw no scale bar
+     * rather than assume one. A bar labelled in microns over pixel-space
+     * coordinates is worse than no bar: it looks like a measurement.
+     */
+    micronsPerUnit?: number;
+}
+/**
+ * A 3D scalar reference volume registered to the observation coordinates — the
+ * anatomical backdrop for a point cloud (an atlas template, or an image z-stack).
+ *
+ * Geometry only; the voxels are fetched through
+ * {@link SpatialDataPort.getVolume} when something is going to draw them. A cloud
+ * without one still renders, just in empty space.
+ *
+ * The observations' coordinate frame must be the volume's own: voxel `(i, j, k)`
+ * covers `[i * voxelSize[0], (i + 1) * voxelSize[0])` on x, and so on. That means
+ * the volume's near corner sits at the coordinate origin, so a renderer can place
+ * the two together knowing nothing else.
+ */
+export interface SpatialVolumeMeta {
+    width: number;
+    height: number;
+    depth: number;
+    /** World size of one voxel per axis, in the observations' units. */
+    voxelSize: [number, number, number];
+}
+/** Look a column's descriptor up by name. */
+export declare function findColumnMeta(dataset: SpatialDataset, name: string): SpatialColumnMeta | undefined;
+export {};

package/lib/contracts/visualizer.contract.d.ts

@@ -7,7 +7,10 @@ import { PlotType, PlotTypeDescriptor } from './plot-type';
 import { ViewerCapabilities } from './capabilities.contract';
 import { IRegionOverlay } from './region-overlay.contract';
 import { IHistogram } from './channel-histogram-api.contract';
-import { ColormapNode, IWandOptions, IBrushOptions } from './display-types';
+import { ColormapNode, IWandOptions, IBrushOptions, SpatialViewState, SpatialColorBy } from './display-types';
+import { SpatialDataset, SpatialEmbedding } from './spatial-dataset.contract';
+import { SpatialSelectionMask } from '../spatial/spatial-selection';
+import type { PlotModeViewport } from './plot-type-contribution.contract';
 /**
  * Backend-neutral visualization contract. Plotly is one implementation;
  * OpenSeadragon is another (for the image plot type). The abstraction renders
@@ -270,6 +273,98 @@ export interface IIntensityControls {
      *  backend, or null if no image extent is known yet. */
     addProfileLine(): Region | null;
 }
+/** A categorical column resolved for charting: labels, codes and map colours. */
+export interface SpatialCategoricalView {
+    name: string;
+    categories: string[];
+    /** `#rrggbb` per category, index-aligned with {@link categories}. */
+    colors: string[];
+    /** Per-observation category index, or `NO_CATEGORY`. */
+    codes: Uint16Array;
+}
+/**
+ * Controls for the SPATIAL_OMICS plot type: what the observation markers are
+ * coloured by, and how they are drawn. Capability-gated like
+ * {@link IIsosurfaceControls} — `getSpatialControls()` returns null unless a
+ * host has bound `SPATIAL_DATA_PORT`.
+ *
+ * The view state is backend-neutral (it lives in the shared store, like the
+ * colormap), so these controls work whichever backend is on screen.
+ */
+export interface ISpatialControls {
+    /** The dataset being visualized, or null. Drives the column/gene pickers and
+     *  the legend. */
+    getDataset$(): Observable<SpatialDataset | null>;
+    /** Current display state (colour source, point scale, opacity, scaling). */
+    getViewState$(): Observable<SpatialViewState>;
+    /** Synchronous read, for seeding a control's initial value. */
+    viewState(): SpatialViewState;
+    /** Patch the display state; the markers rebuild without remounting the scene. */
+    setViewState(partial: Partial<SpatialViewState>): void;
+    /** Colour by an annotation column. Rejects for an unknown column. */
+    colorByColumn(name: string): void;
+    /** Colour by a gene; its vector is fetched on demand. */
+    colorByFeature(name: string): void;
+    /** Clear the colour source — every observation renders in one neutral colour. */
+    clearColorBy(): void;
+    /** Typeahead over feature names, for datasets too wide to inline the list. */
+    searchFeatures(query: string, limit?: number): Promise<string[]>;
+    /** Per-category display colours for a categorical column, index-aligned with
+     *  its `categories` — the legend's swatches, resolved the same way the
+     *  renderer resolves them so the two cannot disagree. */
+    categoryColors(name: string): Promise<string[]>;
+    /**
+     * The values behind a colour source, index-aligned with the observations.
+     * Rejects for a categorical column — there is nothing continuous to chart.
+     */
+    continuousValues(source: SpatialColorBy): Promise<Float32Array>;
+    /**
+     * A categorical column's categories, per-observation codes and display
+     * colours — everything a grouped violin/box needs, with the colours resolved
+     * the same way the map resolves them.
+     */
+    categoricalView(column: string): Promise<SpatialCategoricalView>;
+    /**
+     * One embedding's coordinates — a UMAP, t-SNE or PCA plane over the same observations.
+     *
+     * Optional, and absent when the data source serves none: `SpatialDataPort.getEmbedding`
+     * is itself optional, so a panel must be able to ask whether this exists rather than
+     * calling it and catching.
+     */
+    getEmbedding?(name: string): Promise<SpatialEmbedding>;
+    /** Names of the categorical columns available to group by. */
+    categoricalColumns(): string[];
+    /**
+     * The z positions of the sections the dataset was imaged at, ascending — or
+     * null when its z is continuous rather than sectioned (so there are no sections
+     * to offer) or when there is no dataset.
+     *
+     * Lets a panel offer "one section at a time" for the 3D cloud only where that
+     * means something, and label the chosen one. Scanned once per dataset.
+     */
+    sampledSections(): Float32Array | null;
+    /** The current selection. Empty means "nothing selected", in which case the
+     *  whole tissue renders normally rather than everything being muted. */
+    getSelection$(): Observable<SpatialSelectionMask>;
+    /**
+     * Select every observation inside the currently-drawn regions (their union).
+     * Reuses the existing ROI tools — rectangle, polygon, freehand, wand, brush —
+     * so there is no separate marquee to learn. Returns how many were selected.
+     */
+    selectFromRegions(): number;
+    /** Select every observation in one category of a categorical column — the
+     *  legend click. Rejects for an unknown or continuous column. */
+    selectCategory(column: string, categoryIndex: number): Promise<number>;
+    /**
+     * Select an explicit set of observations, replacing any current selection.
+     *
+     * For a linked plot: lassoing points in an embedding is a selection OF observations,
+     * and every other view — the map, the distributions — reads the same mask, so brushing
+     * one lights up the rest. Returns how many were selected.
+     */
+    selectIndices(indices: Iterable<number>): number;
+    clearSelection(): void;
+}
 /** Display options (colormap/LUT, reverse scale, image metadata). */
 export interface IDisplayOptions {
     getColormap(): Observable<ColormapNode | null>;
@@ -321,6 +416,14 @@ export interface IVisualizer extends IDataRenderer, IRegionStore, IToolControlle
      *  the capability-gated replacement for the deprecated top-level
      *  `setSurfaceDragMode`/`resetSurfaceCamera`. */
     getSurface3dControls(): ISurface3dControls | null;
+    /** Spatial-omics controls when a `SPATIAL_DATA_PORT` is bound, else null.
+     *  Optional: only the routing service implements it, since the state is shared
+     *  rather than owned by any one backend. */
+    getSpatialControls?(): ISpatialControls | null;
+    /** The viewport a contributed plot mode draws over, when the backend on
+     *  screen can provide one (OpenSeadragon), else null. Optional: backends that
+     *  no contributed mode rides on need not implement it. */
+    getPlotModeViewport?(): PlotModeViewport | null;
     /** Binned intensity histogram for a channel from the currently-displayed
      *  pixels, or null when none are available. Feeds the Channels & Histogram
      *  pane. */

package/lib/implementations/napari-js/napari-axes-labels.d.ts

@@ -20,14 +20,16 @@ export interface AxesLabelCamera3D {
     };
 }
 /**
- * Project a world point through a column-major 4×4 MVP to CSS-pixel screen coordinates.
- * Returns `visible: false` when the point is at/behind the camera (w ≤ 0). Pure — unit-tested.
+ * Re-exported from napari-js, which owns the projection now.
+ *
+ * This used to be a local copy: the same column-major multiply, perspective divide and y-flip
+ * that {@link NapariVisualizerService.getSpatialScreenProjection} ALSO carried, written twice
+ * with two different behind-the-eye conventions. The renderer owns the camera and the clip
+ * convention, so it owns the projection; kept as a named export here only so the overlays that
+ * import it from this module do not all have to change.
  */
-export declare function projectPoint(mvp: ArrayLike<number>, p: [number, number, number], vw: number, vh: number): {
-    x: number;
-    y: number;
-    visible: boolean;
-};
+import { projectPoint } from 'napari-js';
+export { projectPoint };
 export declare class NapariAxesLabels {
     private readonly host;
     private readonly camera3d;

package/lib/implementations/napari-js/napari-region-overlay.d.ts

@@ -1,7 +1,14 @@
 import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
 import { RegionStore } from '../../store/region-store.service';
-/** The slice of the napari Viewer the overlay needs (coord transforms + control gating). */
-interface OverlayViewer {
+/**
+ * The slice of the napari Viewer the overlay needs (coord transforms + control gating).
+ *
+ * Exported because the 3D spatial mode supplies a SCREEN-SPACE implementation of it: there the
+ * drawn shape is a lasso in canvas pixels, not a rectangle in image space, so "world" is the
+ * canvas itself and both transforms collapse to identity. That lets the 3D view reuse this whole
+ * overlay — every tool, the handles, the store round-trip — with no 3D-specific drawing code.
+ */
+export interface OverlayViewer {
     canvasToWorld(clientX: number, clientY: number): [number, number];
     worldToCanvas(worldX: number, worldY: number): [number, number];
     setControlsEnabled(enabled: boolean): void;
@@ -45,11 +52,39 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
      *  rectangle corner. `anchor` is the fixed opposite corner for a rectangle resize. */
     private edit;
     constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore);
+    /**
+     * Whether a region tool currently owns the pointer.
+     *
+     * Exposed so the spatial views can tell a bare click on the cloud (select the
+     * class under the cursor) from a click that belongs to a drawing gesture —
+     * placing a polygon vertex is also a click that does not move, and it must not
+     * change the selection behind the shape being drawn.
+     */
+    get toolActive(): boolean;
     setMode(mode: RegionToolMode): void;
     setSelectedBezier(bezier: boolean): void;
+    /**
+     * How finely a drawn vertex may be placed, in world units.
+     *
+     * One by default, because for an image the world IS pixels and a region should align to
+     * them. A dataset whose coordinates are not pixels sets it finer — seqFISH's whole
+     * sample spans about 5 x 7 units, where whole-unit vertices leave roughly six by eight
+     * placeable positions and no ROI can be drawn at all.
+     */
+    private worldQuantum;
+    setWorldQuantum(quantum: number): void;
     destroy(): void;
-    /** Pointer client coords → rounded image coords. */
+    /** Pointer client coords → world coords, snapped to {@link worldQuantum}. */
     private toImage;
+    /**
+     * World units spanned by one screen pixel, measured through the viewer's own transform.
+     *
+     * Read from the transform rather than from the camera, so it holds for both the 2D and
+     * the 3D screen-space adapters without either having to expose a zoom. Falls back to 1
+     * if the transform gives nothing usable, which keeps the established pixel behaviour
+     * rather than collapsing the threshold to zero and recording a point per event.
+     */
+    private worldPerCanvasPixel;
     /** Image coords → SVG-local px (the svg overlays the canvas at the same client rect). */
     private toLocal;
     private readonly onPointerDown;
@@ -112,4 +147,3 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private drawDraft;
     private styleDraft;
 }
-export {};

package/lib/implementations/napari-js/napari-scale-bar.d.ts

@@ -8,8 +8,13 @@
 /** Format a length given in micrometres, picking the unit that suits its magnitude (jit-service
  *  normalises whatever unit Bio-Formats reports to µm). */
 export declare function formatUm(um: number): string;
-/** The slice of the napari Camera the scale bar reads (zoom = CSS px per world/image pixel). */
-interface ScaleBarCamera {
+/**
+ * The slice of the napari Camera the scale bar reads (zoom = CSS px per world/image pixel).
+ *
+ * Exported so the 3D spatial view can satisfy it with a shim: an orbit camera has no `zoom`, but
+ * px-per-world-unit AT THE PIVOT DEPTH is well defined, and that is what a 3D scale bar means.
+ */
+export interface ScaleBarCamera {
     readonly zoom: number;
     readonly changed: {
         connect(listener: () => void): () => void;
@@ -28,4 +33,3 @@ export declare class NapariScaleBar {
     private update;
     destroy(): void;
 }
-export {};

package/lib/implementations/napari-js/napari-spatial-tooltip.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cursor tooltip naming the observation under the pointer, for the spatial-omics
+ * views — the same overlay-in-the-host pattern as {@link NapariScaleBar}.
+ *
+ * A 34-entry legend cannot be read back from a dot: several classes get similar
+ * colours, and matching one to a swatch by eye is the job a tooltip removes. It
+ * shows what the cloud is CURRENTLY coloured by, so it always agrees with the
+ * legend beside it.
+ *
+ * Deliberately not PrimeNG's `pTooltip`: that binds to an element, and these
+ * points are pixels in a WebGPU canvas with no DOM of their own.
+ */
+export declare class NapariSpatialTooltip {
+    private readonly host;
+    private readonly el;
+    private readonly primary;
+    private readonly secondary;
+    /** Gap between the cursor and the box, so the box never sits under the arrow. */
+    private static readonly OFFSET;
+    constructor(host: HTMLElement);
+    /**
+     * Show `lines` at a point given in HOST-relative pixels.
+     *
+     * Flips to the other side of the cursor near an edge rather than being clipped
+     * by the host — a tooltip half outside the plot is worse than one on the left.
+     */
+    show(lines: readonly string[], hostX: number, hostY: number): void;
+    hide(): void;
+    /** True while the box is on screen — for tests, and to skip redundant hides. */
+    get visible(): boolean;
+    dispose(): void;
+}