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

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/image.contract.d.ts

@@ -61,6 +61,10 @@ export interface IImageInfo {
      *  opposed to the scalar `roiJsonStr`, which is one ROI set for the whole
      *  image (a single file or a server z-stack). (jit-ui#93) */
     roiJsonStrs?: (string | null)[];
+    /** Base URL of a server-side region source for this image (see `openHttpRegionSource`):
+     *  its regions are drawn from the server's level-of-detail tiles instead of being loaded
+     *  from `roiJsonStr`. On a stack, slice z shows the source's plane z. */
+    regionSourceUrl?: string;
     /** Per-slice, per-channel plane URLs for a SERVERLESS multichannel image
      *  (`tiled: false` + `imageMeta[0].channelCount > 1`). `channelUrls[z][c]`
      *  is a complete single-band image of channel c at slice z. The OSD simple

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

@@ -3,6 +3,9 @@ import { Observable } from 'rxjs';
 import { Region } from '../models/region';
 import { ClassPreset, PresetSet } from '../models/class-preset';
 import { IImageMetadata } from './image.contract';
+import type { RegionSourceView } from '../region-source/region-source';
+import type { RegionIndexPage, RegionIndexQuery } from '../region-source/region-tiles';
+import type { RegionStyle } from '../region-overlay/region-style';
 /**
  * Public, implementation-agnostic surface that the Region Editor (an *external*
  * consumer of the visualization package) depends on. It deals only in
@@ -30,7 +33,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. */
@@ -78,6 +81,87 @@ export interface IRegionEditorApi {
         width: number;
         height: number;
     } | null;
+    /**
+     * Load `geoJsonStr` as the slice's region source when it is large enough
+     * (`VizConfig.regionSourceMinChars`): resolves true once it is open, false when it is small
+     * and should be imported as regions; rejects when it is not a GeoJSON FeatureCollection.
+     */
+    importRegionSource?(geoJsonStr: string): Promise<boolean>;
+    /**
+     * Drop the slice's region source, for regions imported in its place (a small file replacing a
+     * large one). The other slices keep theirs.
+     */
+    dropRegionSource?(): Promise<void>;
+    /** The slice's region source (null without one) and every change of it. */
+    getRegionSourceView$?(): Observable<RegionSourceView | null>;
+    /** A page of the slice source's features that were not taken from it. */
+    getRegionSourceIndex?(query: Omit<RegionIndexQuery, 'exclude'>): Promise<RegionIndexPage>;
+    /** Take source features into the regions and select them (added with `additive`). */
+    selectSourceFeatures?(ids: readonly string[], additive?: boolean): Promise<number[]>;
+    /** Delete source features without taking them (one undo step). */
+    deleteSourceFeatures?(ids: readonly string[]): void;
+    /**
+     * Features per class still in the slice's region source (not taken); with `stack`, a z-stack's
+     * over every slice.
+     */
+    getRegionSourceClassCounts?(stack?: boolean): Promise<Record<string, number>>;
+    /** The region look (outlines, or filled with labels inside) and every change of it. */
+    getRegionStyle$?(): Observable<RegionStyle>;
+    /** Choose the region look, field by field (overrides a region source's hint). */
+    setRegionStyle?(patch: Partial<RegionStyle>): void;
+    /** Whether a volume view is on screen (regions can then be shown in 3D). */
+    getVolumeView$?(): Observable<boolean>;
+    /**
+     * Whether the volume view's slice pane is wanted (one slice edited beside the 3D view). A volume
+     * view without it lists every slice's classes; with it, the slice's.
+     */
+    getSliceEditor$?(): Observable<boolean>;
+    /** Whether the volume view draws the region reconstructions through the volume, and changes. */
+    getRegionsThroughVolume$?(): Observable<boolean>;
+    /**
+     * Draw the region reconstructions through the volume (it hides none: surfaces traced inside its
+     * bright structures) or hidden behind what it shows in front of them (the default).
+     */
+    setRegionsThroughVolume?(through: boolean): void;
+    /**
+     * Show these groups of classes in the volume view as 3D reconstructions (one surface per group,
+     * in its colour), and only these; [] hides them.
+     */
+    showRegionClasses3d?(groups: ReadonlyArray<{
+        key: string;
+        classes: readonly string[];
+        color: string;
+        label?: string;
+    }>): Promise<void>;
+    /**
+     * Each class's volume over the whole stack, in px² × slices: its outlines' area on every slice,
+     * one slice thick. Times the pixel size and the slice spacing, µm³.
+     */
+    getClassVolumes?(classes: readonly string[]): Promise<Record<string, number>>;
+    /** Highlight the surfaces of these group keys in the volume view (none: all as usual). */
+    highlightRegionClasses3d?(keys: readonly string[]): void;
+    /** A surface clicked in the volume view with the selection tool (its group key), or none (null). */
+    getRegionPicked3d$?(): Observable<{
+        key: string | null;
+        additive: boolean;
+    }>;
+    /** The class groups shown in 3D on the image on screen; emits [] when another image is plotted. */
+    getRegionClasses3d$?(): Observable<ReadonlyArray<{
+        key: string;
+        classes: readonly string[];
+    }>>;
+    /** The classes hidden from view, and every change of them. */
+    getHiddenClasses$?(): Observable<ReadonlySet<string>>;
+    /**
+     * Hide (or show again) these classes: their regions and the region source's features are not
+     * drawn or picked, and their surfaces in the volume view are hidden.
+     */
+    setClassesHidden?(classes: readonly string[], hidden: boolean): void;
+    /** Select every region of these classes on the slice, the source's included (taken). */
+    selectRegionClasses?(classes: readonly string[], additive?: boolean): Promise<void>;
+    /** {@link getGeoJsonString} merged with the region source behind the regions (see
+     *  `RegionStore.getGeoJsonWithSource`); `slice` names a folder stack's slice. */
+    getGeoJsonStringWithSource?(regions: Region[], slice?: number): Promise<string>;
 }
 /** DI token the Region Editor injects instead of the concrete service. */
 export declare const REGION_EDITOR_API: InjectionToken<IRegionEditorApi>;

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/region-store.contract.d.ts

@@ -1,5 +1,8 @@
 import { Rectangle, Polygon, MultiPolygon } from '../models/region';
 import { Region } from '../models/region';
+import type { Observable } from 'rxjs';
+import type { RegionSourceView } from '../region-source/region-source';
+import type { RegionStyle } from '../region-overlay/region-style';
 /**
  * Region-native editing surface — typed geometry operations on the neutral
  * {@link Region} model. The OpenSeadragon overlay (and any future editing UI)
@@ -72,3 +75,22 @@ export interface IRegionEditApi {
     beginBatch(): void;
     endBatch(): void;
 }
+/**
+ * The region-source side of the store, as the overlays use it: a large region set held as a
+ * tiled source (see `RegionStore.attachRegionSource`) that the overlays draw at the zoom's level
+ * of detail and pick from. Optional on the overlays' store: a store without it simply has no
+ * source to draw.
+ */
+export interface IRegionSourceApi {
+    /** The current slice's source as a layer draws it, and every change of it; null without one. */
+    getRegionSourceView$(): Observable<RegionSourceView | null>;
+    /** Take source features into the working set as regions and select them (added to the
+     *  selection with `additive`). Resolves the region ids. */
+    selectSourceFeatures(ids: readonly string[], additive?: boolean): Promise<number[]>;
+    /** The region look (outlines, or filled with inside labels). */
+    getRegionStyle(): RegionStyle;
+    /** Whether a class's label is left out because a subclass of it is drawn too. */
+    isLabelCovered(label: string | undefined): boolean;
+    /** Whether regions labelled `label` are hidden: not drawn, not picked. */
+    isClassHidden(label: string | null | undefined): boolean;
+}

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). */