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

package/lib/implementations/napari-js/napari-volume-region-meshes.d.ts

@@ -0,0 +1,66 @@
+import type { Viewer } from 'napari-js';
+/** A region's 3D reconstruction to show in the volume: a mesh in image px (x, y) and slices (z). */
+export interface RegionMesh3D {
+    /** Identity (a class name): a mesh with the same key and arrays is kept, not rebuilt. */
+    key: string;
+    /** `#rrggbb`. */
+    color: string;
+    /** What hovering it shows ("HPF · Hippocampal formation"); default: the key. */
+    label?: string;
+    vertices: Float32Array;
+    faces: Uint32Array;
+}
+/** Where the stack sits in the volume's world: its full size, and the centred world box it fills. */
+export interface VolumeFrame {
+    /** Image width, height (px) and slice count. */
+    size: [number, number, number];
+    /** The world box (centred on the origin), Z as currently stretched. */
+    world: [number, number, number];
+}
+/** Opacity of a region's surface in the volume. */
+export declare const REGION_MESH_OPACITY = 0.55;
+/** While some surfaces are highlighted: theirs (near opaque, so their shape reads) … */
+export declare const REGION_MESH_HIGHLIGHT_OPACITY = 0.9;
+/** … and the others' (ghosted: still there for context, not in the way). */
+export declare const REGION_MESH_DIMMED_OPACITY = 0.12;
+/**
+ * The region reconstructions shown in a volume view: one translucent surface per region, in its
+ * colour, placed in the volume's world box (pixel x, y and slice z mapped onto it the way the
+ * volume maps its voxels) and re-placed when the volume's Z is stretched. A surface is updated in
+ * place (`setData`, `color`) rather than added again, and picked by napari-js (`pickSurface`).
+ *
+ * Highlighting is focus + context: the highlighted surfaces turn near opaque and the others fade
+ * to a ghost, so the selection stands out while staying in place among its neighbours.
+ */
+export declare class VolumeRegionMeshes {
+    private readonly viewer;
+    private readonly layers;
+    private highlighted;
+    private hidden;
+    /** The meshes to show (kept while the volume has no frame yet). */
+    private wanted;
+    private frame;
+    constructor(viewer: Viewer);
+    /** Show exactly `meshes` (adding, keeping or removing surfaces). */
+    set(meshes: readonly RegionMesh3D[]): void;
+    /** Follow the volume's frame (it opened, or its Z was stretched): re-place every surface. */
+    setFrame(frame: VolumeFrame): void;
+    /** Highlight the surfaces of these keys (none: every surface as usual). */
+    setHighlight(keys: Iterable<string>): void;
+    /** Hide the surfaces of these keys (they are kept, so showing them again is instant). */
+    setHidden(keys: Iterable<string>): void;
+    /** The front-most surface under screen point (`x`, `y`) (canvas CSS px), or null. */
+    pickAt(x: number, y: number): RegionMesh3D | null;
+    /** The meshes shown. */
+    get shown(): RegionMesh3D[];
+    clear(): void;
+    private sync;
+    private add;
+    private opacityOf;
+    private remove;
+}
+/**
+ * Image px / slice coordinates → the volume's centred world box: pixel x of a `w`-wide image
+ * spans the box's width, slice k sits at the middle of its share of the box's depth.
+ */
+export declare function toWorld(vertices: Float32Array, frame: VolumeFrame): Float32Array;

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

@@ -0,0 +1,148 @@
+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, VolumeVoxelsOnScreen } from './napari-scene';
+import { RegionMesh3D } from './napari-volume-region-meshes';
+import { SlicePlanes } from './napari-volume-slice-planes';
+/**
+ * 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;
+    /** Regions' 3D reconstructions shown in the volume (see {@link setRegionMeshes}). */
+    private readonly regionMeshes;
+    /** The planes of the sections shown beside the volume, marked and draggable in it. */
+    private readonly slicePlanes;
+    /** The image's full size (px, px, slices), which reconstructions are in. */
+    private fullSize;
+    /** Clicks and hover on the reconstructions (with the selection tool). */
+    private meshPointer;
+    private toolSub;
+    private selecting;
+    constructor(ctx: SceneContext, info: IImageInfo | undefined, rendering: 'iso' | 'mip');
+    /** Show these region reconstructions in the volume (replacing the ones shown). */
+    setRegionMeshes(meshes: readonly RegionMesh3D[]): void;
+    setRegionHighlight(keys: readonly string[]): void;
+    setRegionHidden(keys: readonly string[]): void;
+    /** Whether the volume lets every region through (see {@link setRegionsThroughVolume}). */
+    private regionsThrough;
+    /**
+     * The volume hides the region reconstructions behind what it shows (its brightest sample along
+     * each ray, napari-js's `'translucent'` depth) — the perspective of a region behind the
+     * cerebellum — or, `through`, hides none (`'translucent_no_depth'`): surfaces traced inside its
+     * bright structures, an OCT's layer boundaries in its bright bands, which that depth speckles
+     * or hides. A multichannel volume's channels add up and hide nothing either way.
+     */
+    setRegionsThroughVolume(through: boolean): void;
+    private applyVolumeDepth;
+    /** Show the planes of the sections beside the volume where they are (null: hide one). */
+    setSlicePlanes(planes: SlicePlanes): void;
+    /**
+     * The assembled volume's voxels per channel (key 0: the grayscale one), its frame, and whether
+     * it is a multichannel composite — what the sections beside it are cut from. Null before it is
+     * assembled.
+     */
+    volumeVoxels(): VolumeVoxelsOnScreen | null;
+    /**
+     * Picking the reconstructions: with the selection tool armed, a click on one selects its class
+     * (null beside them); resting over one names it, whatever the tool.
+     */
+    private listenToRegionMeshes;
+    /** Image px per voxel of the assembled volume (in-plane), or null before it is assembled. */
+    voxelStep(): number | null;
+    /** Place the region reconstructions in the volume's world box as it is now. */
+    private frameRegionMeshes;
+    /**
+     * 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-slice-planes.d.ts

@@ -0,0 +1,43 @@
+import type { Viewer } from 'napari-js';
+import type { VolumeFrame } from './napari-volume-region-meshes';
+/** A plane across the volume: x = const, y = const (image px) or z = const (a slice). */
+export type PlaneAxis = 'x' | 'y' | 'z';
+/** Where each plane is (image px for x and y, the slice for z); null: not shown. */
+export type SlicePlanes = Record<PlaneAxis, number | null>;
+/** Each plane's colour: its axis's, as the axes gizmo draws them. */
+export declare const SLICE_PLANE_COLORS: Readonly<Record<PlaneAxis, string>>;
+/** A plane's opacity: enough to read where it is, not to hide the volume behind it … */
+export declare const SLICE_PLANE_OPACITY = 0.22;
+/** … and while it is dragged. */
+export declare const SLICE_PLANE_DRAG_OPACITY = 0.4;
+export interface SlicePlanesOptions {
+    /** A plane dragged to `value` along its axis (image px, or a fractional slice). */
+    onMove(axis: PlaneAxis, value: number): void;
+}
+/**
+ * The planes of the sections shown beside a volume view: napari-js's {@link SlicePlanesWidget}
+ * (translucent quads in their axis's colour, each with a grip that drags it along its axis) over
+ * the stack's frame. It works in the frame's image px and slices: the widget's box is the image,
+ * one voxel per px, so a px position is the widget's shifted by half a pixel (pixel i spans
+ * [i, i + 1) here, is centred on i there); a slice is the same in both.
+ */
+export declare class VolumeSlicePlanes {
+    private readonly viewer;
+    private readonly host;
+    private readonly opts;
+    private widget;
+    private frame;
+    private planes;
+    /** Set while the planes are moved from here, so the widget's echo is not reported as a drag. */
+    private applying;
+    constructor(viewer: Viewer, host: HTMLElement, opts: SlicePlanesOptions);
+    /** Follow the volume's frame (it opened, or its Z was stretched). */
+    setFrame(frame: VolumeFrame): void;
+    /** Show the planes where they are now (null: hide one). */
+    set(planes: SlicePlanes): void;
+    clear(): void;
+    destroy(): void;
+    /** The widget over the current frame, made when there is one and a plane to show. */
+    private rebuild;
+    private apply;
+}

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;
+}