@jax-data-science/sci-image-visualizer 0.4.0 → 0.6.0

package/index.d.ts

@@ -19,6 +19,7 @@ export * from './lib/contracts/image.contract';
 export * from './lib/contracts/plot-type';
 export * from './lib/contracts/toolbar-config';
 export * from './lib/contracts/toolbar-tool.contract';
+export * from './lib/contracts/plot-type-contribution.contract';
 export * from './lib/contracts/capabilities.contract';
 export * from './lib/contracts/region-overlay.contract';
 export * from './lib/contracts/display-types';

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

@@ -38,6 +38,16 @@ export interface IWandOptions {
 export interface IBrushOptions {
     /** Brush diameter in matrix (image) pixels. */
     size?: number;
+    /**
+     * Paint as one class: new regions take this label, and a stroke only extends
+     * or merges regions with the same label. Unset = the plain brush (label
+     * `'Region'`, extends any region). `setBrushMode(true, …)` sets the class in
+     * full; `setBrushOptions` changes it only when `label` or `color` is passed,
+     * so a size-only update keeps it.
+     */
+    label?: string;
+    /** Colour for the painted regions instead of the shape colour. Kept against preset re-apply. */
+    color?: string;
 }
 /** What drives point colour in the spatial-omics mode: an annotation column
  *  from the dataset, or one feature (gene) vector fetched on demand. */

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

@@ -0,0 +1,199 @@
+/**
+ * How a plot mode gets into the plot-type selector without this library knowing
+ * what it is.
+ *
+ * A package contributes a mode by providing a {@link PlotTypeContribution} on the
+ * {@link PLOT_TYPE_CONTRIBUTIONS} multi-provider token, the same way
+ * `TOOLBAR_TOOLS` contributes toolbar tools. Nothing registers at import time:
+ * installing a package makes a mode available, and adding its provider turns it
+ * on. A plain object works, so the contributing package needs no Angular
+ * compiler and no decorators:
+ *
+ *     { provide: PLOT_TYPE_CONTRIBUTIONS, useValue: myContribution, multi: true }
+ *     { provide: PLOT_TYPE_CONTRIBUTIONS, useFactory: () => makeContribution(), multi: true }
+ *
+ * Provide nothing and the selector, the render path and the panel area behave
+ * exactly as they did before this extension point existed.
+ *
+ * WHY A CONTRIBUTED MODE RIDES ON A BUILT-IN ONE
+ * A contributed mode does not bring a renderer. It names a built-in
+ * {@link ContributedPlotTypeDescriptor.baseType} — in v1 only `PlotType.IMAGE`,
+ * the OpenSeadragon view — and the visualizer plots exactly as if that type had
+ * been selected: same backend, same toolbar, same region tools, same wheel
+ * handling. The contribution then draws over it through the
+ * {@link PlotModeViewport} and talks to the viewer through the public
+ * {@link IVisualizer}. That keeps every rendering decision in one place and means
+ * a contribution can never be half-supported by some code path that switches on
+ * the plot type.
+ *
+ * WHAT THE VISUALIZER GUARANTEES
+ *  1. Contributed descriptors are appended after the built-in ones and curated by
+ *     the same `productionLabel` / test-mode / `requires*` rules.
+ *  2. Selecting one plots with `baseType`'s backend, then calls `activate(ctx)`
+ *     once the viewport is ready.
+ *  3. Leaving the mode — another type, an image switch (or any re-render of the
+ *     base view), or the visualizer being destroyed — calls `session.deactivate()`
+ *     exactly once, before the next mode draws. If the mode is still selected
+ *     when the new image has plotted, a fresh session is activated for it.
+ *  4. `panel` is shown only while a session is live.
+ *  5. A thrown error or rejected promise from `activate`, `deactivate`, `mount`
+ *     or a mount's teardown is caught and logged; none escapes, so a contribution
+ *     cannot break the viewer. Failing to start (`activate`, `mount`, or a panel
+ *     component throwing while it is created / first rendered) falls back
+ *     to `baseType`. Failing to clean up falls back when that same mode is being
+ *     re-activated (base re-render, image switch) — immediately if it already is
+ *     live again — and is only logged when the user has moved to another mode; the
+ *     user explicitly selecting it again gets a fresh attempt.
+ *  6. {@link PLOT_TYPE_CONTRIBUTIONS} has no factory: no providers, no modes.
+ */
+import { InjectionToken, Type } from '@angular/core';
+import type { Observable } from 'rxjs';
+import type { IImageInfo } from './image.contract';
+import type { PlotType, PlotTypeDescriptor, PlotTypeId } from './plot-type';
+import type { IVisualizer } from './visualizer.contract';
+/** A rectangle in level-0 image pixels. */
+export interface PlotModeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Selector metadata for a contributed plot mode. */
+export interface ContributedPlotTypeDescriptor {
+    /** Unique id, namespaced, e.g. 'dianne'. Must not clash with PlotType values. */
+    type: string;
+    /** Test-mode label, e.g. 'Digital Pathology - DIANNE'. */
+    label: string;
+    /** Default-selector label; omit to make the mode test-only (same rule as built-ins). */
+    productionLabel?: string;
+    /** 'pi pi-…' class or asset path, same as PlotTypeDescriptor.icon. */
+    icon?: string;
+    /** Always '2d' in v1. */
+    dimensions: '2d';
+    /** Built-in type whose backend renders the base image. v1 supports PlotType.IMAGE (OSD). */
+    baseType: PlotType;
+    /** Same gates as PlotTypeDescriptor, evaluated in addition to the base type's own. */
+    requiresGrayscale?: boolean;
+    requiresStack?: boolean;
+    /** Hidden until a `SpatialDataset` is published on SPATIAL_DATA_PORT (an overlay of spatial observations). */
+    requiresSpatialData?: boolean;
+    /** Hidden unless the published dataset carries `observations.z`. */
+    requiresSpatial3d?: boolean;
+}
+/** The base view's viewport, as a contributed mode sees it. */
+export interface PlotModeViewport {
+    /** Element the mode's overlay canvas/SVG attaches to; fills the plot area. */
+    getOverlayContainer(): HTMLElement | null;
+    /** Level-0 image px -> client px, and the reverse. */
+    dataToClient(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    clientToData(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    /** Screen px per image px at the current zoom. */
+    dataLengthToScreen(len: number): number;
+    isReady(): boolean;
+    /** Visible image rect in level-0 px, emitted on every redraw frame (pan/zoom animation).
+     *  A new subscriber first receives the current rect when the viewport is ready. */
+    frame$: Observable<PlotModeRect>;
+    /** Same rect, emitted once the viewport settles (existing getViewportChange$ semantics).
+     *  A new subscriber first receives the current rect when the viewport is ready. */
+    settled$: Observable<PlotModeRect>;
+}
+/** The class a {@link PlotModeTools.armBrush} stroke paints. */
+export interface PlotModeBrushClass {
+    /** Label for the painted regions; the stroke only extends or merges regions with it. */
+    label?: string;
+    /** Colour for the painted regions (instead of the toolbar's shape colour). */
+    color?: string;
+}
+/**
+ * The visualizer's own toolbar tools, armed on a mode's behalf. Going through
+ * this rather than {@link IVisualizer} keeps the toolbar in step: the armed
+ * tool's button is highlighted and its controls (e.g. the brush size) show.
+ */
+export interface PlotModeTools {
+    /**
+     * Arm the toolbar brush, painting `brushClass`. Calling it again while the
+     * brush is armed switches class; the next stroke starts a region of it.
+     * The user picking any tool from the toolbar (including the brush) replaces
+     * this with the plain tool.
+     */
+    armBrush(brushClass?: PlotModeBrushClass): void;
+    /** Disarm whatever tool is armed, as if the user toggled it off. */
+    disarm(): void;
+    /** The armed toolbar tool id ('brush', 'pan', … or null). Replays the current value. */
+    activeTool$: Observable<string | null>;
+}
+/** Everything a contributed mode gets to work with while it is active. */
+export interface PlotModeContext {
+    /** Full public visualizer API: regions, region overlay (tool modes), undo, etc. */
+    visualizer: IVisualizer;
+    viewport: PlotModeViewport;
+    /** Current image info from IMAGE_STATE_PORT (null until an image is loaded). */
+    imageInfo$: Observable<IImageInfo | null>;
+    /** Toolbar tools (since 0.6.0). Optional so a context built for 0.5.0 still type-checks. */
+    tools?: PlotModeTools;
+}
+/** A live activation of a contributed mode. */
+export interface PlotModeSession {
+    /** Called when the user leaves the mode, the image changes, or the visualizer is destroyed. */
+    deactivate(): void;
+}
+/**
+ * The mode's side panel, shown in the visualizer's right-hand panel area while
+ * a session is live. Two forms:
+ *
+ *  - `component`: an Angular component, rendered through `NgComponentOutlet`
+ *    with {@link PLOT_MODE_CONTEXT} and {@link PLOT_MODE_SESSION} in its
+ *    injector. Needs an AOT-compiled (partial-Ivy) component.
+ *  - `mount`: framework-agnostic. The visualizer hands over an empty host
+ *    element after `activate` resolves; the function renders into it and returns
+ *    a teardown. The teardown is called exactly once when the mode deactivates,
+ *    before `session.deactivate()`, and the host element is then removed.
+ */
+export type PlotModePanel = {
+    title: string;
+    component: Type<unknown>;
+} | {
+    title: string;
+    mount(host: HTMLElement, ctx: PlotModeContext, session: PlotModeSession): () => void;
+};
+/** A plot mode contributed to the selector. A plain object is enough. */
+export interface PlotTypeContribution {
+    descriptor: ContributedPlotTypeDescriptor;
+    /** Called after the base backend has plotted the image in this mode. */
+    activate(ctx: PlotModeContext): PlotModeSession | Promise<PlotModeSession>;
+    /**
+     * Optional side panel, rendered in the visualizer's right-hand panel area while the
+     * mode is active. A component panel can inject PLOT_MODE_CONTEXT and PLOT_MODE_SESSION.
+     */
+    panel?: PlotModePanel;
+}
+/**
+ * Multi-provider token for contributed plot modes.
+ *
+ * Deliberately has no `factory`: unregistered means no contributed modes, and the
+ * library behaves exactly as before. The visualizer injects it `{ optional: true }`
+ * and treats null as empty.
+ */
+export declare const PLOT_TYPE_CONTRIBUTIONS: InjectionToken<readonly PlotTypeContribution[]>;
+/** The active mode's context, in a component panel's injector. */
+export declare const PLOT_MODE_CONTEXT: InjectionToken<PlotModeContext>;
+/** The active mode's session, in a component panel's injector. */
+export declare const PLOT_MODE_SESSION: InjectionToken<PlotModeSession>;
+/**
+ * One entry in the plot-type selector: a built-in {@link PlotTypeDescriptor}
+ * as-is, or a contributed descriptor completed with its base type's `source`.
+ * Every entry therefore carries the same fields the selector curates by.
+ */
+export interface PlotTypeOption extends Omit<PlotTypeDescriptor, 'type'> {
+    type: PlotTypeId;
+    /** Set only for a contributed mode: the built-in type that renders it. */
+    baseType?: PlotType;
+}
+/** The selector entry for a contributed mode, given its base type's descriptor. */
+export declare function contributedPlotTypeOption(d: ContributedPlotTypeDescriptor, base: PlotTypeDescriptor): PlotTypeOption;

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

@@ -42,6 +42,16 @@ export declare enum PlotType {
      *  {@link SPATIAL_OMICS}: a single-plane dataset has no z to render. */
     SPATIAL_OMICS_3D = "spatial-omics-3d"
 }
+/**
+ * A value the plot-type selector can hold: a built-in {@link PlotType}, or the
+ * `type` of a contributed mode (`ContributedPlotTypeDescriptor.type`, see
+ * `plot-type-contribution.contract.ts`). Everything that decides HOW to render
+ * keeps taking a {@link PlotType}; a contributed id is resolved to its
+ * `baseType` first, so no rendering switch ever sees one.
+ */
+export type PlotTypeId = PlotType | string;
+/** Whether an id names a built-in plot type (as opposed to a contributed one). */
+export declare function isBuiltinPlotType(id: PlotTypeId | null | undefined): id is PlotType;
 /** How many spatial dimensions a plot type renders in. */
 export type PlotDimensions = '2d' | '3d';
 /**

package/lib/contracts/toolbar-tool.contract.d.ts

@@ -35,6 +35,17 @@
  * than an escape hatch that returns a component — the moment one tool draws
  * itself, the toolbar stops being able to lay tools out consistently.
  *
+ * DIALOG TOOLS
+ * Some tools are not "set parameters, run once" but an interactive session: the
+ * user paints, the tool retrains and redraws, over and over (DIANNE). A schema
+ * cannot describe that, so {@link ToolbarDialogToolContribution} is the one
+ * variant that renders its own body. The toolbar still owns the button, its
+ * placement and the dialog chrome; the tool only fills the dialog, with plain
+ * DOM (`mount`), so it needs neither Angular nor this library's PrimeNG version.
+ * Its button sits with the host's own actions at the start of the toolbar, and
+ * shows only in the Image view, the view its context ({@link ToolDialogContext})
+ * draws over.
+ *
  * WHY AN EMPTY MODEL LIST HIDES THE TOOL
  * {@link ToolbarToolContribution.models} returning `[]` removes the tool from
  * the toolbar entirely. This preserves the behaviour the built-in tools already
@@ -45,6 +56,7 @@
 import { InjectionToken } from '@angular/core';
 import type { Observable } from 'rxjs';
 import type { IVisualizer } from './visualizer.contract';
+import type { PlotModeContext, PlotModeSession, PlotModeTools } from './plot-type-contribution.contract';
 /** A number field. Rendered as a stepper, matching the built-in dialogs. */
 export interface NumberParamSpec {
     id: string;
@@ -177,14 +189,81 @@ export interface ToolbarToolContribution {
     run(viz: IVisualizer, params: Record<string, unknown>): Promise<number>;
 }
 /**
- * Multi-provider token for contributed tools.
+ * What a dialog tool gets while its dialog is open: the same surface a
+ * contributed plot mode gets (the public visualizer, the Image view's viewport
+ * and the current image), with the toolbar tools always present.
+ */
+export type ToolDialogContext = PlotModeContext & {
+    tools: PlotModeTools;
+};
+/** A live dialog-tool session. `deactivate()` runs exactly once, after the body's teardown. */
+export type ToolDialogSession = PlotModeSession;
+/**
+ * A toolbar tool that opens a dialog instead of running once (see DIALOG TOOLS
+ * above). Clicking its button opens the dialog and starts a session; clicking it
+ * again, or closing the dialog, ends it.
+ *
+ * The session is bound to the Image view on screen. When that view is re-rendered
+ * (another image, another slice) the session ends and, with the dialog still
+ * open, a fresh one starts once the new view is ready. Leaving the Image view
+ * closes the dialog. As with plot modes, nothing the tool throws or rejects
+ * escapes: a failed start closes the dialog with a warning.
+ */
+export interface ToolbarDialogToolContribution {
+    kind: 'dialog';
+    /** Stable identity. Must not clash with another toolbar tool. */
+    id: string;
+    /** Short name; the dialog title unless `dialog.title` is set. */
+    label: string;
+    icon: ToolIcon;
+    /** Tooltip on the button. */
+    tooltip: string;
+    /** Order among the dialog tools. Lower sorts first; ties keep registration order. */
+    order?: number;
+    dialog?: {
+        title?: string;
+        /** CSS width of the dialog. Default `'22rem'`. */
+        width?: string;
+    };
+    /** Entry for the help dialog's tool list, rendered as HTML (trusted content). */
+    help?: {
+        body: string;
+    };
+    /** Start a session, once the Image view's viewport is ready. */
+    activate(ctx: ToolDialogContext): ToolDialogSession | Promise<ToolDialogSession>;
+    /**
+     * Render the dialog body into `host`; return its teardown (called before
+     * `deactivate()`). Called after `activate` resolves, once the dialog has rendered and
+     * `host` is in the document, so the body can measure itself.
+     */
+    mount(host: HTMLElement, ctx: ToolDialogContext, session: ToolDialogSession): () => void;
+}
+/** Anything provided on {@link TOOLBAR_TOOLS}. A run tool has no `kind`. */
+export type ToolbarContribution = ToolbarToolContribution | ToolbarDialogToolContribution;
+/** Whether a contribution is a {@link ToolbarDialogToolContribution}. */
+export declare function isDialogToolContribution(c: unknown): c is ToolbarDialogToolContribution;
+/**
+ * Multi-provider token for contributed tools: run tools
+ * ({@link ToolbarToolContribution}) and, since 0.6.0, dialog tools
+ * ({@link ToolbarDialogToolContribution}).
  *
  * Deliberately has no `factory`: unregistered means no tools, which is what
  * makes this library shippable without the closed model packages. Inject it
  * `{ optional: true }` and treat null as empty.
  */
-export declare const TOOLBAR_TOOLS: InjectionToken<readonly ToolbarToolContribution[]>;
+export declare const TOOLBAR_TOOLS: InjectionToken<readonly ToolbarContribution[]>;
 /** Sort contributed tools into display order. */
-export declare function sortToolContributions(tools: readonly ToolbarToolContribution[]): ToolbarToolContribution[];
-/** The tools a toolbar should actually show: those with at least one model. */
-export declare function visibleToolContributions(tools: readonly ToolbarToolContribution[] | null | undefined): ToolbarToolContribution[];
+export declare function sortToolContributions<T extends {
+    order?: number;
+}>(tools: readonly T[]): T[];
+/** The run tools a toolbar should actually show: those with at least one model.
+ *  Dialog tools are left out (see {@link dialogToolContributions}). */
+export declare function visibleToolContributions(tools: readonly ToolbarContribution[] | null | undefined): ToolbarToolContribution[];
+/**
+ * The dialog tools, in display order. A malformed one (no string `id`, no
+ * `activate` or `mount` function) or a repeated `id` is dropped with a warning
+ * rather than breaking the toolbar.
+ */
+export declare function dialogToolContributions(tools: readonly ToolbarContribution[] | null | undefined, log?: {
+    warn(...args: unknown[]): void;
+}): ToolbarDialogToolContribution[];

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

@@ -10,6 +10,7 @@ import { IHistogram } from './channel-histogram-api.contract';
 import { ColormapNode, IWandOptions, IBrushOptions, SpatialViewState, SpatialColorBy } from './display-types';
 import { SpatialDataset, SpatialEmbedding } from './spatial-dataset.contract';
 import { SpatialSelectionMask } from '../spatial/spatial-selection';
+import type { PlotModeViewport } from './plot-type-contribution.contract';
 /**
  * Backend-neutral visualization contract. Plotly is one implementation;
  * OpenSeadragon is another (for the image plot type). The abstraction renders
@@ -419,6 +420,10 @@ export interface IVisualizer extends IDataRenderer, IRegionStore, IToolControlle
      *  Optional: only the routing service implements it, since the state is shared
      *  rather than owned by any one backend. */
     getSpatialControls?(): ISpatialControls | null;
+    /** The viewport a contributed plot mode draws over, when the backend on
+     *  screen can provide one (OpenSeadragon), else null. Optional: backends that
+     *  no contributed mode rides on need not implement it. */
+    getPlotModeViewport?(): PlotModeViewport | null;
     /** Binned intensity histogram for a channel from the currently-displayed
      *  pixels, or null when none are available. Feeds the Channels & Histogram
      *  pane. */

package/lib/implementations/osd/openseadragon-visualizer.service.d.ts

@@ -10,6 +10,7 @@ import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
 import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from '../../contracts/visualizer.contract';
 import { ViewerCapabilities } from '../../contracts/capabilities.contract';
 import { IRegionOverlay } from '../../contracts/region-overlay.contract';
+import { PlotModeViewport } from '../../contracts/plot-type-contribution.contract';
 import { BaseStoreVisualizer } from '../base-store-visualizer';
 import { SimpleSliceAccessService } from '../simple-slice-access.service';
 import { WandToolService } from '../../toolbar/wand/wand-tool.service';
@@ -221,6 +222,11 @@ export declare class OpenSeadragonVisualizerService extends BaseStoreVisualizer
     /** Visible image region (full-image pixel coords) emitted when the view
      *  settles, so the intensity inset can re-sample at the current zoom level. */
     private readonly viewportChange$;
+    /** The visible rect on every redraw, coalesced to one emission per animation
+     *  frame. Feeds {@link PlotModeViewport.frame$}. */
+    private readonly frame$;
+    private frameRaf;
+    private plotModeViewport;
     private readonly intensityProfile$;
     /**
      * Subscribe to the shared VisualizerStore colormap/reverse so OSD recolors in
@@ -410,6 +416,21 @@ export declare class OpenSeadragonVisualizerService extends BaseStoreVisualizer
     /** Compute the current viewport's image-pixel rectangle (clamped to the image)
      *  and broadcast it. */
     private emitViewportChange;
+    /** The current viewport's image-pixel rectangle, clamped to the image, or
+     *  null when there is no laid-out viewport. */
+    private visibleImageRect;
+    /** Coalesce redraws into one {@link frame$} emission per animation frame.
+     *  Skipped entirely while nothing listens. */
+    private scheduleFrame;
+    /**
+     * The viewport a contributed plot mode draws over. One stable object per
+     * service: every method reads the CURRENT viewer, so it stays valid across a
+     * viewer rebuild and reports `isReady() === false` while none is mounted
+     * (conversions then return NaN rather than throwing).
+     */
+    getPlotModeViewport(): PlotModeViewport;
+    /** `source`, preceded by the current visible rect for each subscriber (when ready). */
+    private withCurrentRect;
     /** OSD targets the image display; the scalar/3D plot types belong to Plotly. */
     getPlotTypeDescriptors(): PlotTypeDescriptor[];
     getIntensityProfile$(): Observable<IntensityProfile[]>;

package/lib/implementations/osd/osd-coordinate-transform.d.ts

@@ -13,5 +13,11 @@ export declare class OsdCoordinateTransform implements ICoordinateTransform {
         x: number;
         y: number;
     };
+    /** Data (image-pixel) coordinates -> client (mouse event) pixel. The inverse
+     *  of {@link clientToData}. */
+    dataToClient(x: number, y: number): {
+        x: number;
+        y: number;
+    };
     dataLengthToScreen(dataLength: number): number;
 }

package/lib/plot-mode/plot-mode-controller.d.ts

@@ -0,0 +1,130 @@
+import { PlotType, PlotTypeId } from '../contracts/plot-type';
+import { ContributedPlotTypeDescriptor, PlotModeContext, PlotModeSession, PlotTypeContribution } from '../contracts/plot-type-contribution.contract';
+/**
+ * Lifecycle of the contributed plot modes ({@link PlotTypeContribution}) for one
+ * visualizer instance. Package-internal: the visualizer component owns one and
+ * drives it from its render pipeline.
+ *
+ * Owns three things the component should not have to reason about:
+ *  - which contributions are usable (validated and de-duplicated once);
+ *  - the single live session, so `deactivate()` runs exactly once per session
+ *    however many exits race each other (type change, image change, destroy,
+ *    a superseded async activation);
+ *  - isolation: nothing a contribution throws or rejects escapes this class.
+ *    A failure is logged and reported through `onFailed`, and the component
+ *    falls back to the mode's base type.
+ */
+/** The live activation of a contributed mode, as the component renders it. */
+export interface ActivePlotMode {
+    readonly contribution: PlotTypeContribution;
+    readonly ctx: PlotModeContext;
+    readonly session: PlotModeSession;
+    /** Host element handed to a `mount` panel, or null for a component / no panel. */
+    readonly panelHost: HTMLElement | null;
+}
+export interface PlotModeControllerHooks {
+    /** A session is live (and a `mount` panel, if any, has been mounted). */
+    onActivated(active: ActivePlotMode): void;
+    /** The live session is about to end. Called BEFORE any teardown, so a
+     *  component panel can be destroyed while its session is still valid. */
+    onDeactivating(active: ActivePlotMode): void;
+    /** Activation failed (threw, rejected, never got a ready viewport, or its
+     *  panel failed to mount). The component falls back to the base type. */
+    onFailed(contribution: PlotTypeContribution, error: unknown): void;
+}
+/** Minimal logger, injectable for tests. */
+export interface PlotModeLogger {
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** Base types a contributed mode can ride on in this version. */
+export declare const SUPPORTED_CONTRIBUTION_BASE_TYPES: readonly PlotType[];
+/**
+ * Validate what arrived on `PLOT_TYPE_CONTRIBUTIONS`. A malformed or clashing
+ * contribution is dropped with a warning rather than breaking the selector:
+ *  - a nested array (`useValue: [a, b], multi: true`) is flattened one level;
+ *  - `type` must be a non-empty string that is not a built-in `PlotType` value;
+ *  - the first contribution with a given `type` wins;
+ *  - `baseType` must be one of {@link SUPPORTED_CONTRIBUTION_BASE_TYPES};
+ *  - `activate` must be a function.
+ */
+export declare function normalizeContributions(raw: readonly unknown[] | null | undefined, log?: PlotModeLogger): PlotTypeContribution[];
+export declare class PlotModeController {
+    private readonly hooks;
+    private readonly log;
+    readonly contributions: readonly PlotTypeContribution[];
+    private readonly byId;
+    private active;
+    private teardown;
+    /** Bumped by every activate/deactivate, so a pending async activation can
+     *  tell it has been superseded. */
+    private generation;
+    private readyFrame;
+    /** Contributions whose last cleanup (panel teardown / `deactivate()`) threw or
+     *  rejected. Their next automatic re-activation (base re-render, image switch)
+     *  falls back to the base type instead; an explicit selection clears the mark. */
+    private readonly failedCleanup;
+    private readyCb;
+    constructor(raw: readonly unknown[] | null | undefined, hooks: PlotModeControllerHooks, log?: PlotModeLogger);
+    /** Descriptors of the usable contributions, in registration order. */
+    descriptors(): ContributedPlotTypeDescriptor[];
+    /** The contribution for a selector id, if it is a contributed mode. */
+    find(id: PlotTypeId | null | undefined): PlotTypeContribution | undefined;
+    /**
+     * The built-in type that renders `id`: a built-in type is itself, a
+     * contributed id is its `baseType`, and an id that is neither (a stale
+     * contributed id whose provider is gone) resolves to `PlotType.IMAGE`, the
+     * default view.
+     */
+    baseTypeOf(id: PlotTypeId | null | undefined): PlotType;
+    /** The live session, if any. */
+    get current(): ActivePlotMode | null;
+    /** Whether an activation is waiting on the contribution or the viewport. */
+    get pending(): boolean;
+    private pendingId;
+    /**
+     * Start a session for `contribution`. Ends any live one first. Resolves when
+     * the attempt has finished (successfully or not); it never rejects.
+     */
+    activate(contribution: PlotTypeContribution, ctx: PlotModeContext): Promise<void>;
+    /**
+     * End the live session, if any: the component panel is dropped (via
+     * `onDeactivating`), a `mount` panel's teardown runs, then
+     * `session.deactivate()`, then the mount host is removed. Each step is
+     * isolated. A pending activation is cancelled; if it resolves later its
+     * session is deactivated on arrival. Idempotent.
+     */
+    deactivate(): void;
+    /**
+     * Forget recorded cleanup failures. The host calls this when the USER picks a
+     * plot type: an explicit choice gets a fresh attempt, only automatic
+     * re-activations fall back.
+     */
+    clearCleanupFailures(): void;
+    private start;
+    /**
+     * The host could not make the live mode usable (its panel threw while being
+     * created or first rendered): end the session once, then fall back to its base.
+     * No-op when nothing is live.
+     */
+    failActive(err: unknown): void;
+    private fail;
+    private guard;
+    /** Like `guard`, for a contribution callback typed `void` that may still return a
+     *  promise: a rejection is logged instead of escaping as an unhandled rejection. */
+    private guardLogged;
+    /** Run a live session's cleanup; a throw OR a rejection goes to `cleanupFailed`. */
+    private cleanup;
+    /**
+     * A contribution's cleanup failed. If that same contribution is live or starting
+     * again (a base re-render / image switch re-activated it — or, for an async
+     * rejection, already has), end it and fall back to its base type. Otherwise the
+     * user has moved on: remember it, so the next automatic re-activation falls back.
+     */
+    private cleanupFailed;
+    /** Call `cb(true)` once the viewport reports ready (now, or on a later
+     *  animation frame), or `cb(false)` after {@link MAX_READY_FRAMES}. */
+    private whenReady;
+    /** Stop waiting for the viewport; the waiting activation resolves as superseded. */
+    private cancelReadyWait;
+}

package/lib/routing-visualizer.service.d.ts

@@ -17,6 +17,7 @@ import { IChannelHistogramApi, IChannelState, IHistogram } from './contracts/cha
 import { VisualizerStore } from './store/visualizer-store.service';
 import { NapariVisualizerService } from './implementations/napari-js/napari-visualizer.service';
 import { VizConfig } from './contracts/viz-config';
+import { PlotModeViewport } from './contracts/plot-type-contribution.contract';
 import * as i0 from "@angular/core";
 export declare class RoutingVisualizerService implements IVisualizer, IRegionEditorApi, IChannelHistogramApi {
     private plotly;
@@ -98,6 +99,9 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     resetSurfaceCamera(): void;
     setResolutionScale(scale: number): void;
     getResolutionScale(): number;
+    /** The viewport of the backend on screen, for a contributed plot mode. Null
+     *  when that backend cannot provide one (e.g. OSD fell back to Plotly). */
+    getPlotModeViewport(): PlotModeViewport | null;
     getPlotTypeDescriptors(): PlotTypeDescriptor[];
     setStackLoading(b: boolean): void;
     cancelLoading(): void;

package/lib/toolbar/brush/brush-tool.service.d.ts

@@ -4,6 +4,15 @@ import * as i0 from "@angular/core";
 /** Brush parameters. `size` is the brush *diameter* in matrix (image) pixels. */
 export interface BrushOptions {
     size?: number;
+    /**
+     * Paint as one class. With `label` set, new regions take this label, and the
+     * stroke only adopts or merges regions that already have it, so painting one
+     * class never grows another class's region. `color` colours the painted
+     * regions instead of the toolbar's shape colour. Leave both unset for the
+     * plain toolbar brush.
+     */
+    label?: string;
+    color?: string;
 }
 /**
  * The brush host is identical to the wand's — both need the cached-image
@@ -60,6 +69,8 @@ export declare class BrushToolService {
     private lastMatrix;
     private dragging;
     private size;
+    /** The class being painted ({@link BrushOptions.label} / `color`); null = plain brush. */
+    private paintClass;
     private readonly boundMouseDown;
     private readonly boundMouseMove;
     private readonly boundMouseUp;
@@ -68,6 +79,13 @@ export declare class BrushToolService {
     bindHost(host: BrushToolHost): void;
     /** Toggle the brush on/off. */
     setMode(active: boolean, options?: BrushOptions): void;
+    /**
+     * Update size and/or class while armed. The class changes only when `label`
+     * or `color` is passed (as a key, even `undefined`), so a size-only update
+     * keeps it. Switching class drops the active region, so the next stroke
+     * starts a region of the new class.
+     */
+    setOptions(options?: BrushOptions): void;
     /** Live-update the brush size (matrix-pixel diameter). */
     setSize(size: number): void;
     /** Drop the active brush region so the next stroke starts a new one. */
@@ -102,6 +120,9 @@ export declare class BrushToolService {
      * erase stroke deletes every pixel.
      */
     private dropActiveShape;
+    /** Whether the stroke may adopt or merge `region`: always for the plain brush,
+     *  otherwise only a region of the class being painted. */
+    private paintsInto;
     /** A region's closed-polygon vertices (image/data coords), or null when it
      *  isn't a fillable closed polygon (rectangles, open polylines). */
     private regionVerts;