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

package/lib/intensity-inset/intensity-inset.component.d.ts

@@ -0,0 +1,58 @@
+import { ChangeDetectorRef, DestroyRef, NgZone, OnDestroy, OnInit } from '@angular/core';
+import { IImageInfo } from '../contracts/image.contract';
+import { IVisualizer } from '../contracts/visualizer.contract';
+import { Region } from '../models/region';
+import { FloatingPos } from '../visualizer/floating-drag.directive';
+import * as i0 from "@angular/core";
+/**
+ * The floating, draggable intensity-profile inset: shown while any intensity line
+ * exists, charting one trace per line as lines are added, moved or removed.
+ *
+ * Owns the profile and viewport-change subscriptions, the window-resize reflow, the
+ * drag and the per-instance chart div id it is given. The chart itself is drawn by the
+ * backend (`IVisualizer.renderIntensityInset`) so this never reaches a charting
+ * library. Fixed to the viewport, outside the plot div, so it is not clipped to the
+ * canvas.
+ *
+ * OnPush, with its view state in signals: the profile stream may fire outside the zone.
+ */
+export declare class IntensityInsetComponent implements OnInit, OnDestroy {
+    private readonly visualizer;
+    private readonly cdr;
+    private readonly zone;
+    private readonly destroyRef;
+    /** Id of the chart div — unique per viewer: the backend resolves it by id. */
+    divId: string;
+    /** Id of the viewer's plot div: the inset parks near its top-right corner. */
+    plotDivName: string;
+    /** The displayed slice, re-sampled at when the view settles. */
+    zIndex: number;
+    /** The Image view (OSD), whose line sampling is fed from preview frames. */
+    imageView: boolean;
+    /** The image shown (the Image view samples its lines from it). */
+    imageInfo: IImageInfo | undefined;
+    /** True whenever any intensity-profile line exists (whatever the plot type). */
+    protected readonly hasProfiles: import("@angular/core").WritableSignal<boolean>;
+    protected readonly pos: import("@angular/core").WritableSignal<FloatingPos>;
+    /** Where a header drag starts from. */
+    protected readonly dragOrigin: () => FloatingPos;
+    private profiles;
+    private readonly onResize;
+    constructor(visualizer: IVisualizer, cdr: ChangeDetectorRef, zone: NgZone, destroyRef: DestroyRef);
+    ngOnInit(): void;
+    /** Removes the window resize listener; the streams end through `takeUntilDestroyed`. */
+    ngOnDestroy(): void;
+    /** The canvas was resized: reflow the chart a tick later, once the panel has settled. */
+    reflow(): void;
+    /** A slice was committed: keep the lines sampled from it (Image view). */
+    sliceCommitted(z: number): void;
+    /**
+     * Add another line ROI (next bright colour) and select it on the active backend so
+     * it is ready to move or delete. The first line parks the inset near the plot's
+     * top-right. Resolves the new line, or null when no image extent is known yet.
+     */
+    addProfileLine(): Promise<Region | null>;
+    private render;
+    static ɵfac: i0.ɵɵFactoryDeclaration<IntensityInsetComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<IntensityInsetComponent, "viz-intensity-inset", never, { "divId": { "alias": "divId"; "required": false; }; "plotDivName": { "alias": "plotDivName"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "imageView": { "alias": "imageView"; "required": false; }; "imageInfo": { "alias": "imageInfo"; "required": false; }; }, {}, never, never, true, never>;
+}

package/lib/models/bezier.d.ts

@@ -52,8 +52,3 @@ export declare function resolveHandles(xs: number[], ys: number[], closed: boole
  * closed ring returns to its first point.
  */
 export declare function bezierCurveFromHandles(xs: number[], ys: number[], handles: AnchorHandle[], closed: boolean): CurvePoints;
-/**
- * Flatten the smooth Catmull-Rom bezier through the anchors (no custom handles).
- * Falls back to the anchors when there are too few to form a curve.
- */
-export declare function bezierCurve(xs: number[], ys: number[], closed: boolean): CurvePoints;

package/lib/models/class-preset.d.ts

@@ -5,7 +5,12 @@
  * The `PresetSet` is the per-user, server-persisted source of truth for region colours;
  * see `class-color.util.ts` for the deterministic colour-resolution engine.
  */
+/** Where a preset class came from: added by the user, one of the built-in
+ *  defaults, or auto-promoted from an unknown region label. */
 export type PresetSource = 'user' | 'default' | 'auto';
+/** One annotation class and its colour: regions whose `label` matches
+ *  `name` (per the set's {@link MatchMode}) draw in `color` unless their colour
+ *  was overridden by hand. */
 export interface ClassPreset {
     /** The class name — matched against `Region.label`. */
     name: string;
@@ -16,7 +21,14 @@ export interface ClassPreset {
     /** Provenance; `'auto'` = added by opt-in fallback promotion. */
     source?: PresetSource;
 }
+/** How a region label is matched to a preset name: `'exact'` compares the
+ *  strings as is; `'normalized'` trims and lower-cases both first. */
 export type MatchMode = 'exact' | 'normalized';
+/**
+ * The per-user class-colour configuration (server-persisted through the
+ * preferences port): the preset classes, the palette for labels outside them,
+ * and the matching rules. Resolved into region colours by `class-color.util.ts`.
+ */
 export interface PresetSet {
     /** Ordered list of preset classes. */
     classes: ClassPreset[];
@@ -37,3 +49,9 @@ export declare const DEFAULT_FALLBACK_PALETTE: string[];
 export declare function defaultPresetSet(): PresetSet;
 /** True when the set has no usable classes (e.g. the server returned an empty/blank record). */
 export declare function isEmptyPresetSet(set: PresetSet | null | undefined): boolean;
+/**
+ * Validate an untrusted value (e.g. an imported JSON file) as a preset set.
+ * Returns a clean copy — only well-formed `{ name, color }` classes, defaults
+ * for missing optional fields — or null when it has no usable classes.
+ */
+export declare function parsePresetSet(value: unknown): PresetSet | null;

package/lib/models/geometry.d.ts

@@ -1,66 +1,32 @@
 /**
- * Pure geometry helpers extracted from PlotlyService.
+ * Pure SVG-path helpers (build and parse a vertex ring as a Plotly path).
  *
- * No DOM access, no service state, no `this` — every function is testable
- * in isolation. Keep it that way: this module is the dumping ground for
- * shape/mask/SVG-path utilities the wand, vertex eraser, and region editor
- * share. If a helper grows a `this.shapes` reference, it doesn't belong here.
+ * No DOM access, no service state, no `this`. Mask and ring geometry (the
+ * rasterizer, mask set operations, point-in-ring, simplification, contour
+ * tracing) lives in `src/lib/geometry/`.
  */
-/** A bbox-relative binary mask (1 = filled, 0 = empty). */
-export interface BBoxMask {
-    bx: number;
-    by: number;
-    bw: number;
-    bh: number;
-    mask: Uint8Array;
-}
 /** Parsed single-subpath polygon vertices. */
 export interface PolygonVertices {
     xpoints: number[];
     ypoints: number[];
 }
 /**
- * Parse a single-subpath `M x,y L x,y ... Z` path into vertex arrays.
+ * Split a single-subpath `M x,y L x,y ... [Z]` path into vertex arrays, plus
+ * whether it is closed (ends in `Z`). No validation: a coordinate that doesn't
+ * parse comes back as NaN. See {@link parseSvgPathPolygon} for the checked form.
+ */
+export declare function parseSvgPath(path: string): PolygonVertices & {
+    closed: boolean;
+};
+/**
+ * Parse a single-subpath `M x,y L x,y ... [Z]` path into vertex arrays.
  *
  * Returns null for paths we can't safely round-trip (multi-subpath, curves,
- * fewer than three vertices). The wand only adopts shapes it produced or
- * that Plotly's drawclosedpath produces, both of which are single-subpath
- * polygons.
+ * non-numeric coordinates, fewer than three vertices).
  */
 export declare function parseSvgPathPolygon(path: string): PolygonVertices | null;
-/**
- * Build a closed SVG path string `M x,y L x,y L ... Z` from vertex arrays.
- * Returns '' for fewer than three vertices (degenerate).
- */
-export declare function polygonToSvgPath(xpoints: number[], ypoints: number[]): string;
 /**
  * Build an SVG path string from vertex arrays. Closed polygons end with `Z`,
  * open polylines do not. Returns '' for fewer than two vertices (degenerate).
  */
 export declare function verticesToSvgPath(xs: number[], ys: number[], closed: boolean): string;
-/**
- * Compare two Plotly shape objects for "same region" — used by the wand to
- * avoid appending duplicates when the user pushes the same find result more
- * than once. Polygons compare by SVG path string, rectangles compare by
- * (x0, y0, x1, y1).
- */
-export declare function shapesEqual(a: any, b: any): boolean;
-/** Returns true if the two bbox-relative masks share at least one set pixel. */
-export declare function masksOverlap(a: BBoxMask, b: BBoxMask): boolean;
-/**
- * Allocate a fresh accumulator covering both masks and OR them in. The
- * resulting mask's bbox is the smallest rectangle containing both inputs.
- */
-export declare function unionMasks(a: BBoxMask, b: BBoxMask): BBoxMask;
-/**
- * Simplify a closed ring with the Douglas–Peucker algorithm (jit-ui#85):
- * drop every vertex that lies within `epsilon` pixels (the "altitude
- * threshold") of the line between its kept neighbours. Anchored at vertex 0
- * (the ring is closed by appending it). Rings of ≤ 3 vertices, or a
- * non-positive epsilon, are returned unchanged. Output keeps the closed-ring
- * convention (no repeated closing point).
- */
-export declare function simplifyRing(xs: number[], ys: number[], epsilon: number): {
-    xs: number[];
-    ys: number[];
-};

package/lib/models/polygon-edit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Copy-on-write polygon edits (review RT-13, RegionStore split "polygon-edit").
+ *
+ * Every function takes a polygon and returns a NEW {@link Polygon} with the
+ * edit applied — or null when the edit does not apply (an index out of range,
+ * a vertex delete that would degenerate the ring, …), so a caller can skip its
+ * undo step. The input is never mutated: arrays the edit does not touch are
+ * shared with it (structural sharing), arrays it does touch are copied. That
+ * is what lets `RegionStore` keep shallow undo snapshots instead of deep
+ * clones: an instance in a snapshot is never changed after the fact.
+ *
+ * Pure: no DOM, no store. Coordinates are image pixels; bézier handle offsets
+ * are relative to their anchor, as on {@link Polygon}.
+ */
+import { MultiPolygon, Polygon, Rectangle } from './region';
+/** Move exterior vertex `index` to (x, y). Null when `index` is out of range. */
+export declare function moveVertex(p: Polygon, index: number, x: number, y: number): Polygon | null;
+/**
+ * Insert a vertex at (x, y) after `segIndex` (the start vertex of the edge),
+ * clamped to the ring. A bézier polygon with stored handles gives the new
+ * vertex smooth handles from its neighbours and keeps the others' (possibly
+ * hand-edited) handles.
+ */
+export declare function addVertex(p: Polygon, segIndex: number, x: number, y: number): Polygon;
+/**
+ * Delete exterior vertex `index`. Null when out of range, or when it would
+ * leave fewer than 3 vertices (2 for an open polyline).
+ */
+export declare function deleteVertex(p: Polygon, index: number): Polygon | null;
+/** Move vertex `index` of hole `holeIndex` to (x, y). Null when either is out of range. */
+export declare function moveHoleVertex(p: Polygon, holeIndex: number, index: number, x: number, y: number): Polygon | null;
+/**
+ * Insert a vertex at (x, y) on hole `holeIndex`, after `segIndex`. A bézier
+ * polygon re-seeds its hole handles so they stay parallel to the rings. Null
+ * for an out-of-range hole.
+ */
+export declare function addHoleVertex(p: Polygon, holeIndex: number, segIndex: number, x: number, y: number): Polygon | null;
+/**
+ * Delete vertex `index` of hole `holeIndex`. Taking a ring below 3 vertices
+ * drops the whole hole (it would bound no area). Null when out of range.
+ */
+export declare function deleteHoleVertex(p: Polygon, holeIndex: number, index: number): Polygon | null;
+/**
+ * Per-hole bézier handles seeded from the Catmull-Rom default, parallel to
+ * `holes` (both undefined without holes).
+ */
+export declare function seededHoleHandles(holes: number[][][] | undefined): Pick<Polygon, 'holeHandlesIn' | 'holeHandlesOut'>;
+/**
+ * Turn bézier on — seeding editable handles (holes included) from the smooth
+ * default — or off, dropping every handle. The anchors never move. Null when
+ * the polygon is already in that state.
+ */
+export declare function setBezier(p: Polygon, bezier: boolean): Polygon | null;
+/**
+ * Move the `side` control point of exterior vertex `index` to the absolute
+ * point (x, y). Handles missing from a bézier polygon are seeded from the
+ * default first. Null for a non-bézier polygon or an out-of-range index.
+ */
+export declare function moveBezierHandle(p: Polygon, index: number, side: 'in' | 'out', x: number, y: number): Polygon | null;
+/**
+ * Move the `side` control point of vertex `index` on hole `holeIndex` to the
+ * absolute point (x, y), seeding the hole handles first when missing. Null for
+ * a non-bézier polygon or an out-of-range hole/index.
+ */
+export declare function moveHoleBezierHandle(p: Polygon, holeIndex: number, index: number, side: 'in' | 'out', x: number, y: number): Polygon | null;
+/**
+ * A polygon moved by (dx, dy): its vertices and holes (bézier offsets are
+ * relative, so they carry over). `round` snaps the moved coordinates.
+ */
+export declare function translatePolygon(p: Polygon, dx: number, dy: number, round?: (v: number) => number): Polygon;
+/** Any region geometry moved by (dx, dy) (see {@link translatePolygon}). */
+export declare function translateBounds(b: Rectangle | Polygon | MultiPolygon, dx: number, dy: number, round?: (v: number) => number): Rectangle | Polygon | MultiPolygon;

package/lib/models/polygon-factory.d.ts

@@ -0,0 +1,40 @@
+import { MultiPolygon, Polygon, Rectangle, Region } from './region';
+/**
+ * Polygon / Region construction and cloning in one place, so callers stop
+ * hand-filling `npoints`, `xpoints`, `ypoints`, `coordinates` and `closed`
+ * (three redundant views of one ring that every mutator must keep in sync).
+ */
+/** Options for {@link makePolygon}. */
+export interface MakePolygonOptions {
+    /** false for an open polyline; default true. */
+    closed?: boolean;
+    /** Interior rings; omitted when absent or empty. */
+    holes?: number[][][];
+    bezier?: boolean;
+}
+/** A Polygon over the given vertex arrays (taken by reference). */
+export declare function makePolygon(xs: number[], ys: number[], opts?: MakePolygonOptions): Polygon;
+/** The four corners of a rectangle as a closed ring (clockwise from top-left). */
+export declare function rectToRing(r: Pick<Rectangle, 'x' | 'y' | 'width' | 'height'>): {
+    xs: number[];
+    ys: number[];
+};
+/** A deep copy of a polygon: vertices, holes and every bézier handle. */
+export declare function clonePolygon(p: Polygon): Polygon;
+/** A deep copy of any region geometry. */
+export declare function cloneBounds(bounds: Rectangle | Polygon | MultiPolygon): Rectangle | Polygon | MultiPolygon;
+/**
+ * A copy of `existing` (id, name, label, colour, colour override, source,
+ * file name, kind, z, …) with new geometry and optional extra fields. Use it
+ * whenever a tool edits a region's shape, so the edit never drops metadata and
+ * never mutates the store's instance.
+ */
+export declare function replaceBounds(existing: Region, bounds: Region['bounds'], patch?: Partial<Region>): Region;
+/**
+ * The closed polygons a region covers, for image-processing consumers (crop,
+ * segmentation requests): a rectangle's four corners, a closed polygon with its
+ * holes (a bézier region as its flattened curve), one polygon per part of a
+ * multi-polygon. Open polylines cover no area and yield nothing. Coordinates
+ * are rounded to whole pixels.
+ */
+export declare function regionPolygons(region: Region): Polygon[];

package/lib/models/region-clone.d.ts

@@ -0,0 +1,20 @@
+import { Polygon, Region } from './region';
+/**
+ * Copy-on-write region copies and geometry equality (RT-13). Stored regions
+ * are shared with the undo history, so a change is always a copy; these
+ * helpers return the input unchanged when the patch would not change it.
+ * (Deep geometry copies are `cloneBounds` / `clonePolygon` in `polygon-factory`.)
+ */
+/** A shallow copy of `r` with `patch` applied; `r` itself is never changed. */
+export declare function withRegionPatch(r: Region, patch: Partial<Region>): Region;
+/** `r` tagged with slice `z`: itself when it already is, else a copy. */
+export declare function withRegionZ(r: Region, z: number): Region;
+/**
+ * True when two regions have the same geometry: equal rectangles, or polygons
+ * (each part of a multi-polygon, in order) with the same vertices, open/closed
+ * state and holes. Bézier handles, labels and colours are not compared. Mixed
+ * kinds are never equal.
+ */
+export declare function regionsEqual(a: Region, b: Region): boolean;
+/** Same vertices, open/closed state and holes (see {@link regionsEqual}). */
+export declare function polygonsEqual(pa: Polygon, pb: Polygon): boolean;

package/lib/models/region-geojson.d.ts

@@ -0,0 +1,17 @@
+import { Region } from './region';
+/**
+ * Parse a GeoJSON FeatureCollection string (QuPath-compatible) into regions.
+ * Throws on invalid JSON, a missing `features` key, or a feature without
+ * coordinates.
+ */
+export declare function regionsFromGeoJson(geoJsonStr: string): Region[];
+/**
+ * Serialise regions as a GeoJSON FeatureCollection string (QuPath-compatible),
+ * leaving out intensity-profile lines.
+ */
+export declare function regionsToGeoJson(rois: readonly Region[]): string;
+/**
+ * Download a GeoJSON string as `<baseName without extension>.geojson`
+ * (`rois.geojson` without a base name).
+ */
+export declare function downloadGeoJson(jsonString: string, baseName?: string): void;

package/lib/models/region.d.ts

@@ -1,9 +1,20 @@
 import { ShapeSelection } from './shape';
+/**
+ * One annotation region — the backend-neutral model every renderer (Plotly,
+ * OpenSeadragon, napari-js), the RegionStore, the Region Editor and the
+ * GeoJSON/QuPath import/export share.
+ *
+ * Geometry lives in {@link bounds}, in full-resolution image-pixel
+ * coordinates (x right, y down) of slice {@link z}. A region with no bounds
+ * (`null`/absent) is kept but draws nowhere. Regions that arrive as JSON are
+ * rebuilt into class instances by {@link hydrateBounds} on their way into the
+ * store, so `bounds instanceof Rectangle` etc. can be relied on downstream.
+ */
 export declare class Region {
-    /** Stable, unique identity for selection and equality. Minted by
-     *  PlotlyService when a region first enters the system. Never derived
-     *  from array index — name collisions across delete/add cycles must
-     *  not break PrimeNG row selection. */
+    /** Stable, unique identity for selection and equality. Minted by the
+     *  RegionStore when a region first enters it. Never derived from array
+     *  index — name collisions across delete/add cycles must not break PrimeNG
+     *  row selection. */
     id: number;
     name: string;
     bounds?: Rectangle | Polygon | MultiPolygon | null;
@@ -37,6 +48,7 @@ export declare class Region {
      *  or a region drawn without a slice context (jit-ui#93). */
     z: number;
     shapeColor?: string | undefined;
+    /** @deprecated Unused by the library; will be removed in the next minor release. */
     bytesPerPixel: number;
     /**
      * resolution is the resolution at which the region
@@ -49,13 +61,19 @@ export declare class Region {
      * at resolution = 0
      */
     resolution: number;
+    /** @deprecated Unused by the library; will be removed in the next minor release. */
     cropped: boolean;
+    /** @deprecated Unused by the library; will be removed in the next minor release. */
     tileNumber: number;
     tileCoordinates: number[] | null;
     /** True for intensity-profile line ROIs (the intensity tool's lines). These are
      *  NOT annotation regions: they never appear in the Region Editor and editor
      *  operations (select/save/delete) must never touch them. */
     isProfile(): boolean;
+    /**
+     * A debug string: the rectangle's box, or the polygon's SVG path.
+     * @deprecated Unused by the library; will be removed in the next minor release.
+     */
     toString(): string;
     /**
      * Returns a ShapeSelection object that can be used to
@@ -67,12 +85,23 @@ export declare class Region {
     isRectangle(bnds: any): bnds is Rectangle;
     isPolygon(bnds: any): bnds is Polygon;
 }
+/** An axis-aligned box in image-pixel coordinates: (`x`, `y`) is the top-left
+ *  (minimum) corner, `width`/`height` extend right/down. */
 export declare class Rectangle {
     x: number;
     y: number;
     width: number;
     height: number;
 }
+/**
+ * A polygon or open polyline in image-pixel coordinates, optionally with holes
+ * and smoothed into a bézier curve.
+ *
+ * The vertices are stored twice and must agree: as the parallel `xpoints` /
+ * `ypoints` arrays (length `npoints`; the Java/JIT wire shape) and as
+ * `coordinates` `[x, y]` pairs (what GeoJSON export reads). The ring is
+ * implicitly closed — the first vertex is not repeated at the end.
+ */
 export declare class Polygon {
     npoints: number;
     xpoints: number[];
@@ -132,6 +161,13 @@ export declare class MultiPolygon {
     /** One or more disjoint closed polygons (each may have holes). */
     polygons: Polygon[];
 }
+/**
+ * A region's geometry as a host may supply it: a {@link Rectangle} or
+ * {@link Polygon} instance, or a plain object with the same fields (e.g. parsed
+ * JSON, possibly with only some of them). Image-pixel coordinates. Plain objects
+ * become class instances via {@link hydrateBounds} when they enter the store;
+ * {@link Region.bounds} itself is always an instance (or a {@link MultiPolygon}).
+ */
 export type Bounds = Rectangle | Polygon | {
     x?: number;
     y?: number;

package/lib/models/shape.d.ts

@@ -1,5 +1,13 @@
 import { Region } from './region';
 import { Datum, Font, Shape, ShapeLabel, ShapeLine, XAxisName, YAxisName } from 'plotly.js-dist-min';
+/**
+ * A {@link Region} projected to a Plotly layout shape (`rect` or SVG `path`),
+ * carrying the region's identity, class label and file name along so it
+ * round-trips through Plotly's relayout. Coordinates are the plot's data
+ * coordinates, which are the region's image pixels. Built by
+ * {@link Region.getShape}; {@link getRegion} converts back (only `rect` and
+ * `path` shapes — anything else throws).
+ */
 export declare class ShapeSelection implements Shape {
     /** Stable, unique identity carried alongside the shape so it round-trips
      *  through Plotly's relayout untouched. Plotly preserves unknown

package/lib/plot-mode/contribution-host.d.ts

@@ -0,0 +1,125 @@
+import { Injector, NgZone, Type } from '@angular/core';
+import { Observable } from 'rxjs';
+import { Message } from 'primeng/api';
+import { IImageInfo } from '../contracts/image.contract';
+import { PlotType, PlotTypeId } from '../contracts/plot-type';
+import { PlotModeTools, PlotTypeContribution } from '../contracts/plot-type-contribution.contract';
+import { ToolbarContribution, ToolbarDialogToolContribution } from '../contracts/toolbar-tool.contract';
+import { IVisualizer } from '../contracts/visualizer.contract';
+import { PlotModeController } from './plot-mode-controller';
+/** The live contributed mode's side panel, as the template renders it. */
+export interface PlotModePanelView {
+    title: string;
+    /** An Angular component panel, with its own injector… */
+    component: Type<unknown> | null;
+    injector: Injector | null;
+    /** …or a plain host element a `mount` panel rendered into. */
+    host: HTMLElement | null;
+}
+/** The open dialog tool's dialog, as the template renders it. */
+export interface ToolDialogView {
+    title: string;
+    width: string;
+    host: HTMLElement;
+}
+/** What the contributions need from the viewer that hosts them. */
+export interface ContributionViewer {
+    readonly visualizer: IVisualizer;
+    readonly zone: NgZone;
+    /** The toolbar tools a contribution may arm (`PlotModeContext.tools`). */
+    readonly tools: PlotModeTools;
+    /** Parent of a component panel's injector. */
+    readonly injector?: Injector;
+    imageInfo$(): Observable<IImageInfo | null>;
+    /** The selector's id (a built-in type or a contributed mode). */
+    selectedId(): PlotTypeId;
+    /** The built-in type being rendered. */
+    renderedType(): PlotType;
+    /** A contributed mode could not start: select its base type, already on screen. */
+    selectBase(type: PlotType): void;
+    notify(message: Message): void;
+    detectChanges(): void;
+}
+/**
+ * Hosts the library's two kinds of contributed sessions over the viewer:
+ *  - **plot modes** (`PLOT_TYPE_CONTRIBUTIONS`): a selector entry riding on a built-in
+ *    base type, with an optional side panel;
+ *  - **dialog tools** (`TOOLBAR_TOOLS`, `kind: 'dialog'`): a floating dialog over the
+ *    Image view, whose body the tool mounts once the dialog is in the document.
+ *
+ * Both run through a {@link PlotModeController} (one live session each, isolated from
+ * a failing contribution). A session is bound to the base view it drew over, so it
+ * ends before anything else draws ({@link endSessions}) and restarts once the next
+ * render has landed ({@link activate}).
+ */
+export declare class ContributionHost {
+    private readonly viewer;
+    readonly plotModes: PlotModeController;
+    readonly toolDialogs: PlotModeController;
+    /** Dialog tools, sorted; their buttons show in the Image view only. */
+    readonly dialogTools: ToolbarDialogToolContribution[];
+    /** The live mode's panel; null while no contributed session is live. */
+    plotModePanel: PlotModePanelView | null;
+    /** The open dialog tool's live dialog. */
+    toolDialog: ToolDialogView | null;
+    /** The dialog tool the user has open (its session may be between renders). */
+    openDialogToolId: string | null;
+    private destroying;
+    /** The live dialog body's teardown, and a pending wait for its host to connect. */
+    private toolDialogTeardown;
+    private toolDialogFrame;
+    constructor(plotTypeContributions: readonly PlotTypeContribution[] | null | undefined, toolContributions: readonly ToolbarContribution[] | null | undefined, viewer: ContributionViewer);
+    /** End both sessions: the view they drew over is about to go. An open dialog tool
+     *  stays open and restarts on the next {@link activate}. */
+    endSessions(): void;
+    /** A render landed: start the selected mode's session and the open dialog tool's. */
+    activate(): void;
+    /** The viewer is being destroyed: end both sessions without touching its view. */
+    destroy(): void;
+    /** The toolbar button: open the tool's dialog, or close it if it is open. */
+    toggleDialogTool(id: string): void;
+    /** Close the open dialog tool: its body is torn down, then its session ends. */
+    closeDialogTool(): void;
+    /** Attach a `mount` panel's host element once the panel dialog renders its slot. */
+    attachPanelSlot(slot: HTMLElement | undefined): void;
+    /** Attach the open dialog tool's host element once its dialog renders its slot. */
+    attachToolDialogSlot(slot: HTMLElement | undefined): void;
+    /**
+     * Start the selected contributed mode's session, once its base view has plotted.
+     * No-op for a built-in type, or when the base on screen is not the one the mode
+     * rides on. A backend that cannot provide a viewport for it (e.g. OSD fell back to
+     * Plotly) counts as a failed activation.
+     */
+    private activateSelectedPlotMode;
+    /** Start (or restart, after a re-render) the open dialog tool's session. */
+    private activateOpenDialogTool;
+    /** A session's context over the backend on screen, or null when it has no viewport. */
+    private context;
+    /** Render the live mode's panel. Activation can resolve outside Angular (an OSD
+     *  callback, a contribution's own promise), hence the zone re-entry. */
+    private showPlotModePanel;
+    /** Drop the panel (destroying a component panel) before the session ends. */
+    private hidePlotModePanel;
+    /** A contributed mode could not start. Its base type is already on screen — the base
+     *  plotted first — so just select it: nothing needs to re-plot. */
+    private fallBackFromPlotMode;
+    /**
+     * The dialog-tool session is live: render the dialog, then mount the tool's body
+     * once the host element is in the document, so `mount()` can measure it and start
+     * widgets that need a connected element.
+     */
+    private showToolDialog;
+    /**
+     * Mount `tool`'s body into `host` once it is connected (the dialog may attach it a
+     * frame later, when it moves itself to `<body>`). If it never connects within
+     * {@link TOOL_DIALOG_ATTACH_FRAMES} it is mounted anyway, with a warning, rather than
+     * leaving an empty dialog. A throwing `mount()` fails the session like a failed start.
+     */
+    private mountToolDialogBody;
+    /** The dialog-tool session is about to end: tear the body down first, then drop the dialog. */
+    private hideToolDialog;
+    /** A dialog tool could not start: close it and say so. */
+    private dialogToolFailed;
+    /** Run change detection; returns what it threw (logged), or null. */
+    private detectChangesSafely;
+}

package/lib/plot-mode/plot-type-menu.d.ts

@@ -0,0 +1,60 @@
+import { ViewerCapabilities } from '../contracts/capabilities.contract';
+import { IImageInfo } from '../contracts/image.contract';
+import { PlotTypeDescriptor, PlotTypeId } from '../contracts/plot-type';
+import { ContributedPlotTypeDescriptor, PlotTypeOption } from '../contracts/plot-type-contribution.contract';
+/** What a spatial-omics dataset on offer contributes to the plot-type gates. */
+export interface SpatialGates {
+    /** A dataset is published on `SPATIAL_DATA_PORT`. */
+    hasDataset: boolean;
+    /** Its observations carry a z, so it can be drawn as a 3D cloud. */
+    has3d: boolean;
+    /** It brings pixels of its own: a tissue image it registers onto, or a volume
+     *  published as a z-stack image. */
+    hasPixels: boolean;
+}
+/** Everything {@link computePlotTypeMenu} gates on. */
+export interface PlotTypeMenuInput {
+    /** The built-in types the backend advertises. */
+    descriptors: PlotTypeDescriptor[];
+    /** Contributed plot modes (`PLOT_TYPE_CONTRIBUTIONS`). */
+    contributions: ContributedPlotTypeDescriptor[];
+    caps: ViewerCapabilities;
+    imageInfo: IImageInfo | undefined;
+    spatial: SpatialGates;
+    /** Offer every backend's type under its full label, not just the curated set. */
+    testMode: boolean;
+}
+/** The selector's entries: {@link builtIn} then the contributed modes. */
+export interface PlotTypeMenu {
+    builtIn: PlotTypeDescriptor[];
+    menu: PlotTypeOption[];
+}
+/**
+ * Plot types offered in the selector for the current image:
+ *  - Outside **test mode**, only the curated default set (descriptors with a
+ *    `productionLabel`) is offered, shown under suffix-free names — Image,
+ *    Heatmap, Contour and the napari Surface / Volume / Isosurface. Test mode
+ *    exposes every backend's type under its full (backend-suffixed) label.
+ *  - 3D types hidden when the backend can't render a 3D scene.
+ *  - stack-only types (volume, isosurface) hidden unless the file is a stack —
+ *    a volume needs multiple z-slices.
+ *  - scalar-intensity types (contour, surface, isosurface) hidden for RGB
+ *    images — they map a single intensity per pixel. Image and Heatmap render
+ *    any image. A multichannel image's bands are each scalar, so it passes.
+ *  - spatial-omics types hidden until a `SpatialDataset` is published on
+ *    `SPATIAL_DATA_PORT` — the mode has nothing to draw without observations,
+ *    exactly as a volume has nothing to draw without a stack.
+ *  - image-sourced types hidden while a dataset that brings no pixels is up.
+ *
+ * Contributed modes come after every built-in one, under the same label rule and
+ * their own stack/grayscale/spatial gates; a mode also needs whatever its base view
+ * needs, so the base type's gates apply too.
+ */
+export declare function computePlotTypeMenu(input: PlotTypeMenuInput): PlotTypeMenu;
+/**
+ * The type to fall back to when `selected` is no longer offered — Image when it is
+ * on offer, else the first type still offered — or null when `selected` is still
+ * offered (or nothing is). With no image loaded the pixel modes are gone, and falling
+ * back to Image would select a mode the selector does not list and nothing can draw.
+ */
+export declare function reconcilePlotType(menu: PlotTypeOption[], selected: PlotTypeId): PlotTypeId | null;