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

package/lib/geometry/raster.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure binary-mask helpers: polygon rasterization (napari-js's `rasterizePolygon`)
+ * and bbox-relative mask set operations. No DOM, no Angular — the mask-export
+ * worker imports this.
+ */
+/** A bbox-relative binary mask (1 = filled, 0 = empty) whose pixel (0,0) sits
+ *  at (bx, by) in the frame it was rasterized in. */
+export interface BBoxMask {
+    bx: number;
+    by: number;
+    bw: number;
+    bh: number;
+    mask: Uint8Array;
+}
+/**
+ * The largest bbox (in pixels) {@link rasterizePolygon} allocates before it
+ * falls back to clipping at the window. Also the cap the wand/brush use to
+ * decide whether a region can be edited at the current zoom.
+ */
+export declare const MAX_RASTER_PIXELS: number;
+/**
+ * Rasterize a closed polygon (minus its holes) into a bbox-relative mask, e.g.
+ * as the starting point for a wand/brush stroke accumulator.
+ *
+ * Pixel (px, py) covers `[px, px + 1) × [py, py + 1)` and is set when its centre
+ * is inside — the rule under which the pixel-edge outlines `geometry/contour`
+ * traces come back as exactly the pixels they were traced from.
+ *
+ * Returns the bbox origin plus the filled mask, or null if the polygon is
+ * degenerate (covers no pixel centre). The polygon's full extent is kept even
+ * where it is negative or exceeds `imageWidth`×`imageHeight` (jit-ui#102); only
+ * a bbox larger than {@link MAX_RASTER_PIXELS} is clipped to that window (rare:
+ * a region enormous at the current zoom; accepts the clip).
+ */
+export declare function rasterizePolygon(xpoints: number[], ypoints: number[], imageWidth: number, imageHeight: number, holes?: number[][][]): BBoxMask | null;
+/** Returns true if the two bbox-relative masks share at least one set pixel. */
+export declare function masksOverlap(a: BBoxMask, b: BBoxMask): boolean;
+/**
+ * Allocate a fresh accumulator covering both masks and OR them in. The
+ * resulting mask's bbox is the smallest rectangle containing both inputs.
+ */
+export declare function unionMasks(a: BBoxMask, b: BBoxMask): BBoxMask;

package/lib/geometry/reconstruct.d.ts

@@ -0,0 +1,54 @@
+import type { Mesh } from 'napari-js/geometry';
+/**
+ * A region's outlines on one slice: rings as interleaved `x, y` image pixels (holes included), and
+ * open polylines (a layer boundary), likewise.
+ */
+export interface SliceOutlines {
+    z: number;
+    rings: ArrayLike<number>[];
+    /**
+     * The feature each ring is part of (equal ids, one feature): a feature's rings fill even-odd (its
+     * holes), the features as their union, so one inside or over another cuts no hole in it. Absent:
+     * the rings are one feature.
+     */
+    ringGroups?: ArrayLike<number>;
+    lines?: ArrayLike<number>[];
+}
+export interface ReconstructOptions {
+    /** In-plane voxel edge, image px (default 1). Raised to keep the mask within `maxVoxels`. */
+    pixelStep?: number;
+    /** At most this many voxels (default 32 M). */
+    maxVoxels?: number;
+    /** Laplacian smoothing passes (default 2). */
+    smooth?: number;
+}
+/**
+ * The mesh of the region outlined by `slices`, in image pixels (x, y) and slice indices (z: slice
+ * k's plane at z = k): the filled outlines' surface, and the sheet through the lines (see
+ * {@link loftLines}). Empty when no slice has an area and no two slices have lines.
+ */
+export declare function reconstruct(slices: readonly SliceOutlines[], opts?: ReconstructOptions): Mesh;
+/**
+ * The area inside `rings` (interleaved `x, y`), even-odd: a ring inside an odd number of others is
+ * a hole. Exact for rings that do not cross (a polygon set's exteriors and holes).
+ */
+export declare function ringsArea(rings: readonly ArrayLike<number>[]): number;
+/**
+ * The rings of each feature (see {@link SliceOutlines.ringGroups}), in the order first met; one
+ * feature of every ring without `groups`.
+ */
+export declare function featureRings(rings: readonly ArrayLike<number>[], groups?: ArrayLike<number>): ArrayLike<number>[][];
+/**
+ * The area of a slice's outlines (px²): each feature's (even-odd, see {@link ringsArea}), the
+ * features as their union, so a feature inside or over another of the slice adds only what it
+ * covers beyond it. Features whose extents overlap are measured together, by the length of their
+ * union along each row, exact between the rows through their vertices where no outline crosses
+ * another (and refined where one does).
+ */
+export declare function outlinesArea(rings: readonly ArrayLike<number>[], groups?: ArrayLike<number>): number;
+/**
+ * The volume of the region outlined by `slices`, in px² × slices (one slice thick per outline):
+ * the sum of each slice's area (see {@link outlinesArea}; Cavalieri's estimator). Times µm per px²
+ * and per slice, µm³.
+ */
+export declare function outlinedVolume(slices: readonly SliceOutlines[]): number;

package/lib/geometry/reslice-image.d.ts

@@ -0,0 +1,33 @@
+import type { Colormap } from 'napari-js';
+import type { SectionAxis } from './section';
+/** One channel of a volume as it is displayed. */
+export interface VolumeChannelVoxels {
+    /** uint8 voxels, x fastest, then y, then z. */
+    data: Uint8Array;
+    /** The colormap the 3D view draws the channel with (a tint, or the display colormap). */
+    colormap: Colormap;
+    /** Display window over 0..255. */
+    min: number;
+    max: number;
+    /** napari-js gamma (see `toNapariGamma`): the windowed value t shows as t^γ. */
+    gamma: number;
+    visible: boolean;
+}
+export interface VolumeVoxels {
+    width: number;
+    height: number;
+    depth: number;
+    channels: readonly VolumeChannelVoxels[];
+    invert: boolean;
+}
+/** An RGBA image, row by row. */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+/**
+ * The image of the plane `axis = index` (a voxel index): through x, slices across and y down;
+ * through y, x across and slices down — the section coordinates of `geometry/section`.
+ */
+export declare function resliceImage(vol: VolumeVoxels, axis: SectionAxis, index: number): RgbaImage;

package/lib/geometry/ring.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure ring (closed polyline) helpers: bounds, containment, vertex dropping and
+ * simplification. No DOM, no Angular, no `this` — usable from workers.
+ *
+ * A ring is a pair of parallel `xs`/`ys` arrays without a repeated closing
+ * vertex; hole rings use the `[[x, y], …]` convention of {@link Polygon.holes}.
+ */
+/** Axis-aligned bounds of a ring. Infinite (min > max) for an empty ring. */
+export interface RingBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/** The axis-aligned bounds of a ring's vertices. */
+export declare function ringBounds(xs: ArrayLike<number>, ys: ArrayLike<number>): RingBounds;
+/**
+ * Standard ray-cast (even-odd) point-in-ring test. (px, py) and the ring
+ * vertices must be in the same coordinate system. Rings with fewer than three
+ * vertices contain nothing.
+ */
+export declare function pointInRing(px: number, py: number, xs: ArrayLike<number>, ys: ArrayLike<number>): boolean;
+/**
+ * Point-in-region test that honours interior rings (holes): inside the
+ * exterior AND outside every hole. Coordinates must share the polygon's frame.
+ * With no holes this is exactly {@link pointInRing}.
+ */
+export declare function pointInPolygonWithHoles(px: number, py: number, xs: ArrayLike<number>, ys: ArrayLike<number>, holes?: number[][][]): boolean;
+/** {@link pointInRing} over a `[[x, y], …]` ring (the hole convention), without splitting it. */
+export declare function pointInPairRing(px: number, py: number, ring: ReadonlyArray<ArrayLike<number>>): boolean;
+/**
+ * Drop every vertex whose Euclidean distance to (cx, cy) is less than
+ * `radius`. Returns trimmed parallel arrays plus how many vertices were
+ * removed (so the caller can detect a no-op tick and skip the relayout).
+ */
+export declare function dropVerticesWithinRadius(xpoints: number[], ypoints: number[], cx: number, cy: number, radius: number): {
+    xpoints: number[];
+    ypoints: number[];
+    removed: number;
+};
+/**
+ * Erase the part of a ring that lies within `radius` of (cx, cy): every vertex
+ * inside the disc goes (as {@link dropVerticesWithinRadius}), and the outline is
+ * rejoined where it crosses the disc's edge rather than at the next vertex left
+ * standing. On a densely sampled outline the two agree; on a sparse one (a
+ * traced box is four corners) dropping a corner would otherwise cut straight to
+ * the neighbouring corners. A `closed` ring wraps; an open one (a polyline) has
+ * no edge from its last vertex back to its first. Returns the trimmed parallel
+ * arrays plus how many of the ring's own vertices were removed (0: unchanged).
+ */
+export declare function eraseRingWithinRadius(xpoints: number[], ypoints: number[], cx: number, cy: number, radius: number, closed?: boolean): {
+    xpoints: number[];
+    ypoints: number[];
+    removed: number;
+};
+/**
+ * Simplify a closed ring with the Douglas–Peucker algorithm (jit-ui#85):
+ * drop every vertex that lies within `epsilon` pixels (the "altitude
+ * threshold") of the line between its kept neighbours. Anchored at vertex 0
+ * (the ring is closed by appending it). Rings of ≤ 3 vertices, or a
+ * non-positive epsilon, are returned unchanged. Output keeps the closed-ring
+ * convention (no repeated closing point).
+ */
+export declare function simplifyRing(xs: number[], ys: number[], epsilon: number): {
+    xs: number[];
+    ys: number[];
+};

package/lib/geometry/section.d.ts

@@ -0,0 +1,52 @@
+import { SliceOutlines } from './reconstruct';
+/** The plane: x = const (a section along y and the slices) or y = const (along x and the slices). */
+export type SectionAxis = 'x' | 'y';
+/** A class's outlines in a section, as interleaved `u, v`. */
+export interface ClassSection {
+    /** Closed outlines, holes included (even-odd). */
+    rings: Float64Array[];
+    /** Open lines; a line of one point is where the class crosses on one slice only. */
+    lines: Float64Array[];
+}
+export interface SectionOptions {
+    /** Slices in the stack. */
+    depth: number;
+    /** Image px across the section's in-plane axis: the image height through x, its width through y. */
+    extent: number;
+    /** In-plane cell size of the closed shapes' cut, image px (default 1). */
+    step?: number;
+    /** Farthest a line moves between neighbouring slices and is still joined, image px (default extent / 10). */
+    maxJump?: number;
+}
+/** `[x0, y0, x1, y1]`, image px. */
+type Box = [number, number, number, number];
+/** A ring or line with its extent. */
+interface Indexed {
+    points: ArrayLike<number>;
+    box: Box;
+}
+interface IndexedSlice {
+    z: number;
+    rings: Indexed[];
+    /** Each ring's feature (see SliceOutlines.ringGroups); absent: one feature. */
+    ringGroups?: ArrayLike<number>;
+    lines: Indexed[];
+}
+/**
+ * Every class's outlines with each ring's and line's extent (and the class's): made once, it cuts
+ * any number of sections visiting only the outlines a plane crosses.
+ */
+export interface SectionIndex {
+    readonly classes: ReadonlyMap<string, {
+        box: Box;
+        slices: readonly IndexedSlice[];
+    }>;
+}
+/** Index every class's outlines for cutting (see {@link SectionIndex}). */
+export declare function indexOutlines(byClass: ReadonlyMap<string, readonly SliceOutlines[]>): SectionIndex;
+/**
+ * Each class's cut by the plane `axis = at`; classes the plane misses are left out. Pass an
+ * {@link indexOutlines} index to cut many sections of the same outlines.
+ */
+export declare function sectionOutlines(outlines: SectionIndex | ReadonlyMap<string, readonly SliceOutlines[]>, axis: SectionAxis, at: number, opts: SectionOptions): Map<string, ClassSection>;
+export {};

package/lib/hex-color-picker/hex-color-picker.component.d.ts

@@ -1,47 +1,81 @@
-import { ChangeDetectorRef, ElementRef, EventEmitter, OnDestroy, Renderer2 } from '@angular/core';
+import { ChangeDetectorRef, ElementRef, EventEmitter, NgZone, OnDestroy, Renderer2 } from '@angular/core';
 import * as i0 from "@angular/core";
+/**
+ * A compact colour picker: a swatch button that opens a honeycomb palette with a
+ * hex field, the system colour picker, HSL sliders and RGB fields. Bind `[color]`
+ * and listen to `(colorChange)` (committed picks) and, for a live preview,
+ * `(colorInput)` (every intermediate colour while dragging).
+ */
 export declare class HexColorPickerComponent implements OnDestroy {
     private elRef;
     private renderer;
     private cdr;
+    private ngZone;
     private static readonly DROPDOWN_WIDTH;
-    private _color;
+    /** The colour shown (the swatch, the hex field, the selected cell). */
+    private readonly current;
+    /** The committed colour: a swatch/hex pick, or a slider/field/system-picker
+     *  edit once it is released. Hosts commit their state on this. */
     colorChange: EventEmitter<string>;
-    open: boolean;
-    swatchBtn: ElementRef<HTMLButtonElement>;
-    dropdownRef: ElementRef<HTMLDivElement>;
-    hue: number;
-    saturation: number;
-    lightness: number;
-    red: number;
-    green: number;
-    blue: number;
-    readonly colorRows: string[][];
+    /** Every intermediate colour while a slider, number field or the system picker
+     *  is being dragged — for a live preview; {@link colorChange} follows on release. */
+    colorInput: EventEmitter<string>;
+    /** The last colour emitted on (or received through) `color`, so a release
+     *  without a change doesn't commit again. */
+    private committed;
+    /** Removes the document click listener; set only while the dropdown is open. */
+    private unlistenDocumentClick;
+    /** The palette dropdown is open. */
+    protected readonly open: import("@angular/core").WritableSignal<boolean>;
+    private swatchBtn;
+    private dropdownRef;
+    protected readonly hue: import("@angular/core").WritableSignal<number>;
+    protected readonly saturation: import("@angular/core").WritableSignal<number>;
+    protected readonly lightness: import("@angular/core").WritableSignal<number>;
+    protected readonly red: import("@angular/core").WritableSignal<number>;
+    protected readonly green: import("@angular/core").WritableSignal<number>;
+    protected readonly blue: import("@angular/core").WritableSignal<number>;
+    /** Slider tracks: hue is fixed; saturation and lightness follow the other two. */
+    protected readonly hueGradient: string;
+    protected readonly satGradient: import("@angular/core").Signal<string>;
+    protected readonly lightGradient: import("@angular/core").Signal<string>;
+    protected readonly colorRows: string[][];
     private normalizeHexColor;
+    /** The colour (`#RRGGBB`) to show; upper-cased on the way in. */
     get color(): string;
     set color(val: string);
-    constructor(elRef: ElementRef, renderer: Renderer2, cdr: ChangeDetectorRef);
+    constructor(elRef: ElementRef, renderer: Renderer2, cdr: ChangeDetectorRef, ngZone: NgZone);
     ngOnDestroy(): void;
-    toggle(): void;
+    protected toggle(): void;
+    /**
+     * Close on a click outside the swatch and dropdown. Registered only while
+     * open and outside the Angular zone, so the many pickers on a page (one per
+     * class row and channel) don't each run app-wide change detection on every
+     * click anywhere (RT-22).
+     */
+    private listenForOutsideClicks;
+    private stopListeningForOutsideClicks;
     private appendDropdownToBody;
     private removeDropdownFromBody;
-    selectColor(hex: string): void;
-    selectAndClose(hex: string): void;
+    protected selectColor(hex: string): void;
+    /** Live preview from the system colour picker while it is open. */
+    protected previewColor(hex: string): void;
+    /** Commit the current colour (`colorChange`) unless it was already committed. */
+    protected commitColor(): void;
+    protected selectAndClose(hex: string): void;
+    /** Close the palette dropdown (no-op when closed). */
     close(): void;
-    onHexInput(value: string): void;
-    onHslChange(): void;
-    onRgbChange(): void;
-    get hueGradient(): string;
-    get satGradient(): string;
-    get lightGradient(): string;
-    onDocumentClick(event: Event): void;
+    protected onHexInput(value: string): void;
+    protected onHslChange(): void;
+    protected onRgbChange(): void;
+    /** Close the dropdown when `event` is a click outside the picker. */
+    protected onDocumentClick(event: Event): void;
+    private isOutside;
     private syncFromHex;
     private syncRgbFromHex;
+    private setRgb;
     private syncHslFromRgb;
-    private hexToRgb;
-    private rgbToHex;
     private rgbToHsl;
-    private hslToHex;
     static ɵfac: i0.ɵɵFactoryDeclaration<HexColorPickerComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<HexColorPickerComponent, "hex-color-picker", never, { "color": { "alias": "color"; "required": false; }; }, { "colorChange": "colorChange"; }, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HexColorPickerComponent, "hex-color-picker", never, { "color": { "alias": "color"; "required": false; }; }, { "colorChange": "colorChange"; "colorInput": "colorInput"; }, never, never, true, never>;
 }

package/lib/implementations/base-store-visualizer.d.ts

@@ -1,28 +1,35 @@
 import { Observable } from 'rxjs';
 import { IDisplayOptions, IRegionStore } from '../contracts/visualizer.contract';
 import { Region } from '../models/region';
-import { ColormapNode } from '../contracts/display-types';
+import { CanvasToolId, CanvasToolOptions, ColormapNode, IBrushOptions, IWandOptions } from '../contracts/display-types';
+import type { CanvasToolManager } from '../toolbar/tool-kit/canvas-tool-manager';
 import { IImageMetadata } from '../contracts/image.contract';
 import { RegionStore } from '../store/region-store.service';
 import { VisualizerStore } from '../store/visualizer-store.service';
 /**
- * Shared store-delegation base for the OpenSeadragon and napari-js
+ * Shared store-delegation base for the OpenSeadragon, napari-js and Plotly
  * `IVisualizer` backends. The entire `IRegionStore` and `IDisplayOptions`
  * surfaces (plus the two classification-colour members) are pure forwarders to
- * the shared `RegionStore` / `VisualizerStore` in BOTH backends — so they live
- * here once, as a single source of truth, rather than being copied per backend.
- * (This is the "cross-backend behaviour that isn't rendering belongs in a
- * shared abstraction" convention from CLAUDE.md; the extraction closes
- * SHARED-BACKEND-REFACTOR.md.)
+ * the shared `RegionStore` / `VisualizerStore` — so they live here once, as a
+ * single source of truth, rather than being copied per backend. (This is the
+ * "cross-backend behaviour that isn't rendering belongs in a shared
+ * abstraction" convention from CLAUDE.md; see
+ * docs/history/2026-07-shared-backend-refactor.md.)
+ *
+ * The on-canvas tool controls (`setActiveTool` and the per-tool setters) live
+ * here too: each subclass creates its own {@link CanvasToolManager} over its own
+ * tool host and gates pointer/readback in {@link beforeToolChange}.
  *
  * Backend-specific members — `load`/`plot`/`reset`/zoom/`setZIndex`/readback,
- * the region OVERLAY, tool wiring, histograms, scale bar, tiling, colormap LUT
- * application — deliberately stay in each subclass.
+ * the region OVERLAY, the tool host, SAM/Cellpose runs, histograms, scale bar,
+ * tiling, colormap LUT application — deliberately stay in each subclass. Plotly keeps a Plotly-shape
+ * working-set beside the store and redraws it from the store's update events
+ * (like the OSD/napari overlays), so it overrides only the colormap and reverse
+ * scale (a live restyle) and `exportRegions` (the file name).
  *
  * NOT `@Injectable`: an abstract base doesn't participate in Angular DI. Each
  * subclass stays `@Injectable`, declares its own injected dependencies
- * (including the two stores), and passes them to `super(...)`. Plotly is
- * intentionally not a subclass — it has its own region model.
+ * (including the two stores), and passes them to `super(...)`.
  */
 export declare abstract class BaseStoreVisualizer implements IRegionStore, IDisplayOptions {
     protected readonly regionStore: RegionStore;
@@ -39,9 +46,6 @@ export declare abstract class BaseStoreVisualizer implements IRegionStore, IDisp
     getShowShapeLabel(): boolean;
     getShapeColor(): string;
     getFillColor(): string;
-    plotPreviousShapes(): void;
-    setPreviousShapes(shapes: any[]): void;
-    getPreviousShapes(): any[];
     undo(): void;
     redo(): void;
     canUndo(): boolean;
@@ -59,13 +63,55 @@ export declare abstract class BaseStoreVisualizer implements IRegionStore, IDisp
     setDisplaySlice(z: number): void;
     getSliceRegions(): Region[];
     getStackSaveSlices(): Map<number, Region[]>;
+    /** This backend's canvas tools, created by the subclass over its own host. */
+    protected abstract readonly canvasTools: CanvasToolManager;
+    /**
+     * Runs before every tool change, for the backend's pointer and readback
+     * gating (pan/zoom off while a tool holds the pointer, a fresh pixel
+     * readback). Return false to arm nothing; the armed tool is disarmed anyway.
+     */
+    protected beforeToolChange(_next: CanvasToolId | null): boolean;
+    /**
+     * Arm one on-canvas tool, disarming the armed one; null — or any id that is
+     * not a canvas tool (a region draw mode, pan) — disarms only. Re-arming the
+     * armed tool applies `options` and keeps its work in progress.
+     */
+    setActiveTool(id: string | null, options?: CanvasToolOptions): void;
+    /** @deprecated Use {@link setActiveTool}(`'wand'`, options) / (null). */
+    setWandMode(active: boolean, options?: IWandOptions): void;
+    setWandOptions(options: IWandOptions): void;
+    clearActiveWandRegion(): void;
+    /** @deprecated Use {@link setActiveTool}(`'brush'`, options) / (null). */
+    setBrushMode(active: boolean, options?: IBrushOptions): void;
+    setBrushOptions(options: IBrushOptions): void;
+    /** @deprecated Use {@link setActiveTool}(`'eraseVertex'`, { radius }) / (null). */
+    setVertexEraserMode(active: boolean): void;
+    setVertexEraserRadius(radius: number): void;
+    /** @deprecated Use {@link setActiveTool}(`'zoomToBox'`) / (null). */
+    setZoomToBoxMode(active: boolean): void;
+    /** @deprecated Use {@link setActiveTool}(`'samPoint'`) / (null). */
+    setSamPointMode(active: boolean): void;
+    commitSamPoints(): void;
+    clearSamPoints(): void;
+    /** A per-tool setter: arm `id`, or disarm it if it is the armed tool. */
+    private setToolMode;
+    /** Drop what is bound to the view (each backend's own teardown). */
+    abstract unsubscribe(): void;
+    /** The view is going away: release what is bound to it (`IViewerBackend.detach`) —
+     *  first the armed tool, whose overlay canvas and ResizeObserver sit on the view's
+     *  container (the backend outlives the view). */
+    detach(): void;
+    /** Each backend's own fit (Plotly autorange, OSD home, napari camera fit). */
+    abstract autoscale(): void;
+    /** Fit the image into the view (`IViewerBackend.fitToView`). */
+    fitToView(): void;
     getClassificationColors(): Map<string, string>;
     setClassificationColor(label: string, color: string): void;
     getColormap(): Observable<ColormapNode | null>;
     setColormap(colormap: ColormapNode): void;
     getColormapOptions(): ColormapNode[];
     getReverseScale(): Observable<boolean>;
-    setReverseScale(reverscale: any): void;
+    setReverseScale(reverscale: boolean): void;
     setImageMeta(imageMeta: IImageMetadata[]): void;
     getImageMeta(): Observable<IImageMetadata[]>;
 }

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

@@ -0,0 +1,36 @@
+import type { AxesLayer, SurfaceLayer, Viewer } from 'napari-js';
+import type { AxisLabelSpec } from 'napari-js/overlays';
+import { ISurface3dControls } from '../../contracts/visualizer.contract';
+import type { SceneContext } from './napari-scene';
+/** A centred world box. */
+export interface Box3 {
+    width: number;
+    height: number;
+    depth: number;
+}
+/**
+ * The 3D coordinate-axes / scale gizmo (review Appendix B): napari-js's `AxesLayer` plus the DOM
+ * X/Y/Z labels that track it (its `AxesLabelsOverlay`) — what the volume and the surface used to
+ * build twice.
+ */
+export declare class Axes3dGizmo {
+    private readonly viewer;
+    readonly layer: AxesLayer;
+    private readonly labels;
+    constructor(viewer: Viewer, host: HTMLElement, box: Box3, labels: AxisLabelSpec[], opts: {
+        visible: boolean;
+        voxelSize?: [number, number, number];
+    });
+    setVisible(visible: boolean): void;
+    /** The box's depth changed (the volume's Z-height handle): restretch the axis and its labels. */
+    setDepth(depth: number, labels: AxisLabelSpec[]): void;
+    destroy(): void;
+}
+/** A Plotly-style 3D drag mode, as napari-js's camera drag mode (orbit/turntable → rotate). */
+export declare function cameraDragMode(mode: string): 'pan' | 'zoom' | 'rotate';
+/**
+ * The 3D view controls every 3D image scene offers: camera drag mode and re-framing, the axes
+ * gizmo's visibility and the surface's wireframe — both persisted in the viewer settings, so the
+ * next mount re-applies them.
+ */
+export declare function surface3dControls(ctx: SceneContext, gizmo: () => Axes3dGizmo | null, surface?: () => SurfaceLayer | null): ISurface3dControls;

package/lib/implementations/napari-js/napari-display-state.d.ts

@@ -0,0 +1,76 @@
+import { Subscription } from 'rxjs';
+import type { Colormap } from 'napari-js';
+import { IChannelState } from '../../contracts/channel-histogram-api.contract';
+import { Rgb } from '../../contracts/colormap-lut';
+import { ColormapNode, SpatialViewState } from '../../contracts/display-types';
+import { VisualizerStore } from '../../store/visualizer-store.service';
+/** The display settings every napari layer's colours are derived from. */
+export interface DisplaySnapshot {
+    /** The selected display colormap node (a name or inline stops in `data.value`), if any. */
+    colormap: ColormapNode | null;
+    reverse: boolean;
+    invert: boolean;
+}
+/** The grayscale display colormap from the store selection (+reverse), defaulting to gray.
+ *  Maps the store colormap node to a napari `Colormap` via the library's LUT factory; the
+ *  multichannel tint ramps are built inside napari-js's `MultiChannelImageView` from each
+ *  channel's hex colour. */
+export declare function grayscaleColormap(s: DisplaySnapshot): Colormap | string;
+/** A channel's tint colormap (black→colour), flipped for reverse-scale. Invert is not a colormap
+ *  flip: it goes on the layer (`invert`), before gamma, as on the 2D image. */
+export declare function channelTintColormap(color: string, s: DisplaySnapshot): Colormap | string;
+/**
+ * Colour map for the volume/isosurface (and the surface and 3D scatter). 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 flips the ramp; invert is the layer's own
+ * `invert` (window → invert → gamma → colormap), not a second flip — the two differ once gamma ≠ 1.
+ */
+export declare function volumeColormap(st: IChannelState | undefined, s: DisplaySnapshot): Colormap | string;
+/** The LUT a continuous spatial layer draws with: the view's own choice, else the display
+ *  colormap and its reverse flag — one rule for the markers, the cloud and both gene maps. */
+export declare function spatialLut(view: SpatialViewState, s: DisplaySnapshot): Rgb[];
+/**
+ * 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 spatialLut} 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.
+ */
+export declare function continuousColormapKey(view: SpatialViewState, s: DisplaySnapshot): string;
+/**
+ * The store's display state as the napari layers consume it (review Appendix B, step 3;
+ * NAPARI-SVC-21): one subscription to channel states, colormap, reverse, invert and the selected
+ * channel, a {@link DisplaySnapshot} of the last values seen, and the colormap/LUT derivations
+ * every scene shares.
+ *
+ * The snapshot outlives a scene, as the scenes' builders read it before their own subscription
+ * has emitted; each scene owns the subscription {@link watch} hands it.
+ */
+export declare class NapariDisplayState implements DisplaySnapshot {
+    private readonly store;
+    colormap: ColormapNode | null;
+    reverse: boolean;
+    invert: boolean;
+    constructor(store: VisualizerStore);
+    /**
+     * Follow the store: record the colormap/reverse/invert the builders read, then hand `apply`
+     * the channel states and the selected channel. Emits at once with the current values.
+     */
+    watch(apply: (channels: IChannelState[], selected: number) => void): Subscription;
+    /**
+     * Follow the invert setting alone: record it for the builders, then hand it to `apply` — for a
+     * scene that draws inverted layers without the channel states (the spatial cloud's density
+     * volumes). Emits at once with the current value.
+     */
+    watchInvert(apply: (invert: boolean) => void): Subscription;
+    /** The spatial scenes' share: they follow the colormap and reverse flag (not invert) through
+     *  their own subscription, because a gene map recolours with them. */
+    record(colormap: ColormapNode | null, reverse: boolean): void;
+    grayscaleColormap(): Colormap | string;
+    channelTintColormap(color: string): Colormap | string;
+    volumeColormap(st: IChannelState | undefined): Colormap | string;
+    spatialLut(view: SpatialViewState): Rgb[];
+    continuousColormapKey(view: SpatialViewState): string;
+}