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

package/lib/implementations/napari-js/napari-visualizer.service.d.ts

@@ -1,30 +1,28 @@
 import { Observable, BehaviorSubject } from 'rxjs';
 import { Image } from 'image-js';
 import { IImageInfo } from '../../contracts/image.contract';
-import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
-import { SpatialObservations } from '../../contracts/spatial-dataset.contract';
-import { TranscriptEstimate } from './napari-spatial-tiles';
-import { SpatialSelectionStore } from '../../store/spatial-selection.service';
-import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
-import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from '../../contracts/visualizer.contract';
-import { ViewerCapabilities } from '../../contracts/capabilities.contract';
-import { IRegionOverlay } from '../../contracts/region-overlay.contract';
 import { IHistogram } from '../../contracts/channel-histogram-api.contract';
-import { IWandOptions, IBrushOptions } from '../../contracts/display-types';
-import { VizConfig } from '../../contracts/viz-config';
+import { CanvasToolId } from '../../contracts/display-types';
+import { IRegionOverlay } from '../../contracts/region-overlay.contract';
+import { SpatialObservations } from '../../contracts/spatial-dataset.contract';
+import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
 import { TileAccessPort } from '../../contracts/ports/tile-access.port';
-import { BaseStoreVisualizer } from '../base-store-visualizer';
-import { SimpleSliceAccessService } from '../simple-slice-access.service';
+import { VizConfig } from '../../contracts/viz-config';
+import { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
+import { ViewerCapabilities } from '../../contracts/capabilities.contract';
+import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
+import { IViewerBackend, PixelData, IIsosurfaceControls, IIntensityControls, ISurface3dControls, IOsdViewOptions, IVolumeResolution, IIntensityViewportSource } from '../../contracts/visualizer.contract';
 import { VisualizerStore } from '../../store/visualizer-store.service';
 import { RegionStore } from '../../store/region-store.service';
-import { WandToolService } from '../../toolbar/wand/wand-tool.service';
-import { BrushToolService } from '../../toolbar/brush/brush-tool.service';
-import { VertexEraserToolService } from '../../toolbar/vertex-eraser/vertex-eraser-tool.service';
-import { ZoomToBoxToolService } from '../../toolbar/zoom-to-box/zoom-to-box-tool.service';
+import { SpatialSelectionStore } from '../../store/spatial-selection.service';
+import { CanvasToolManager } from '../../toolbar/tool-kit/canvas-tool-manager';
+import { WandService } from '../../toolbar/wand/wand.service';
 import { SamToolService } from '../../toolbar/segmentation/sam-tool.service';
 import { SamPointToolService } from '../../toolbar/segmentation/sam-point-tool.service';
 import { CellSegmentToolService } from '../../toolbar/segmentation/cell-segment-tool.service';
-import { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
+import { BaseStoreVisualizer } from '../base-store-visualizer';
+import { SimpleSliceAccessService } from '../simple-slice-access.service';
+import { TranscriptEstimate } from './napari-spatial-tiles';
 import * as i0 from "@angular/core";
 /** Opaque handle from {@link NapariVisualizerService.load}, passed back to plot(). */
 interface NapariLoaded {
@@ -34,138 +32,42 @@ interface NapariLoaded {
      *  handle's `filename` doesn't match the requested image (guards against stale clicks). */
     filename: string;
 }
-export declare class NapariVisualizerService extends BaseStoreVisualizer implements IVisualizer {
-    private readonly tiles;
-    private readonly wandTool;
-    private readonly brushTool;
-    private readonly eraserTool;
-    private readonly zoomToBoxTool;
+/**
+ * The WebGPU image backend, built on the published `napari-js` library (jit-ui#102: a
+ * browser-based napari shipped as a JS library, alongside OpenSeadragon for images and Plotly
+ * for 3D).
+ *
+ * One scene is mounted per {@link plot}, chosen by plot type:
+ *  - **2D image** (and the region-centroid scatter and spatial-omics views over it): pyramidal
+ *    `TiledSource`s against the jit-service `/tile` endpoint when `/tiles/info` describes the
+ *    image, else a single stitched level (`tiled:false` stacks fetch each slice's own URL);
+ *    multichannel additive tints, grayscale colormap or RGB; scale bar, navigator, region
+ *    overlay and the shared pixel tools (wand, brush, eraser, zoom-to-box, SAM/cellpose).
+ *  - **Volume / isosurface / 3D scatter / surface**: slices assembled into a decimated volume
+ *    (or one height field per slice), with the axes gizmo and the Z-height handle.
+ *  - **Spatial omics 2D / 3D**: observation markers or a 3D cloud, gene maps, density volumes,
+ *    level-of-detail tiles, hover tooltip and click-to-select.
+ *
+ * Per-channel histograms come from the client data, or from the server's `/histogram` for
+ * >8-bit images; TIFF export from `/export/tiff`. Region state and display options delegate to
+ * the shared {@link RegionStore} / {@link VisualizerStore} through {@link BaseStoreVisualizer},
+ * exactly as OSD does. napari-js's render loop and the hot pointer paths run outside the
+ * Angular zone.
+ */
+export declare class NapariVisualizerService extends BaseStoreVisualizer implements IViewerBackend {
     private readonly samTool;
     private readonly samPointTool;
-    private readonly cellSegmentTool;
-    private readonly cellSegmenter;
     private readonly simpleStack;
-    private readonly spatialData;
-    private readonly selectionStore;
     readonly capabilities: ViewerCapabilities;
-    private readonly api;
+    /** The jit-service tile server: descriptor, slices, tiled sources, histograms, export. */
+    private readonly tileClient;
+    /** napari-js's render loop and the hot pointer/timer paths run outside the Angular zone
+     *  (NAPARI-SVC-25); what they produce for the UI re-enters it through {@link inZone}. */
+    private readonly zone;
     private viewer;
     private canvas;
     private host;
     private loaded;
-    private lastPixels;
-    private currentPlotType;
-    /** napari-js high-level view owning the 3D volume layers (one additive tinted layer per channel
-     *  for multichannel, or a single grayscale volume). Null in 2D. */
-    private volumeView;
-    /** True when the volume is composited from per-channel layers (vs a single grayscale volume). */
-    private volumeMultichannel;
-    /** napari-js height-field surface mesh (NAPARI_SURFACE plot type; null otherwise). Built from a
-     *  single grayscale slice by {@link buildSurface} via napari-js's `heightField` + `addSurface`. */
-    private surfaceLayer;
-    /** Which band the surface samples (a channel index for multichannel, else the composite). */
-    private surfaceChannel;
-    /** True when the mounted Surface follows one band of a multichannel image. */
-    private surfaceMultichannel;
-    /** Pre-loaded per-slice luminance planes (already decimated to the surface grid), keyed by z,
-     *  so the stack slider rebuilds the surface instantly. Filled by {@link preloadSurfacePlanes}. */
-    private readonly surfacePlanes;
-    /** In-plane grid cap for the active surface load (full grid ÷ the decimate factor). */
-    private surfaceMaxGrid;
-    /** Contrast window [min,max] the current surface mesh was built with. A change reshapes the
-     *  mesh (pixel height = intensity within [min,max]), so it triggers a geometry rebuild. */
-    private surfaceWindow;
-    /** Persisted wireframe choice for the surface (re-applied when a new surface mounts). */
-    private surfaceWireframe;
-    /** napari-js 2D scatter points (region centroids) + its region-change subscription. */
-    private scatter2dPoints;
-    private scatterRegionSub;
-    /** napari-js 3D scatter (voxel point cloud). */
-    private scatter3dLayer;
-    /** Spatial-omics observation markers + the dataset/view subscription driving them. */
-    private spatialPoints;
-    /** The 3D point cloud. One layer: selection is a per-point alpha on it, not a second. */
-    private spatialPoints3d;
-    private spatialLayerKey3d;
-    /** Interleaved x,y,z, cached so a colour change does not re-walk 3.7M observations. */
-    private spatialPositions3d;
-    /** Identity of the scalars currently uploaded — see {@link rebuildSpatialPoints3d}. */
-    private spatialScalarKey3d;
-    /** The anatomical volume the cloud sits inside, when the dataset has one. */
-    private spatialVolume;
-    private spatialVolumeKey;
-    /** Per-cluster density volumes drawn alongside the cloud, and what they were
-     *  built from — rasterising is seconds of work, so it must not repeat for a
-     *  change that cannot affect the field. */
-    private densityLayers;
-    private densityKey;
-    /** Selection identity, as a number the density key can carry. */
-    private lastSelectionSeen;
-    private selectionRevision;
-    /** The gene map: its layer, the field it was estimated from, and the inputs each
-     *  was built for — the field is the expensive half and survives a recolour. */
-    private geneMapLayer;
-    private geneMapKey;
-    private geneMapField;
-    private geneMapFieldKey;
-    /** The 3D gene map: its volume layer, the field behind it, and the inputs each
-     *  was built for — same two clocks as the 2D map. */
-    private geneMapVolumeLayer;
-    private geneMapVolumeKey;
-    private geneMapVolumeField;
-    private geneMapVolumeFieldKey;
-    /** Offset applied to observation coordinates to sit them in the volume's box. */
-    private spatialOrigin3d;
-    /** Cursor tooltip for the spatial views, and everything it needs: what the
-     *  cloud is coloured by, and where each drawn observation is. */
-    private spatialTooltip;
-    private hoverSource;
-    private hoverSourceKey;
-    /** Sequences the async resolutions. The KEY is only committed once one lands,
-     *  so a superseded fetch cannot leave the cache claiming to hold a source it
-     *  never stored. */
-    private hoverSourceToken;
-    /** Drawn observations' positions for hit-testing, indexed BY OBSERVATION with
-     *  NaN for anything not drawn. Screen pixels in 3D (the camera moves them, so
-     *  they are rebuilt when it does) and WORLD units in 2D (where the camera only
-     *  scales, so the pointer is converted instead of 374k points). */
-    private hoverPositions;
-    private hoverPositionsRev;
-    /**
-     * Screen-space bucket index over the 3D projection, built on the first hover after the
-     * scene moved rather than when it moves.
-     *
-     * Lazily, and that is the whole design: an orbit drag changes the camera every frame, so
-     * building eagerly would spend tens of milliseconds a frame indexing for picks nobody is
-     * making. Deferred, it is built once when the drag stops and the pointer next moves —
-     * measured upstream at 3.7M points, that turns a 12.6 ms scan per pointermove into
-     * 0.066 ms.
-     */
-    private hoverIndex;
-    /** Bumped whenever the cached positions go stale: a marker rebuild, or — in 3D
-     *  only, where the projection depends on it — a camera move. */
-    private spatialSceneRev;
-    private hoverPointer;
-    private hoverFrame;
-    private hoverOff;
-    /** Observation indices the cached 3D positions belong to, in the same order;
-     *  null when every observation is drawn. Without it a projection built from the
-     *  positions is indexed by DRAWN order and silently attributes each point to
-     *  the wrong observation as soon as a section is isolated. */
-    private spatialDrawn3d;
-    /** Reused projection buffers — see {@link getSpatialScreenProjection}. */
-    private spatialProjection3d;
-    /** Per-observation depth from the last projection, for the depth-aware hover pick. */
-    private spatialDepths3d;
-    /** The (viewer, dataset) whose 3D scene has already had its opening framing. */
-    /** Whose 2D observations the camera has been framed on — see {@link frameSpatialPointsOnce}. */
-    private spatial2dFramed;
-    /** Dataset the 3D scale bar was built for. */
-    private spatialScaleBarKey;
-    private spatialSub;
-    /** Level-of-detail cell outlines, transcripts and density over the 2D view — created on
-     *  first use, and only when a spatial port is bound. */
-    private spatialTilesMgr;
     /** For the panel: the transcripts-in-view estimate and the density window in use. */
     readonly transcriptEstimate$: BehaviorSubject<TranscriptEstimate | null>;
     /** Transcripts of each selected gene in view (see NapariSpatialTileLayers.geneCountsIn). */
@@ -175,713 +77,70 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
         hi: number;
         max: number;
     } | null>;
-    /** Latest (dataset, view, selection) the spatial subscription saw, so a slice
-     *  change can rebuild the markers for the new plane. */
-    private spatialLatest;
-    /** Which dataset the current marker layer was built for, so a display-only
-     *  change (size, colour, opacity, selection) can update it in place. */
-    private spatialLayerKey;
-    /** Monotonic guard for the async colour rebuild: fetching a gene vector is a
-     *  round-trip, so a fast sequence of colour-by changes can resolve out of
-     *  order. Only the newest rebuild is allowed to touch the layer. */
-    private spatialRebuildToken;
     /** "x reloading…" at the bottom of the canvas: the tile layers' loads and the observations'. */
-    private loadingBadge;
-    private tileLoading;
-    private observationsLoading;
-    /** Image tiles in flight, and the scene they belong to: a fetch that outlives {@link reset}
-     *  settles against the old generation and leaves the new scene's count alone. */
-    private imageTilesLoading;
-    private imageTilesGeneration;
-    /** Monotonic load generation. Bumped by {@link reset} and {@link cancelLoading}; the frame-loading
-     *  loops (volume assembly, surface preload) capture it and bail when it changes, so a Cancel (or a
-     *  new plot) actually stops fetching frames instead of running to completion in the background. */
-    private loadToken;
-    /** Decimate factor for the napari 3D types (1 = Full, 2 = ½ default, 4 = ¼, 8 = ⅛). Applied when a
-     *  volume/isosurface/surface (re)loads; changing it needs a re-plot (it changes fetched data). */
-    private resolutionScale;
-    /** 3D coordinate-axes / scale gizmo for the volume/isosurface view (null in 2D). */
-    private axesLayer;
-    /** DOM X/Y/Z + scale labels tracking the 3D axes gizmo (null in 2D). */
-    private axesLabels;
-    /** Draggable Z-height grip over the volume (null unless a volume/isosurface is mounted). */
-    private zHandle;
-    /** User Z-height factor for the volume (1 = the volume's natural proportions); driven by the
-     *  in-view drag handle. Reset per mount. */
-    private volumeZScale;
-    /** Volume world box at `volumeZScale = 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 volumeWorldBase;
-    private volumeSampledDepth;
-    /** Persisted axes on/off choice, re-applied when a new volume mounts. Defaults on. */
-    private axesVisible;
-    private volumeDims;
-    /** 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 volumeChannelData;
+    private readonly badge;
+    /** The store's display state (colormap, reverse, invert) and the colormaps derived from it. */
+    private readonly display;
+    /**
+     * The mounted scene's lifetime: aborted by {@link reset}, so everything a plot starts — its
+     * descriptor poll, its tile fetches, its badge counts, its awaits — can tell that a newer plot
+     * has replaced it. A tile that settles after a reset belongs to the aborted scene and leaves the
+     * new scene's count alone.
+     */
+    private lifetime;
+    /** What {@link plot} mounted, while it is mounted. */
+    private scene;
+    /** Spatial state that outlives a scene (latest data, windows, estimated gene-map fields). */
+    private readonly spatial;
+    /** Viewer settings that outlive a scene. */
+    private readonly settings;
+    /**
+     * Frame loading (volume assembly, surface preload): aborted by {@link reset} AND by
+     * {@link cancelLoading}, so a Cancel actually stops fetching frames instead of running to
+     * completion in the background, while the scene itself stays mounted. (Latest-wins WITHIN a
+     * scene — a scrub, a colour rebuild, a hover-source fetch — is each scene's own business.)
+     */
+    private loading;
+    /** The image's full-resolution size as the last scene drew it (it outlives the scene). */
     private imageW;
     private imageH;
-    /** Monotonic slice-request id so a slow out-of-order slice fetch can't clobber a newer one. */
-    private sliceReq;
-    /** Cached `/tiles/info` pyramid descriptor + the infoB64 it was fetched for. */
-    private descriptor;
-    private descriptorKey;
-    /** How the current 2D image is composited (drives histogram + state application). */
-    private imageMode;
-    /** napari-js high-level view that owns the per-channel layer set (build + live display
-     *  updates) for the current {@link imageMode}. Rebuilt on each (re)render. */
-    private channelView;
-    /** Live subscription applying channel-state / colormap changes to the layers. */
-    private displaySub;
-    /** Latest grayscale colormap selection from the store (applied to the single gray layer). */
-    private currentColormap;
-    private currentReverse;
-    /** Latest invert toggle from the store (flips intensity before the colormap, like OSD). */
-    private invertEnabled;
-    /** Physical scale bar overlay for the 2D image (null when 3D or the image has no µm/pixel). */
-    private scaleBar;
-    /** Overview minimap (bottom-right), as OSD's navigator. */
-    private navigator;
-    /** Whether the navigator is shown — the same host setting OSD's navigator honours. */
-    private navigatorVisible;
-    /** Bumped per thumbnail request, so a slow one cannot overwrite a newer slice's. */
-    private navigatorToken;
-    /** SVG region-drawing overlay for the 2D image (null until a 2D image is plotted). */
-    private regionOverlay;
-    /** Pixel-tool plumbing: the plot div id, coord transform, and bound tool hosts. */
-    private plotDivId;
-    private coordTransform;
-    private wandHost;
-    private eraserHost;
-    /** Cached CachedImageData built from the last readback (rebuilt when lastPixels changes). */
-    private cachedImage;
-    private cachedImageSource;
-    /** Visible world rect captured AT the last readback — must pair with `lastPixels` so the pixel
-     *  tools' ratios/origin match the matrix's camera (using the live rect after a pan/zoom would
-     *  mis-scale the region). */
-    private lastPixelsRect;
-    /** Image smoothing (bilinear) vs nearest-neighbour (crisp pixels, the default). */
-    private imageSmoothing;
-    /** True when the 2D image is rendered via pyramidal TiledSources (descriptor available). */
-    private tiled;
-    /** Debounced readback timer + camera-change unsubscribe (keep lastPixels current for tools). */
-    private readbackTimer;
-    private cameraReadbackOff;
-    /** Coarse per-channel luminance sample (keyed by channel index) for the histogram in tiled mode,
-     *  where the layers have no full in-memory pixels. Refreshed on plot + slice change. */
-    private readonly histSamples;
-    /** Native-bit-depth histograms from `/histogram`, keyed `${z}|${channel}` (>8-bit images). */
-    private readonly nativeHistograms;
+    /** The region overlay, the pixel tools and the displayed-pixel readback they read. */
+    private readonly tools;
+    /** This backend's own wand, brush, eraser, zoom-to-box and SAM point tools. */
+    protected readonly canvasTools: CanvasToolManager;
     private readonly stackLoading$;
     private readonly stackLoadingProgress$;
     private readonly autoscaleEvent$;
-    private readonly intensityProfile$;
     private readonly viewportChange$;
-    constructor(tiles: TileAccessPort, store: VisualizerStore, regionStore: RegionStore, wandTool: WandToolService, brushTool: BrushToolService, eraserTool: VertexEraserToolService, zoomToBoxTool: ZoomToBoxToolService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, simpleStack: SimpleSliceAccessService, config: VizConfig, spatialData?: SpatialDataPort | null, selectionStore?: SpatialSelectionStore | null);
-    /**
-     * Fetch + cache the server pyramid descriptor (`GET /tiles/info`): the REAL per-level tile grid,
-     * tile size, channel metadata and physical pixel size. The backend returns 202 while the source
-     * is still caching, so we poll briefly. Cached per `infoB64`; returns null if it never becomes
-     * ready (callers fall back to a single-tile fetch). This is the authoritative grid — guessing
-     * level dims from `trueImageSize` overshoots the real grid and the server 400s out-of-range tiles.
-     */
-    private ensureDescriptor;
-    /**
-     * Fetch a COMPLETE rendered slice as an `ImageBitmap` by stitching the server's REAL tile grid
-     * (from `/tiles/info`) — not just the top-left tile, which only ever showed a large image's
-     * corner. Picks the finest pyramid level whose grid fits `budgetTiles` and whose longest side is
-     * within the GPU texture limit, fetches that grid concurrently, and stitches it into one canvas.
-     *
-     * `channel` selects a single band as grayscale (real levels only); omit for the server composite.
-     * `budgetTiles` caps the grid: the 2D view uses the full budget for detail; the 3D volume passes
-     * 1 for a cheap overview tile per slice (it downsamples to {@link VOLUME_MAX_SLICE}). Falls back
-     * to a single `col=0,row=0` tile when no descriptor is available (small/simple images, volumes).
-     */
-    private fetchSlice;
-    load(imageInfo: IImageInfo, zIndex: number): Promise<NapariLoaded>;
-    plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, _inPlace?: boolean): Promise<boolean>;
-    /** The grayscale display colormap from the store selection (+reverse), defaulting to gray.
-     *  Maps the jit-ui store colormap node to a napari `Colormap` via the library's LUT factory;
-     *  the multichannel tint ramps are built inside {@link MultiChannelImageView} from each
-     *  channel's hex colour. */
-    private grayscaleColormap;
-    /** Fetch a stitched slice and read it back as a single-channel uint8 plane. `channel` selects a
-     *  band (multichannel); omit it for the grayscale composite (all overview levels available, so a
-     *  large image picks a fitting downscaled level rather than only the full-res real level). */
-    private fetchChannelData;
-    /** Decode an `ImageBitmap` (server bands are grayscale, R=G=B) to a single-channel uint8 plane.
-     *  `maxSide` caps the longest side (downscaling on the canvas draw) — used to keep pre-loaded
-     *  surface slice planes small. */
-    private bitmapToLuminance;
-    /**
-     * Render the 2D image for slice `z`. With a server pyramid descriptor we use a pyramidal
-     * {@link TiledSource} per layer so the view refines to higher resolution on zoom (like OSD) and
-     * sits naturally in full-resolution coordinates; without one we fall back to the single-level
-     * stitch. Three display modes either way: multichannel additive tint, grayscale colormap, RGB.
-     */
-    private renderImage;
-    /** Single-level stitch fallback (no descriptor): the pre-tiling path. */
-    private renderImageStitched;
-    /**
-     * Render the 2D image with pyramidal {@link TiledSource}s — the view refines to higher resolution
-     * as you zoom in (the visual fetches the level whose texels ≈ screen pixels) and sits in full-res
-     * coordinates so regions align. Same three modes as the stitch path. Per-channel layers use the
-     * REAL pyramid levels (per-channel tiles only exist there); the composite uses all levels.
-     */
-    private renderImageTiled;
-    /** Build a pyramidal TiledSource backed by the server `/tile` endpoint. `channel` selects a band
-     *  (grayscale luminance, real levels only); omit it for the composite (RGBA, all levels).
-     *  `scene` is the generation of the render that asked for it, taken before that render's awaits. */
-    private buildTiledSource;
-    /** (Re)fetch a coarse per-channel luminance sample for the histogram (tiled mode has no full
-     *  in-memory pixels). One cheap overview tile per channel; cached by channel index. */
-    private refreshHistogramSamples;
-    /** Subscribe channel states + grayscale colormap → live-apply to the rendered layers (no
-     *  re-fetch; only z changes re-fetch). Replaces any prior subscription. */
-    private subscribeDisplayState;
-    /** Subscribe the store colormap (+reverse), invert, and channel state → the volume/isosurface
-     *  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. Replaces any prior subscription. */
-    private subscribeVolumeDisplayState;
-    /** A channel's tint colormap (black→colour) with reverse-scale / invert applied by flipping. */
-    private channelTintColormap;
-    /**
-     * Colour map for the volume/isosurface. A real colormap selection (viridis/magma/…) wins;
-     * otherwise the channel's colour tints it (so the channel-dialog colour swatch recolors the 3D
-     * render). Reverse-scale and invert each flip the ramp — the `VolumeLayer` has no per-layer
-     * invert, so both are emulated by reversing the colormap.
-     */
-    private volumeColormap;
-    /** Apply the current channel states / colormap to the live layers (no re-fetch), delegating the
-     *  per-channel layer mutations to the {@link MultiChannelImageView}. */
-    private applyDisplayState;
-    /** (Re)install the physical scale bar over the 2D image, sized from the image's µm/pixel
-     *  (`/tiles/info` mppX, falling back to the image metadata). No-op without a physical size. */
-    private installScaleBar;
-    /**
-     * The overview navigator for a 2D view with an image: a coarse thumbnail of the whole
-     * image with the viewport on it; click or drag to pan at the current zoom (as OSD).
-     */
-    private showLoading;
-    private installNavigator;
-    /**
-     * Draw the navigator's thumbnail from the coarsest pyramid level. A multichannel image
-     * is composited from its channels in their display colours, so the overview looks like
-     * the view rather than like channel 0 in grey.
-     */
-    private refreshNavigatorImage;
+    constructor(tiles: TileAccessPort, store: VisualizerStore, regionStore: RegionStore, wandService: WandService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, simpleStack: SimpleSliceAccessService, config: VizConfig, spatialData?: SpatialDataPort | null, selectionStore?: SpatialSelectionStore | null);
+    /** Run `fn` inside the Angular zone: for output (subjects the UI renders, store writes)
+     *  produced by work that runs outside it. */
+    private inZone;
+    /** What a scene is built from (see {@link SceneContext}). */
+    private sceneContext;
+    /**
+     * Record the image to draw. No network work happens here — the descriptor poll and the tile,
+     * volume and spatial fetches all run in {@link plot} under its scene signal, which a newer plot,
+     * {@link reset} or `cancelLoading()` aborts — so `signal` is only checked: an already-aborted
+     * load rejects with an `AbortError` and leaves the recorded image alone.
+     */
+    load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<NapariLoaded>;
+    plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
+    /** The scene a plot type mounts. */
+    private createScene;
     /** Show/hide the overview navigator (same setting as OSD's). */
     setNavigatorVisible(visible: boolean): void;
-    /** Convert a napari-js `Histogram` (bin count + min/max) to the pane's `IHistogram` (bin edges). */
-    private toIHistogram;
-    /**
-     * Mount the 3D volume/isosurface. A multichannel image becomes one additive, tinted
-     * {@link VolumeLayer} per channel (so each channel's colour composites into the render); a
-     * grayscale/composite image uses a single volume. Adds the axes gizmo + labels and wires the
-     * display-state subscription. The caller owns `viewer.ready`.
-     */
-    private mountVolume;
-    /**
-     * 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.
-     */
-    private setVolumeZScale;
-    /** Build the X/Y/Z axis-end label specs for the 3D 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. */
-    private buildAxesLabels;
-    /**
-     * 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;
-    /**
-     * Assemble a downsampled uint8 volume (luminance) from the per-slice tile endpoint. Slices are
-     * fetched with bounded concurrency (keeps the connection pool full without flooding it on a deep
-     * stack) and read into the volume as each arrives, driving {@link stackLoadingProgress$} so the
-     * host shows a determinate progress bar instead of a bare spinner.
-     */
-    private assembleVolume;
-    /**
-     * Mount the NAPARI_SCATTER 2D scatter: the slice image with a points layer at each region's
-     * centroid (napari-js analog of Plotly's region-centroid scatter). Rebuilds the points live as
-     * regions change.
-     */
-    private mountScatter;
-    /** (Re)build the 2D scatter's point layer at the current region centroids. */
-    private rebuildScatterPoints;
-    /** Region centroids as flat `[x, y, …]` data coords (rectangle / polygon / multipolygon). */
-    private regionCentroids;
-    /**
-     * The interaction stack every 2D mode needs: the region overlay (draw/select/edit), the pixel
-     * tools that read back displayed pixels (wand, brush, vertex eraser, zoom-to-box, SAM/cellpose),
-     * and a camera hook that keeps that readback current as the view pans/zooms and tiled levels
-     * load.
-     *
-     * Extracted because forgetting it is invisible: the toolbar gates its region buttons on 2D-vs-3D
-     * rather than on plot type, so a 2D mode that skips this shows every tool and silently does
-     * nothing. That is exactly what happened to the spatial and region-centroid scatter modes.
-     */
-    private install2dInteraction;
-    /** Marker radius (image px) for a dataset that declares none — segmented cells often don't. */
-    private static readonly SPATIAL_FALLBACK_RADIUS;
-    /** Smallest marker DIAMETER, in slice pixels, over a volume-backed dataset. A cell's real
-     *  size is honoured wherever it survives the grid: the ABC atlas serves 5 µm radii on a
-     *  40 µm/px template, so drawing them to scale would put every cell a fifth of a pixel wide
-     *  and the section would come up empty. The point-size control scales up from this floor. */
-    private static readonly SPATIAL_SLICE_MIN_DIAMETER_PX;
-    /** Longest side of the gene-map raster, in field pixels. A gene map is a smooth
-     *  field read as territory, so it gains nothing from matching a 2 Gpx slide's
-     *  resolution — and the estimate costs one pass over this many pixels. */
-    private static readonly GENE_MAP_MAX_SIDE;
-    /** Kernel σ in field pixels at smoothing 1: wide enough to read between cells,
-     *  tight enough to keep a nucleus-scale structure distinct. */
-    private static readonly GENE_MAP_SIGMA;
-    /** Clusters drawn as density volumes at once. Past a handful, additive translucent
-     *  clouds stop being separable by eye — and each one is a full rasterisation. */
-    private static readonly DENSITY_MAX_CLUSTERS;
-    /** Colour for observations when nothing is selected to colour by: visible, neutral, and
-     *  obviously not encoding anything. */
-    /** How much larger a selected marker is drawn, so a small selection is findable inside a
-     *  3.7M-point cloud rather than merely brighter. */
-    private static readonly SPATIAL_SELECTED_SIZE_SCALE;
-    private static readonly SPATIAL_NEUTRAL_COLOR;
-    /**
-     * Mount the SPATIAL_OMICS view: the tissue image with one marker per observation, coloured by
-     * an annotation column or a gene. The markers rebuild whenever the dataset or the view state
-     * changes, so switching the colour-by column does not remount the scene.
-     *
-     * Sets up the full 2D interaction stack — region overlay, pixel-tool hosts, readback currency —
-     * exactly as the plain image view does. That is NOT optional here: this mode's selection is
-     * driven by drawn ROIs, so without the overlay there is no way to make a selection at all.
-     */
-    private mountSpatialOmics;
-    /**
-     * Whether the 2D observation markers are drawn: when the user wants them, and not while
-     * cell outlines are on screen — then a cell IS its outline, and a circle on top of it is
-     * noise. Zoomed out past the outline threshold, the circles stand in for the cells.
-     */
-    private spatialPointsVisible;
-    /**
-     * The tiled-geometry manager, built on first use. Its host callbacks read this
-     * service's live state, so it never holds a stale dataset or colormap.
-     */
-    private spatialTiles;
-    /**
-     * Region drawing for the 3D cloud.
-     *
-     * Reuses {@link NapariRegionOverlay} verbatim by handing it a SCREEN-SPACE viewer: the drawn
-     * shape is a lasso in canvas pixels, so "world" is the canvas and both transforms are identity
-     * (bar the client→canvas offset). Every existing tool — rectangle, polygon, freehand — therefore
-     * works in 3D with no new drawing code.
-     *
-     * A screen-space shape stops meaning anything the moment the camera moves, so an orbit clears
-     * the drawn regions. The SELECTION it produced is kept: that is the durable artefact, and the
-     * highlighted points stay highlighted from every angle.
-     */
-    private install3dInteraction;
-    /** Movement, in screen pixels, under which a press-release is a CLICK and not a
-     *  drag. An orbit or a pan starts the same way, so the two have to be told
-     *  apart by how far the pointer travelled. */
-    private static readonly CLICK_SLOP_PX;
-    /** Longest press-release still treated as a click. A long press with the mouse
-     *  held still is more likely an interrupted drag than a selection. */
-    private static readonly CLICK_MAX_MS;
-    /** Pointer distance, in screen pixels, that still counts as "on" a marker.
-     *  Generous relative to a 1.5px disc: the cursor is a blunt instrument, and a
-     *  tooltip you have to hunt for is worse than none. */
-    private static readonly HOVER_RADIUS_PX;
-    /**
-     * Cursor tooltip for the spatial views: hover a marker, read its class.
-     *
-     * A 34-entry legend cannot be read back from a dot — several classes get
-     * similar colours, and matching one to a swatch by eye is exactly the task this
-     * removes. It reports whatever the cloud is CURRENTLY coloured by, so it and
-     * the legend can never say different things.
-     *
-     * Listens on the HOST rather than the canvas so it keeps working over the region
-     * overlay (an SVG covering the canvas, which would otherwise swallow every
-     * move), and throttles to one hit-test per animation frame: a pointermove can
-     * fire far more often than that, and each test is a pass over the cloud.
-     */
-    private installSpatialHover;
-    private removeSpatialHover;
-    /** Hit-test the last pointer position and show or hide the tooltip. */
-    private updateHover;
-    /**
-     * Select the class of the marker at a client position — the canvas equivalent of
-     * clicking that class in the panel's legend, and the same selection object, so
-     * the two controls cannot produce different results.
-     *
-     * Clicking a class that is already the whole selection CLEARS it, which is what
-     * the legend does. Compared against the selection itself rather than against a
-     * remembered click, so selecting from the legend and then clicking the same
-     * class on the canvas still toggles.
-     */
-    private selectClassAt;
-    /**
-     * Which observation is under the cursor.
-     *
-     * In 3D this defers to napari-js's {@link nearestProjectedIndex} WITH the depths the
-     * projection produced, so the front-most candidate wins. That matters more than it
-     * sounds: the renderer depth-tests the billboards, and in a 3.7M-point cloud the cursor
-     * covers many of them — picking the one nearest the cursor's centre regularly names a
-     * cell that something else is drawn over, which reads as a wrong tooltip rather than as
-     * a subtlety of picking.
-     *
-     * In 2D the positions are WORLD coordinates on one plane, so there is no depth to break
-     * ties with and the existing nearest-marker rule is the right one.
-     */
-    private pickObservation;
-    /**
-     * Positions to hit-test against, rebuilt only when the scene or camera moved.
-     *
-     * A pass over 3.7M observations is not something to do per pointermove, and the
-     * cloud does not move between frames unless something says it did.
-     */
-    private hoverPositionsFor;
-    /**
-     * The 2D markers' WORLD positions, indexed by observation, NaN for any not on
-     * the displayed plane — the same affine and the same subset the marker layer was
-     * built from, so the tooltip cannot point at a cell that is not drawn.
-     */
-    private hoverWorldPositions;
-    /**
-     * What the tooltip says, resolved once per colour source rather than per hover.
-     *
-     * Fetched separately from the colouring on purpose: the reference port caches
-     * columns, but a host's need not, and re-fetching a 3.7M-element vector because
-     * the pointer moved would be indefensible either way.
-     */
-    private resolveHoverSource;
-    /**
-     * Project every observation to canvas pixels under the current 3D camera.
-     *
-     * The projection itself is the renderer's: `viewer.projectPoints` owns the camera, the
-     * viewport in CSS pixels, the perspective divide and the y-flip. This used to be fifteen
-     * lines of column-major matrix arithmetic here, duplicating a second copy in
-     * `napari-axes-labels` — and the two had drifted on what to do with a NaN w.
-     *
-     * What is left is the part that is genuinely this adapter's: SCATTERING the drawn subset
-     * back into observation order. The cloud holds only the points of the displayed section,
-     * in its own packing; every consumer indexes by observation. NaN stands for "not on
-     * screen", which is also the right answer for an observation whose section is hidden.
-     *
-     * Null when the 3D cloud is not mounted, so the caller falls back to the 2D affine path.
-     */
+    /** Observations projected to canvas pixels under the 3D camera (the spatial 3D cloud), indexed
+     *  by observation with NaN for any not drawn; null when no cloud is mounted. */
     getSpatialScreenProjection(obs: SpatialObservations): Float32Array | null;
-    /** Rebuild the markers on any dataset or view-state change. */
-    private subscribeSpatial;
-    /** (Re)build the observation marker layer for the current dataset + view state. */
-    private rebuildSpatialPoints;
-    /**
-     * Tell the region overlay how finely a drawn vertex may be placed.
-     *
-     * Region geometry is stored in whole world units, which is right when the world IS
-     * pixels — a region should align to them. It is wrong for a dataset that registers onto
-     * no image: seqFISH's observations span about 5 x 7 units in total, so whole-unit
-     * vertices leave roughly six by eight placeable positions across the entire sample and
-     * an ROI cannot be drawn at any zoom. Nothing errors; the tool just cannot express the
-     * shape.
-     *
-     * Keyed on whether the dataset brings PIXELS rather than on the extent, because the
-     * extent cannot tell the two apart — 2,000 units is a small slide or a large section
-     * depending only on what the units are, and only the dataset knows.
-     */
-    private setRegionGridFor;
-    /**
-     * Frame the 2D camera on the observations, for a dataset that brings no image.
-     *
-     * The 2D camera is normally fitted to the IMAGE, because the observations are in that
-     * image's pixel space and framing the image frames them too. A dataset with no
-     * reference image has coordinates in its own units instead — seqFISH's span about
-     * 5x7 — so the image framing left over from whatever was on screen before puts the
-     * whole cloud offscreen: measured at 9.7 x 13.4 PIXELS, centred 256px from where the
-     * camera was looking. The points are all there and drawn; they are a speck. Which
-     * looks exactly like the dataset having failed to load.
-     *
-     * Once per dataset, as napari-js's `fit3d: 'once'` does for the cloud: re-colouring,
-     * slicing or picking a gene re-adds this layer, and re-framing on those would move
-     * the camera under the user — the camera tools and the canvas drag are meant to be
-     * the only things that do.
-     */
-    /**
-     * Hide the image layer for a dataset that brings no image of its own.
-     *
-     * The host's viewer keeps whatever image was last loaded, and for a dataset that
-     * registers onto none that picture belongs to something else entirely — the example's
-     * default slide, say. It is not merely irrelevant: the two live in different coordinate
-     * spaces (image pixels against the embedding's own units), so the leftover is magnified
-     * roughly a hundredfold. At the fitted zoom the camera sits inside its corner, where it
-     * reads as blank background, and it appears only once you zoom out far enough to find
-     * it — which is exactly how it gets noticed.
-     *
-     * Hidden rather than removed, and hidden HERE rather than by clearing the host's image
-     * state: that state drives the whole render pipeline, including a Plotly backend whose
-     * fields are declared with definite-assignment assertions, so emptying it throws from
-     * whichever field the next path happens to read. This touches one layer's visibility
-     * and nothing else.
-     */
-    private hideForeignImage;
-    private frameSpatialPointsOnce;
-    /**
-     * The **gene map**: the active gene's expression as a continuous field drawn under
-     * the cells.
-     *
-     * A scatter coloured by a gene says which cells express it; it cannot say where,
-     * because the eye will not integrate thousands of dots into a territory. The field
-     * is a kernel-weighted MEAN per cell (see `spatial-expression.ts`), so a dense
-     * region does not glow merely for being dense, and it is transparent wherever no
-     * cell was measured — an unsampled gap must not read as "not expressed".
-     *
-     * It shares the points' LUT, percentile window and log flag, so the layer under
-     * the cells and the cells themselves cannot disagree about what a colour means.
-     *
-     * Estimated on the DISPLAYED image's pixel grid, coarsened so the long side is at
-     * most {@link GENE_MAP_MAX_SIDE}: a smooth field gains nothing from a slide's full
-     * resolution. For a volume-backed dataset that grid is the current slice, and only
-     * that plane's observations are included — the same rule the markers follow.
-     */
-    private ensureGeneMap;
-    /**
-     * The plane a volume-backed dataset is currently showing: its pixel affine, the
-     * observations that fall in it, and the marker floor that grid needs.
-     *
-     * Null for a dataset with a real `imageRef` (its coordinates are already the
-     * image's pixels and every observation belongs to the one section) and for one
-     * with no volume at all — both of which draw exactly as before.
-     */
-    private spatialSlab;
-    /** Per-point colours for the drawn subset. A broadcast tuple stays broadcast —
-     *  it is one colour for every point either way. */
-    private gatherColors;
-    /**
-     * Redraw the observation markers over a freshly rendered image.
-     *
-     * Two reasons, both invisible from the spatial store — which is why a scrub or a
-     * re-render never reached the markers on its own:
-     *  - the image render CLEARS the layer list, taking the markers with it;
-     *  - over a volume-backed dataset the displayed plane decides which
-     *    observations belong on screen at all, so the cells have to move with the
-     *    section rather than hang over a different one.
-     *
-     * Uses the latest values the marker subscription saw; a no-op until it has seen
-     * any, in the 3D cloud (no image, no plane), and with no dataset to draw.
-     */
-    private redrawSpatialMarkers;
-    /**
-     * Mount the SPATIAL_OMICS_3D view: observations as a 3D point cloud under the orbit camera.
-     *
-     * Deliberately much thinner than the 2D mount. There is no tissue image to render (a registered
-     * volume like the Allen CCF has no single reference plane), so no scale bar, no readback, and no
-     * 2D interaction stack — the region tools draw in screen space and have no meaning against an
-     * orbiting camera, which is why `Select from ROIs` is hidden in this mode. `addPoints3D` puts
-     * the viewer in 3D and frames the camera on the cloud itself.
-     */
-    private mountSpatialOmics3d;
-    /**
-     * Scale bar for the 3D cloud, measured at the ORBIT PIVOT.
-     *
-     * A perspective camera has no single scale — things farther away are smaller — so a bar can
-     * only be true at one depth. The pivot is the honest choice: it is what the camera is framing,
-     * what a zoom moves towards, and where the eye is anyway. napari's own 3D scale bar works the
-     * same way.
-     *
-     * `NapariScaleBar` needs CSS px per world unit, which an orbit camera does not expose, but at
-     * the pivot it is exactly `viewportHeight / (2 * distance * tan(fov / 2))` — the same
-     * relationship `Camera3D.pan` uses to track the cursor. The bar then converts through
-     * `micronsPerUnit`, and draws nothing at all when the dataset does not declare one, because a
-     * bar labelled in microns over unknown units would read as a measurement.
-     */
-    private installSpatial3dScaleBar;
-    /** Base marker diameter for the 3D cloud, in SCREEN pixels (the layer's unit). */
-    private static readonly SPATIAL_3D_BASE_SIZE;
-    /** (Re)build the 3D point cloud for the current dataset + view state. */
-    private rebuildSpatialPoints3d;
-    /**
-     * The **3D gene map**: the active gene's expression over the whole sectioned
-     * specimen, as one raymarched volume.
-     *
-     * Two things it can be, and the panel's `Volume rendering` toggle picks which:
-     *
-     *  - **sheets** — exactly the planes that were imaged, each carrying that
-     *    slide's own 2D gene map, with the gaps between sections empty. A stack of
-     *    measured fields, at their true z.
-     *  - **volume** — the same fields smoothed along z, so the planes between the
-     *    sections carry an interpolated value. An estimate, and drawn as a
-     *    translucent cloud for the same reason the density volumes are.
-     *
-     * One `VolumeLayer` rather than a textured quad per section: an `ImageLayer`
-     * renders only at `ndisplay === 2`, so 53 sheets in the orbit view would need a
-     * new layer type upstream — while a scalar volume whose z sampling already IS
-     * the section spacing expresses the sheets exactly, and the same lattice then
-     * gives the interpolated version for free.
-     *
-     * Estimated on the reference volume's own lattice (`densityGrid` at stride 1),
-     * so the field lands voxel-for-voxel on the anatomy and needs no offset — a
-     * `VolumeLayer` has no translate, and napari centres both boxes on the world
-     * origin.
-     */
-    private ensureGeneMapVolume;
-    /**
-     * Cluster density volumes: each cluster rasterised into a smooth scalar field and
-     * raymarched alongside the cloud, tinted with the cluster's own legend colour.
-     *
-     * This is what makes a serially sectioned dataset readable as an anatomical
-     * distribution. The cloud shows measured cells and nothing else — but at 200 µm
-     * section spacing the eye cannot integrate a stack of discs into a shape, and
-     * every gap reads as absence. A density field is a different object from a cell:
-     * an estimate, defined between the imaged planes, drawn as a translucent cloud so
-     * it cannot be mistaken for measurement. Individual cells are never interpolated —
-     * consecutive sections sample different cells, so there is nothing to interpolate
-     * along.
-     *
-     * One volume per cluster rather than one for everything: additive blending is what
-     * makes two clusters' territories comparable, and a single blended field would
-     * answer no question anyone asks of a taxonomy. Capped at
-     * {@link DENSITY_MAX_CLUSTERS} by cell count.
-     *
-     * Keyed so it rebuilds only when the field would actually differ — the dataset,
-     * the colour column, the bandwidth, or the selection.
-     */
-    private ensureDensityVolumes;
-    /**
-     * Identity of the colour scale a continuous spatial layer will draw with, for a
-     * cache key: the explicit choice, or else the display colormap and its reverse
-     * flag, since that is what {@link spatialContinuousLut} falls back to.
-     *
-     * The gene maps cache their coloured output, so without this in the key a change
-     * of colour scale left the field on screen in the previous colours — the markers
-     * recoloured and the map under them did not.
-     */
-    private continuousColormapKey;
-    /**
-     * A revision number for a selection object.
-     *
-     * The store hands out a NEW mask object per change, so object identity is the
-     * cheap and exact way to tell two selections apart — a fingerprint over 3.7M
-     * mask bytes would be neither. Counting revisions keeps the cache key a short
-     * string.
-     */
-    private selectionRev;
-    /**
-     * The clusters to rasterise: the categories of the active categorical colouring,
-     * biggest first and capped, each with its legend colour.
-     *
-     * Restricted to the current selection when there is one, so "select a region,
-     * check the box" answers which clusters live there. With no categorical colouring
-     * there is one group — total cell density, which is a real question on its own
-     * ("where is the tissue dense?") and the honest thing to show when the view is
-     * not encoding a taxonomy.
-     */
-    private densityGroups;
-    /**
-     * Add (or keep) the dataset's reference volume, and derive the offset that sits the
-     * observations inside it.
-     *
-     * `VolumeLayer` has no translate: napari-js maps the volume's unit cube to a world box
-     * **centred on the origin**, sized `dims x voxelSize`. The observations, by contract, are in
-     * the volume's own frame with its near corner at the coordinate origin. So the two only line
-     * up if the POINTS move — by half the box — which is what {@link spatialOrigin3d} is.
-     *
-     * A failed or absent volume is not fatal: the cloud renders on its own, at its own
-     * coordinates, and the camera frames the points instead.
-     */
-    private ensureSpatialVolume;
-    private removeSpatial3dLayers;
-    /** A one-colour colormap, for the "nothing to colour by" state. */
-    private spatialFlatColormap;
-    /**
-     * The per-point scalar + colormap + window that colour the 3D cloud.
-     *
-     * Continuous data is the natural fit: values go straight through the active colormap with the
-     * same percentile window the 2D path uses. Categorical data has to be smuggled through the same
-     * scalar channel — see {@link SPATIAL_3D_MAX_CATEGORIES}. Codes map to LUT blocks, and
-     * `contrastLimits` of `[-0.5, K - 0.5]` puts code `i` at the centre of block `i`, which is what
-     * makes the round-trip exact instead of approximately right.
-     */
-    private spatialScalar3d;
-    /** Category codes → a stepped LUT, exact for up to {@link SPATIAL_3D_MAX_CATEGORIES}. */
-    private encodeSpatial3dCategorical;
-    /** Continuous values → the active colormap over a percentile-clipped window. */
-    private encodeSpatial3dContinuous;
-    /**
-     * Per-observation colours for the current view state, or a single flat colour when nothing is
-     * selected to colour by. Categorical columns use the column's own palette; continuous columns
-     * and gene vectors go through the active colormap with a percentile-clipped window.
-     */
-    private spatialFaceColors;
-    /** Continuous values → RGBA through the active colormap and a clipped window. */
-    private encodeSpatialContinuous;
-    /**
-     * Mount the NAPARI_SCATTER3D 3D scatter: the downsampled voxel grid as a 3D point cloud colored
-     * by intensity (napari-js analog of Plotly's voxel scatter3d). Assembles a coarse volume, then
-     * emits a flat-strided sample of voxels (capped at {@link SCATTER3D_MAX_POINTS}) via `addPoints3D`.
-     */
-    private mountScatter3d;
-    /** Store colormap / reverse / invert / channel window → the 3D scatter's colormap + contrast. */
-    private subscribeScatter3dDisplayState;
-    /**
-     * Mount the NAPARI_SURFACE height-field surface. A height field is single-scalar, so for a
-     * multichannel image the surface follows ONE band — the first visible channel (fallback 0) —
-     * coloured by that channel's window/colormap (like the Plotly SURFACE, which is grayscale-only).
-     * Pre-loads every slice's height data with a progress bar (as the volume does) so the stack
-     * slider re-slices instantly, then builds the mesh for the current slice. All mesh + GPU work
-     * lives in napari-js (`heightField` + `Viewer.addSurface`); this backend supplies scalar slices.
-     */
-    private mountSurface;
-    /** Add the 3D axes gizmo + DOM labels around the (origin-centered) surface mesh, matching the
-     *  volume/isosurface. Installed once per mount; the box tracks the mesh bounds, X/Y show the
-     *  physical (or pixel) extent, and Z is the intensity/height axis. */
-    private installSurfaceAxes;
-    /** X/Y/Z end-labels for the surface gizmo: X/Y are the physical (µm) or pixel extent of the FULL
-     *  image; Z is the intensity/height axis. Anchors are in the centered box (matching AxesLayer). */
-    private buildSurfaceAxesLabels;
-    /**
-     * Pre-fetch every stack slice's luminance plane (decimated to the surface grid) into
-     * {@link surfacePlanes}, driving {@link stackLoadingProgress$} — the same load-with-progress UX
-     * as the volume, but keeping one 2D plane per slice rather than packing a 3D volume. Bounded
-     * concurrency keeps the connection pool busy without flooding it on a deep stack.
-     */
-    private preloadSurfacePlanes;
-    /**
-     * Fetch slice `z` as a single WHOLE-image luminance plane (decimated to `maxGrid`). Prefers the
-     * app's complete per-slice image (`smallUrls`/`urls`, exactly like the Plotly surface) so the
-     * surface always covers the FULL slice — the tile-pyramid `fetchSlice` path would fall back to a
-     * single top-left tile (a corner) for self-contained / non-`/tiles/info` images. Falls back to
-     * stitching the tile grid only when no complete-image URL is available.
-     */
-    /** Tile budget to stitch a whole slice at ~`targetPx` resolution from the pyramid: a higher target
-     *  pulls a FINER pyramid level (more real detail). Shared by the surface plane fetch and the volume
-     *  assembly so both scale their in-plane resolution with the decimate factor. */
-    private tileBudgetFor;
-    private fetchSurfacePlane;
-    /** The channel state driving the surface: the chosen band for multichannel (matched by index),
-     *  else the single grayscale channel. */
-    private surfaceState;
-    /**
-     * (Re)build the surface mesh for slice `z` from the pre-loaded plane cache (instant — this is
-     * what the stack slider calls); a slice missing from the cache is fetched on demand. napari-js's
-     * pure `heightField` builds the triangle grid (z = normalized intensity), then `addSurface`
-     * renders it. The slice plane also feeds the intensity histogram (key 0).
-     */
-    private buildSurface;
-    /** Subscribe the store colormap / reverse / invert / channel window → the surface, so histogram
-     *  & channel-dialog edits update it live without a re-fetch. **min/max reshapes the surface's
-     *  height** (a pixel's height = its intensity within [min,max]), so a window change rebuilds the
-     *  mesh geometry (from the cached slice); colour-only edits (colormap/LUT, gamma, reverse, invert)
-     *  just update the layer's uniforms. */
-    private subscribeSurfaceDisplayState;
     private fitCameraSoon;
     /** @deprecated Plotly-specific; host re-drives plot() from its image stream. */
     reloadAndPlot(): void;
+    /**
+     * End the mounted scene: abort its lifetime (its descriptor poll, tile counts, frame loading and
+     * awaits) and dispose it — its layers, keys, subscriptions and listeners go with it, so the next
+     * plot can never inherit an "already built" key (NAPARI-SVC-1) — then tear the viewer down.
+     */
     reset(): void;
     relayout(_trueImageSize?: number[]): void;
     /** @deprecated Plotly-specific axis reset. */
@@ -890,12 +149,15 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     autoscale(): void;
     zoomIn(): void;
     zoomOut(): void;
+    /** Zoom by `factor` (> 1 = in) on whichever camera is live: the 2D camera's zoom, or — in a 3D
+     *  scene, where that would change nothing visible — the orbit camera's distance. */
+    private zoomBy;
     setDragMode(_mode: string | false): void;
     setImageSmoothingEnabled(enabled: boolean): void;
     setShowStack(_showstack: boolean): void;
     setZIndex(zIndex: number): void;
     setStackLoading(stackLoading: boolean): void;
-    /** Cancel in-flight frame loading: bump the load generation so the volume-assembly / surface
+    /** Cancel in-flight frame loading: abort {@link loading} so the volume-assembly / surface
      *  preload workers stop fetching more frames, and clear the loading flag + progress. */
     cancelLoading(): void;
     isStackLoading(): Observable<boolean>;
@@ -913,78 +175,54 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
         height: number;
     } | null;
     downloadImage(): void;
-    setPlotType(plotType: PlotType): void;
+    /** No-op: the mounted scene is fixed per {@link plot}; a new plot type takes a re-plot. */
+    setPlotType(_plotType: PlotType): void;
     /** Map a Plotly-style 3D drag mode onto napari-js's camera drag mode. */
     setSurfaceDragMode(mode: string): void;
-    /** Re-frame the 3D camera on the current 3D layer. A surface mesh sits in the positive octant
-     *  (not centred), so frame it by its own bounds; a volume/isosurface uses its centred box. */
+    /** Re-frame the 3D camera on the scene: napari-js frames the union of every 3D layer's bounds
+     *  (surface, volume, point cloud), with the viewport-aware framing its adders use. */
     resetSurfaceCamera(): void;
     getAutoscaleEvent(): Observable<unknown>;
+    /**
+     * The plot types this backend can mount — every type {@link plot} dispatches on.
+     *
+     * Contract-only in production: the router answers `getPlotTypeDescriptors` from the Plotly
+     * service, so nothing reaches this one through it; it is kept accurate for direct callers.
+     */
     getPlotTypeDescriptors(): PlotTypeDescriptor[];
     /** The napari 3D decimate factor (1 = full … 8 = ⅛). Read by the toolbar to init the control. */
     getResolutionScale(): number;
     /** Set the decimate factor for the napari 3D types. Takes effect on the next (re)load — the host
      *  re-plots after calling this, since decimation changes the fetched/assembled data. */
     setResolutionScale(scale: number): void;
-    getIntensityProfile$(): Observable<IntensityProfile[]>;
-    renderIntensityInset(_divId: string, _profiles: IntensityProfile[]): void;
-    /** Read the displayed composite into `lastPixels` (the pixel-tools' source) + emit the clamped
-     *  visible region. A fresh PixelData object means cachedImageData() rebuilds automatically. */
-    private runReadback;
-    private scheduleReadback;
-    /** Debounced readback — armed on camera changes so `lastPixels` tracks the current view after a
-     *  pan/zoom settles (and after tiled levels finish loading), which the on-canvas pixel tools
-     *  (wand/brush/SAM) read synchronously. Coalesces rapid changes. */
-    private armReadback;
-    /** Build the coordinate transform + tool hosts for the current viewer (called from plot()). The
-     *  pixel tools read displayed pixels synchronously from the last readback and convert pointer
-     *  coords via the napari camera, exactly mirroring the OSD host. */
-    private buildToolHosts;
-    private zoomBoxHost;
-    /** Zoom/pan the camera to fit a data-space rectangle `[xMin, xMax, yMax, yMin]`. */
-    private applyZoomToBox;
-    /** Build CachedImageData from the most recent readback (RGBA device pixels → [y][x]=[r,g,b]),
-     *  with ratios/origin mapping image coords ↔ readback pixels. Cached until the readback changes. */
-    private cachedImageData;
-    setWandMode(active: boolean, options?: IWandOptions): void;
-    setWandOptions(options: IWandOptions): void;
-    clearActiveWandRegion(): void;
-    setBrushMode(active: boolean, options?: IBrushOptions): void;
-    setBrushOptions(options: IBrushOptions): void;
-    setVertexEraserMode(active: boolean): void;
-    setVertexEraserRadius(radius: number): void;
-    setZoomToBoxMode(active: boolean): void;
+    /** napari-js has the navigator and image smoothing too (its 2D views). */
+    getOsdViewOptions(): IOsdViewOptions;
+    private readonly viewOptions;
+    /** The 3D decimate factor (the 3D types' Resolution control). */
+    getVolumeResolution(): IVolumeResolution;
+    private readonly volumeResolution;
+    /** Where the camera settled, for the intensity inset's re-sampling. */
+    getIntensitySampling(): IIntensityViewportSource;
+    private readonly viewportSource;
+    protected beforeToolChange(next: CanvasToolId | null): boolean;
     segmentRectangles(): Promise<number>;
     segmentRectanglesCellpose(): Promise<number>;
     setSamModel(id: string): void;
-    setSamPointMode(active: boolean): void;
-    commitSamPoints(): void;
-    clearSamPoints(): void;
-    ensureIntensitySampling(_imageInfo: IImageInfo, _zIndex: number): Promise<void>;
-    refreshIntensitySamplingForRoi(_x: number, _y: number, _width: number, _height: number, _zIndex: number): void;
-    getViewportChange$(): Observable<{
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }>;
     getRegionOverlay(): IRegionOverlay | null;
     getIsosurfaceControls(): IIsosurfaceControls | null;
     getIntensityControls(): IIntensityControls | null;
     getSurface3dControls(): ISurface3dControls | null;
     getHistogram(channelIndex: number, bins: number): IHistogram | null;
     getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
-    /** Fetch + cache one channel's native-bit-depth histogram from `GET /histogram` (>8-bit). */
-    private fetchNativeHistogram;
-    /** Per-channel histogram of the displayed RGB composite (R/G/B byte), from the last readback. */
-    private rgbHistogram;
+    /** Save the displayed composite as a PNG. Through file-saver, which (unlike revoking an object
+     *  URL straight after `a.click()`) does not race the browser's download. */
     exportComposite(): void;
     /** Native-bit-depth (16/32-bit) multi-band TIFF export via the server `/export/tiff` endpoint —
      *  the displayed PNG is an 8-bit figure, this preserves the true pixel values. Visible channels
      *  only (omitted when all are visible → server default). Mirrors the OSD backend. */
     exportData(): Promise<void>;
     unsubscribe(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NapariVisualizerService, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, null, null, { optional: true; }, null]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NapariVisualizerService, [null, null, null, null, null, null, null, { optional: true; }, null, null, { optional: true; }, null]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NapariVisualizerService>;
 }
 export {};