@jax-data-science/sci-image-visualizer 0.1.0

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

@@ -0,0 +1,72 @@
+/**
+ * Library-owned data interfaces for the image the visualization renders.
+ *
+ * The visualization package must not import the host app's concrete models
+ * (`main/models/file-info`), or it can't become a standalone library. These
+ * slim interfaces declare only the fields the library reads/writes; the host's
+ * `ImageInfo`/`ImageMetadata` classes are pure data holders that satisfy them
+ * structurally, so the host keeps passing its own instances unchanged.
+ */
+/** Per-channel metadata from the server descriptor (issue #76). */
+export interface IChannelInfo {
+    name: string;
+    /** Suggested display tint as "#RRGGBB". */
+    color: string;
+    /** Embedded 256-entry display LUT as "#RRGGBB" (intensity→color), or
+     *  null/undefined when the file has no palette for this channel. */
+    lut?: string[] | null;
+    bitDepth?: number;
+    /** Pixel-type minimum (e.g. 0 for unsigned). Native-unit floor of the window. */
+    minAllowed?: number;
+    /** Pixel-type maximum (e.g. 65535 for unsigned 16-bit). Native-unit ceiling. */
+    maxAllowed?: number;
+}
+/** Per-series image metadata (physical size + dimensions). */
+export interface IImageMetadata {
+    channelCount: number;
+    rgbChannels: number;
+    x: number;
+    y: number;
+    z: number;
+    /** Physical pixel size in µm; null/undefined when the format reports none. */
+    mppX?: number | null;
+    mppY?: number | null;
+    /** Per-channel name/color/LUT for multichannel (non-RGB) images, when known. */
+    channelInfo?: IChannelInfo[] | null;
+}
+/** The image currently being visualized. Field optionality mirrors the host's
+ *  `ImageInfo` so its instances are assignable to this interface. */
+export interface IImageInfo {
+    isGrayscale: boolean;
+    trueImageSize: number[];
+    urls: string[];
+    /** Optional small-tier URLs (fast blurry placeholder), 1:1 with `urls`. */
+    smallUrls?: string[];
+    isStack: boolean;
+    showStack: boolean;
+    scaleRatio: boolean;
+    fileName: string;
+    roiJsonStr?: string;
+    /** Per-slice ROI GeoJSON, aligned 1:1 with `urls`, for a folder stack where
+     *  each slice is a separate file with its own sibling `<stem>.geojson`
+     *  (`null` for slices without one). When present, the component applies
+     *  `roiJsonStrs[z]` for the displayed slice and swaps it on scrub — as
+     *  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)[];
+    imageMeta: IImageMetadata[];
+    /** How the OpenSeadragon backend should source this image.
+     *  - `true`/absent (default): server-tiled — OSD polls `/tiles/info` for a
+     *    pyramid and fetches tiles from the slide-crop server (whole-slide path).
+     *  - `false`: a self-contained, directly-loadable image — `urls[zIndex]` is a
+     *    complete image (e.g. a `blob:` URL built from a client-side pixel buffer),
+     *    opened via OSD's single-image source with no tile server. Lets in-memory
+     *    images (the processing pipeline) use the OSD viewer without a round-trip. */
+    tiled?: boolean;
+    /** One-shot hint: open the stack on this slice instead of slice 0 (e.g. the
+     *  host clicked a specific file within a numbered image series). The
+     *  component consumes and clears this the first time it sees the object, so
+     *  re-delivering the same ImageInfo (e.g. a plot-type switch) doesn't reset
+     *  the user's current scrub position. */
+    initialZIndex?: number;
+}

package/lib/contracts/intensity.d.ts

@@ -0,0 +1,18 @@
+import { IHistogram } from './channel-histogram-api.contract';
+/**
+ * Shared intensity helpers (refactoring plan, Step 5). The two backends use
+ * two DIFFERENT scalar projections by design — do not unify them:
+ *  - Plotly projects `[r,g,b]` frame cells with ITU-R BT.601 luminance (matches
+ *    what its heatmap has always rendered);
+ *  - the OSD tile path takes the max of the decoded RGBA channels (single-band
+ *    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;
+/** 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;

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

@@ -0,0 +1,108 @@
+/**
+ * The kind of rendering a viewer backend should produce for the loaded data.
+ *
+ * Lives in `contracts/` (rather than inside a specific backend) because it is
+ * part of the backend-neutral plotting contract: both the Plotly backend and
+ * any future backend (e.g. OpenSeadragon) accept a `PlotType` on `plot()`.
+ *
+ * NOTE: a backend may not support every type — 3D types (`SURFACE`,
+ * `SCATTER3D`, `ISOSURFACE`) are gated behind `ViewerFeature.Surface3D` in the
+ * capabilities contract, so a 2D-only backend can advertise that it can't
+ * render them and the UI can hide the option.
+ */
+export declare enum PlotType {
+    /** Natively-tiled, zoomable raster rendered by OpenSeadragon (the default
+     *  view for an image). Heatmap remains the Plotly scalar-image rendering. */
+    IMAGE = "image",
+    HEATMAP = "heatmap",
+    SURFACE = "surface",
+    CONTOUR = "contour",
+    SCATTER = "scatter",
+    LINE = "line",
+    SCATTER3D = "scatter3d",
+    ISOSURFACE = "isosurface",
+    /** WebGPU napari-js renderings (jit-ui#102), selectable alongside the OSD/Plotly types. The 3D
+     *  types take a runtime decimate factor (Full / ½ / ¼ / ⅛) instead of fixed hi/lo-res variants. */
+    NAPARI_IMAGE = "napari-image",
+    NAPARI_VOLUME = "napari-volume",
+    NAPARI_ISOSURFACE = "napari-isosurface",
+    /** WebGPU height-field surface mesh (z = intensity), the napari-js analog of Plotly SURFACE. */
+    NAPARI_SURFACE = "napari-surface",
+    /** WebGPU 2D scatter of region centroids (napari-js analog of Plotly SCATTER). */
+    NAPARI_SCATTER = "napari-scatter",
+    /** WebGPU 3D scatter of the downsampled voxel cloud (napari-js analog of Plotly SCATTER3D). */
+    NAPARI_SCATTER3D = "napari-scatter3d"
+}
+/** How many spatial dimensions a plot type renders in. */
+export type PlotDimensions = '2d' | '3d';
+/**
+ * Where a plot type pulls its data from:
+ *  - `image`   — the loaded pixel matrices / z-stack (HEATMAP, SURFACE, …)
+ *  - `regions` — the drawn/derived regions (SCATTER of region centroids, …)
+ */
+export type PlotDataSource = 'image' | 'regions';
+/**
+ * Backend-neutral metadata about a plot type. Drives UI affordances (which
+ * types are 3D, which need an image stack, how to label them in a dropdown)
+ * without any backend's trace-building logic leaking into the contract.
+ */
+export interface PlotTypeDescriptor {
+    type: PlotType;
+    /** Human-readable label for menus/dropdowns. Shown in **test mode**, where
+     *  every backend's type is offered, so it carries the backend suffix (e.g.
+     *  "Surface (napari · WebGPU)") to disambiguate same-named modes. */
+    label: string;
+    /**
+     * Label shown in the **default (non-test) selector**, where a single curated
+     * 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).
+     */
+    productionLabel?: string;
+    /**
+     * Icon shown to the left of the label in the plot-type selector. Either a
+     * PrimeNG icon class (starts with `pi `, e.g. `pi pi-image`) rendered as a
+     * font glyph, or a served SVG asset path (e.g. `assets/plotting/surface.svg`)
+     * rendered as an `<img>`. Both are tinted to the toolbar's primary blue.
+     */
+    icon?: string;
+    dimensions: PlotDimensions;
+    source: PlotDataSource;
+    /** True when the type only makes sense over a multi-frame z-stack. */
+    requiresStack?: boolean;
+    /** True when the type maps a single scalar intensity per pixel (contour,
+     *  surface, intensity profile, isosurface) — only meaningful for grayscale.
+     *  Image/Heatmap render RGB fine; Scatter uses regions. */
+    requiresGrayscale?: boolean;
+}
+/**
+ * Single source of truth for plot-type metadata. LINE is intentionally absent —
+ * intensity profiles are now Region-based line ROIs (available in Heatmap/Image
+ * mode), so LINE is no longer offered in the selector (the enum member is kept
+ * for future use). Hence the `Partial` record.
+ */
+export declare const PLOT_TYPE_DESCRIPTORS: Partial<Record<PlotType, PlotTypeDescriptor>>;
+export declare function getPlotTypeDescriptor(type: PlotType): PlotTypeDescriptor | undefined;
+export declare function isThreeDimensional(type: PlotType): boolean;
+/** napari-js volume. */
+export declare function isNapariVolume(type: PlotType): boolean;
+/** napari-js isosurface. */
+export declare function isNapariIsosurface(type: PlotType): boolean;
+/** napari-js height-field surface mesh. */
+export declare function isNapariSurface(type: PlotType): boolean;
+/** napari-js 2D scatter (region centroids). */
+export declare function isNapariScatter(type: PlotType): boolean;
+/** napari-js 3D scatter (voxel point cloud). */
+export declare function isNapariScatter3d(type: PlotType): boolean;
+/** Any napari-js 3D plot type (volume, isosurface, surface, or 3D scatter). Resolution is a runtime
+ *  decimate factor (Full / ½ / ¼ / ⅛) — see the service's `resolutionScale`. */
+export declare function isNapari3d(type: PlotType): boolean;
+/** Decimate factors offered by the Resolution control (1 = Full … 8 = ⅛). */
+export declare const NAPARI_DECIMATE_OPTIONS: {
+    label: string;
+    value: number;
+}[];
+/** Default decimate factor: ¼. The caps are set so ¼ is a sensible default resolution while ½ and
+ *  Full offer 2× and 4× the detail for opt-in high-resolution renders. */
+export declare const NAPARI_DEFAULT_DECIMATE = 4;

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

@@ -0,0 +1,29 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { IImageInfo } from '../image.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
+ * that delegates to those. Read methods return the host's live streams; write
+ * methods push state back to the host (e.g. loading flags, the updated image).
+ */
+export interface ImageStatePort {
+    getFilename$(): Observable<string | undefined>;
+    isImageCached$(): Observable<boolean>;
+    getImageInfo$(): Observable<IImageInfo | null>;
+    getImageLoadingMessage$(): Observable<string>;
+    getCacheProgress$(): Observable<number | null>;
+    getPanelWidth$(): Observable<number>;
+    isImageLoading$(): Observable<boolean>;
+    isZoom$(): Observable<boolean>;
+    /** Push an updated image descriptor to the host (partial — only set fields). */
+    setImageInfo(info: Partial<IImageInfo>): void;
+    setImageLoading(loading: boolean): void;
+    setImageLoadingMessage(message: string): void;
+    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;
+}
+export declare const IMAGE_STATE_PORT: InjectionToken<ImageStatePort>;

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

@@ -0,0 +1,19 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { PresetSet } from '../../models/class-preset';
+/**
+ * Port for persisting the per-user annotation-class preset set (jit-ui#70).
+ *
+ * The library defines the contract; the app supplies an adapter that talks to the
+ * jit-service `/api/preferences/annotation-classes` endpoint. The user is keyed
+ * server-side from the authenticated JWT, so no user id is passed here.
+ *
+ * Mirrors `RegionIoPort` / `REGION_IO_PORT`.
+ */
+export interface PreferencesPort {
+    /** Load the current user's preset set; resolves to `null` if none has been saved yet. */
+    loadPresetSet(): Observable<PresetSet | null>;
+    /** Persist (upsert) the current user's preset set. */
+    savePresetSet(set: PresetSet): Observable<void>;
+}
+export declare const PREFERENCES_PORT: InjectionToken<PreferencesPort>;

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

@@ -0,0 +1,29 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+/**
+ * Region file I/O, inverted as a port so the visualization library's region
+ * editor doesn't import the app's `FilesService` (the library performs no backend
+ * requests itself). The host supplies an adapter that delegates to its file
+ * service; the editor only needs the selected file's name (to derive default ROI
+ * filenames), an existence check, and a save. Bound to {@link REGION_IO_PORT}.
+ */
+export interface RegionIoPort {
+    /** Name of the currently selected file (e.g. "image.tif"), or undefined when
+     *  none is selected. Used to derive a default ROI filename stem. */
+    getSelectedFileName(): string | undefined;
+    /** Whether an ROI file named `name` already exists for the selected file. */
+    roiFileExists(name: string): Observable<boolean>;
+    /** Persist the regions (already serialized to a GeoJSON string) as `filename`. */
+    saveGeoJson(geoJsonStr: string, filename: string): Observable<void>;
+    /**
+     * Persist a folder-stack's regions as one geojson per slice-file (jit-ui#93).
+     * Each entry's `z` is the zero-based slice index; the host maps it to that
+     * slice-file's sibling `<stem>.geojson` in the same folder. Completes once
+     * every slice has been written. (jit-ui#93)
+     */
+    saveSliceGeoJsons(slices: {
+        z: number;
+        geoJsonStr: string;
+    }[]): Observable<void>;
+}
+export declare const REGION_IO_PORT: InjectionToken<RegionIoPort>;

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

@@ -0,0 +1,27 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { Rectangle } from '../../models/region';
+/**
+ * File/tile/zoom backend, inverted as a port so the visualization library doesn't
+ * import the app's `FilesService` (nor its `ZoomRequest`/`DisplayType` request
+ * models). The host supplies an adapter that builds the concrete request from
+ * these library-native arguments and the currently-selected file.
+ */
+export interface TileAccessPort {
+    /** Base64-encoded info for the currently-selected file (used for `/tile` and
+     *  `/tiles/info` requests), or null when nothing is selected. Collapses the
+     *  host's `getSelectedFileInfo()` + `encode(rawData)`. */
+    getSelectedInfoB64(): string | null;
+    /** Server-side crop/zoom of the current image to `roi`; resolves to raw image
+     *  bytes. `screen` is the on-screen diagram rectangle. The host builds the
+     *  request (including the selected file) internally. */
+    zoomOnRegion(roi: Rectangle, screen: Rectangle, zIndex: number): Observable<ArrayBuffer>;
+    /** Switch the host's display back to the diagram view (replaces the app's
+     *  `selectDisplayType(DisplayType.Diagram)`). */
+    selectDiagramDisplay(): void;
+    /** Auth headers (e.g. `Authorization: Bearer …`) for OSD's own tile fetches
+     *  (its AJAX loader + prefetch bypass Angular's HttpClient interceptor, so the
+     *  host supplies them). Hides the app's Auth0 dependency from the library. */
+    getAuthHeaders(): Promise<Record<string, string>>;
+}
+export declare const TILE_ACCESS_PORT: InjectionToken<TileAccessPort>;

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

@@ -0,0 +1,83 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { Region } from '../models/region';
+import { ClassPreset, PresetSet } from '../models/class-preset';
+import { IImageMetadata } from './image.contract';
+/**
+ * Public, implementation-agnostic surface that the Region Editor (an *external*
+ * consumer of the visualization package) depends on. It deals only in
+ * **annotation** regions — intensity-profile lines (`Region.isProfile()`) are
+ * owned by the intensity tool and are filtered out / preserved internally, so
+ * the editor never sees or disturbs them.
+ *
+ * The editor injects this via {@link REGION_EDITOR_API} (bound to the concrete
+ * `RoutingVisualizerService` with `useExisting`) instead of importing the
+ * service class, so it cannot reach the implementation. This is the boundary
+ * that lets `services/visualization` become a library whose only public surface
+ * is the contracts.
+ *
+ * Selection is expressed in terms of {@link Region}s, not array indices — the
+ * index space (which includes profile lines) stays internal to the package.
+ */
+export interface IRegionEditorApi {
+    getShowShapeLabel(): boolean;
+    getShapeColor(): string;
+    getFillColor(): string;
+    /** Annotation regions for the current image. Intensity-profile lines are
+     *  never included. */
+    getAnnotationRegions(): Region[];
+    /** Replace the annotation regions. Intensity-profile lines in the store are
+     *  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[]>;
+    /** The currently-selected annotation regions (profile lines never appear). */
+    getSelectedRegions$(): Observable<Region[]>;
+    /** Set the selection to these regions. */
+    setSelectedRegions(regions: Region[]): void;
+    getClassificationColors(): Map<string, string>;
+    setClassificationColor(label: string, color: string): void;
+    /** The current per-user preset set (source of truth for region colours). */
+    getPresetSet(): PresetSet;
+    /** Emits the preset set on every change (BehaviorSubject-backed). */
+    getPresetSet$(): Observable<PresetSet>;
+    /** Replace the whole preset set (persists per-user). */
+    setPresetSet(set: PresetSet): void;
+    /** Add or update one class by name (persists). */
+    upsertClass(preset: ClassPreset): void;
+    /** Remove a class by name (persists). */
+    removeClass(name: string): void;
+    /** Restore the default preset set (persists). */
+    resetPresets(): void;
+    getImageMeta(): Observable<IImageMetadata[]>;
+    importRegions(geoJsonStr: string): Region[];
+    getGeoJsonString(regions: Region[]): string;
+    /** True while a per-slice z-stack region session is active — the editor then
+     *  saves/edits regions per displayed slice. */
+    isStackMode(): boolean;
+    /** How the current stack persists: `combined` = one z-indexed geojson
+     *  (single-file z-stack, QuPath schema); `per-slice-file` = one geojson per
+     *  slice-file (folder stack). */
+    getStackSaveLayout(): 'combined' | 'per-slice-file';
+    /** Every slice's annotation regions (profile lines excluded), each tagged
+     *  with its zero-based {@link Region.z}, for a combined z-indexed save. */
+    getSliceAnnotationRegions(): Region[];
+    /** Per-slice annotation regions for a folder-stack (`per-slice-file`) save:
+     *  zero-based slice index → that slice's annotation regions. Includes
+     *  now-empty slices loaded non-empty, so their file is overwritten empty. */
+    getStackSaveAnnotationSlices(): Map<number, Region[]>;
+    /**
+     * Full-resolution image size (image-pixel dimensions) used to size an exported
+     * region mask. Backend-neutral: prefers the active renderer's reported size
+     * and falls back to the image metadata. Returns null when no size is known.
+     *
+     * The mask itself is rasterized off the main thread (see the Region Editor's
+     * mask worker) from the region geometry and this size.
+     */
+    getMaskImageSize(): {
+        width: number;
+        height: number;
+    } | null;
+}
+/** 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

@@ -0,0 +1,47 @@
+/**
+ * Region *rendering* abstraction — distinct from `IRegionStore` (which owns the
+ * region data/state, shared across backends). An `IRegionOverlay` draws the
+ * store's regions on a specific backend's canvas and handles draw/select
+ * interaction:
+ *
+ *  - `PlotlyRegionOverlay` — Plotly renders regions natively as plot shapes and
+ *    edits them via its own drag modes, so its adapter is thin (maps the mode
+ *    onto Plotly drag modes; redraw is a no-op).
+ *  - `OsdRegionOverlay` — OpenSeadragon shows pre-rendered tiles, so regions are
+ *    drawn on an SVG layer kept aligned to the viewport, with custom draw/select.
+ *
+ * Both read the same `IRegionStore`, so regions stay in sync regardless of which
+ * backend is rendering the image.
+ */
+/**
+ * Region interaction modes.
+ *
+ *  - `none`          — display only; backend navigation (OSD pan/zoom) is live.
+ *  - `select`        — click to select; on OSD also drag a vertex / resize a
+ *                      rectangle / move the region body.
+ *  - `drawrect`      — press-drag-release a rectangle.
+ *  - `drawclosedpath`— freehand closed polygon (press-drag-release).
+ *  - `drawopenpath`  — freehand open polyline (press-drag-release).
+ *
+ * Vertex-editing tools (OSD only; Plotly maps them to no-op):
+ *  - `drawpolygon`   — click to place each vertex; click the first vertex (or
+ *                      double-click) to close.
+ *  - `addpoint`      — click an edge of the selected polygon to insert a vertex.
+ *  - `deletepoint`   — click a vertex of the selected polygon to remove it.
+ *  - `move`          — drag the selected region body to translate it.
+ */
+export type RegionToolMode = 'none' | 'select' | 'drawrect' | 'drawclosedpath' | 'drawopenpath' | 'drawpolygon' | 'addpoint' | 'deletepoint' | 'move';
+export interface IRegionOverlay {
+    /** Set the active draw/select interaction (or 'none' to just display). */
+    setMode(mode: RegionToolMode): void;
+    /** Re-render the regions (e.g. after the store changes or the view moves). */
+    redraw(): void;
+    /**
+     * Convert the selected region(s) to/from a bezier curve (toBezier /
+     * toPolygon). A one-shot action, not a mode. No-op on backends
+     * that don't render beziers (Plotly).
+     */
+    setSelectedBezier(bezier: boolean): void;
+    /** Detach handlers/DOM and stop listening to the store. */
+    destroy(): void;
+}

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

@@ -0,0 +1,74 @@
+import { Rectangle, Polygon, MultiPolygon } from '../models/region';
+import { Region } from '../models/region';
+/**
+ * Region-native editing surface — typed geometry operations on the neutral
+ * {@link Region} model. The OpenSeadragon overlay (and any future editing UI)
+ * mutates regions through these calls instead of reaching into a backend's
+ * own shape representation (e.g. Plotly's `x0/y0/x1/y1` / `M…L…Z` dicts).
+ *
+ * Implemented by the shared `RegionStore`, which owns region *state*; backends
+ * own *rendering* and react to the store's update event. This replaces the
+ * Plotly-shaped `IRegionEditStore` (getShapes/applyShapesChange) the OSD
+ * overlay used to depend on.
+ *
+ * Coordinates are always **image pixels**. Vertex operations apply to polygon
+ * regions only; calling them on a rectangle (or with an out-of-range id/index)
+ * is a no-op.
+ */
+export interface IRegionEditApi {
+    /** Add a region to the current image, mint its id, select it, and emit.
+     *  Returns the assigned id. */
+    addRegion(region: Region): number;
+    /** Remove the region with this id (and drop it from the selection). */
+    removeRegion(id: number): void;
+    /** Replace a region's geometry wholesale (e.g. after a rectangle resize). */
+    updateBounds(id: number, bounds: Rectangle | Polygon | MultiPolygon): void;
+    /** Translate the whole region by (dx, dy) image pixels. */
+    moveRegion(id: number, dx: number, dy: number): void;
+    /** Move a single polygon vertex to (x, y). No-op for rectangles. */
+    moveVertex(id: number, index: number, x: number, y: number): void;
+    /** Move a single vertex on interior ring `holeIndex` (a hole) to (x, y).
+     *  No-op for rectangles, or an out-of-range hole/vertex index (jit-ui#85). */
+    moveHoleVertex(id: number, holeIndex: number, index: number, x: number, y: number): void;
+    /** Insert a vertex on interior ring `holeIndex` after `segIndex` (jit-ui#85). */
+    addHoleVertex(id: number, holeIndex: number, segIndex: number, x: number, y: number): void;
+    /** Delete the vertex at `index` on interior ring `holeIndex`; dropping the
+     *  ring below 3 vertices removes the whole hole (jit-ui#85). */
+    deleteHoleVertex(id: number, holeIndex: number, index: number): void;
+    /** Insert a vertex at (x, y) immediately after `segIndex` (the start vertex
+     *  of the edge the point lies on). No-op for rectangles. */
+    addVertex(id: number, segIndex: number, x: number, y: number): void;
+    /** Delete the vertex at `index`. No-op for rectangles, or when removing it
+     *  would drop the polygon below its minimum (3 closed / 2 open). */
+    deleteVertex(id: number, index: number): void;
+    /**
+     * Toggle the bezier-curve flag on a region (toBezier = `true`,
+     * toPolygon = `false`). The vertices stay put — only the smooth-curve
+     * rendering/export is added or removed. A rectangle is first converted to a
+     * 4-anchor closed polygon when smoothing; turning bezier off on a rectangle
+     * is a no-op.
+     */
+    setBezier(id: number, bezier: boolean): void;
+    /**
+     * Move one of a bezier vertex's two cubic control handles to absolute point
+     * (x, y). `side` is the in- or out-handle. No-op unless the region is a bezier
+     * polygon. The handle is stored relative to its anchor, so it follows the
+     * anchor when the vertex is moved.
+     */
+    moveBezierHandle(id: number, index: number, side: 'in' | 'out', x: number, y: number): void;
+    /**
+     * Move a bezier control handle on an interior ring (donut hole) — like
+     * {@link moveBezierHandle} but for `holes[holeIndex]`. No-op unless the region is a bezier
+     * polygon with hole handles (jit-ui#102).
+     */
+    moveHoleBezierHandle(id: number, holeIndex: number, index: number, side: 'in' | 'out', x: number, y: number): void;
+    /**
+     * Coalesce the emits from a burst of edits (e.g. a live vertex drag) into a
+     * single update on `endBatch`. Calls nest; the update fires when the
+     * outermost batch closes. The overlay still redraws itself per frame — this
+     * only throttles the store's `regionUpdate$` so downstream consumers (the
+     * Region Editor table) update once per gesture, not once per pointer move.
+     */
+    beginBatch(): void;
+    endBatch(): void;
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Contracts for the client-side, promptable Segment Anything (SAM) tooling
+ * (jit-ui#90). A SAM model is a promptable encoder/decoder ONNX pair: the heavy
+ * encoder runs once per image (its embedding is cached), and the light decoder
+ * runs per prompt (box/points) to produce a mask.
+ *
+ * The inference backend is abstracted behind {@link ISamSession} so the tool
+ * (SamToolService) is testable with a fake and so different runtimes (an
+ * onnxruntime-web session today, a worker-backed one later) can be swapped in.
+ */
+/** A promptable SAM model: a quantized encoder + decoder ONNX pair. */
+export interface SamModelDef {
+    /** Stable id used by the registry (e.g. 'microsam-vit-b-lm'). */
+    id: string;
+    /** Human label for a model picker. */
+    label: string;
+    /** Encoder ONNX URL (image → image embedding). Empty until hosted. */
+    encoderUrl: string;
+    /** Decoder ONNX URL (embedding + prompts → mask). Empty until hosted. */
+    decoderUrl: 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). */
+    inputSize: number;
+    /** True for microscopy-finetuned checkpoints (micro-sam, pathoSAM). */
+    microscopy?: boolean;
+    /** Override the onnxruntime-web execution providers for the ENCODER session
+     *  (decoder is always WASM). Defaults to WebGPU-with-WASM-fallback. Set to
+     *  `['wasm']` for architectures whose fp16 attention overflows on the WebGPU
+     *  EP and returns an empty mask (e.g. micro-sam ViT-T's TinyViT encoder),
+     *  which run correctly — and fast, when small — on WASM. */
+    encoderProviders?: string[];
+    /** Run inference in-process on the main thread instead of the SAM Web Worker.
+     *  Only valid for small WASM-only models (e.g. micro-sam ViT-T) where the
+     *  worker's spawn + second-ORT-runtime + message overhead outweighs its
+     *  off-thread benefit. WebGPU models ignore this (they must stay in the
+     *  worker to avoid freezing the tab). */
+    inProcess?: boolean;
+}
+/** Cached encoder output for one image (reused across every prompt on it). */
+export interface SamEmbedding {
+    /** Flattened embedding tensor, shape `dims`. */
+    data: Float32Array;
+    /** Embedding tensor dims, e.g. [1, 256, 64, 64]. */
+    dims: number[];
+    /** `inputSize / max(imageWidth, imageHeight)` — scales prompt coords. */
+    scale: number;
+    /** Image (matrix) size the embedding was computed for. */
+    imageWidth: number;
+    imageHeight: number;
+    /** Opaque handle to the embedding cached inside the inference Web Worker, when
+     *  the session runs off-thread. `decode` passes it back so the worker reuses
+     *  the cached tensor instead of round-tripping the (multi-MB) embedding data;
+     *  `data` is then an empty placeholder. Absent for in-process/fake sessions. */
+    token?: number;
+}
+/** A prompt for one object, in image (matrix) pixel coordinates. */
+export interface SamPrompt {
+    /** Box prompt `[x0,y0,x1,y1]` (issue #90's primary affordance). */
+    box?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    /** Point prompts; `label` 1 = positive (include), 0 = negative (exclude). */
+    points?: {
+        x: number;
+        y: number;
+        label: 0 | 1;
+    }[];
+}
+/** A decoded mask, binary (0/1), at image (matrix) resolution. */
+export interface SamMaskResult {
+    mask: Uint8Array;
+    width: number;
+    height: number;
+    /** Model-predicted IoU quality score for the chosen mask. */
+    iou: number;
+}
+/**
+ * Promptable-SAM inference backend. Lifecycle: `loadModel` once, `embed` once
+ * per image, `decode` per prompt.
+ */
+export interface ISamSession {
+    /** Load the model; `onProgress` reports encoder-download fraction (0..1). */
+    loadModel(model: SamModelDef, onProgress?: (fraction: number) => void): Promise<void>;
+    isLoaded(): boolean;
+    /** Run the encoder on an RGBA image; returns a cacheable embedding. */
+    embed(image: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    }): Promise<SamEmbedding>;
+    /** Run the decoder for one prompt against a cached embedding. */
+    decode(embedding: SamEmbedding, prompt: SamPrompt): Promise<SamMaskResult>;
+    dispose(): void;
+}

package/lib/contracts/toolbar-config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which groups of controls the visualization toolbar shows. All default to `true`
+ * (the full toolbar); a consumer embedding `<visualizer>` can hide groups
+ * it doesn't want via the `toolbarTools` input — e.g. the processing pipeline shows
+ * only the zoom and region tools.
+ *
+ * Groups not listed here (stack navigation, 3D-scene controls, isosurface band) are
+ * already shown only when the image/plot type calls for them, so a single 8-bit
+ * image never surfaces them regardless of these flags.
+ */
+export interface ToolbarToolVisibility {
+    /** Plot-type selector, intensity-profile line, Channels & Histogram, download,
+     *  and fit-to-view (autoscale) — everything that isn't a zoom or region tool. */
+    specialTools?: boolean;
+    /** Zoom drag, zoom box, pan, zoom in, zoom out. */
+    zoomTools?: boolean;
+    /** Region drawing/editing: select, rectangle, polyline, freeform, polygon vertex
+     *  editing, wand, vertex eraser, delete, Bézier/polygon conversion. */
+    regionTools?: boolean;
+    /** The Help button and its dialog. */
+    help?: boolean;
+}
+/** Full toolbar — the default when no `toolbarTools` is supplied. */
+export declare const ALL_TOOLBAR_TOOLS: Required<ToolbarToolVisibility>;