@jax-data-science/sci-image-visualizer 0.8.3 → 0.9.0

package/lib/implementations/napari-js/napari-volume-scene.d.ts

@@ -0,0 +1,104 @@
+import { MultiChannelVolumeView } from 'napari-js';
+import type { AxisLabelSpec } from 'napari-js/overlays';
+import { IImageInfo } from '../../contracts/image.contract';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { IIsosurfaceControls, ISurface3dControls } from '../../contracts/visualizer.contract';
+import { Axes3dGizmo, Box3 } from './napari-axes-gizmo';
+import type { NapariScene, SceneContext } from './napari-scene';
+/**
+ * NAPARI_VOLUME / NAPARI_ISOSURFACE (review Appendix B, cluster F): the stack assembled into a
+ * decimated volume — one additive, tinted `VolumeLayer` per channel for a multichannel image, a
+ * single grayscale volume otherwise — with the axes gizmo and the in-view Z-height handle.
+ */
+export declare class VolumeScene implements NapariScene {
+    private readonly ctx;
+    private readonly info;
+    private readonly rendering;
+    /** napari-js high-level view owning the volume layers. */
+    view: MultiChannelVolumeView | null;
+    /** True when the volume is composited from per-channel layers (vs a single grayscale volume). */
+    private multichannel;
+    /** Volume world box at Z-scale 1 (base) + the sampled voxel depth — enough to recompute the
+     *  Z-axis voxel scale, axes depth, and overlay anchors as the handle stretches Z. */
+    private worldBase;
+    private sampledDepth;
+    private dims;
+    /** Assembled uint8 volume data per channel (key = channel index), kept for the volume intensity
+     *  histogram. Key 0 holds the grayscale/composite volume in the single-channel case. */
+    private readonly channelData;
+    gizmo: Axes3dGizmo | null;
+    private zHandle;
+    private displaySub;
+    constructor(ctx: SceneContext, info: IImageInfo | undefined, rendering: 'iso' | 'mip');
+    /**
+     * Assemble and render the volume, then add the axes gizmo + labels and the Z handle and follow
+     * the display state.
+     */
+    mount(): Promise<void>;
+    /**
+     * Assemble each channel's volume from the server tiles (or the single grayscale volume) under
+     * the stack progress bar, with the display settings it is drawn with. `dims` is null when
+     * nothing was assembled (a Cancel, a new plot, or no slices).
+     */
+    private assembleChannels;
+    /** The volume's world box for the assembled `dims`, independent of the decimate factor. */
+    private worldBox;
+    /**
+     * The whole stack is already on screen: no plane to step. (This used to write `viewer.dims.z`,
+     * which only a tiled 2D image reads — a volume raymarches every slice — and schedule a readback
+     * of a frame that had not changed. The toolbar shows no slice control in volume / isosurface
+     * mode, as Plotly's isosurface ignores the slice too.)
+     */
+    setZ(): void;
+    /** The intensity histogram of the assembled (downsampled) uint8 volume for the requested
+     *  channel (multichannel) or the single grayscale volume. */
+    histogram(channel: number, bins: number): IHistogram | null;
+    isoControls(): IIsosurfaceControls | null;
+    surface3dControls(): ISurface3dControls | null;
+    dispose(): void;
+    /**
+     * Restretch the volume's Z height live (driven by the in-view {@link NapariVolumeZHandle}). Only
+     * the per-axis `voxelSize` / axes depth change — the voxel textures are untouched — so dragging is
+     * smooth. `factor` is relative to the volume's natural proportions (1). Persists across re-mounts
+     * (resolution changes) so the chosen height sticks.
+     */
+    setZScale(factor: number): void;
+    /** The X/Y/Z axis-end label specs for the gizmo. Anchors are in the volume's centred world box
+     *  (matching the AxesLayer geometry); the scale text reflects the FULL image extent — physical µm
+     *  when µm/pixel is known, else pixel (X/Y) / slice (Z) counts. */
+    axesLabels(vol: Box3): AxisLabelSpec[];
+    /**
+     * The image's declared extent in pixels/slices, and its physical spacing per
+     * axis in µm (0 = undeclared, and then that axis reads in pixels).
+     *
+     * One place, because the volume world box and the axis labels have to agree
+     * about what the image's real dimensions are — the sampled grid is decimated and
+     * says nothing about either.
+     */
+    private imageExtent;
+    /** The store's colormap, reverse, invert and channel windows → the volume's transfer function:
+     *  colour (channel tint or selected colormap), the intensity window (min/max → contrastLimits)
+     *  and gamma, mirroring the grayscale image's display controls so the histogram pane drives the
+     *  3D render. */
+    private followDisplayState;
+}
+/**
+ * NAPARI_SCATTER3D (review Appendix B, cluster H): the downsampled voxel grid as a 3D point cloud
+ * coloured by intensity (the napari-js analog of Plotly's voxel scatter3d). Assembles a coarse
+ * volume, then emits a flat-strided sample of voxels (capped at `SCATTER3D_MAX_POINTS`).
+ */
+export declare class Scatter3dScene implements NapariScene {
+    private readonly ctx;
+    private readonly info;
+    private layer;
+    /** The assembled volume (key 0), for the intensity histogram. */
+    private readonly channelData;
+    private displaySub;
+    constructor(ctx: SceneContext, info: IImageInfo | undefined);
+    mount(): Promise<void>;
+    /** The whole stack is already on screen: no plane to step. */
+    setZ(): void;
+    histogram(channel: number, bins: number): IHistogram | null;
+    surface3dControls(): ISurface3dControls | null;
+    dispose(): void;
+}

package/lib/implementations/napari-js/napari-volume-z-handle.d.ts

@@ -1,14 +1,10 @@
-/**
- * Draggable Z-height handle for the napari-js WebGPU volume (jit-ui#102). A small DOM grip is drawn
- * over the 3D canvas at the projected top-face centre of the volume box (reusing the axes-label
- * {@link projectPoint} projection, so it tracks the box as the volume orbits). Dragging it up makes
- * the volume taller, down makes it flatter — the host maps the drag to a Z-scale factor and
- * restretches the volume + axes live (only the model matrix changes; the voxel texture is untouched).
- *
- * Direct-manipulation counterpart of {@link NapariAxesLabels}: both are absolute-positioned overlays
- * updated on every `camera3d.changed`, but this one accepts pointer input.
- */
-import { AxesLabelCamera3D } from './napari-axes-labels';
+/** The slice of napari's Camera3D the handle reads. `viewProjection` is column-major (gl-matrix). */
+export interface ZHandleCamera3D {
+    viewProjection(vw: number, vh: number): ArrayLike<number>;
+    readonly changed: {
+        connect(listener: () => void): () => void;
+    };
+}
 export interface VolumeZHandleOptions {
     /** Current top-face-centre world point (the box is centred at the origin, so `[0, 0, +halfZ]`). */
     topAnchor: () => [number, number, number];
@@ -33,7 +29,7 @@ export declare class NapariVolumeZHandle {
     private dragging;
     private startY;
     private startScale;
-    constructor(host: HTMLElement, camera3d: AxesLabelCamera3D, opts: VolumeZHandleOptions);
+    constructor(host: HTMLElement, camera3d: ZHandleCamera3D, opts: VolumeZHandleOptions);
     setVisible(visible: boolean): void;
     /** Reproject the handle to the current top-face anchor. Called on camera move, resize, and after
      *  the host applies a new scale (so the grip follows the growing/shrinking box). */

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

@@ -0,0 +1,59 @@
+import type { ToScreen } from '../../../region-overlay/region-geometry';
+import { Affine } from '../../../region-overlay/svg-region-renderer';
+import type { OverlayViewer } from '../napari-region-overlay';
+/**
+ * The region overlay's coordinate spaces: pointer CLIENT pixels, svg-LOCAL pixels and WORLD
+ * units, through the viewer's own transforms (see {@link OverlayViewer}).
+ *
+ * World → svg-local is the viewer's camera affine (`canvasTransform`), which reads no layout, so
+ * drawing and following the camera read none. Only a pointer, in client pixels, needs the svg's
+ * client origin: read once per {@link withOrigin} block (a gesture event), as an uncached read
+ * per vertex — interleaved with the elements a redraw appends — forced a synchronous layout per
+ * vertex (review NAPARI-BOUNDARY-10).
+ */
+export declare class OverlayProjection {
+    private readonly svg;
+    private readonly viewer;
+    /**
+     * 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;
+    /** The svg's client origin and the camera affine, cached while a {@link withOrigin} block runs. */
+    private origin;
+    private camera;
+    constructor(svg: SVGSVGElement, viewer: OverlayViewer);
+    setWorldQuantum(quantum: number): void;
+    /** Pointer client coords → world coords, snapped to the world quantum (for placing vertices). */
+    toImage(clientX: number, clientY: number): [number, number];
+    /** Pointer client coords → world coords, exact (for picking: snapping is for placing). */
+    toWorld(clientX: number, clientY: number): [number, number];
+    /**
+     * 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.
+     */
+    worldPerCanvasPixel(): number;
+    /** Run `fn` with the svg's client origin and the camera affine read once (nested calls reuse them). */
+    withOrigin<T>(fn: () => T): T;
+    /** Client px → SVG-local px. */
+    clientToLocal(clientX: number, clientY: number): [number, number];
+    /** World coords → SVG-local px, through the camera affine: no layout read. */
+    toLocal(imgX: number, imgY: number): [number, number];
+    /** {@link toLocal} as the shared region geometry takes it. */
+    readonly toScreen: ToScreen;
+    /** Screen distance (px) between a client point and a world point. */
+    screenDist(clientX: number, clientY: number, imgX: number, imgY: number): number;
+    /**
+     * The world → svg-local affine for the current camera: the viewer's `canvasTransform`, which
+     * reads no layout. The svg and the canvas share an origin (see {@link OverlayViewer}).
+     */
+    affine(): Affine;
+}

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

@@ -0,0 +1,15 @@
+import type { HandleHit } from '../../../region-overlay/region-geometry';
+import type { RegionStore } from '../../../store/region-store.service';
+/**
+ * A live drag of the select/move tools: the region's body, or one of its handles as the
+ * shared `hitHandle` names it (a rectangle corner with its fixed opposite `anchor`, or a
+ * vertex / bézier control point on `ring` -1 for the exterior, else a hole).
+ */
+export type RegionEdit = {
+    id: number;
+    last: [number, number];
+} & ({
+    kind: 'body';
+} | HandleHit);
+/** Apply the drag of `edit` to the pointer at world point `(x, y)`, through the store's edit ops. */
+export declare function applyRegionEdit(store: RegionStore, edit: RegionEdit, x: number, y: number): void;

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

@@ -0,0 +1,54 @@
+import { Region } from '../../../models/region';
+import type { RegionStore } from '../../../store/region-store.service';
+import { Affine } from '../../../region-overlay/svg-region-renderer';
+/** Rendered handle size (screen px). */
+export declare const HANDLE_SIZE = 7;
+/** An axis-aligned box from a drag's start to its current point (any order). */
+export interface DragBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** A region being drawn: a rectangle drag, or a freehand / click-placed path. */
+export interface RegionDraft {
+    rect: DragBox | null;
+    path: Array<[number, number]> | null;
+}
+/**
+ * What the napari region overlay draws, over the shared {@link SvgRegionRenderer}: the regions
+ * in world coordinates (styled from the store's colours, labelled when labels are on), and in
+ * screen space the selected regions' grab handles (corners, vertices, bézier control points),
+ * the draft being drawn and the rubber-band marquee.
+ */
+export declare class NapariRegionSvgRenderer {
+    private readonly svg;
+    private readonly store;
+    private readonly renderer;
+    /** Dedicated marquee rect element, updated directly during the drag (no full region redraw). */
+    private marqueeEl;
+    constructor(svg: SVGSVGElement, store: RegionStore);
+    /** Follow the camera: one transform attribute plus the screen-space elements. */
+    setCamera(affine: Affine): void;
+    /** Rebuild the regions (world space) and their labels. */
+    render(regions: readonly Region[], selected: readonly number[]): void;
+    /** Rebuild the screen-space overlay only: the selected regions' handles and the draft. */
+    renderOverlay(regions: readonly Region[], selected: readonly number[], draft: RegionDraft): void;
+    /** Show the marquee over svg-local corners `(lx, ly)`–`(rx, ry)`, creating it on first use. */
+    showMarquee(lx: number, ly: number, rx: number, ry: number): void;
+    /** Remove the marquee element from the SVG. */
+    clearMarquee(): void;
+    /** A region's outline colour. */
+    private strokeOf;
+    /** Draw a region's classification label at its top-left, when labels are enabled (matches OSD). */
+    private drawLabel;
+    /** Draw grab handles for a selected region: rectangle corners or polygon vertices. */
+    private drawHandles;
+    /** Draw one bezier control point as a small circle connected to its anchor by a tangent line.
+     *  `handle` is the control point's absolute position in image space. */
+    private drawBezierHandle;
+    private style;
+    /** Draw the in-progress rectangle / path preview. */
+    private drawDraft;
+    private styleDraft;
+}

package/lib/implementations/napari-js/spatial-tiles/categorical-lookup.d.ts

@@ -0,0 +1,26 @@
+import type { SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
+import type { SpatialViewState } from '../../../contracts/display-types';
+import { SpatialColumn, SpatialDataset } from '../../../contracts/spatial-dataset.contract';
+/** A categorical column's per-observation codes and its metadata (categories, colours). */
+export interface CategoricalCodes {
+    codes: Uint16Array;
+    meta: SpatialColumn['meta'];
+}
+/** Per-observation group codes, and which codes are switched off (1) in the group list. */
+export interface HiddenCodes {
+    codes: Uint16Array;
+    hidden: Uint8Array;
+}
+/**
+ * The categorical columns the cells, the transcripts and the hover all read: the cell-type
+ * column's codes, and which of its groups the user switched off. A failed request rejects;
+ * the caller decides whether that fails its group of the plan or degrades to "no types".
+ */
+export declare class CategoricalLookup {
+    private readonly port;
+    constructor(port: SpatialDataPort);
+    /** Codes of the column `name`, or null when it is not categorical. */
+    codes(name: string): Promise<CategoricalCodes | null>;
+    /** Codes of the group column that are switched off, or null when none are. */
+    hiddenCodes(dataset: SpatialDataset, view: SpatialViewState): Promise<HiddenCodes | null>;
+}

package/lib/implementations/napari-js/spatial-tiles/cell-layers.d.ts

@@ -0,0 +1,70 @@
+import type { Rgb } from '../../../contracts/colormap-lut';
+import type { SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
+import type { SpatialViewState } from '../../../contracts/display-types';
+import { SpatialDataset } from '../../../contracts/spatial-dataset.contract';
+import { SpatialSelectionMask } from '../../../spatial/spatial-selection';
+import { DataRect } from '../../../spatial/lod';
+import type { CategoricalLookup } from './categorical-lookup';
+import type { OrderedLayerGroups, TileGroup } from './layer-groups';
+import type { PlanContext } from './plan-context';
+/** What the cell layers need from the service. */
+export interface CellLayersHost {
+    /** The continuous LUT the view is using (so cells coloured by a gene match the markers). */
+    continuousLut(view: SpatialViewState): Rgb[];
+    /** Outlines appeared or disappeared: the markers' visibility follows. */
+    polygonsShownChanged(shown: boolean): void;
+}
+/**
+ * The cell outlines of the 2D spatial view, at the polygon level the zoom calls for: a fill,
+ * an outline or both (plus nucleus outlines for the "both" cell set), coloured by the view's
+ * cell-colour mode, with switched-off groups left out of the geometry.
+ *
+ * Geometry and style are keyed apart, so a recolour (a new cell-type column, a selection)
+ * rewrites the per-shape values of the existing layers and never re-expands the rings.
+ */
+export declare class CellLayers {
+    private readonly port;
+    private readonly groups;
+    private readonly lookup;
+    private readonly host;
+    private polygonsShown;
+    /** Rings currently drawn and the (dataset, set, tiles) they came from. */
+    private currentRings;
+    private cellGeometryKey;
+    private currentNuclei;
+    private cellStyleKey;
+    /** Selection identity → revision, so a change key can name a selection cheaply. */
+    private lastSelection;
+    private selectionRevision;
+    /** Continuous colourings' windows, per (vector, clip, log): `contrastWindow` sorts every
+     *  value, and a selection or opacity change recolours with the vector unchanged (SPATIAL-12). */
+    private readonly contrastWindows;
+    constructor(port: SpatialDataPort, groups: OrderedLayerGroups<TileGroup>, lookup: CategoricalLookup, host: CellLayersHost);
+    /** True while outlines are on screen — the service hides its dots then. */
+    get outlinesShown(): boolean;
+    /** The viewer went away (its layers with it): the outlines are no longer shown. */
+    detached(): void;
+    /** Draw the cells covering `rect` at the level `pxPerUnit` calls for, or drop them. */
+    plan(dataset: SpatialDataset, view: SpatialViewState, selection: SpatialSelectionMask, rect: DataRect, pxPerUnit: number, ctx: PlanContext): Promise<void>;
+    /**
+     * The cell layers: the fill and the outline the view's draw mode asks for, and with "both" the
+     * nucleus outlines over them. A geometry change builds new layers; a style change restyles them.
+     */
+    private drawCells;
+    private selectionRev;
+    /**
+     * The rings' colours by their owners, by the view's cell-colour mode (Xenium Explorer's "Cell
+     * Color"): one RGBA per shape for a grouping, values + colormap for a measurement, one colour
+     * for "single". A selection mutes what it leaves out.
+     */
+    private cellColors;
+    /**
+     * The cell rings (and, for "both", the nucleus rings) covering `rect` at `level`, minus
+     * the hidden groups — reused when nothing that decides them changed. Null when the
+     * view went stale or the dataset has no set to draw.
+     */
+    private cellGeometry;
+    /** Remove the cell layers and forget what they showed. */
+    drop(): void;
+    private setPolygonsShown;
+}

package/lib/implementations/napari-js/spatial-tiles/density-layer.d.ts

@@ -0,0 +1,61 @@
+import type { Viewer } from 'napari-js';
+import { type SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
+import type { SpatialViewState } from '../../../contracts/display-types';
+import type { SpatialDataset } from '../../../contracts/spatial-dataset.contract';
+import type { OrderedLayerGroups, TileGroup } from './layer-groups';
+import type { PlanContext } from './plan-context';
+/** The density window in use and the densest bin (transcripts per unit area). */
+export interface DensityStats {
+    lo: number;
+    hi: number;
+    max: number;
+}
+/** Xenium Explorer's "Estimated Transcript Points". */
+export interface TranscriptEstimate {
+    /** Transcripts of the visible genes estimated to be in view. */
+    points: number;
+    /** The marker budget. */
+    max: number;
+}
+/**
+ * The transcript density image of the 2D spatial view: the visible genes' summed density
+ * raster, one scalar layer in the `density` group, windowed and coloured on the GPU.
+ *
+ * Bins at or below the window's low end are transparent (`transparentBelow`), so a window,
+ * colormap or opacity change is a uniform or LUT update of the same layer: only new genes or a
+ * new bin size fetch and upload a raster.
+ */
+export declare class DensityLayer {
+    private readonly port;
+    private readonly groups;
+    private readonly changed;
+    /** The density window in use and the densest bin, for the panel's threshold control. */
+    stats: DensityStats | null;
+    /** The drawn raster in transcripts per unit area, its densest bin and its auto window. */
+    private raster;
+    /** The colormap the layer was given, so an unchanged one does not rebuild its LUT. */
+    private colormapKey;
+    constructor(port: SpatialDataPort, groups: OrderedLayerGroups<TileGroup>, changed: (stats: DensityStats) => void);
+    /** Draw the view's density, or drop it; an unchanged (genes, bin, window, colormap) is a no-op. */
+    plan(dataset: SpatialDataset, view: SpatialViewState, ctx: PlanContext): Promise<void>;
+    /** Window, colour and opacity onto the drawn layer: uniforms and a LUT, no re-upload. */
+    private restyle;
+}
+/**
+ * Transcripts in view for the visible genes, against the marker budget — it tells the user
+ * whether the budget will force grouping. Caches the per-gene dataset totals for the latest
+ * gene set.
+ */
+export declare class TranscriptEstimator {
+    private readonly port;
+    private readonly changed;
+    /** Per-gene dataset totals for the in-view estimate, for the latest gene set. */
+    private countsCache;
+    constructor(port: SpatialDataPort, changed: (estimate: TranscriptEstimate | null) => void);
+    /**
+     * Transcripts in view for the visible genes: each gene's dataset total times the share
+     * of the tissue on screen. An estimate — expression is not uniform — which is also what
+     * Xenium Explorer shows; it tells the user whether the budget will force grouping.
+     */
+    plan(dataset: SpatialDataset, view: SpatialViewState, viewer: Viewer, w: number, h: number, ctx: PlanContext): Promise<void>;
+}

package/lib/implementations/napari-js/spatial-tiles/layer-groups.d.ts

@@ -0,0 +1,67 @@
+import type { Layer, Viewer } from 'napari-js';
+import type { SpatialPolygons } from '../../../contracts/spatial-dataset.contract';
+/** The layer groups of the 2D spatial tile view. */
+export type TileGroup = 'density' | 'cellFill' | 'cellOutline' | 'nucleusOutline' | 'transcripts';
+/**
+ * Bottom to top: cell fill, cell outline, nucleus outline, the transcript density, then the
+ * transcripts. The density goes OVER the service's observation markers on purpose: under 10^5
+ * dots it would only show in the gaps between cells.
+ */
+export declare const TILE_LAYER_ORDER: readonly TileGroup[];
+/**
+ * One napari-js layer per named group, kept in a fixed bottom-to-top order, plus what each
+ * group currently shows (its key), so an unchanged plan is a no-op.
+ *
+ * Order is kept with `LayerList.move`, which restacks a layer without disposing its GPU visual
+ * (a remove + re-add would re-upload its whole buffer, review NAPARI-BOUNDARY-11). A plan still
+ * restores the order once, after all its groups are in place, and moves only the layers that
+ * are out of place ({@link restoreOrder}).
+ */
+export declare class OrderedLayerGroups<G extends string> {
+    private readonly order;
+    private current;
+    private readonly layers;
+    /** What each group currently shows, so an unchanged plan is a no-op. */
+    private readonly keys;
+    constructor(order: readonly G[]);
+    /** The viewer the groups are drawn into, while attached. */
+    get viewer(): Viewer | null;
+    attach(viewer: Viewer): void;
+    /** Remove every group's layer from the viewer and forget the layers, keys and viewer. */
+    detach(): void;
+    /** Whether `group` has a layer (on screen or not). */
+    has(group: G): boolean;
+    /** `group`'s layer (on screen or not), if it has one. */
+    layer(group: G): Layer | undefined;
+    /** Whether `group`'s layer is in the viewer now. */
+    shown(group: G): boolean;
+    /** What `group` currently shows, as its plan keyed it. */
+    key(group: G): string | undefined;
+    setKey(group: G, key: string): void;
+    /** Forget what `group` shows, so the next plan redraws it. */
+    forgetKey(group: G): void;
+    /** Whether `layer` is one of the groups' layers. */
+    owns(layer: Layer): boolean;
+    /**
+     * Put a shapes layer in place for `group`: a geometry change builds a new layer, a
+     * colour-only change mutates the per-shape colours or values/colormap of the existing one.
+     */
+    upsertShapes(group: G, wanted: boolean, geometryChanged: boolean, rings: SpatialPolygons, opts: Parameters<Viewer['addShapes']>[2] & object): void;
+    /**
+     * Install `layer` as `group`'s layer. The layer was just added by the caller, so it is on
+     * top: the plan puts the groups that belong above it back in place once it is done
+     * ({@link restoreOrder}), rather than after every replaced group.
+     */
+    replace(group: G, layer: Layer): void;
+    /**
+     * Put the groups' layers in order, moving to the top only from the first one out of place
+     * (and, with `aboveOthers`, the first one under a layer that is not ours — the service's
+     * markers). Everything before that is already where it belongs. A move keeps each layer
+     * mounted (no `removed`/`added`), so nothing is re-uploaded.
+     */
+    restoreOrder(aboveOthers: boolean): void;
+    /** Remove `group`'s layer and forget its key. */
+    drop(group: G): void;
+    /** Drop every group. */
+    dropAll(): void;
+}

package/lib/implementations/napari-js/spatial-tiles/plan-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Loads in flight, per layer label ("Transcripts", "Cells"…), for the canvas loading badge.
+ * Shared by every plan: a label stays reported while any plan still loads it.
+ */
+export declare class LoadTracker {
+    private readonly changed;
+    private readonly loading;
+    constructor(changed: (labels: string[]) => void);
+    /** Report `label` loading while `work` is in flight. */
+    track<T>(label: string, work: Promise<T>): Promise<T>;
+    /** Forget every load (the viewer went away) and report none. */
+    clear(): void;
+}
+/**
+ * One run of `NapariSpatialTileLayers.plan()`. Completeness belongs to the run that did the
+ * fetching: on the instance, a superseded run's failed tile marked the CURRENT run incomplete,
+ * which then skipped caching its keys and retried for nothing (review NAPARI-BOUNDARY-9).
+ */
+export declare class PlanContext {
+    private readonly isStale;
+    private readonly loads;
+    private failed;
+    /** `isStale` turns true once a newer plan started or the viewer changed. */
+    constructor(isStale: () => boolean, loads: LoadTracker);
+    /** True once a newer plan started or the viewer changed. */
+    stale(): boolean;
+    /** Set when a fetch of this run failed (see fetchAll): don't cache it as done; retry. */
+    get incomplete(): boolean;
+    /** A request of this run failed: what it drew must not be cached as done. */
+    markIncomplete(): void;
+    /** Report `label` loading while `work` is in flight. */
+    track<T>(label: string, work: Promise<T>): Promise<T>;
+    /**
+     * Fetch every tile, drawing what arrived. A failure does not fail the view, but it marks this
+     * run incomplete: the caller must not cache it as done, and `plan()` retries it.
+     */
+    fetchAll<K, T>(keys: K[], load: (k: K) => Promise<T>): Promise<T[]>;
+}

package/lib/implementations/napari-js/spatial-tiles/transcript-hover.d.ts

@@ -0,0 +1,71 @@
+import type { PointsLayer } from 'napari-js';
+import type { SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
+import { SpatialTranscriptTile } from '../../../contracts/spatial-dataset.contract';
+import type { CategoricalCodes } from './categorical-lookup';
+/** What one transcript entry is — decides what hovering it says. */
+export type TranscriptKind = 'genes' | 'individual' | 'bins';
+/** A bin grid: its size and origin, so a hovered bin's square can be recovered. */
+export interface TranscriptBin {
+    size: number;
+    origin: [number, number];
+}
+/**
+ * Tooltips for the transcript markers of the 2D spatial view.
+ *
+ * Reads only what the transcript layer last drew — handed over one way through
+ * {@link setDrawn} / {@link setTypes} — and asks the server for the slower details (distinct
+ * genes in a group, its top genes and cells, the cell's display id) once the pointer has
+ * rested on a marker, caching them until the next draw.
+ */
+export declare class TranscriptHover {
+    private readonly port;
+    private readonly layerShown;
+    /** What the transcript layer currently shows (written by drawing, read by hover). */
+    private drawn;
+    /** The cell-type column, to name the cell a marker is in. */
+    private types;
+    /** µm per observation unit of the drawn dataset, for describing a grouped marker's area. */
+    private micronsPerUnit;
+    /** Details already fetched, by hovered entry. */
+    private readonly cache;
+    private key;
+    private timer;
+    /** `layerShown` says whether the transcript layer is on screen now (it may have been dropped). */
+    constructor(port: SpatialDataPort, layerShown: () => boolean);
+    /** The transcript layer was redrawn: hover names these entries now (cached details are dropped). */
+    setDrawn(drawn: DrawnTranscripts, micronsPerUnit: number | null): void;
+    /** The cell-type column the drawn entries' cells are named by, or null. */
+    setTypes(types: CategoricalCodes | null): void;
+    /** Nothing is drawn any more. */
+    clear(): void;
+    /** Stop a pending details request and forget what was drawn. */
+    dispose(): void;
+    /**
+     * Tooltip lines for the transcript marker under world point `(wx, wy)`, or null.
+     *
+     * The marker is napari-js's pick on the drawn layer: hit anywhere on it, or within
+     * `radiusWorld` of its centre when it is smaller than that, the NEAREST centre winning
+     * among several (an exact tie, such as two genes' groups on one bin centre, goes to the one
+     * drawn on top). Returns what is known at once (gene, count, cell type); anything that needs
+     * the server — distinct genes in a group, its top genes and cells, the cell's display id —
+     * arrives through `onDetails` once the pointer has rested on the marker briefly.
+     */
+    hoverAt(wx: number, wy: number, radiusWorld: number, onDetails: (lines: string[]) => void): string[] | null;
+    private fetchDetails;
+    /** The tooltip text for entry `i`, with the server's details when they have arrived. */
+    private describe;
+}
+/** What the transcript layer currently shows — what hovering needs to name a marker. */
+export interface DrawnTranscripts {
+    kind: TranscriptKind;
+    bin?: TranscriptBin;
+    merged: SpatialTranscriptTile;
+    /** The layer the entries are drawn in, one marker per entry in the same order. */
+    layer: PointsLayer;
+    genes: string[];
+    /** For a grouped gene selection: each entry's group, and the groups' names. */
+    entryGroup?: Int32Array;
+    groupNames?: string[];
+    /** Each group's genes, when the markers came from the density grids (for the hover). */
+    groupGenes?: string[][];
+}