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

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

@@ -0,0 +1,346 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { Image } from 'image-js';
+import { IImageInfo, IImageMetadata } from './image.contract';
+import { Region } from '../models/region';
+import { PlotType, PlotTypeDescriptor } from './plot-type';
+import { ViewerCapabilities } from './capabilities.contract';
+import { IRegionOverlay } from './region-overlay.contract';
+import { IHistogram } from './channel-histogram-api.contract';
+import { ColormapNode, IWandOptions, IBrushOptions } from './display-types';
+/**
+ * Backend-neutral visualization contract. Plotly is one implementation;
+ * OpenSeadragon is another (for the image plot type). The abstraction renders
+ * data — a raster image OR a scientific plot (heatmap, surface, contour,
+ * scatter, line, isosurface) — draws regions on it, and drives on-canvas tools.
+ *
+ * Split into role interfaces so a consumer can depend only on the slice it
+ * uses, then composed into `IVisualizer`.
+ *
+ * Types are intentionally permissive (`any` where the current Plotly service
+ * is untyped) so `PlotlyService` satisfies the contract without a typing
+ * rewrite — tightening is a follow-up, not part of standing the interface up.
+ */
+/** Pixel readback shape returned by `getDisplayedPixelData`. */
+export interface PixelData {
+    width: number;
+    height: number;
+    channels: number;
+    data: Uint8ClampedArray;
+}
+/** Intensity sampled along a line ROI (PlotType.LINE over image data). */
+export interface IntensityProfile {
+    /** Distance along the line. In microns when the image carries a physical
+     *  pixel size (mpp); otherwise in image pixels. See {@link unit}. */
+    positions: number[];
+    /** Sampled intensity (grayscale value or RGB luminance). */
+    values: number[];
+    /** Unit of {@link positions}: 'µm' when scaled by the image's mpp, else 'px'. */
+    unit?: 'µm' | 'px';
+    /** Stable id of the line ROI this profile came from (multi-line support). */
+    id?: number;
+    /** Colour of the line ROI — the inset trace is drawn in the same colour. */
+    color?: string;
+}
+/**
+ * The render/viewport role: load data, render it (image or plot), and handle
+ * zoom, stack navigation, and pixel readback.
+ */
+export interface IDataRenderer {
+    load(imageInfo: IImageInfo, zIndex: number): Promise<any>;
+    /** `imageLoaded` is the backend-specific handle returned by `load()` —
+     *  treat it as opaque and pass it straight through. */
+    plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
+    /** @deprecated Plotly-specific re-render; the OSD backend no-ops it. The host
+     *  re-drives `plot()` from its image stream instead. */
+    reloadAndPlot(): void;
+    reset(): void;
+    relayout(trueImageSize?: number[]): void;
+    /** @deprecated Plotly-specific (axis reset); the OSD backend no-ops it. Gate
+     *  on {@link ViewerCapabilities} before calling. */
+    resetAxes(): void;
+    /** @deprecated Plotly-specific (autoscale); the OSD backend no-ops it. Gate
+     *  on {@link ViewerCapabilities} before calling. */
+    autoscale(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setDragMode(mode: string | false): void;
+    /** Show/hide the overview navigator (the minimap). OpenSeadragon only — Plotly
+     *  no-ops it (it has no navigator). Applied when the viewer is (re)created, and
+     *  toggled live when one is already mounted. */
+    setNavigatorVisible(visible: boolean): void;
+    /** Image smoothing (bilinear interpolation). `false` = nearest-neighbour, so
+     *  zooming past 1:1 shows crisp pixel blocks (pixel-level inspection).
+     *  OpenSeadragon only — Plotly no-ops it. Applied at viewer creation and live
+     *  (with a redraw) when one is mounted. */
+    setImageSmoothingEnabled(enabled: boolean): void;
+    setShowStack(showstack: boolean): void;
+    setZIndex(zIndex: number): void;
+    setStackLoading(stackLoading: boolean): void;
+    isStackLoading(): Observable<boolean>;
+    getStackLoadingProgress(): Observable<number>;
+    /** Cancel any in-flight multi-frame loading (volume-assembly / surface preload) so it stops
+     *  fetching more frames and clears the loading state. Optional — only backends that stream a
+     *  z-stack (napari-js WebGPU) do real work here; others no-op. */
+    cancelLoading?(): void;
+    getTrueImageSize(): {
+        width: number;
+        height: number;
+    } | null;
+    getCurrentImage(): Promise<Image | null>;
+    getDisplayedPixelData(): PixelData | null;
+    /**
+     * The region of the original, full-resolution image that the pixels returned
+     * by {@link getDisplayedPixelData} currently cover — `{ x, y, width, height }`
+     * in full-image pixel coordinates. When zoomed/panned into a sub-area this is
+     * the crop's origin + extent; when zoomed out/panned beyond the edges, the
+     * rectangle may extend outside the image bounds (matching the pixel readback
+     * canvas). Lets a consumer map displayed-pixel coordinates back to the original
+     * image via `origin + displayedPx * (extent / displayedDim)`.
+     *
+     * Returns `null` when the viewport isn't laid out yet or the backend can't
+     * report it — callers should then fall back to the full-image scale (treat
+     * the displayed pixels as a downsample of the whole image).
+     */
+    getDisplayedSourceRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    downloadImage(): void;
+    setPlotType(plotType: PlotType): void;
+    /** Set the napari 3D decimate factor (1 = full … 8 = ⅛). Optional — only the napari-js WebGPU
+     *  backend honors it; changing it re-loads the current 3D plot at the coarser/finer sampling. */
+    setResolutionScale?(scale: number): void;
+    /** The current napari 3D decimate factor (to initialize the Resolution control). Optional. */
+    getResolutionScale?(): number;
+    /** @deprecated Use `getSurface3dControls()` — 3D scene controls only exist on
+     *  a backend that renders 3D plot types; this method silently no-ops on OSD. */
+    setSurfaceDragMode(mode: string): void;
+    /** @deprecated Use `getSurface3dControls()` — see {@link setSurfaceDragMode}. */
+    resetSurfaceCamera(): void;
+    getAutoscaleEvent(): Observable<any>;
+    /** Plot types this backend advertises (drives the UI selector). */
+    getPlotTypeDescriptors(): PlotTypeDescriptor[];
+    /** Intensity along the line ROIs; emits the full set as any line is added,
+     *  moved, or removed (PlotType.LINE). One entry per line ROI. */
+    getIntensityProfile$(): Observable<IntensityProfile[]>;
+    /** Render the floating intensity-profile inset chart into `divId` from the
+     *  given profiles (one trace per line ROI, coloured to match its line).
+     *  Owned by the backend so consumers never reach a charting library directly. */
+    renderIntensityInset(divId: string, profiles: IntensityProfile[]): void;
+}
+/** Region/shape state: CRUD, selection, classification colours, GeoJSON I/O. */
+export interface IRegionStore {
+    setRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string, append?: boolean): void;
+    /** Framework-neutral accessor — the canonical way to read current regions. */
+    getRegions(): Region[];
+    getRegionPolygons(): any[];
+    getRegionUpdateEvent(): Observable<any[]>;
+    setSelectedShapeIndices(indices: number[]): void;
+    getSelectedShapeIndices$(): Observable<number[]>;
+    /** Select a specific region (by identity), highlighting it on whichever
+     *  backend is rendering — Plotly sets its active-shape handles, OpenSeadragon
+     *  highlights the SVG element. No-op if the region isn't in the store. */
+    selectRegion(region: Region): void;
+    deleteActiveShape(): void;
+    getShowShapeLabel(): boolean;
+    getShapeColor(): string;
+    getFillColor(): string;
+    getClassificationColors(): Map<string, string>;
+    setClassificationColor(label: string, color: string): void;
+    plotPreviousShapes(): void;
+    setPreviousShapes(shapes: any[]): void;
+    getPreviousShapes(): any[];
+    /** Undo the most recent region action (jit-ui#85). Restores the region set to
+     *  the state before that action; up to a small fixed depth (10) is retained,
+     *  so it can be invoked up to 10 times in a row. No-op when nothing is left to
+     *  undo. */
+    undo(): void;
+    /** Re-apply the most recently undone region action. No-op when there's
+     *  nothing to redo (any fresh region action clears the redo future). */
+    redo(): void;
+    /** Synchronous read of {@link getCanUndo$}. */
+    canUndo(): boolean;
+    /** Synchronous read of {@link getCanRedo$}. */
+    canRedo(): boolean;
+    /** Emits whether an undo step is currently available — drives the toolbar
+     *  Undo button's enabled (greyed-out) state. */
+    getCanUndo$(): Observable<boolean>;
+    /** Emits whether a redo step is currently available — drives the toolbar
+     *  Redo button's enabled (greyed-out) state. */
+    getCanRedo$(): Observable<boolean>;
+    /** Clear the undo/redo history (e.g. on image load/switch). */
+    resetUndoHistory(): void;
+    importRegions(geoJsonStr: string): Region[];
+    exportRegions(regions: Region[]): void;
+    getGeoJsonString(regions: Region[]): string;
+    /** Begin a per-slice z-stack region session (jit-ui#93). `slices` maps each
+     *  zero-based slice index to that slice's regions; the store shows `initialZ`
+     *  live while holding the rest, so scrubbing swaps region sets and edits on a
+     *  slice persist. `saveLayout` records how the stack persists — `combined`
+     *  (one z-indexed geojson, single-file z-stack) or `per-slice-file` (folder
+     *  stack). See {@link setDisplaySlice}, {@link getSliceRegions}. */
+    enterStackMode(slices: Map<number, Region[]>, initialZ?: number, saveLayout?: 'combined' | 'per-slice-file'): void;
+    /** End the per-slice session (single-plane image, or the stack was closed). */
+    exitStackMode(): void;
+    /** True while a per-slice z-stack session is active. */
+    isStackMode(): boolean;
+    /** How the current stack persists to disk (jit-ui#93). */
+    getStackSaveLayout(): 'combined' | 'per-slice-file';
+    /** Swap the live region set to slice `z` (stack mode only), capturing the
+     *  current slice's edits first. Called on every committed slice scrub. */
+    setDisplaySlice(z: number): void;
+    /** Every slice's regions for save/export, each tagged with its zero-based
+     *  {@link Region.z}; the flat set outside stack mode. */
+    getSliceRegions(): Region[];
+    /** Slices to write on a per-slice-file save (folder stack, jit-ui#93): each
+     *  slice with regions, plus slices cleared since load (empty, to overwrite).
+     *  Keyed by zero-based slice index; regions tagged with their z. */
+    getStackSaveSlices(): Map<number, Region[]>;
+}
+/** On-canvas tool modes (wand, brush, vertex eraser, zoom-to-box). */
+export interface IToolController {
+    setWandMode(active: boolean, options?: IWandOptions): void;
+    setWandOptions(options: IWandOptions): void;
+    clearActiveWandRegion(): void;
+    /** Brush region tool. `size` (matrix-pixel diameter) sizes the painted disc. */
+    setBrushMode(active: boolean, options?: IBrushOptions): void;
+    setBrushOptions(options: IBrushOptions): void;
+    setVertexEraserMode(active: boolean): void;
+    setVertexEraserRadius(radius: number): void;
+    setZoomToBoxMode(active: boolean): void;
+    /** Box-prompted SAM segmentation: segment every rectangle region into masks.
+     *  Returns the number of mask regions added. (jit-ui#90) */
+    segmentRectangles(): Promise<number>;
+    /** Cellpose-on-crop: client slide-crop each rectangle and segment cells in it
+     *  (cellpose-SAM via the host's CELL_SEGMENTER). Returns regions added. */
+    segmentRectanglesCellpose(): Promise<number>;
+    /** Choose the registered SAM model the segment tools use (jit-ui#90 P1). */
+    setSamModel(id: string): void;
+    /** Toggle the interactive SAM point-prompt tool (click = +point, Shift = -). */
+    setSamPointMode(active: boolean): void;
+    /** Finalise / discard the in-progress SAM point object. */
+    commitSamPoints(): void;
+    clearSamPoints(): void;
+}
+/**
+ * Controls specific to the ISOSURFACE plot type. Optional and capability-gated
+ * (`ViewerFeature.Isosurface`): only a backend that renders isosurfaces exposes
+ * it, via `IVisualizer.getIsosurfaceControls()`. Kept off the always-on
+ * contract so consumers never call a control that's meaningless for the current
+ * plot type / backend.
+ */
+export interface IIsosurfaceControls {
+    /** Live-update the isosurface intensity band [isomin, isomax] over 0–255. */
+    setIsoRange(isoMin: number, isoMax: number): void;
+}
+/**
+ * Controls specific to the 3D plot types (SURFACE / SCATTER3D / ISOSURFACE
+ * scenes). Capability-gated like {@link IIsosurfaceControls}: only a backend
+ * that renders 3D scenes exposes it, via `IVisualizer.getSurface3dControls()` —
+ * the deprecated top-level `setSurfaceDragMode`/`resetSurfaceCamera` silently
+ * no-op on 2D-only backends.
+ */
+export interface ISurface3dControls {
+    /** Switch the 3D scene interaction mode (orbit / turntable / pan / zoom). */
+    setSurfaceDragMode(mode: string): void;
+    /** Reset the 3D scene camera to its default eye position. */
+    resetSurfaceCamera(): void;
+    /** Toggle the 3D coordinate-axes / scale gizmo on/off. Optional — only the napari-js WebGPU
+     *  volume/isosurface backend renders one (jit-ui#102). */
+    setAxesVisible?(visible: boolean): void;
+    /** Whether the axes gizmo is currently shown (for initializing the toggle UI). Optional. */
+    axesVisible?(): boolean;
+    /** Render the surface as a wireframe (edges) instead of a filled surface. Optional — only the
+     *  napari-js WebGPU surface backend supports it (jit-ui#102). */
+    setWireframe?(on: boolean): void;
+    /** Whether the surface is currently drawn as a wireframe (for initializing the toggle UI). */
+    wireframe?(): boolean;
+}
+/**
+ * Controls specific to the LINE (intensity-profile) plot type. Capability-gated
+ * like {@link IIsosurfaceControls}: only a backend that renders the line-ROI /
+ * inset exposes it, via `IVisualizer.getIntensityControls()`.
+ */
+export interface IIntensityControls {
+    /** Add another line ROI (next bright palette colour) and its inset trace.
+     *  Returns the created region so the caller can select it on the active
+     *  backend, or null if no image extent is known yet. */
+    addProfileLine(): Region | null;
+}
+/** Display options (colormap/LUT, reverse scale, image metadata). */
+export interface IDisplayOptions {
+    getColormap(): Observable<ColormapNode | null>;
+    setColormap(colormap: ColormapNode): void;
+    getColormapOptions(): ColormapNode[];
+    getReverseScale(): Observable<boolean>;
+    setReverseScale(reverscale: any): void;
+    setImageMeta(imageMeta: IImageMetadata[]): void;
+    getImageMeta(): Observable<IImageMetadata[]>;
+}
+/**
+ * Intensity-profile sampling (PlotType.LINE). The sampling *source* lives in the
+ * Plotly backend (it owns pixel readback); OpenSeadragon contributes only the
+ * viewport-change signal that drives re-sampling at the current zoom. Each
+ * backend implements the part it owns and no-ops the rest — mirroring the
+ * deprecated no-op pattern on {@link IDataRenderer} — so the contract is uniform
+ * and a consumer can depend on `IVisualizer` alone (no concrete-type reach-in).
+ */
+export interface IIntensitySampling {
+    /** Populate the intensity-sampling cache for the current image/slice so the
+     *  line-ROI profiles have pixel data. Real on Plotly; no-op on OSD. */
+    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
+    /** Re-sample the profiles from a fresh crop of the given image-pixel ROI at
+     *  display resolution. Real on Plotly; no-op on OSD. */
+    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+    /** Visible-region changes (image-pixel coords), emitted when the view settles,
+     *  so the inset can re-sample at the current zoom. Real on OSD; empty on Plotly
+     *  (its high-def zoom updates the sampling cache inline instead). */
+    getViewportChange$(): Observable<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+}
+/** Composite contract a visualization backend implements. */
+export interface IVisualizer extends IDataRenderer, IRegionStore, IToolController, IDisplayOptions, IIntensitySampling {
+    readonly capabilities: ViewerCapabilities;
+    /** This backend's region renderer. May be null until a plot is mounted
+     *  (OpenSeadragon). Drives region draw/select modes uniformly. */
+    getRegionOverlay(): IRegionOverlay | null;
+    /** Isosurface controls when this backend advertises `ViewerFeature.Isosurface`,
+     *  else null — so consumers gate on the returned object, not a no-op method. */
+    getIsosurfaceControls(): IIsosurfaceControls | null;
+    /** Intensity (line-ROI) controls when the backend renders the LINE plot type,
+     *  else null. */
+    getIntensityControls(): IIntensityControls | null;
+    /** 3D scene controls when this backend renders 3D plot types, else null —
+     *  the capability-gated replacement for the deprecated top-level
+     *  `setSurfaceDragMode`/`resetSurfaceCamera`. */
+    getSurface3dControls(): ISurface3dControls | null;
+    /** Binned intensity histogram for a channel from the currently-displayed
+     *  pixels, or null when none are available. Feeds the Channels & Histogram
+     *  pane. */
+    getHistogram(channelIndex: number, bins: number): IHistogram | null;
+    /** Async histogram stream — native bit depth for >8-bit images (server), else
+     *  the 8-bit client histogram. */
+    getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
+    /** Export the displayed image, composited with the current display settings,
+     *  as a publication-ready PNG download. */
+    exportComposite(): void;
+    /** Export the underlying image data as a data-preserving multi-band TIFF
+     *  (native bit depth). No-op on backends that can't provide it. */
+    exportData(): void;
+    unsubscribe(): void;
+}
+/**
+ * DI token for the active visualization backend. Bind it (`useExisting`) to the
+ * `RoutingVisualizerService`, which selects Plotly vs OpenSeadragon per plot
+ * type. Consumers — including this library's own `VisualizerComponent` —
+ * inject `IVisualizer` through this token rather than the concrete router, so
+ * the routing/fallback implementation can change without touching constructors.
+ */
+export declare const VISUALIZER: InjectionToken<IVisualizer>;

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

@@ -0,0 +1,25 @@
+import { InjectionToken } from '@angular/core';
+/**
+ * Static configuration the visualization library needs from the host, supplied
+ * via DI so the library never imports the app's `environment`.
+ */
+export interface VizConfig {
+    /** Base URL of the tile/crop server (`/tile`, `/tiles/info`, zoom). */
+    slideCropServer: string;
+    /**
+     * Optional CSS selector for a host element whose current width the Region
+     * Editor dialog should match when it first opens (e.g. the app's right
+     * panel). Measured once per open — it does not track later resizes. When
+     * absent or the element isn't found, the dialog falls back to a quarter of
+     * the page width (25vw).
+     */
+    regionEditorWidthSelector?: string;
+    /**
+     * Opt in to the experimental WebGPU **napari-js** backend for the IMAGE plot type
+     * (jit-ui#102). When `true`, the router renders images through napari-js with OpenSeadragon
+     * as the fallback; when absent/false, OpenSeadragon remains the default. Other plot types
+     * are unaffected.
+     */
+    useNapariRenderer?: boolean;
+}
+export declare const VIZ_CONFIG: InjectionToken<VizConfig>;

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

@@ -0,0 +1,47 @@
+import { ChangeDetectorRef, ElementRef, EventEmitter, OnDestroy, Renderer2 } from '@angular/core';
+import * as i0 from "@angular/core";
+export declare class HexColorPickerComponent implements OnDestroy {
+    private elRef;
+    private renderer;
+    private cdr;
+    private static readonly DROPDOWN_WIDTH;
+    private _color;
+    colorChange: EventEmitter<string>;
+    open: boolean;
+    swatchBtn: ElementRef<HTMLButtonElement>;
+    dropdownRef: ElementRef<HTMLDivElement>;
+    hue: number;
+    saturation: number;
+    lightness: number;
+    red: number;
+    green: number;
+    blue: number;
+    readonly colorRows: string[][];
+    private normalizeHexColor;
+    get color(): string;
+    set color(val: string);
+    constructor(elRef: ElementRef, renderer: Renderer2, cdr: ChangeDetectorRef);
+    ngOnDestroy(): void;
+    toggle(): void;
+    private appendDropdownToBody;
+    private removeDropdownFromBody;
+    selectColor(hex: string): void;
+    selectAndClose(hex: string): void;
+    close(): void;
+    onHexInput(value: string): void;
+    onHslChange(): void;
+    onRgbChange(): void;
+    get hueGradient(): string;
+    get satGradient(): string;
+    get lightGradient(): string;
+    onDocumentClick(event: Event): void;
+    private syncFromHex;
+    private syncRgbFromHex;
+    private syncHslFromRgb;
+    private hexToRgb;
+    private rgbToHex;
+    private rgbToHsl;
+    private hslToHex;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HexColorPickerComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HexColorPickerComponent, "hex-color-picker", never, { "color": { "alias": "color"; "required": false; }; }, { "colorChange": "colorChange"; }, never, never, false, never>;
+}

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

@@ -0,0 +1,71 @@
+import { Observable } from 'rxjs';
+import { IDisplayOptions, IRegionStore } from '../contracts/visualizer.contract';
+import { Region } from '../models/region';
+import { ColormapNode } from '../contracts/display-types';
+import { IImageMetadata } from '../contracts/image.contract';
+import { RegionStore } from '../store/region-store.service';
+import { VisualizerStore } from '../store/visualizer-store.service';
+/**
+ * Shared store-delegation base for the OpenSeadragon and napari-js
+ * `IVisualizer` backends. The entire `IRegionStore` and `IDisplayOptions`
+ * surfaces (plus the two classification-colour members) are pure forwarders to
+ * the shared `RegionStore` / `VisualizerStore` in BOTH backends — so they live
+ * here once, as a single source of truth, rather than being copied per backend.
+ * (This is the "cross-backend behaviour that isn't rendering belongs in a
+ * shared abstraction" convention from CLAUDE.md; the extraction closes
+ * SHARED-BACKEND-REFACTOR.md.)
+ *
+ * Backend-specific members — `load`/`plot`/`reset`/zoom/`setZIndex`/readback,
+ * the region OVERLAY, tool wiring, histograms, scale bar, tiling, colormap LUT
+ * application — deliberately stay in each subclass.
+ *
+ * NOT `@Injectable`: an abstract base doesn't participate in Angular DI. Each
+ * subclass stays `@Injectable`, declares its own injected dependencies
+ * (including the two stores), and passes them to `super(...)`. Plotly is
+ * intentionally not a subclass — it has its own region model.
+ */
+export declare abstract class BaseStoreVisualizer implements IRegionStore, IDisplayOptions {
+    protected readonly regionStore: RegionStore;
+    protected readonly store: VisualizerStore;
+    protected constructor(regionStore: RegionStore, store: VisualizerStore);
+    setRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string, append?: boolean): void;
+    getRegions(): Region[];
+    getRegionPolygons(): any[];
+    getRegionUpdateEvent(): Observable<any[]>;
+    setSelectedShapeIndices(indices: number[]): void;
+    getSelectedShapeIndices$(): Observable<number[]>;
+    selectRegion(region: Region): void;
+    deleteActiveShape(): void;
+    getShowShapeLabel(): boolean;
+    getShapeColor(): string;
+    getFillColor(): string;
+    plotPreviousShapes(): void;
+    setPreviousShapes(shapes: any[]): void;
+    getPreviousShapes(): any[];
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getCanUndo$(): Observable<boolean>;
+    getCanRedo$(): Observable<boolean>;
+    resetUndoHistory(): void;
+    importRegions(geoJsonStr: string): Region[];
+    exportRegions(regions: Region[]): void;
+    getGeoJsonString(regions: Region[]): string;
+    enterStackMode(slices: Map<number, Region[]>, initialZ?: number, saveLayout?: 'combined' | 'per-slice-file'): void;
+    exitStackMode(): void;
+    isStackMode(): boolean;
+    getStackSaveLayout(): 'combined' | 'per-slice-file';
+    setDisplaySlice(z: number): void;
+    getSliceRegions(): Region[];
+    getStackSaveSlices(): Map<number, Region[]>;
+    getClassificationColors(): Map<string, string>;
+    setClassificationColor(label: string, color: string): void;
+    getColormap(): Observable<ColormapNode | null>;
+    setColormap(colormap: ColormapNode): void;
+    getColormapOptions(): ColormapNode[];
+    getReverseScale(): Observable<boolean>;
+    setReverseScale(reverscale: any): void;
+    setImageMeta(imageMeta: IImageMetadata[]): void;
+    getImageMeta(): Observable<IImageMetadata[]>;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * DOM text labels for the napari-js 3D axes gizmo (jit-ui#102). The {@link AxesLayer} draws the
+ * axis lines/ticks/box in WebGPU; this overlay adds the crisp X/Y/Z + scale text on top, projected
+ * with the 3D camera's view-projection so each label tracks its anchor as the volume orbits.
+ * Mirrors the {@link NapariScaleBar} overlay pattern (absolute-positioned over the host, updated on
+ * every `camera3d.changed`). Falls back to pixel/slice counts when no physical µm/pixel is known.
+ */
+/** One axis label: a world-space anchor (the axis end, in the volume's centred box), the text to
+ *  show, and its colour (matching the WebGPU axis colour). */
+export interface AxisLabelSpec {
+    anchor: [number, number, number];
+    text: string;
+    color: string;
+}
+/** The slice of napari's Camera3D this overlay reads. `viewProjection` is column-major (gl-matrix). */
+export interface AxesLabelCamera3D {
+    viewProjection(vw: number, vh: number): ArrayLike<number>;
+    readonly changed: {
+        connect(listener: () => void): () => void;
+    };
+}
+/**
+ * Project a world point through a column-major 4×4 MVP to CSS-pixel screen coordinates.
+ * Returns `visible: false` when the point is at/behind the camera (w ≤ 0). Pure — unit-tested.
+ */
+export declare function projectPoint(mvp: ArrayLike<number>, p: [number, number, number], vw: number, vh: number): {
+    x: number;
+    y: number;
+    visible: boolean;
+};
+export declare class NapariAxesLabels {
+    private readonly host;
+    private readonly camera3d;
+    private readonly labels;
+    private readonly els;
+    private readonly disconnectCamera;
+    private readonly resizeObserver?;
+    private visible;
+    constructor(host: HTMLElement, camera3d: AxesLabelCamera3D, labels: AxisLabelSpec[]);
+    setVisible(visible: boolean): void;
+    /** Replace the label anchors/text in place (same count) and reproject — lets a host move the
+     *  labels when the box geometry changes live (e.g. a Z-height gizmo restretching the volume)
+     *  without tearing down and recreating the DOM elements (which would flicker). */
+    updateAnchors(labels: AxisLabelSpec[]): void;
+    private update;
+    destroy(): void;
+}

package/lib/implementations/napari-js/napari-region-overlay.d.ts

@@ -0,0 +1,115 @@
+import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
+import { RegionStore } from '../../store/region-store.service';
+/** The slice of the napari Viewer the overlay needs (coord transforms + control gating). */
+interface OverlayViewer {
+    canvasToWorld(clientX: number, clientY: number): [number, number];
+    worldToCanvas(worldX: number, worldY: number): [number, number];
+    setControlsEnabled(enabled: boolean): void;
+    readonly camera: {
+        readonly changed: {
+            connect(listener: () => void): () => void;
+        };
+    };
+}
+/**
+ * SVG region overlay for the napari-js WebGPU image view (jit-ui#102), mirroring the OSD backend's
+ * {@link OsdRegionOverlay} but driven by napari's `canvasToWorld`/`worldToCanvas` transforms.
+ * Vector shapes are drawn in an absolutely-positioned `<svg>` over the canvas (no need to push
+ * them through WebGPU). It writes completed shapes to the shared {@link RegionStore} (so save /
+ * undo / export work identically to OSD) and re-renders from the store on every camera move,
+ * region change, and selection change.
+ *
+ * Supports (jit-ui#102): rectangle / polygon / freehand path drawing, click-select and rubber-band
+ * marquee select, pan/zoom gating via `setControlsEnabled`, body move, vertex move/add/delete,
+ * bezier handle editing, and donut holes (including hole vertex + hole-bezier-handle editing) —
+ * full parity with {@link OsdRegionOverlay}.
+ */
+export declare class NapariRegionOverlay implements IRegionOverlay {
+    private readonly host;
+    private readonly viewer;
+    private readonly store;
+    private readonly svg;
+    private readonly subs;
+    private readonly disconnectCamera;
+    private mode;
+    private selected;
+    /** In-progress drawing state (image-space). */
+    private draftRect;
+    /** In-progress rubber-band selection marquee (select mode), image-space. */
+    private marquee;
+    /** Dedicated marquee rect element, updated directly during the drag (no full region redraw). */
+    private marqueeEl;
+    private draftPath;
+    private drawing;
+    /** In-progress manipulation (select/move modes): dragging a body, a polygon vertex, or a
+     *  rectangle corner. `anchor` is the fixed opposite corner for a rectangle resize. */
+    private edit;
+    constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore);
+    setMode(mode: RegionToolMode): void;
+    setSelectedBezier(bezier: boolean): void;
+    destroy(): void;
+    /** Pointer client coords → rounded image coords. */
+    private toImage;
+    /** Image coords → SVG-local px (the svg overlays the canvas at the same client rect). */
+    private toLocal;
+    private readonly onPointerDown;
+    private readonly onPointerMove;
+    private readonly onPointerUp;
+    /** Click-to-place polygon: add a vertex, or close when clicking near the first one. */
+    private handlePolygonClick;
+    private readonly onDblClick;
+    /** The currently-selected region (single selection), or null. */
+    private selectedRegion;
+    /** Screen distance (px) between a client point and an image coord. */
+    private screenDist;
+    /**
+     * Start a select/move interaction: grab a handle (rectangle corner) or vertex of the already-
+     * selected region first; otherwise select the topmost region under the cursor and drag its body.
+     */
+    private beginManipulation;
+    /** Create/update the marquee rect element directly (avoids a full region redraw per move). */
+    private updateMarqueeEl;
+    /** Remove the marquee element from the SVG. */
+    private clearMarqueeEl;
+    /** Test whether a client point grabs a rectangle corner or a polygon vertex of `region`. */
+    private hitHandle;
+    /** Apply the live drag for the active manipulation (image coords `ix,iy`). */
+    private applyManipulation;
+    /** addpoint mode: insert a vertex on the selected polygon's nearest edge at the click. */
+    private handleAddPoint;
+    /** deletepoint mode: remove the selected polygon's vertex nearest the click. */
+    private handleDeletePoint;
+    /** Distance from point (px,py) to segment (ax,ay)-(bx,by), in image units. */
+    private pointSegDist;
+    /** Finalize a rubber-band marquee: select every region whose bounding box it overlaps (a tiny
+     *  marquee is treated as a click on empty space → clear the selection). */
+    private finishMarquee;
+    /** A region's bounding box in image coords (rectangle, polygon, or multipolygon), or null. */
+    private regionBBox;
+    private commitRectangle;
+    private commitPolygon;
+    private hitTest;
+    redraw(): void;
+    /** Draw a region's classification label at its top-left, when labels are enabled (matches OSD). */
+    private drawLabel;
+    /** Draw grab handles for the selected region: rectangle corners or polygon vertices. */
+    private drawHandles;
+    /** Draw one bezier control point (anchor + handle offset) as a small circle connected to its
+     *  anchor by a tangent line. `handle` is the [dx,dy] offset from the anchor in image space. */
+    private drawBezierHandle;
+    private buildRegionEl;
+    /** Path data for a polygon: the exterior ring (bezier or straight) plus any holes (bezier when
+     *  the donut carries hole handles, else straight) as sub-paths — even-odd fill cuts them out. */
+    private polygonPathData;
+    /** SVG path data for a straight ring/polyline in image coords (closed appends `Z`). */
+    private straightPath;
+    /** SVG cubic-bezier path data for any ring (exterior or hole): anchors joined by cubic segments
+     *  whose control points are `anchor + handleOut` (leaving) and `nextAnchor + handleIn` (arriving),
+     *  in image space. Used for both the exterior and (donut) hole rings. */
+    private ringBezierPath;
+    private style;
+    /** Draw the in-progress rectangle / path preview. */
+    private drawDraft;
+    private styleDraft;
+}
+export {};