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

package/lib/contracts/display-types.d.ts

@@ -38,6 +38,16 @@ export interface IWandOptions {
 export interface IBrushOptions {
     /** Brush diameter in matrix (image) pixels. */
     size?: number;
+    /**
+     * Paint as one class: new regions take this label, and a stroke only extends
+     * or merges regions with the same label. Unset = the plain brush (label
+     * `'Region'`, extends any region). `setBrushMode(true, …)` sets the class in
+     * full; `setBrushOptions` changes it only when `label` or `color` is passed,
+     * so a size-only update keeps it.
+     */
+    label?: string;
+    /** Colour for the painted regions instead of the shape colour. Kept against preset re-apply. */
+    color?: string;
 }
 /** What drives point colour in the spatial-omics mode: an annotation column
  *  from the dataset, or one feature (gene) vector fetched on demand. */
@@ -103,7 +113,8 @@ export interface SpatialViewState {
      * setting for a backdrop and a useless one for the measurement.
      */
     volumeOpacity: number;
-    /** Draw the observation cloud (3D). */
+    /** Draw the observation markers — the 3D cloud, or the 2D circles. In 2D they also
+     *  stand in for cells too small on screen to outline. */
     showPoints: boolean;
     /**
      * Restrict the cloud to ONE imaged section, by index into the dataset's sampled
@@ -168,5 +179,97 @@ export interface SpatialViewState {
      *  the markers: turning the cells down to read the field underneath must not
      *  turn the field down with them. */
     geneMapOpacity: number;
+    /**
+     * Draw cell boundaries (for a dataset with `polygonTiles` or `polygons`).
+     *
+     * Outlines are level-of-detail: coarse rings when zoomed out, every vertex at the
+     * finest zoom, and none at all once a cell is a few pixels wide — there the
+     * observation markers already draw it as a dot.
+     *
+     * `null` (the default) means automatic: on for any dataset that has outlines, since a
+     * segmented cell is better shown as its shape than as a circle. A boolean is the
+     * user's explicit choice.
+     */
+    showCells: boolean | null;
+    /** Which boundary set (`cell`, `nucleus`, or `both` — cells as set by
+     *  {@link cellDraw}, nuclei outlined over them); null takes the dataset's default. */
+    cellSet: string | null;
+    /**
+     * What colours the cells — Xenium Explorer's "Cell Color": the active group
+     * ({@link cellTypeColumn}), one gene's expression ({@link cellColorGene}), the cell's
+     * transcript density, one flat colour, or how the cell was segmented.
+     */
+    cellColorMode: 'group' | 'gene' | 'transcriptDensity' | 'single' | 'segmentation';
+    cellColorGene: string | null;
+    /** `#rrggbb` for {@link cellColorMode} `single`. */
+    cellSingleColor: string;
+    /**
+     * Categories of {@link cellTypeColumn} switched off in the groups list: their cells are
+     * not drawn, nor the transcripts inside them. Cleared when the group column changes.
+     */
+    hiddenGroups: string[];
+    /** Draw the tissue image (the Images section's switch). */
+    showImage: boolean;
+    /** Draw the annotation regions (the Annotations section's switch). Selecting from them
+     *  still works while they are hidden. */
+    showAnnotations: boolean;
+    /** Fill the cells with their colour, outline them, or both. */
+    cellDraw: 'fill' | 'outline' | 'both';
+    /** Opacity of the cell fill (outlines draw opaque). */
+    cellOpacity: number;
+    /**
+     * The categorical column that says what TYPE each cell is: it colours the cells
+     * whenever nothing else is chosen, and it colours every transcript by the cell it
+     * falls in. Null picks the dataset's first categorical column. Swapping between a
+     * pipeline's clustering and a curated annotation is swapping this.
+     */
+    cellTypeColumn: string | null;
+    /** Genes whose transcripts are drawn. */
+    transcriptGenes: string[];
+    /** Selected genes switched off with their eye toggle — kept in the list, not drawn. */
+    transcriptHiddenGenes: string[];
+    /** Per-gene marker colour (`#rrggbb`); genes not listed take the palette by position. */
+    transcriptGeneColors: Record<string, string>;
+    /** Named gene groups (e.g. marker genes per cell type) for the selected-genes tree. */
+    transcriptGeneGroups: {
+        name: string;
+        genes: string[];
+    }[];
+    /**
+     * Draw EVERY gene's transcripts instead of {@link transcriptGenes}: grouped into bins
+     * sized by how many transcripts they hold, finer as the camera zooms in, down to one
+     * marker per transcript once those fit {@link transcriptBudget}.
+     */
+    transcriptAllGenes: boolean;
+    /**
+     * Most transcript markers drawn at once. The level of detail is chosen to stay under it,
+     * which is what keeps pan and zoom responsive however dense the data is.
+     */
+    transcriptBudget: number;
+    /**
+     * How transcripts are drawn: `circles` sized by how many transcripts each stands for,
+     * `glyphs` (one icon shape per gene), or a `density` raster. Circles and glyphs are
+     * level-of-detail — aggregated when zoomed out, one per transcript at the finest zoom.
+     */
+    transcriptMode: 'off' | 'circles' | 'glyphs' | 'density';
+    /** Colour transcripts by the type of the cell they fall in, or by gene. */
+    transcriptColorBy: 'cellType' | 'gene';
+    /** Glyph per gene for `glyphs` mode; genes not listed take one by position. */
+    transcriptGlyphs: Record<string, TranscriptGlyphName>;
+    /** Multiplier on transcript marker size. */
+    transcriptScale: number;
+    transcriptOpacity: number;
+    /** `high` keeps only confidently decoded transcripts. */
+    transcriptQuality: 'high' | 'all';
+    /** Opacity of the transcript density raster. */
+    densityOpacity: number;
+    /** Density bin edge in observation units (µm): 10, 20, 40 or 80. */
+    densityBin: number;
+    /** Colour window in transcripts per unit² (µm²); null derives it from the data. */
+    densityRange: [number, number] | null;
+    /** Colormap for the density bins; null uses Inferno. */
+    densityColormap: ColormapValue | null;
 }
+/** Transcript glyph names — see `TRANSCRIPT_GLYPHS` in `spatial/spatial-tiles.ts`. */
+export type TranscriptGlyphName = 'circle' | 'star' | 'triangle' | 'square' | 'diamond' | 'cross' | 'hexagon' | 'triangle-down' | 'pentagon' | 'x';
 export declare const DEFAULT_SPATIAL_VIEW: SpatialViewState;

package/lib/contracts/plot-type-contribution.contract.d.ts

@@ -103,6 +103,31 @@ export interface PlotModeViewport {
      *  A new subscriber first receives the current rect when the viewport is ready. */
     settled$: Observable<PlotModeRect>;
 }
+/** The class a {@link PlotModeTools.armBrush} stroke paints. */
+export interface PlotModeBrushClass {
+    /** Label for the painted regions; the stroke only extends or merges regions with it. */
+    label?: string;
+    /** Colour for the painted regions (instead of the toolbar's shape colour). */
+    color?: string;
+}
+/**
+ * The visualizer's own toolbar tools, armed on a mode's behalf. Going through
+ * this rather than {@link IVisualizer} keeps the toolbar in step: the armed
+ * tool's button is highlighted and its controls (e.g. the brush size) show.
+ */
+export interface PlotModeTools {
+    /**
+     * Arm the toolbar brush, painting `brushClass`. Calling it again while the
+     * brush is armed switches class; the next stroke starts a region of it.
+     * The user picking any tool from the toolbar (including the brush) replaces
+     * this with the plain tool.
+     */
+    armBrush(brushClass?: PlotModeBrushClass): void;
+    /** Disarm whatever tool is armed, as if the user toggled it off. */
+    disarm(): void;
+    /** The armed toolbar tool id ('brush', 'pan', … or null). Replays the current value. */
+    activeTool$: Observable<string | null>;
+}
 /** Everything a contributed mode gets to work with while it is active. */
 export interface PlotModeContext {
     /** Full public visualizer API: regions, region overlay (tool modes), undo, etc. */
@@ -110,6 +135,8 @@ export interface PlotModeContext {
     viewport: PlotModeViewport;
     /** Current image info from IMAGE_STATE_PORT (null until an image is loaded). */
     imageInfo$: Observable<IImageInfo | null>;
+    /** Toolbar tools (since 0.6.0). Optional so a context built for 0.5.0 still type-checks. */
+    tools?: PlotModeTools;
 }
 /** A live activation of a contributed mode. */
 export interface PlotModeSession {

package/lib/contracts/ports/spatial-data.port.d.ts

@@ -1,6 +1,21 @@
 import { InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
-import { SpatialColumn, SpatialDataset, SpatialEmbedding, SpatialPolygons } from '../spatial-dataset.contract';
+import { SpatialColumn, SpatialDataset, SpatialDensityRaster, SpatialEmbedding, SpatialPolygonTile, CategoricalColumnMeta, SpatialPolygons, SpatialTranscriptCounts, SpatialTranscriptSummary, SpatialTranscriptTile } from '../spatial-dataset.contract';
+/** Options for {@link SpatialDataPort.getTranscriptTile}. */
+export interface TranscriptTileQuery {
+    /**
+     * Genes to include, by name; the tile's `gene` codes index this list. `[ALL_GENES]`
+     * asks for every gene, unaggregated, at level 0 only and clipped to {@link box} — the
+     * `gene` codes are then the dataset's own gene indices.
+     */
+    genes: string[];
+    /** `high` (default) keeps only confidently decoded transcripts. */
+    quality?: 'high' | 'all';
+    /** Clip to `[x0, y0, x1, y1]` in observation units. */
+    box?: [number, number, number, number];
+}
+/** {@link TranscriptTileQuery.genes} value meaning "every gene". */
+export declare const ALL_GENES = "*";
 /**
  * Spatial-omics data access, inverted as a port so the visualization library
  * never learns how the data is stored or served — exactly like
@@ -66,6 +81,49 @@ export interface SpatialDataPort {
      * `polygons`. Optional — a spot-based assay (Visium) has no segmentation.
      */
     getPolygons?(): Promise<SpatialPolygons>;
+    /**
+     * One tile of boundaries from `polygonTiles`. An empty tile resolves with `count` 0 —
+     * a tile outside the tissue is an answer, not an error. Optional: only datasets that
+     * advertise `polygonTiles` need it.
+     */
+    getPolygonTile?(set: string, level: number, gx: number, gy: number): Promise<SpatialPolygonTile>;
+    /**
+     * One tile of transcripts from `transcriptTiles`, restricted to `query.genes`.
+     * Optional: only datasets that advertise `transcriptTiles` need it.
+     */
+    getTranscriptTile?(level: number, gx: number, gy: number, query: TranscriptTileQuery): Promise<SpatialTranscriptTile>;
+    /**
+     * One tile of the all-gene grouping pyramid (`transcriptBins`): an entry per bin, with
+     * `weight` its transcript count and `observation` its dominant cell.
+     */
+    getTranscriptBins?(level: number, tx: number, ty: number): Promise<SpatialTranscriptTile>;
+    /**
+     * What is inside `box` (observation units): transcript count, distinct genes and cells,
+     * the most frequent of each — optionally restricted to `genes` — plus display ids for
+     * `cells`. Omit `box` for a cell-id lookup only. Optional; drives the hover details of
+     * transcript markers.
+     */
+    getTranscriptSummary?(query: {
+        box?: [number, number, number, number];
+        genes?: string[];
+        cells?: number[];
+    }): Promise<SpatialTranscriptSummary>;
+    /**
+     * The summed transcript density of `genes` (`[ALL_GENES]` for every gene) on the
+     * dataset's `density` raster, re-binned to `binSize` observation units when given.
+     * Optional: only datasets that advertise `density` need it.
+     */
+    getDensity?(genes: string[], binSize?: number): Promise<SpatialDensityRaster>;
+    /**
+     * Import a cell grouping — a CSV/TSV of `cell_id` and `group` — under `label`. The new
+     * categorical column is added to the dataset (which re-emits) and resolved. Optional.
+     */
+    importGroups?(label: string, table: string): Promise<{
+        column: CategoricalColumnMeta;
+        matched: number;
+    }>;
+    /** Transcript totals per gene, for estimating how many markers a selection draws. */
+    getTranscriptCounts?(genes: string[]): Promise<SpatialTranscriptCounts>;
     /**
      * The reference volume's voxels: a uint8 scalar field, x-fastest, of exactly
      * `width * height * depth` bytes as the dataset's {@link SpatialVolumeMeta}

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

@@ -63,6 +63,20 @@ export interface CategoricalColumnMeta extends SpatialColumnMetaBase {
     kind: 'categorical';
     /** Category labels; a value's label is `categories[codes[i]]`. */
     categories: string[];
+    /**
+     * Heading the column is listed under in a group picker — e.g. "Xenium Onboard Analysis
+     * groups" for a pipeline's clusterings, "Imported groups" for ones added by a user.
+     */
+    section?: string;
+    /**
+     * Columns that are variants of one choice — k-means at k = 2…10 — share a family: a
+     * picker lists the family once and offers the variants beside it.
+     */
+    family?: {
+        id: string;
+        label: string;
+        variant: 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
@@ -228,6 +242,149 @@ export interface SpatialEmbedding {
     y: Float32Array;
     z?: Float32Array;
 }
+/**
+ * Level-of-detail geometry, served one grid tile at a time.
+ *
+ * Whole-dataset vectors stop working somewhere past 10^5 observations: 717k Xenium cell
+ * outlines are ~140 MB, and a whole-transcriptome run has ~10^9 transcripts. What scales
+ * is what map tiles do — a square grid in the observations' coordinate space, one grid
+ * per level, each level's tiles twice the size of the one below and carrying coarser
+ * geometry. The renderer asks only for the tiles on screen, at the level the zoom needs.
+ *
+ * Tile `(gx, gy)` at level `l` covers `[gx·s, (gx+1)·s) × [gy·s, (gy+1)·s)` with
+ * `s = levels[l].tileSize`, in the same units as {@link SpatialObservations.x}.
+ */
+export interface SpatialTileLevel {
+    /** Edge length of one tile, in observation coordinate units. */
+    tileSize: number;
+}
+/** Axis-aligned extent `[minX, minY, maxX, maxY]` in observation coordinates. */
+export type SpatialBounds = [number, number, number, number];
+/** Tiled cell/nucleus boundaries. Level 0 is the finest (every vertex). */
+export interface SpatialPolygonTilesMeta {
+    bounds: SpatialBounds;
+    /** Boundary sets on offer — typically `cell` and `nucleus`. */
+    sets: {
+        name: string;
+        label: string;
+    }[];
+    /** The set to draw when the user has not chosen. */
+    defaultSet?: string;
+    levels: SpatialTileLevel[];
+}
+/** Tiled transcripts. Level 0 is one entry per transcript; coarser levels aggregate. */
+export interface SpatialTranscriptTilesMeta {
+    bounds: SpatialBounds;
+    /** Total transcripts, for display. */
+    count?: number;
+    /** Real genes (control probes excluded). Names come from the feature search. */
+    geneCount: number;
+    hasZ: boolean;
+    levels: (SpatialTileLevel & {
+        /** True when an entry stands for several transcripts (see {@link SpatialTranscriptTile.weight}). */
+        aggregated: boolean;
+    })[];
+    /**
+     * Levels up to and including this one assign each entry to the cell it lies in
+     * exactly; above it the assignment names the cell nearest an aggregate's centroid.
+     */
+    exactCellLevel?: number;
+}
+/**
+ * The all-gene transcript grouping pyramid: square bins, four times coarser per level,
+ * each holding a count, a centroid and the cell that contributed most of its transcripts.
+ * Served per tile, in the {@link SpatialTranscriptTile} layout (one entry per bin).
+ *
+ * Tile `(tx, ty)` of level `l` covers `origin + [tx·s, (tx+1)·s) × [ty·s, (ty+1)·s)` with
+ * `s = levels[l].tileSize` — note the origin, which the per-gene tiles do not have.
+ */
+export interface SpatialTranscriptBinsMeta {
+    bounds: SpatialBounds;
+    origin: [number, number];
+    /** Transcripts the pyramid was built from. */
+    count: number;
+    levels: {
+        binSize: number;
+        tileSize: number;
+    }[];
+}
+/**
+ * A grouping pyramid the server is still building (it builds one itself when a dataset
+ * arrives without it). "All genes" becomes available once it is done.
+ */
+export interface SpatialTranscriptBinsStatus {
+    state: 'queued' | 'building' | 'failed';
+    /** Source tiles processed so far, of `total`. */
+    done?: number;
+    total?: number;
+    message?: string;
+}
+/** What is in an area — the hover details of a transcript marker or grouped bin. */
+export interface SpatialTranscriptSummary {
+    /** Absent for a pure cell-id lookup. */
+    transcripts?: number;
+    /** Distinct genes among them. */
+    genes?: number;
+    topGenes?: {
+        name: string;
+        count: number;
+    }[];
+    /** Distinct cells they fall in, and how many fall in none. */
+    cells?: number;
+    unassigned?: number;
+    topCells?: {
+        index: number;
+        id?: string;
+        count: number;
+    }[];
+    /** Display ids of the cells asked for, by observation index. */
+    cellIds?: Record<number, string>;
+}
+/** A per-gene transcript-count raster covering the section. */
+export interface SpatialDensityMeta {
+    /** Size of one raster cell, in observation units, `[x, y]`. */
+    gridSize: [number, number];
+    /** Observation-space position of raster cell (0, 0)'s near corner. */
+    origin: [number, number];
+    rows: number;
+    cols: number;
+}
+/** "No observation" in {@link SpatialTranscriptTile.observation}. */
+export declare const NO_OBSERVATION = 4294967295;
+/** One tile of boundaries: rings as in {@link SpatialPolygons}, plus who owns each ring. */
+export interface SpatialPolygonTile extends SpatialPolygons {
+    /** Observation index of ring `i` — the join key to columns and features. */
+    observation: Uint32Array;
+}
+/** One tile of transcripts (or aggregates of them). Every array has length {@link count}. */
+export interface SpatialTranscriptTile {
+    readonly count: number;
+    aggregated: boolean;
+    x: Float32Array;
+    y: Float32Array;
+    z: Float32Array;
+    /** Transcripts each entry stands for — 1 at an unaggregated level. */
+    weight: Uint32Array;
+    /** Observation (cell) the entry falls in, or {@link NO_OBSERVATION}. */
+    observation: Uint32Array;
+    /** Index into the `genes` list the tile was requested with. */
+    gene: Uint16Array;
+}
+/** Transcript totals for an estimate of how many markers a selection would draw. */
+export interface SpatialTranscriptCounts {
+    /** Total transcripts per requested gene, over the whole dataset. */
+    counts: Record<string, number>;
+    /** Total over every gene. */
+    total: number;
+    /** Extent the totals are spread over (observation units). */
+    bounds: SpatialBounds;
+}
+/** A summed density raster for a list of genes; `values` is row-major `rows × cols`. */
+export interface SpatialDensityRaster {
+    meta: SpatialDensityMeta;
+    genes: string[];
+    values: Float32Array;
+}
 export interface SpatialDataset {
     /** Stable id — the key the port's lazy accessors are scoped to. */
     id: string;
@@ -243,6 +400,16 @@ export interface SpatialDataset {
     volume?: SpatialVolumeMeta;
     /** Embeddings available for these observations, whose coordinates are fetched on demand. */
     embeddings?: SpatialEmbeddingMeta[];
+    /** Level-of-detail boundaries, fetched per tile — see {@link SpatialPolygonTilesMeta}. */
+    polygonTiles?: SpatialPolygonTilesMeta;
+    /** Level-of-detail transcripts, fetched per tile — see {@link SpatialTranscriptTilesMeta}. */
+    transcriptTiles?: SpatialTranscriptTilesMeta;
+    /** A served per-gene transcript density raster. */
+    density?: SpatialDensityMeta;
+    /** The all-gene transcript grouping pyramid, when it has been built. */
+    transcriptBins?: SpatialTranscriptBinsMeta;
+    /** Present while the server is still building {@link transcriptBins}. */
+    transcriptBinsStatus?: SpatialTranscriptBinsStatus;
     /**
      * Microns per observation coordinate unit — what makes a scale bar possible.
      *

package/lib/contracts/toolbar-tool.contract.d.ts

@@ -35,6 +35,17 @@
  * than an escape hatch that returns a component — the moment one tool draws
  * itself, the toolbar stops being able to lay tools out consistently.
  *
+ * DIALOG TOOLS
+ * Some tools are not "set parameters, run once" but an interactive session: the
+ * user paints, the tool retrains and redraws, over and over (DIANNE). A schema
+ * cannot describe that, so {@link ToolbarDialogToolContribution} is the one
+ * variant that renders its own body. The toolbar still owns the button, its
+ * placement and the dialog chrome; the tool only fills the dialog, with plain
+ * DOM (`mount`), so it needs neither Angular nor this library's PrimeNG version.
+ * Its button sits with the host's own actions at the start of the toolbar, and
+ * shows only in the Image view, the view its context ({@link ToolDialogContext})
+ * draws over.
+ *
  * WHY AN EMPTY MODEL LIST HIDES THE TOOL
  * {@link ToolbarToolContribution.models} returning `[]` removes the tool from
  * the toolbar entirely. This preserves the behaviour the built-in tools already
@@ -45,6 +56,7 @@
 import { InjectionToken } from '@angular/core';
 import type { Observable } from 'rxjs';
 import type { IVisualizer } from './visualizer.contract';
+import type { PlotModeContext, PlotModeSession, PlotModeTools } from './plot-type-contribution.contract';
 /** A number field. Rendered as a stepper, matching the built-in dialogs. */
 export interface NumberParamSpec {
     id: string;
@@ -177,14 +189,81 @@ export interface ToolbarToolContribution {
     run(viz: IVisualizer, params: Record<string, unknown>): Promise<number>;
 }
 /**
- * Multi-provider token for contributed tools.
+ * What a dialog tool gets while its dialog is open: the same surface a
+ * contributed plot mode gets (the public visualizer, the Image view's viewport
+ * and the current image), with the toolbar tools always present.
+ */
+export type ToolDialogContext = PlotModeContext & {
+    tools: PlotModeTools;
+};
+/** A live dialog-tool session. `deactivate()` runs exactly once, after the body's teardown. */
+export type ToolDialogSession = PlotModeSession;
+/**
+ * A toolbar tool that opens a dialog instead of running once (see DIALOG TOOLS
+ * above). Clicking its button opens the dialog and starts a session; clicking it
+ * again, or closing the dialog, ends it.
+ *
+ * The session is bound to the Image view on screen. When that view is re-rendered
+ * (another image, another slice) the session ends and, with the dialog still
+ * open, a fresh one starts once the new view is ready. Leaving the Image view
+ * closes the dialog. As with plot modes, nothing the tool throws or rejects
+ * escapes: a failed start closes the dialog with a warning.
+ */
+export interface ToolbarDialogToolContribution {
+    kind: 'dialog';
+    /** Stable identity. Must not clash with another toolbar tool. */
+    id: string;
+    /** Short name; the dialog title unless `dialog.title` is set. */
+    label: string;
+    icon: ToolIcon;
+    /** Tooltip on the button. */
+    tooltip: string;
+    /** Order among the dialog tools. Lower sorts first; ties keep registration order. */
+    order?: number;
+    dialog?: {
+        title?: string;
+        /** CSS width of the dialog. Default `'22rem'`. */
+        width?: string;
+    };
+    /** Entry for the help dialog's tool list, rendered as HTML (trusted content). */
+    help?: {
+        body: string;
+    };
+    /** Start a session, once the Image view's viewport is ready. */
+    activate(ctx: ToolDialogContext): ToolDialogSession | Promise<ToolDialogSession>;
+    /**
+     * Render the dialog body into `host`; return its teardown (called before
+     * `deactivate()`). Called after `activate` resolves, once the dialog has rendered and
+     * `host` is in the document, so the body can measure itself.
+     */
+    mount(host: HTMLElement, ctx: ToolDialogContext, session: ToolDialogSession): () => void;
+}
+/** Anything provided on {@link TOOLBAR_TOOLS}. A run tool has no `kind`. */
+export type ToolbarContribution = ToolbarToolContribution | ToolbarDialogToolContribution;
+/** Whether a contribution is a {@link ToolbarDialogToolContribution}. */
+export declare function isDialogToolContribution(c: unknown): c is ToolbarDialogToolContribution;
+/**
+ * Multi-provider token for contributed tools: run tools
+ * ({@link ToolbarToolContribution}) and, since 0.6.0, dialog tools
+ * ({@link ToolbarDialogToolContribution}).
  *
  * Deliberately has no `factory`: unregistered means no tools, which is what
  * makes this library shippable without the closed model packages. Inject it
  * `{ optional: true }` and treat null as empty.
  */
-export declare const TOOLBAR_TOOLS: InjectionToken<readonly ToolbarToolContribution[]>;
+export declare const TOOLBAR_TOOLS: InjectionToken<readonly ToolbarContribution[]>;
 /** Sort contributed tools into display order. */
-export declare function sortToolContributions(tools: readonly ToolbarToolContribution[]): ToolbarToolContribution[];
-/** The tools a toolbar should actually show: those with at least one model. */
-export declare function visibleToolContributions(tools: readonly ToolbarToolContribution[] | null | undefined): ToolbarToolContribution[];
+export declare function sortToolContributions<T extends {
+    order?: number;
+}>(tools: readonly T[]): T[];
+/** The run tools a toolbar should actually show: those with at least one model.
+ *  Dialog tools are left out (see {@link dialogToolContributions}). */
+export declare function visibleToolContributions(tools: readonly ToolbarContribution[] | null | undefined): ToolbarToolContribution[];
+/**
+ * The dialog tools, in display order. A malformed one (no string `id`, no
+ * `activate` or `mount` function) or a repeated `id` is dropped with a warning
+ * rather than breaking the toolbar.
+ */
+export declare function dialogToolContributions(tools: readonly ToolbarContribution[] | null | undefined, log?: {
+    warn(...args: unknown[]): void;
+}): ToolbarDialogToolContribution[];

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

@@ -8,7 +8,7 @@ import { ViewerCapabilities } from './capabilities.contract';
 import { IRegionOverlay } from './region-overlay.contract';
 import { IHistogram } from './channel-histogram-api.contract';
 import { ColormapNode, IWandOptions, IBrushOptions, SpatialViewState, SpatialColorBy } from './display-types';
-import { SpatialDataset, SpatialEmbedding } from './spatial-dataset.contract';
+import { CategoricalColumnMeta, SpatialDataset, SpatialEmbedding, SpatialTranscriptCounts } from './spatial-dataset.contract';
 import { SpatialSelectionMask } from '../spatial/spatial-selection';
 import type { PlotModeViewport } from './plot-type-contribution.contract';
 /**
@@ -334,6 +334,27 @@ export interface ISpatialControls {
     getEmbedding?(name: string): Promise<SpatialEmbedding>;
     /** Names of the categorical columns available to group by. */
     categoricalColumns(): string[];
+    /**
+     * Import a cell grouping (CSV/TSV of `cell_id`, `group`) as a new categorical column.
+     * Optional: only data sources that can join cell ids implement it.
+     */
+    importGroups?(label: string, table: string): Promise<{
+        column: CategoricalColumnMeta;
+        matched: number;
+    }>;
+    /** Transcript totals per gene — for the points estimate. Optional. */
+    transcriptCounts?(genes: string[]): Promise<SpatialTranscriptCounts>;
+    /** Estimated transcripts in view for the current selection, against the marker budget. */
+    getTranscriptEstimate$?(): Observable<{
+        points: number;
+        max: number;
+    } | null>;
+    /** The density map's colour window in use (auto-derived or set) and its densest bin. */
+    getDensityStats$?(): Observable<{
+        lo: number;
+        hi: number;
+        max: number;
+    } | null>;
     /**
      * 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

package/lib/implementations/napari-js/napari-navigator.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Overview navigator (minimap) for the napari-js 2D views, mirroring the OSD backend's
+ * built-in navigator: a thumbnail of the whole image in the bottom-right corner with the
+ * current viewport drawn on it. Clicking re-centres the main view on that point at the
+ * same zoom; dragging pans continuously — exactly OSD's behaviour.
+ *
+ * napari keeps layers at full-resolution pixel scale, so the camera's world units ARE
+ * image pixels and the thumbnail maps onto `[0, width) × [0, height)` directly.
+ */
+/** The slice of the napari 2D camera the navigator reads and drives. */
+export interface NavigatorCamera {
+    center: readonly [number, number];
+    readonly zoom: number;
+    readonly changed: {
+        connect(listener: () => void): () => void;
+    };
+}
+/** Where the thumbnail sits inside the navigator box, in CSS px. */
+export interface NavigatorLayout {
+    /** Box size. */
+    width: number;
+    height: number;
+    /** CSS px per world unit (image pixel). */
+    scale: number;
+}
+/** Fraction of the host's width the navigator takes — OSD's `navigatorSizeRatio`. */
+export declare const NAVIGATOR_SIZE_RATIO = 0.16;
+/** Box size and scale for a `worldW × worldH` image in a host `hostW` wide. */
+export declare function navigatorLayout(hostW: number, worldW: number, worldH: number, ratio?: number): NavigatorLayout | null;
+/** The part of the world the camera shows, as `[x0, y0, x1, y1]`. */
+export declare function viewportWorldRect(center: readonly [number, number], zoom: number, hostW: number, hostH: number): [number, number, number, number];
+/** A point in the navigator box → world coordinates, clamped to the image. */
+export declare function navigatorToWorld(px: number, py: number, layout: NavigatorLayout, worldW: number, worldH: number): [number, number];
+export declare class NapariNavigator {
+    private readonly host;
+    private readonly camera;
+    private worldW;
+    private worldH;
+    /** Called when the pointer enters the navigator — e.g. to hide a hover tooltip that
+     *  was describing the canvas underneath. */
+    private readonly onEnter?;
+    private readonly box;
+    private readonly canvas;
+    private readonly region;
+    private readonly disconnectCamera;
+    private readonly resizeObserver?;
+    /** Aborted by destroy() to remove every DOM listener the box holds. */
+    private readonly listeners;
+    private layout;
+    private image;
+    private dragging;
+    private visible;
+    constructor(host: HTMLElement, camera: NavigatorCamera, worldW: number, worldH: number, 
+    /** Called when the pointer enters the navigator — e.g. to hide a hover tooltip that
+     *  was describing the canvas underneath. */
+    onEnter?: (() => void) | undefined);
+    /** The thumbnail to draw: any image of the whole world (a coarse pyramid level). */
+    setImage(image: CanvasImageSource | null): void;
+    /** The image's world size changed (another image was loaded). */
+    setWorld(width: number, height: number): void;
+    setVisible(visible: boolean): void;
+    destroy(): void;
+    private relayout;
+    private drawImage;
+    /** Draw the viewport rectangle, clipped to the box (as OSD does when zoomed out). */
+    private updateRegion;
+    /** Re-centre the main view on the navigator point under the pointer, keeping the zoom. */
+    private panTo;
+    private readonly onDown;
+    private readonly onMove;
+    private readonly onUp;
+}

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

@@ -48,6 +48,7 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private marqueeEl;
     private draftPath;
     private drawing;
+    private regionsVisible;
     /** In-progress manipulation (select/move modes): dragging a body, a polygon vertex, or a
      *  rectangle corner. `anchor` is the fixed opposite corner for a rectangle resize. */
     private edit;
@@ -124,6 +125,8 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private commitRectangle;
     private commitPolygon;
     private hitTest;
+    /** Show or hide the drawn regions. A region being drawn stays visible either way. */
+    setRegionsVisible(visible: boolean): void;
     redraw(): void;
     /** Draw a region's classification label at its top-left, when labels are enabled (matches OSD). */
     private drawLabel;