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

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

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

@@ -0,0 +1,129 @@
+import type { ChannelView } from 'napari-js';
+import { IImageInfo } from '../../contracts/image.contract';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+/**
+ * Pure helpers and constants of the napari-js backend: no viewer, no store, no network. Shared by
+ * the service and its scenes (review Appendix B, step 1).
+ */
+/**
+ * A short, stable id for a colormap value, for cache keys.
+ *
+ * Half the library's colormaps are NAMES and half are inline `[stop, colour]`
+ * arrays of 256 entries. Stringifying the array kind would put 6 KB in a key that
+ * is rebuilt and compared on every view change; hashing it keeps the key small,
+ * and it only has to distinguish one colormap from another.
+ */
+export declare function colormapId(value: unknown): string;
+export declare const VOLUME_MAX_SLICE = 1024;
+/** Reference in-plane world size (long side) for the volume/axes box, in arbitrary world units.
+ *  The box is anchored to this reference regardless of the chosen decimate factor, so changing the
+ *  resolution changes DETAIL, not the volume's proportions (Z no longer appears to shrink when the
+ *  in-plane sampling grows). Set to the DEFAULT decimate's in-plane cap so the default view is
+ *  unchanged; higher/lower resolutions keep that same shape. */
+export declare const VOLUME_WORLD_INPLANE_REF: number;
+/** Max concurrent slice fetches when assembling a volume — keeps the connection pool busy
+ *  without flooding it (browsers cap ~6/host) on a deep stack. */
+export declare const VOLUME_FETCH_CONCURRENCY = 8;
+/** Volume/isosurface sampling for a decimate factor `scale` (1 = Full 1024, 2 = ½ 512, 4 = ¼ 256
+ *  default, 8 = ⅛ 128): the in-plane cap halves each step; slices stay un-subsampled until ⅛, then
+ *  subsample. */
+export declare function volumeResolutionFor(scale: number): {
+    maxSlice: number;
+    sliceStep: number;
+};
+/** Fully-normalized intensity height as a fraction of the in-plane extent — matches the Plotly
+ *  SURFACE z-aspect (~0.4) so the relief isn't exaggerated. */
+export declare const SURFACE_Z_ASPECT = 0.4;
+/** "Full" mesh grid cap; the decimate factor divides it (default ¼ → 220, ½ → 440, Full → 880). */
+export declare const SURFACE_MAX_GRID = 880;
+/** Coefficient scaling the pyramid tile budget with the target resolution — a higher target pulls a
+ *  finer pyramid level (more real detail). Shared by the surface plane fetch + volume assembly. */
+export declare const STITCH_BUDGET_COEFF = 16;
+/** Surface mesh target grid for a decimate factor `scale`: the grid cap shrinks by `scale` (every
+ *  slice is kept — the z-slider needs them all). The source is fetched at a matching resolution. */
+export declare function surfaceResolutionFor(scale: number): {
+    maxGrid: number;
+};
+/** 3D scatter: in-plane cap for the assembled voxel grid, and the max number of points emitted
+ *  (the grid is flat-strided down to this) — keeps the billboard count interactive. */
+export declare const SCATTER3D_MAX_XY = 64;
+export declare const SCATTER3D_MAX_POINTS = 150000;
+/** How long a pan/zoom must settle before the viewport (and, for pixel tools, the canvas
+ *  readback) is refreshed — coalesces the camera's per-frame changes. */
+export declare const READBACK_DEBOUNCE_MS = 250;
+export declare const TILE_SIZE = 512;
+/** Max tiles stitched for one displayed slice (512px tiles → up to ~6144² at full res). Beyond
+ *  this we step to a coarser pyramid level so a large image stays tractable. */
+export declare const MAX_STITCH_TILES = 144;
+/** WebGPU default `maxTextureDimension2D` — a stitched slice's longest side must fit a texture. */
+export declare const MAX_TEXTURE_DIM = 8192;
+/** Concurrent tile requests per stitched slice. Firing a whole grid at once (hundreds of requests
+ *  for a large level) overwhelmed the tile server (504s); a small pool keeps the pipe full without
+ *  flooding it — and slice-level workers already run several stitches in parallel on top of this. */
+export declare const TILE_FETCH_CONCURRENCY = 6;
+/** Split RGB tiles kept for a band that asks after the other two (see
+ *  `NapariTileClient.rgbBandSources`): ~3 × 256 KB per 512px tile. */
+export declare const RGB_BAND_CACHE_TILES = 16;
+/** How long to poll `/tiles/info` (202 while the server caches the source) before falling back to
+ *  a single tile. Generous like the OSD backend — a cold whole-slide can take minutes to cache. */
+export declare const DESCRIPTOR_TIMEOUT_MS = 120000;
+/** Wait between two `/tiles/info` polls while the server answers 202. */
+export declare const DESCRIPTOR_POLL_INTERVAL_MS = 1200;
+/** A decoded single-channel uint8 plane. */
+export interface LumaPlane {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}
+/**
+ * `IChannelState.gamma` → the `gamma` a napari-js layer or view takes.
+ *
+ * The shared channel state follows the ImageJ/Fiji convention the OSD backend draws
+ * (`osd/display-pipeline.ts`: output = t^(1/γ), so γ > 1 BRIGHTENS the midtones), while
+ * napari-js's shaders apply `pow(t, gamma)` (napari's convention: γ > 1 darkens). Every gamma
+ * handed to napari-js goes through here, so one slider in the Channels & Histogram dialog moves
+ * both backends the same way. Both backends apply window → invert → gamma, per channel before
+ * an additive merge (NAPARI-BOUNDARY-2; pinned by `osd/display-pipeline.cross-backend.spec.ts`).
+ */
+export declare function toNapariGamma(gamma: number | undefined): number;
+/** A 2D canvas (an `OffscreenCanvas` where available) and its context; throws, naming `what`,
+ *  when no 2D context can be had. */
+export declare function create2dCanvas(width: number, height: number, what: string): {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+};
+/**
+ * Run `fn` over `items` with at most `concurrency` in flight — keeps the connection pool busy
+ * without flooding the server — starting no further item once `stop()` says so.
+ */
+export declare function mapPool<T>(items: readonly T[], concurrency: number, fn: (item: T) => Promise<void>, stop?: () => boolean): Promise<void>;
+/** A serverless multichannel stack (`tiled:false` + `channelUrls`): no tile descriptor, so its
+ *  channel count comes from `imageMeta`, and each band is fetched from its own plane URLs. */
+export declare function isServerlessMultichannel(simple: boolean, info: IImageInfo | undefined): boolean;
+/** The stack's declared slice count (`imageMeta.z`, else one URL per slice); 0 when unknown. */
+export declare function stackDepth(info: IImageInfo | undefined): number;
+/** The R, G and B bands of RGBA8 pixels as three uint8 planes (alpha dropped). */
+export declare function splitRgbBands(px: {
+    data: ArrayLike<number>;
+    width: number;
+    height: number;
+}): LumaPlane[];
+/** A decoded single-channel uint8 plane as a napari-js typed image source. */
+export declare function typedPlane(d: LumaPlane): ChannelView['source'];
+/** Default tint for a channel index, cycling the Fiji palette. */
+export declare function tintFor(channel: number): string;
+/** Convert a napari-js `Histogram` (bin count + min/max) to the pane's `IHistogram` (bin edges). */
+export declare function toIHistogram(h: {
+    counts: Uint32Array;
+    bins: number;
+    min: number;
+    max: number;
+}): IHistogram;
+/**
+ * Additively composite grayscale channel images, each tinted with its display colour —
+ * the navigator's picture of a multichannel image.
+ */
+export declare function tintedComposite(images: Array<CanvasImageSource & {
+    width: number;
+    height: number;
+}>, colors: string[]): HTMLCanvasElement;

package/lib/implementations/napari-js/napari-image-2d-scene.d.ts

@@ -0,0 +1,162 @@
+import type { TiledSource } from 'napari-js';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { TileDescriptor } from '../tile-server';
+import type { NapariScene, SceneContext } from './napari-scene';
+/** What the scenes built over the 2D image add to it. */
+export interface Image2dOptions {
+    /** Draw the loaded image (false: an image-less spatial dataset, the observations alone). */
+    image?: boolean;
+    /** Whether to fit the camera to the image once it is drawn (default: when there is one). */
+    fit?: () => boolean;
+    /** After a slice change. `rerendered` when the stitched path re-rendered the image — which
+     *  CLEARS the layer list, taking every other layer with it. */
+    onSlice?: (rerendered: boolean) => void;
+    /** The pointer entered the navigator (e.g. to hide a hover tooltip over the canvas). */
+    onNavigatorInteract?: () => void;
+}
+/**
+ * The 2D image (review Appendix B, cluster E): pyramidal `TiledSource`s against the `/tile`
+ * endpoint when `/tiles/info` describes the image, else a single stitched level (`tiled:false`
+ * stacks fetch each slice's own URL, a serverless multichannel stack each channel's own plane);
+ * multichannel additive tints, grayscale colormap or RGB (recoloured per band, see
+ * {@link syncRgbBands}); the coarse histogram samples of the tiled path, the scale bar, the
+ * overview navigator and the 2D interaction stack (region overlay + pixel tools). The
+ * region-centroid scatter and the spatial 2D scene are built over it.
+ */
+export declare class Image2dScene implements NapariScene {
+    private readonly ctx;
+    private readonly opts;
+    /** How the image is composited (drives the histogram and the display-state updates). */
+    imageMode: 'grayscale' | 'multichannel' | 'rgb';
+    /** True when the image is rendered via pyramidal TiledSources (descriptor available). */
+    tiled: boolean;
+    /** napari-js high-level view owning the per-channel layer set for {@link imageMode}. */
+    private channelView;
+    /** Latest wins for a stitched slice: a slow older slice can't clobber a newer one. */
+    private sliceReq;
+    /** RGB: the R, G and B bands as layer sources (typed planes, or band `TiledSource`s that share
+     *  one request per tile) and the stitched level's scale — what {@link syncRgbBands} draws. */
+    private rgbBands;
+    /** RGB: the three additive band layers while the channel states recolour the image; null while
+     *  the RGB layer draws it as it is. */
+    private bandLayers;
+    /** Coarse per-channel luminance sample (keyed by channel index) for the histogram in tiled mode,
+     *  where the layers have no full in-memory pixels — and an RGB image's raw bands in either mode.
+     *  Refreshed on mount + slice change. */
+    readonly histSamples: Map<number, Uint8Array>;
+    /** Latest-wins token for {@link refreshHistogramSamples}. */
+    private histGen;
+    /** Physical scale bar overlay (null when the image has no µm/pixel). */
+    private scaleBar;
+    /** Overview minimap (bottom-right), as OSD's navigator. */
+    private navigator;
+    /** Bumped per thumbnail request, so a slow one cannot overwrite a newer slice's. */
+    private navigatorToken;
+    /** The current slice's per-channel thumbnail bitmaps (multichannel only), kept so a tint or
+     *  visibility change recolours the thumbnail without re-fetching it. */
+    private navigatorChannels;
+    /** The tints/visibility the thumbnail was last composited with — see {@link recolorNavigator}. */
+    private navigatorTintKey;
+    private displaySub;
+    constructor(ctx: SceneContext, opts?: Image2dOptions);
+    private get hasImage();
+    mount(): Promise<void>;
+    setZ(z: number): void;
+    histogram(channel: number, bins: number): IHistogram | null;
+    setImageSmoothing(enabled: boolean): void;
+    setNavigatorVisible(visible: boolean): void;
+    /** Show the navigator only for a dataset that brings pixels of its own (and when the user
+     *  wants it): with no image of its own there is nothing for an overview to show. */
+    showNavigatorFor(datasetHasPixels: boolean): void;
+    dispose(): void;
+    /**
+     * Render slice `z`. With a server pyramid descriptor each layer is a pyramidal
+     * {@link TiledSource}, so the view refines to higher resolution on zoom (like OSD) and sits
+     * naturally in full-resolution coordinates; without one, the single-level stitch. Three display
+     * modes either way: multichannel additive tint, grayscale colormap, RGB.
+     */
+    render(z: number, token?: number): Promise<void>;
+    /** Single-level stitch fallback (no descriptor): the pre-tiling path. */
+    private renderStitched;
+    /**
+     * Render 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 renderTiled;
+    /** A pyramidal TiledSource whose tiles count on the loading badge while `scene` (the render that
+     *  asked for it, taken before its awaits) is current. */
+    tiledSource(desc: TileDescriptor, channel: number | undefined, channels: 1 | 4, scene: AbortSignal): TiledSource;
+    /** Channel `c`'s layer in the additive multichannel composite: tinted by its display colour
+     *  (store, else descriptor, else the Fiji palette), with its window, gamma and visibility. */
+    private tintedChannelView;
+    /** The single grayscale layer: the selected colormap, with the channel's window and gamma. */
+    private grayscaleChannelView;
+    /** (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, fetched together; cached by channel
+     *  index. Latest wins: a scrub fires one refresh per slice, and an older slice's samples that
+     *  land after a newer one's are dropped rather than shown as the current distribution. */
+    refreshHistogramSamples(z: number, desc: Pick<TileDescriptor, 'channels'>): Promise<void>;
+    /** Channel states + grayscale colormap → live-apply to the rendered layers (no re-fetch; only z
+     *  changes re-fetch), and recolour the navigator thumbnail. */
+    private followDisplayState;
+    /** 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;
+    /**
+     * RGB: draw the image as it is while its channel states leave it so (default R/G/B tints, full
+     * window, γ 1, all shown, no invert: {@link rgbNeedsRecolor}) — the RGB layer, unchanged, with
+     * the coarse underlay a tiled one keeps while it pans. Otherwise draw its R, G and B bands as
+     * three additive layers, each with its channel's window, invert, gamma, tint and visibility —
+     * what OSD's RGB recolour computes per pixel (the merge order of `osd/display-pipeline`). The
+     * band layers sit just above the hidden RGB layer, so whatever is drawn over the image stays
+     * over it. A host with no R/G/B channel model (fewer than three states) gets only the invert.
+     */
+    private syncRgbBands;
+    /** (Re)install the physical scale bar (napari-js's `ScaleBarOverlay` on the 2D camera's zoom),
+     *  sized from the image's µm/pixel (`/tiles/info` mppX, falling back to the image metadata).
+     *  No-op without a physical size. */
+    installScaleBar(): void;
+    /**
+     * The overview navigator (napari-js's `NavigatorOverlay`): a coarse thumbnail of the whole
+     * image with the viewport on it; click or drag to pan at the current zoom (as OSD).
+     */
+    private installNavigator;
+    /**
+     * Draw the navigator's thumbnail from the coarsest pyramid level. A multichannel image
+     * is composited from its channels in their display colours (see {@link recolorNavigator}),
+     * so the overview looks like the view rather than like channel 0 in grey.
+     */
+    private refreshNavigatorImage;
+    /** Replace the per-channel thumbnail bitmaps (closing the previous ones). */
+    private setNavigatorChannels;
+    /**
+     * Composite the multichannel thumbnail in the channels' CURRENT display tints, skipping hidden
+     * channels — the store's channel states, as the 2D layers use, not the server's defaults.
+     * Re-run on every display-state change; it only redraws (never re-fetches), and only when a
+     * tint or a visibility actually changed, so a window/gamma drag costs a string compare.
+     */
+    private recolorNavigator;
+}
+/**
+ * NAPARI_SCATTER (review Appendix B, cluster H): the slice image with a points layer at each
+ * region's centroid (the napari-js analog of Plotly's region-centroid scatter), rebuilt live as
+ * regions change. This mode plots REGION centroids, so the image's region tools come with it —
+ * drawing a region adds a point at once.
+ */
+export declare class ScatterRegionsScene implements NapariScene {
+    private readonly ctx;
+    readonly image: Image2dScene;
+    private points;
+    private regionSub;
+    constructor(ctx: SceneContext);
+    mount(): Promise<void>;
+    setZ(z: number): void;
+    histogram(channel: number, bins: number): IHistogram | null;
+    setImageSmoothing(enabled: boolean): void;
+    setNavigatorVisible(visible: boolean): void;
+    dispose(): void;
+    /** (Re)build the point layer at the current region centroids. */
+    private rebuildPoints;
+}

package/lib/implementations/napari-js/napari-loading-badge.d.ts

@@ -7,7 +7,6 @@
  */
 export declare const SHOW_AFTER_MS = 150;
 export declare class NapariLoadingBadge {
-    private readonly host;
     private readonly el;
     private names;
     private timer;