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

package/index.d.ts

@@ -1,9 +1,11 @@
 /**
- * Public API of the jax-image-visualization library. External consumers import
- * ONLY from here (`@jax-data-science/sci-image-visualizer`); everything else under `lib/` is
- * internal. The surface is contracts + tokens + neutral models + the Angular
- * module, plus the routing service the host's composition root binds the tokens
- * to (`useExisting`).
+ * Public API of `@jax-data-science/sci-image-visualizer`. External consumers import
+ * ONLY from here; everything else under `lib/` is internal. The surface is
+ * contracts + tokens + neutral models + the Angular module and components, plus
+ * `provideVisualization()` for an isolated, component-scoped viewer. The library
+ * binds the tokens itself (VisualizationModule / provideVisualization), so a host
+ * injects `VISUALIZER`, `REGION_EDITOR_API` and `CHANNEL_HISTOGRAM_API` and supplies
+ * only the ports and `VIZ_CONFIG`.
  */
 export * from './lib/contracts/visualizer.contract';
 export * from './lib/contracts/region-editor-api.contract';
@@ -26,13 +28,12 @@ export * from './lib/contracts/display-types';
 export * from './lib/contracts/sam.contract';
 export * from './lib/contracts/cell-segmenter.contract';
 export { CellposeSegmenterService } from './lib/toolbar/segmentation/cellpose-segmenter.service';
-export { SpatialDataHttpService, SupersededError } from './lib/implementations/spatial-data-http/spatial-data-http.service';
+export { SpatialDataHttpService, SupersededError, } from './lib/implementations/spatial-data-http/spatial-data-http.service';
 export { SPATIAL_WIRE_VERSION, isLittleEndian, assertManifestVersion, datasetFromManifest, decodeCoords, decodeRadius, decodeColumn, decodeFeatureVector, decodePolygons, } from './lib/implementations/spatial-data-http/spatial-wire';
 export type { SpatialManifest, SpatialDatasetSummary, SpatialRadiusSpec, } from './lib/implementations/spatial-data-http/spatial-wire';
-export { encodeCategorical, encodeContinuous, resolveCategoryColors, contrastWindow, markerDiameters, toRgbaTuples, lutFor, DEFAULT_CATEGORICAL_PALETTE, DEFAULT_MUTED_OPACITY, MISSING_COLOR, } from './lib/spatial/spatial-encoding';
-export type { RGBA, CategoricalEncodingOptions, ContinuousEncodingOptions, } from './lib/spatial/spatial-encoding';
+export { encodeCategorical, encodeContinuous, resolveCategoryColors, contrastWindow, markerDiameters, lutFor, DEFAULT_CATEGORICAL_PALETTE, DEFAULT_MUTED_OPACITY, MISSING_COLOR, } from './lib/spatial/spatial-encoding';
+export type { RGBA, CategoricalEncodingOptions, ContinuousEncodingOptions } from './lib/spatial/spatial-encoding';
 export { selectInRegions, selectByCategory, mutedFromSelection, pointInRing, emptySelection, countMask, maskToIndices, } from './lib/spatial/spatial-selection';
-export type { SpatialSelectionMask } from './lib/spatial/spatial-selection';
 export { SpatialSelectionStore } from './lib/store/spatial-selection.service';
 export * from './lib/contracts/instance-segmenter.contract';
 export * from './lib/contracts/semantic-segmenter.contract';
@@ -41,17 +42,19 @@ export { cropImage, CropImageOptions } from './lib/processing/image-crop';
 export { ImageConverterService } from './lib/processing/image-converter.service';
 export { SAM_MODELS, DEFAULT_SAM_MODEL_ID, getSamModel, isSamModelReady, setSamModelUrls, setDefaultSamModel, getDefaultSamModelId, } from './lib/toolbar/segmentation/sam-model-registry';
 export { setOrtWasmBase, getOrtWasmBase } from './lib/toolbar/segmentation/ort-runtime-config';
+export { clearSamModelCache } from './lib/toolbar/segmentation/sam-onnx-core';
 export * from './lib/models/region';
 export * from './lib/models/class-preset';
 export { ShapeSelection } from './lib/models/shape';
 export { VisualizationModule } from './lib/visualization.module';
 export { RoutingVisualizerService } from './lib/routing-visualizer.service';
 export { provideVisualization } from './lib/provide-visualization';
+export { VIZ_TOAST_KEY, VIZ_ALERT_TOAST_KEY } from './lib/toast-outlets';
 export { VisualizerComponent } from './lib/visualizer.component';
 export { RegionEditorComponent } from './lib/region-editor/region-editor.component';
 export { HexColorPickerComponent } from './lib/hex-color-picker/hex-color-picker.component';
 export { ChannelHistogramComponent } from './lib/channel-histogram/channel-histogram.component';
-export { SpatialControlsComponent, } from './lib/spatial-controls/spatial-controls.component';
+export { SpatialControlsComponent } from './lib/spatial-controls/spatial-controls.component';
 export type { SpatialLegendEntry } from './lib/spatial-controls/spatial-controls.component';
 export { SpatialChartsComponent } from './lib/spatial-controls/spatial-charts/spatial-charts.component';
 export { buildOmicsTraces, omicsLayout, benefitsFromGrouping, } from './lib/implementations/plotly/omics-trace-builders';

package/lib/channel-histogram/channel-histogram.component.d.ts

@@ -10,94 +10,104 @@ import * as i0 from "@angular/core";
  * {@link CHANNEL_HISTOGRAM_API} into the shared store, and both rendering
  * backends recolor the displayed image live. The pane depends only on the
  * contract, never the concrete visualizer.
+ *
+ * OnPush: the API's channel / colormap / invert / image streams, the async
+ * histogram and the slider-activity timer mark it for check.
  */
 export declare class ChannelHistogramComponent implements OnInit, OnDestroy {
     private api;
     /** Dialog visibility, two-way bound so the host (toolbar button) can open it. */
     visible: boolean;
+    /** The dialog was opened or closed; two-way with {@link visible}. */
     visibleChange: EventEmitter<boolean>;
-    readonly histogramDiv = "channel-histogram-plot";
-    readonly lutColors: readonly {
+    /** DOM id of the Plotly histogram element — per instance, so two panes don't collide. */
+    protected readonly histogramDiv: string;
+    protected readonly lutColors: readonly {
         name: string;
         color: string;
     }[];
-    channels: IChannelState[];
-    selected: IChannelState | null;
-    invert: boolean;
-    logScale: boolean;
+    protected channels: IChannelState[];
+    protected selected: IChannelState | null;
+    protected invert: boolean;
+    protected logScale: boolean;
     /** Bounded retries while the (async) histogram sampling resolves. */
     private histRetries;
+    private histRetryTimer?;
     /** The selected channel's current histogram. Native bit depth (with
      *  observed/range fields) for >8-bit images, else the 8-bit client histogram.
      *  Drives the plot, the native window labels, and the export-button gate. */
-    hist: IHistogram | null;
+    protected get hist(): IHistogram | null;
+    protected set hist(h: IHistogram | null);
+    private _hist;
+    /** {@link nativeRange} of {@link hist}, kept with it so the template's window
+     *  getters read it instead of re-deriving (and allocating) it per check. */
+    private range;
     private histSub?;
     /** Which window control is being adjusted right now — drives a small
      *  non-blocking activity spinner next to that slider, since the image recolor
      *  isn't instant on large stacks. Cleared a short moment after movement stops
      *  (the recolor isn't directly observable, so this is a trailing heuristic). */
-    activeAdjust: 'min' | 'max' | 'gamma' | null;
+    protected activeAdjust: 'min' | 'max' | 'gamma' | null;
     private adjustTimer?;
-    colormapOptions: any;
-    selectedColormap: any;
-    private subs;
+    protected colormapOptions: any;
+    protected selectedColormap: any;
+    private readonly destroyRef;
+    private readonly cdr;
+    private readonly zone;
+    /** Re-render this OnPush view, re-entering the zone when the change came from outside it. */
+    private changed;
     /** Keeps the Plotly histogram sized to the (resizable) dialog body. */
     private resizeObserver?;
     constructor(api: IChannelHistogramApi);
     /** Per-channel pseudo-colour only applies when there's more than one channel
      *  (RGB / fluorescence). A single grayscale channel uses the colormap instead. */
-    get multichannel(): boolean;
+    protected get multichannel(): boolean;
     ngOnInit(): void;
+    /** Stops the pending histogram load / retry and activity timer, the resize
+     *  observer and the Plotly plot; the API streams end through `takeUntilDestroyed`. */
     ngOnDestroy(): void;
-    onVisibleChange(v: boolean): void;
+    protected onVisibleChange(v: boolean): void;
     /** p-dialog (onShow): the plot div now exists, so draw the histogram and keep
      *  it sized to the dialog (which is resizable) via a ResizeObserver. */
-    onShow(): void;
+    protected onShow(): void;
     private teardownResize;
-    selectChannel(ch: IChannelState): void;
-    onMinChange(value: any): void;
-    onMaxChange(value: any): void;
-    onGammaChange(value: any): void;
+    protected selectChannel(ch: IChannelState): void;
+    protected onMinChange(value: number | string | null | undefined): void;
+    protected onMaxChange(value: number | string | null | undefined): void;
+    protected onGammaChange(value: number | string | null | undefined): void;
     /** Flag a control as actively adjusting so its spinner shows; auto-clears a
      *  short moment after the last change (kept alive while the user keeps
      *  dragging, since each change resets the timer). */
     private markBusy;
-    onVisibleToggle(ch: IChannelState, value: boolean): void;
-    onColorChange(ch: IChannelState, color: string): void;
-    onColormap(node: TreeNode): void;
-    onInvert(value: boolean): void;
-    toggleLog(value: boolean): void;
+    protected onVisibleToggle(ch: IChannelState, value: boolean): void;
+    protected onColorChange(ch: IChannelState, color: string): void;
+    protected onColormap(node: TreeNode): void;
+    protected onInvert(value: boolean): void;
+    protected toggleLog(value: boolean): void;
     /** Quick-assign a preset LUT colour to a channel (Fiji palette). */
-    setPreset(ch: IChannelState, color: string): void;
+    protected setPreset(ch: IChannelState, color: string): void;
     /** Export the displayed composite as a publication-ready PNG (8-bit figure). */
-    exportComposite(): void;
+    protected exportComposite(): void;
     /** Export the underlying data as a true-16-bit multi-band TIFF (server-side). */
-    exportData(): void;
+    protected exportData(): void;
     /** True when the current channel histogram is native >8-bit (16-bit etc.):
      *  gates the native slider labelling and the 16-bit TIFF export button. */
-    get is16bit(): boolean;
-    /** The native value range the 8-bit display window maps onto — the observed
-     *  pixel extremes for a native histogram, else plain 0..255 (so 8-bit images
-     *  pass through unchanged). The 8-bit tile is server-stretched across this
-     *  range, so it's the best client-side native↔display mapping. */
+    protected get is16bit(): boolean;
+    /** {@link nativeRange} of the current histogram. */
     private obsRange;
     /** 8-bit display value (0..255) → native units. */
     private toNative;
     /** Native units → clamped 8-bit display value (0..255). */
     private toDisp;
     /** Selected channel window endpoints in native units (for the sliders). */
-    get minNative(): number;
-    get maxNative(): number;
+    protected get minNative(): number;
+    protected get maxNative(): number;
     /** Native slider bounds + step (256 display steps across the native range). */
-    get sliderMin(): number;
-    get sliderMax(): number;
-    get sliderStep(): number;
-    auto(): void;
-    reset(): void;
-    /** Saturation-based auto-window over a (native or 8-bit) histogram: pick
-     *  [min,max] so ~`saturation` of pixels clip at each end, dropping a dominant
-     *  first/last bin (background/padding). Returns native bin values. */
-    private autoWindow;
+    protected get sliderMin(): number;
+    protected get sliderMax(): number;
+    protected get sliderStep(): number;
+    protected auto(): void;
+    protected reset(): void;
     /** Fetch the selected channel's histogram (native for 16-bit, else 8-bit) and
      *  (re)draw it. Async — the native path hits the server; the 8-bit path may be
      *  null until tile sampling resolves, so we retry a few times. */
@@ -108,5 +118,5 @@ export declare class ChannelHistogramComponent implements OnInit, OnDestroy {
     private markerShapes;
     private histogramLayout;
     static ɵfac: i0.ɵɵFactoryDeclaration<ChannelHistogramComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ChannelHistogramComponent, "channel-histogram", never, { "visible": { "alias": "visible"; "required": false; }; }, { "visibleChange": "visibleChange"; }, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ChannelHistogramComponent, "channel-histogram", never, { "visible": { "alias": "visible"; "required": false; }; }, { "visibleChange": "visibleChange"; }, never, never, true, never>;
 }

package/lib/contracts/capabilities.contract.d.ts

@@ -1,11 +1,12 @@
 /**
  * Optional features a viewer backend may or may not support. Consumers query
- * `IImageViewer.capabilities` and degrade gracefully (hide a toolbar item,
+ * `IVisualizer.capabilities` and degrade gracefully (hide a toolbar item,
  * skip a render path) rather than calling a method that no-ops.
  *
  * The Plotly backend supports the scientific/data features; the OpenSeadragon
  * backend supports `ImageDisplay` (large zoomable image) but not the
- * scalar-data features. The eventual router picks a backend per plot type.
+ * scalar-data features. `RoutingVisualizerService` picks a backend per plot type
+ * and reports Plotly's capabilities, so the UI keeps offering every type.
  */
 export declare enum ViewerFeature {
     /** Display a raster/tiled image (HEATMAP/RGB image, OSD's strength). */
@@ -23,6 +24,7 @@ export declare enum ViewerFeature {
     /** Live isosurface intensity bounds (isomin/isomax) — see IIsosurfaceControls. */
     Isosurface = "isosurface"
 }
+/** The feature set a backend advertises (see {@link ViewerFeature}). */
 export interface ViewerCapabilities {
     has(feature: ViewerFeature): boolean;
 }

package/lib/contracts/cell-segmenter.contract.d.ts

@@ -24,6 +24,7 @@ export interface CellSegmentProgress {
     /** Human-readable phase, e.g. 'Running inference (tile 3/8)…'. */
     onStatus?: (status: string) => void;
 }
+/** A segmenter that labels every cell of an image (one exclusive label per pixel). */
 export interface ICellSegmenter {
     /** Segment all cells in an RGBA image into an instance label map. */
     segmentCells(image: {

package/lib/contracts/channel-histogram-api.contract.d.ts

@@ -97,4 +97,8 @@ export interface IChannelHistogramApi {
      *  meaningful for >8-bit images; a no-op on backends that can't provide it. */
     exportData(): void;
 }
+/**
+ * DI token for the Channels & Histogram pane's API. The library binds it to its router
+ * (VisualizationModule / provideVisualization); hosts inject it, they do not provide it.
+ */
 export declare const CHANNEL_HISTOGRAM_API: InjectionToken<IChannelHistogramApi>;

package/lib/contracts/color.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The one CSS colour parser (review NAPARI-BOUNDARY-29, CORE-25, RT-28).
+ *
+ * Seven call sites used to parse colours by hand, each accepting a different
+ * subset (`#rgb` here, `#rrggbb` only there, `rgb()` in one place) and each
+ * falling back to a different colour on bad input. They now all call
+ * {@link parseCssColor}, which returns null for anything it does not
+ * understand, and keep their own fallback at the call site
+ * (`parseCssColor(s) ?? MISSING_COLOR`).
+ *
+ * Pure: no DOM, no Angular. Channels are 0–255 integers.
+ */
+/** An RGB colour, each channel 0–255. */
+export type Rgb = [number, number, number];
+/**
+ * Parse a CSS colour to RGB, or null when it is not one this parser accepts.
+ *
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa` (the `#` may be omitted, and the
+ * alpha is ignored), and `rgb(r, g, b)` / `rgba(r, g, b, a)` with comma- or
+ * space-separated channels (rounded and clamped to 0–255). Named colours
+ * (`red`) are not accepted.
+ */
+export declare function parseCssColor(s: string | null | undefined): Rgb | null;
+/** `#rrggbb` (lower-case) for an RGB colour; channels are rounded and clamped to 0–255. */
+export declare function rgbToHex(rgb: Readonly<Rgb>): string;
+/** {@link parseCssColor} for hex input: `#rgb` / `#rrggbb` / `#rrggbbaa` (with or without `#`), or null. */
+export declare function hexToRgb(hex: string | null | undefined): Rgb | null;

package/lib/contracts/colormap-lut.d.ts

@@ -7,15 +7,30 @@
  * to Plotly's `colorscale` — so the two surfaces stay in lock-step.
  *
  * A colormap value is either:
- *   - an array of `[stop, color]` pairs (the matplotlib `*_LUT` constants), or
- *   - a Plotly built-in scale *name* string (e.g. 'Viridis', 'Reds').
+ *   - an array of `[stop, color]` pairs (the matplotlib tables, see {@link lutScale}), or
+ *   - a Plotly built-in scale *name* string (e.g. 'Viridis', 'Reds'), or
+ *   - a 256-entry RGB table itself (a `napari-js/colormaps` `*_LUT`), used as is.
  * `color` may be `'rgb(r, g, b)'` or `'#rrggbb'`/`'#rgb'`.
  */
-export type Rgb = [number, number, number];
+import { Rgb } from './color';
+export type { Rgb };
+type Stop = [number, string];
+/**
+ * A 256-entry RGB table (a `napari-js/colormaps` `*_LUT`, `Uint8Array(768)`) as an inline
+ * Plotly colorscale: one `[i / 255, 'rgb(r, g, b)']` stop per entry, the shape the colormap
+ * tree hands to Plotly's `colorscale` and to {@link buildColormapLut}. Stops are rounded to
+ * six decimals, as the colormap asset this replaces carried them.
+ */
+export declare function lutScale(lut: ArrayLike<number>): Stop[];
 /**
  * Build a 256-entry RGB lookup table from a `COLORMAP_OPTIONS` value, indexed by
  * grayscale value 0–255. Returns null if the value can't be resolved to a scale.
- * @param value  array of `[stop, color]` pairs, or a Plotly built-in name string
+ *
+ * The Plotly side (the value's forms, the colour strings, the built-in names) is
+ * parsed here; the interpolation is napari-js's own `Colormap` sampled by `buildLut`,
+ * so both backends ramp a scale the same way.
+ * @param value  array of `[stop, color]` pairs, a Plotly built-in name string, or a
+ *   256-entry RGB `Uint8Array(768)`
  * @param reverse  mirror the scale (matches Plotly's `reversescale`)
  */
 export declare function buildColormapLut(value: unknown, reverse?: boolean): Rgb[] | null;

package/lib/contracts/coordinate-transform.contract.d.ts

@@ -7,9 +7,9 @@ import { Region } from '../models/region';
  *
  * "Data coordinates" are the backend's shape coordinate space: Plotly data
  * coords for Plotly, image-pixel coords for OpenSeadragon. The tools convert
- * data -> image-matrix using the per-image ratio they already get from the host
- * (`getCachedImageData().ratios` / `getCachedImageRatio()`), so that division
- * stays in the tool and the transform stays purely screen<->data.
+ * data -> image-matrix using the per-axis ratios they already get from the host
+ * (`getCachedImageData().ratios`, see `MatrixFrame`), so that division stays in
+ * the tool and the transform stays purely screen<->data.
  */
 export interface ICoordinateTransform {
     /** Client (mouse event) pixel -> data coordinates. */

package/lib/contracts/display-types.d.ts

@@ -49,6 +49,23 @@ export interface IBrushOptions {
     /** Colour for the painted regions instead of the shape colour. Kept against preset re-apply. */
     color?: string;
 }
+/** Options for the vertex eraser. */
+export interface IVertexEraserOptions {
+    /** Eraser radius in matrix (image) pixels. */
+    radius?: number;
+}
+/**
+ * The on-canvas tools `IToolController.setActiveTool` arms: magic wand, brush,
+ * vertex eraser, box zoom and SAM point prompts. Any other id (a region draw
+ * mode such as `'drawrect'`, `'pan'`) arms none of them.
+ */
+export type CanvasToolId = 'wand' | 'brush' | 'eraseVertex' | 'zoomToBox' | 'samPoint';
+/** Every {@link CanvasToolId}. */
+export declare const CANVAS_TOOL_IDS: readonly CanvasToolId[];
+/** Whether `id` names an on-canvas tool. */
+export declare function isCanvasToolId(id: string | null | undefined): id is CanvasToolId;
+/** Options for {@link CanvasToolId} tools: the wand's, the brush's or the eraser's. */
+export type CanvasToolOptions = IWandOptions | IBrushOptions | IVertexEraserOptions;
 /** What drives point colour in the spatial-omics mode: an annotation column
  *  from the dataset, or one feature (gene) vector fetched on demand. */
 export interface SpatialColorBy {
@@ -274,4 +291,8 @@ export interface SpatialViewState {
 }
 /** Transcript glyph names — see `TRANSCRIPT_GLYPHS` in `spatial/spatial-tiles.ts`. */
 export type TranscriptGlyphName = 'circle' | 'star' | 'triangle' | 'square' | 'diamond' | 'cross' | 'hexagon' | 'triangle-down' | 'pentagon' | 'x';
+/**
+ * The spatial view a dataset opens with: no colour source, points and volume shown, the
+ * optional layers off. A complete state to spread partial view-state patches over.
+ */
 export declare const DEFAULT_SPATIAL_VIEW: SpatialViewState;

package/lib/contracts/instance-segmenter.contract.d.ts

@@ -34,6 +34,10 @@ export interface InstanceDetection {
     classId: number;
     className: string;
 }
+/**
+ * The result of one {@link IInstanceSegmenter} run: every detection, in the pixel frame of
+ * the `width × height` image that was segmented.
+ */
 export interface InstanceSegmentation {
     detections: InstanceDetection[];
     width: number;
@@ -119,6 +123,7 @@ export interface InstanceSegmentProgress {
     /** Human-readable phase, e.g. 'Running inference (tile 3/8)…'. */
     onStatus?: (status: string) => void;
 }
+/** A segmenter that returns discrete, classified, possibly overlapping instances. */
 export interface IInstanceSegmenter {
     /** Detect and outline all instances in an RGBA image. */
     segmentInstances(image: {

package/lib/contracts/intensity.d.ts

@@ -8,11 +8,22 @@ import { IHistogram } from './channel-histogram-api.contract';
  *    tiles encode gray as r=g=b, so max is exact; it also tolerates tinted
  *    pixels).
  */
-/** ITU-R BT.601 luminance for an RGB pixel (Plotly's scalar projection). */
-export declare function bt601Luminance(r: number, g: number, b: number): number;
+/** ITU-R BT.601 luminance for an RGB pixel (Plotly's scalar projection): napari-js's
+ *  `luminance8`, under the name SIV's callers use, so there is one copy of the weights. */
+export { luminance8 as bt601Luminance } from 'napari-js';
 /** Max of the three channels (the OSD tile path's scalar projection).
  *  NOTE: the per-pixel recolor loop in `osd/display-pipeline.ts` keeps this
  *  inlined on purpose — it runs ~262k times per tile. */
 export declare function maxRgb(r: number, g: number, b: number): number;
 /** Wrap 256 raw bin counts as an IHistogram (0..255 left edges + max). */
 export declare function histogram256(counts: number[]): IHistogram;
+/**
+ * Saturation-based auto-window: pick `[min, max]` so about `saturation` (0..0.5) of the
+ * pixels clip at each end of the histogram. A dominant first or last bin (unscanned
+ * padding, clipped background) is dropped first so it does not skew the range.
+ *
+ * Returns values from `h.bins` (native units for a native histogram), or `fallback` when
+ * the histogram is empty or holds no counts — each caller keeps its own: the 8-bit store
+ * falls back to the full byte range, the channel histogram to its slider bounds.
+ */
+export declare function autoWindowFromHistogram(h: IHistogram, saturation: number, fallback: readonly [number, number]): [number, number];

package/lib/contracts/plot-type.d.ts

@@ -79,7 +79,7 @@ export interface PlotTypeDescriptor {
      * mode owns each name — so it drops the backend suffix (e.g. just "Surface").
      * A type WITHOUT a `productionLabel` is **test-only**: hidden from the default
      * selector and shown only when the host enables test mode. This is the single
-     * knob that curates the default plot-mode list (jax-image-visualization).
+     * knob that curates the default plot-mode list.
      */
     productionLabel?: string;
     /**
@@ -116,7 +116,9 @@ export interface PlotTypeDescriptor {
  * for future use). Hence the `Partial` record.
  */
 export declare const PLOT_TYPE_DESCRIPTORS: Partial<Record<PlotType, PlotTypeDescriptor>>;
+/** The built-in descriptor (label, icon, dimensions, data source) of a plot type, if any. */
 export declare function getPlotTypeDescriptor(type: PlotType): PlotTypeDescriptor | undefined;
+/** Whether a built-in plot type renders in 3D (its descriptor says `dimensions: '3d'`). */
 export declare function isThreeDimensional(type: PlotType): boolean;
 /** napari-js volume. */
 export declare function isNapariVolume(type: PlotType): boolean;

package/lib/contracts/ports/image-state.port.d.ts

@@ -1,6 +1,7 @@
 import { InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
 import { IImageInfo } from '../image.contract';
+import type { VisualizerHandle } from '../visualizer.contract';
 /**
  * Host image/loading/zoom state, inverted as a port so the visualization library
  * doesn't import the app's `MainState`/`MainFacade`. The host supplies an adapter
@@ -23,7 +24,10 @@ export interface ImageStatePort {
     setZoom(zoom: boolean): void;
     setImageCached(cached: boolean): void;
     setLoadingError(error: boolean): void;
-    /** Register the active diagram/visualization component with the host. */
-    setDiagram(diagram: unknown): void;
+    /** Register the mounted visualizer with the host, or `null` once it is destroyed. */
+    setDiagram(diagram: VisualizerHandle | null): void;
 }
+/**
+ * DI token for the host's {@link ImageStatePort}. Required: the visualizer component injects it.
+ */
 export declare const IMAGE_STATE_PORT: InjectionToken<ImageStatePort>;

package/lib/contracts/ports/preferences.port.d.ts

@@ -16,4 +16,8 @@ export interface PreferencesPort {
     /** Persist (upsert) the current user's preset set. */
     savePresetSet(set: PresetSet): Observable<void>;
 }
+/**
+ * DI token for the host's {@link PreferencesPort}. Optional: without it, the annotation-class
+ * preset set is not persisted.
+ */
 export declare const PREFERENCES_PORT: InjectionToken<PreferencesPort>;

package/lib/contracts/ports/region-io.port.d.ts

@@ -26,4 +26,5 @@ export interface RegionIoPort {
         geoJsonStr: string;
     }[]): Observable<void>;
 }
+/** DI token for the host's {@link RegionIoPort}. Required by the region editor. */
 export declare const REGION_IO_PORT: InjectionToken<RegionIoPort>;

package/lib/contracts/ports/spatial-data.port.d.ts

@@ -145,15 +145,9 @@ export interface SpatialDataPort {
      * mode should never pay for it.
      */
     getVolume?(): Promise<Uint8Array>;
-    /**
-     * Server-side "which observations fall inside this polygon", for datasets
-     * too large to hit-test client-side. Optional: without it the library
-     * point-in-polygons the resident coordinates itself, which is fine into the
-     * 10^5 range. Coordinates are in the same space as the observations.
-     */
-    queryRoi?(polygon: {
-        x: number[];
-        y: number[];
-    }): Promise<Uint32Array>;
 }
+/**
+ * DI token for the host's {@link SpatialDataPort}. Optional: a host that serves no
+ * spatial-omics data binds nothing, and the spatial plot types stay hidden.
+ */
 export declare const SPATIAL_DATA_PORT: InjectionToken<SpatialDataPort>;

package/lib/contracts/ports/tile-access.port.d.ts

@@ -24,4 +24,5 @@ export interface TileAccessPort {
      *  host supplies them). Hides the app's Auth0 dependency from the library. */
     getAuthHeaders(): Promise<Record<string, string>>;
 }
+/** DI token for the host's {@link TileAccessPort}. Required by the OpenSeadragon backend. */
 export declare const TILE_ACCESS_PORT: InjectionToken<TileAccessPort>;

package/lib/contracts/region-editor-api.contract.d.ts

@@ -30,7 +30,7 @@ export interface IRegionEditorApi {
      *  preserved (the editor must not be able to drop them). */
     setAnnotationRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string): void;
     /** Change signal — fires whenever regions change on any backend. */
-    getRegionUpdateEvent(): Observable<any[]>;
+    getRegionUpdateEvent(): Observable<Region[]>;
     /** The currently-selected annotation regions (profile lines never appear). */
     getSelectedRegions$(): Observable<Region[]>;
     /** Set the selection to these regions. */

package/lib/contracts/region-overlay.contract.d.ts

@@ -31,6 +31,11 @@
  *  - `move`          — drag the selected region body to translate it.
  */
 export type RegionToolMode = 'none' | 'select' | 'drawrect' | 'drawclosedpath' | 'drawopenpath' | 'drawpolygon' | 'addpoint' | 'deletepoint' | 'move';
+/**
+ * A backend's on-canvas region layer: draws the shared `RegionStore`'s regions
+ * over the image and runs the draw / select / vertex-edit interactions. Obtained
+ * from `IVisualizer.getRegionOverlay()`.
+ */
 export interface IRegionOverlay {
     /** Set the active draw/select interaction (or 'none' to just display). */
     setMode(mode: RegionToolMode): void;

package/lib/contracts/sam.contract.d.ts

@@ -18,6 +18,13 @@ export interface SamModelDef {
     encoderUrl: string;
     /** Decoder ONNX URL (embedding + prompts → mask). Empty until hosted. */
     decoderUrl: string;
+    /**
+     * Revision of the hosted ONNX files. Downloaded models are cached by URL AND revision,
+     * and hosted URLs are typically mutable (`.../resolve/main/...`), so bump this when the
+     * files are re-exported under the same URLs: browsers then fetch the new files once and
+     * drop their older copies. Absent means the URL alone is the cache key.
+     */
+    revision?: string;
     /** Decoder I/O family — SAM v1 vs v2/v3 differ in mask output size + names. */
     variant: 'sam1' | 'sam2' | 'sam3';
     /** Encoder input side length (1024 for SAM v1). */

package/lib/contracts/semantic-segmenter.contract.d.ts

@@ -25,6 +25,10 @@ export interface SemanticRegion {
     /** Area in pixels, holes already subtracted. */
     area: number;
 }
+/**
+ * The result of one {@link ISemanticSegmenter} run: the class layers found, in the pixel
+ * frame of the `width × height` image that was segmented.
+ */
 export interface SemanticSegmentation {
     regions: SemanticRegion[];
     /** Total pixels assigned to each class, indexed by class id. */
@@ -43,6 +47,7 @@ export interface SemanticSegmentation {
      */
     unassignedFraction: number;
 }
+/** Options for one {@link ISemanticSegmenter} run. */
 export interface SemanticSegmentOptions {
     /** Which registered model to run. Defaults to the registry's default. */
     modelId?: string;
@@ -90,6 +95,7 @@ export interface SemanticSegmentProgress {
     /** Human-readable phase, e.g. 'Segmenting patch 3/8…'. */
     onStatus?: (status: string) => void;
 }
+/** A segmenter that assigns every pixel a class and returns the class regions. */
 export interface ISemanticSegmenter {
     /** Assign every pixel a class and return the resulting regions. */
     segmentSemantic(image: {

package/lib/contracts/spatial-dataset.contract.d.ts

@@ -99,6 +99,7 @@ export interface ContinuousColumnMeta extends SpatialColumnMetaBase {
     min?: number;
     max?: number;
 }
+/** Descriptor of one per-observation column, discriminated by `kind`. */
 export type SpatialColumnMeta = CategoricalColumnMeta | ContinuousColumnMeta;
 /**
  * Code meaning "this observation has no category" (unassigned / filtered out /
@@ -120,8 +121,11 @@ export interface ContinuousColumn {
     /** Length = {@link SpatialObservations.count}. */
     values: Float32Array;
 }
+/** A loaded column with its values, discriminated by `meta.kind`. */
 export type SpatialColumn = CategoricalColumn | ContinuousColumn;
+/** Narrow a loaded column to a categorical one. */
 export declare function isCategoricalColumn(c: SpatialColumn): c is CategoricalColumn;
+/** Narrow a loaded column to a continuous one. */
 export declare function isContinuousColumn(c: SpatialColumn): c is ContinuousColumn;
 /**
  * The feature (gene) matrix, described but never delivered whole. Vectors come
@@ -182,11 +186,6 @@ export interface SpatialImageRef {
     mppX?: number;
     mppY?: number;
 }
-/**
- * A spatial-omics dataset: everything cheap enough to hold resident. Column and
- * feature *values*, and polygon *geometry*, are fetched through
- * {@link SpatialDataPort} as they are displayed.
- */
 /**
  * A precomputed low-dimensional embedding over the SAME observations — UMAP, t-SNE, PCA.
  *
@@ -370,7 +369,6 @@ export interface SpatialTranscriptTile {
     /** Index into the `genes` list the tile was requested with. */
     gene: Uint16Array;
 }
-/** Transcript totals for an estimate of how many markers a selection would draw. */
 /** The per-gene levels: each level's bin and tile size, on the all-gene pyramid's grid. */
 export interface SpatialTranscriptGeneBinsMeta {
     origin: [number, number];
@@ -399,6 +397,7 @@ export interface SpatialMarkerGenes {
         }[];
     }[];
 }
+/** Transcript totals for an estimate of how many markers a selection would draw. */
 export interface SpatialTranscriptCounts {
     /** Total transcripts per requested gene, over the whole dataset. */
     counts: Record<string, number>;
@@ -413,6 +412,11 @@ export interface SpatialDensityRaster {
     genes: string[];
     values: Float32Array;
 }
+/**
+ * A spatial-omics dataset: everything cheap enough to hold resident. Column and
+ * feature *values*, and polygon *geometry*, are fetched through
+ * {@link SpatialDataPort} as they are displayed.
+ */
 export interface SpatialDataset {
     /** Stable id — the key the port's lazy accessors are scoped to. */
     id: string;
@@ -473,6 +477,15 @@ export interface SpatialVolumeMeta {
     /** World size of one voxel per axis, in the observations' units. */
     voxelSize: [number, number, number];
 }
+/**
+ * A selection over a dataset's N observations: `mask[i] === 1` when observation `i` is
+ * selected, and `count` the number selected. Pure data, so it lives with the dataset
+ * contract; the selection logic that builds one is in `spatial/spatial-selection.ts`.
+ */
+export interface SpatialSelectionMask {
+    mask: Uint8Array;
+    count: number;
+}
 /** Look a column's descriptor up by name. */
 export declare function findColumnMeta(dataset: SpatialDataset, name: string): SpatialColumnMeta | undefined;
 export {};