@jax-data-science/sci-image-visualizer 0.4.0 → 0.5.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/plot-type-contribution.contract.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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>;
+}
+/** 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>;
+}
+/** 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/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/toolbar.component.d.ts

@@ -1,9 +1,10 @@
 import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
 import { MenuItem } from 'primeng/api';
 import { IImageInfo } from '../contracts/image.contract';
-import { PlotType, PlotTypeDescriptor } from '../contracts/plot-type';
+import { PlotType, PlotTypeId } from '../contracts/plot-type';
 import { ToolbarToolVisibility } from '../contracts/toolbar-config';
 import { ToolbarToolContribution } from '../contracts/toolbar-tool.contract';
+import { PlotTypeOption } from '../contracts/plot-type-contribution.contract';
 import * as i0 from "@angular/core";
 /**
  * Presentational toolbar for the plotting viewport.
@@ -20,9 +21,18 @@ import * as i0 from "@angular/core";
 export declare class ToolbarComponent implements OnChanges {
     /** Current image (gates which control groups are shown). */
     imageInfo: IImageInfo | undefined;
-    /** Plot types the active backend advertises. */
-    plotTypeOptions: PlotTypeDescriptor[];
-    selectedPlotType: PlotType;
+    /** Plot types the active backend advertises, then any contributed modes. */
+    plotTypeOptions: PlotTypeOption[];
+    /** The selector's value: a built-in type or a contributed mode's id. */
+    selectedPlotType: PlotTypeId;
+    /**
+     * The built-in type that renders {@link selectedPlotType} — its `baseType`
+     * for a contributed mode. Every tool/control decision below reads
+     * {@link effectivePlotType}, so a contributed mode gets exactly its base
+     * type's toolbar. When unbound, a built-in selection is its own base and
+     * anything else is treated as the default Image view.
+     */
+    basePlotType: PlotType | null;
     /** Isosurface band as a 0–255 slider position (mapped onto the volume's real
      *  intensity range by the renderer). Defaults to the full range. */
     isoRange: number[];
@@ -82,7 +92,7 @@ export declare class ToolbarComponent implements OnChanges {
     contributedTools: ToolbarToolContribution[];
     /** Active checkpoint per contributed tool, keyed by tool id. */
     toolModelIds: Record<string, string>;
-    selectPlotType: EventEmitter<PlotType>;
+    selectPlotType: EventEmitter<string>;
     /** Intensity (LINE) mode: add another colored line ROI + inset trace. */
     addProfileLine: EventEmitter<void>;
     /** Toggle image smoothing (bilinear) vs nearest-neighbour (crisp pixels). */
@@ -196,6 +206,8 @@ export declare class ToolbarComponent implements OnChanges {
     /** Keeps each contributed tool's `p-menu` overlay alive across CD ticks —
      *  re-creating it mid-interaction swallows the click on a menu item. */
     trackToolById(_index: number, tool: ToolbarToolContribution): string;
+    /** The built-in type whose tools and controls apply to the current selection. */
+    get effectivePlotType(): PlotType;
     /** The Image plot type renders as a natively pan/zoom-able raster, so the
      *  generic zoom/pan tools are hidden. */
     get isImageView(): boolean;
@@ -230,5 +242,5 @@ export declare class ToolbarComponent implements OnChanges {
     get isIntensityCapable(): boolean;
     showHelp(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<ToolbarComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarComponent, "plotting-toolbar", never, { "imageInfo": { "alias": "imageInfo"; "required": false; }; "plotTypeOptions": { "alias": "plotTypeOptions"; "required": false; }; "selectedPlotType": { "alias": "selectedPlotType"; "required": false; }; "isoRange": { "alias": "isoRange"; "required": false; }; "maxIndex": { "alias": "maxIndex"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "isHeatmap": { "alias": "isHeatmap"; "required": false; }; "is3dRegions": { "alias": "is3dRegions"; "required": false; }; "activeDragMode": { "alias": "activeDragMode"; "required": false; }; "activeSurface3dMode": { "alias": "activeSurface3dMode"; "required": false; }; "axesVisible": { "alias": "axesVisible"; "required": false; }; "wireframeActive": { "alias": "wireframeActive"; "required": false; }; "resolutionScale": { "alias": "resolutionScale"; "required": false; }; "wandSensitivity": { "alias": "wandSensitivity"; "required": false; }; "brushSize": { "alias": "brushSize"; "required": false; }; "vertexEraserRadius": { "alias": "vertexEraserRadius"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; "stackOptions": { "alias": "stackOptions"; "required": false; }; "tools": { "alias": "tools"; "required": false; }; "imageSmoothingEnabled": { "alias": "imageSmoothingEnabled"; "required": false; }; "samModels": { "alias": "samModels"; "required": false; }; "samModelId": { "alias": "samModelId"; "required": false; }; "contributedTools": { "alias": "contributedTools"; "required": false; }; "toolModelIds": { "alias": "toolModelIds"; "required": false; }; }, { "selectPlotType": "selectPlotType"; "addProfileLine": "addProfileLine"; "toggleImageSmoothing": "toggleImageSmoothing"; "isoRangeChange": "isoRangeChange"; "openChannelHistogram": "openChannelHistogram"; "openSpatialControls": "openSpatialControls"; "openRegionEditor": "openRegionEditor"; "selectStackOption": "selectStackOption"; "zScrub": "zScrub"; "zSlide": "zSlide"; "zIndexInput": "zIndexInput"; "reloadAndPlot": "reloadAndPlot"; "downloadImage": "downloadImage"; "autoscaleImage": "autoscaleImage"; "toggleDragMode": "toggleDragMode"; "zoomIn": "zoomIn"; "zoomOut": "zoomOut"; "toggleSurface3dMode": "toggleSurface3dMode"; "resetSurfaceCamera": "resetSurfaceCamera"; "toggleAxes": "toggleAxes"; "toggleWireframe": "toggleWireframe"; "selectResolution": "selectResolution"; "deleteRegion": "deleteRegion"; "undoRegion": "undoRegion"; "redoRegion": "redoRegion"; "segmentRegions": "segmentRegions"; "segmentCellpose": "segmentCellpose"; "runTool": "runTool"; "toolModelChange": "toolModelChange"; "openToolParams": "openToolParams"; "samModelChange": "samModelChange"; "wandSensitivityChange": "wandSensitivityChange"; "brushSizeChange": "brushSizeChange"; "vertexEraserRadiusChange": "vertexEraserRadiusChange"; }, never, ["*"], false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ToolbarComponent, "plotting-toolbar", never, { "imageInfo": { "alias": "imageInfo"; "required": false; }; "plotTypeOptions": { "alias": "plotTypeOptions"; "required": false; }; "selectedPlotType": { "alias": "selectedPlotType"; "required": false; }; "basePlotType": { "alias": "basePlotType"; "required": false; }; "isoRange": { "alias": "isoRange"; "required": false; }; "maxIndex": { "alias": "maxIndex"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "isHeatmap": { "alias": "isHeatmap"; "required": false; }; "is3dRegions": { "alias": "is3dRegions"; "required": false; }; "activeDragMode": { "alias": "activeDragMode"; "required": false; }; "activeSurface3dMode": { "alias": "activeSurface3dMode"; "required": false; }; "axesVisible": { "alias": "axesVisible"; "required": false; }; "wireframeActive": { "alias": "wireframeActive"; "required": false; }; "resolutionScale": { "alias": "resolutionScale"; "required": false; }; "wandSensitivity": { "alias": "wandSensitivity"; "required": false; }; "brushSize": { "alias": "brushSize"; "required": false; }; "vertexEraserRadius": { "alias": "vertexEraserRadius"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; "stackOptions": { "alias": "stackOptions"; "required": false; }; "tools": { "alias": "tools"; "required": false; }; "imageSmoothingEnabled": { "alias": "imageSmoothingEnabled"; "required": false; }; "samModels": { "alias": "samModels"; "required": false; }; "samModelId": { "alias": "samModelId"; "required": false; }; "contributedTools": { "alias": "contributedTools"; "required": false; }; "toolModelIds": { "alias": "toolModelIds"; "required": false; }; }, { "selectPlotType": "selectPlotType"; "addProfileLine": "addProfileLine"; "toggleImageSmoothing": "toggleImageSmoothing"; "isoRangeChange": "isoRangeChange"; "openChannelHistogram": "openChannelHistogram"; "openSpatialControls": "openSpatialControls"; "openRegionEditor": "openRegionEditor"; "selectStackOption": "selectStackOption"; "zScrub": "zScrub"; "zSlide": "zSlide"; "zIndexInput": "zIndexInput"; "reloadAndPlot": "reloadAndPlot"; "downloadImage": "downloadImage"; "autoscaleImage": "autoscaleImage"; "toggleDragMode": "toggleDragMode"; "zoomIn": "zoomIn"; "zoomOut": "zoomOut"; "toggleSurface3dMode": "toggleSurface3dMode"; "resetSurfaceCamera": "resetSurfaceCamera"; "toggleAxes": "toggleAxes"; "toggleWireframe": "toggleWireframe"; "selectResolution": "selectResolution"; "deleteRegion": "deleteRegion"; "undoRegion": "undoRegion"; "redoRegion": "redoRegion"; "segmentRegions": "segmentRegions"; "segmentCellpose": "segmentCellpose"; "runTool": "runTool"; "toolModelChange": "toolModelChange"; "openToolParams": "openToolParams"; "samModelChange": "samModelChange"; "wandSensitivityChange": "wandSensitivityChange"; "brushSizeChange": "brushSizeChange"; "vertexEraserRadiusChange": "vertexEraserRadiusChange"; }, never, ["*"], false, never>;
 }

package/lib/visualizer.component.d.ts

@@ -1,4 +1,4 @@
-import { ChangeDetectorRef, AfterViewInit, EventEmitter, NgZone, OnChanges, OnDestroy, OnInit, SimpleChanges } from '@angular/core';
+import { ChangeDetectorRef, AfterViewInit, ElementRef, EventEmitter, Injector, NgZone, OnChanges, OnDestroy, OnInit, SimpleChanges, Type } from '@angular/core';
 import { Subscription } from 'rxjs';
 import { MenuItem, MessageService, TreeNode } from 'primeng/api';
 import { ContextMenu } from 'primeng/contextmenu';
@@ -7,7 +7,9 @@ import { ImageStatePort } from './contracts/ports/image-state.port';
 import { Polygon } from './models/region';
 import { RegionOpsService } from './region-ops.service';
 import { VisualizerStore } from './store/visualizer-store.service';
-import { PlotType, PlotTypeDescriptor } from './contracts/plot-type';
+import { PlotType, PlotTypeDescriptor, PlotTypeId } from './contracts/plot-type';
+import { PlotTypeContribution, PlotTypeOption } from './contracts/plot-type-contribution.contract';
+import { PlotModeController } from './plot-mode/plot-mode-controller';
 import { IVisualizer } from './contracts/visualizer.contract';
 import { SamToolService } from './toolbar/segmentation/sam-tool.service';
 import { SamPointToolService } from './toolbar/segmentation/sam-point-tool.service';
@@ -30,6 +32,7 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     private regionOps;
     private vizConfig?;
     private spatialData?;
+    private injector?;
     /** Per-instance toast key. MessageService is a global singleton, so two live
      *  `<visualizer>` instances (main viewer + pipeline-dialog preview) sharing
      *  one key would each render the same message — a duplicate toast. A unique
@@ -204,9 +207,48 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     wireframeActive: boolean;
     /** napari 3D decimate factor (1 = Full … 8 = ⅛; default ½); changing it re-plots. */
     resolutionScale: number;
-    /** Plot types the active backend advertises (3D gated by capability). */
+    /** The selector's entries: the built-in plot types the active backend
+     *  advertises (3D gated by capability), then any contributed modes
+     *  ({@link PLOT_TYPE_CONTRIBUTIONS}). */
+    plotTypeMenu: PlotTypeOption[];
+    /**
+     * The built-in plot types on offer — {@link plotTypeMenu} without contributed
+     * modes. Kept with its original type so existing readers are unaffected.
+     */
     plotTypeOptions: PlotTypeDescriptor[];
-    selectedPlotType: PlotType;
+    /**
+     * What the selector shows: a built-in type or a contributed mode's id. Every
+     * rendering and tool decision goes through {@link basePlotType} instead, so a
+     * contributed mode behaves exactly like the built-in type it rides on.
+     */
+    selectedPlotTypeId: PlotTypeId;
+    /**
+     * The built-in plot type being rendered. With no contributed mode active this
+     * is the selection itself; during one it is the mode's `baseType`. Kept with its
+     * original `PlotType` type for existing readers — use {@link selectedPlotTypeId}
+     * for the selector's id. Assigning selects that built-in type.
+     */
+    get selectedPlotType(): PlotType;
+    set selectedPlotType(type: PlotType);
+    /** Contributed plot modes and their single live session. */
+    readonly plotModes: PlotModeController;
+    /**
+     * The live contributed mode's side panel, as the template renders it: an
+     * Angular component with its own injector, or a plain host element a `mount`
+     * panel rendered into. Null while no contributed session is live.
+     */
+    plotModePanel: {
+        title: string;
+        component: Type<unknown> | null;
+        injector: Injector | null;
+        host: HTMLElement | null;
+    } | null;
+    private destroying;
+    /** Where a `mount` panel's host element is attached once the dialog renders. */
+    set plotModePanelSlot(ref: ElementRef<HTMLElement> | undefined);
+    /** The built-in type actually rendered for {@link selectedPlotTypeId}: itself
+     *  for a built-in type, `baseType` for a contributed mode. */
+    get basePlotType(): PlotType;
     /** Floating intensity-profile inset (LINE mode). */
     readonly intensityInsetDiv = "intensity-inset-plot";
     profilePanelPos: {
@@ -276,7 +318,7 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
     private wheelListener?;
     /** Debounced z-slice scrubbing (see SliceScrubber — refactoring plan Step 7). */
     private readonly scrubber;
-    constructor(state: ImageStatePort, plotService: IVisualizer, messageService: MessageService, ngZone: NgZone, cdr: ChangeDetectorRef, session: VisualizerStore, samTool: SamToolService, cellSegmentTool: CellSegmentToolService, samPointTool: SamPointToolService, regionOps: RegionOpsService, vizConfig?: VizConfig | undefined, toolContributions?: readonly ToolbarToolContribution[], spatialData?: SpatialDataPort | undefined);
+    constructor(state: ImageStatePort, plotService: IVisualizer, messageService: MessageService, ngZone: NgZone, cdr: ChangeDetectorRef, session: VisualizerStore, samTool: SamToolService, cellSegmentTool: CellSegmentToolService, samPointTool: SamPointToolService, regionOps: RegionOpsService, vizConfig?: VizConfig | undefined, toolContributions?: readonly ToolbarToolContribution[], spatialData?: SpatialDataPort | undefined, plotTypeContributions?: readonly PlotTypeContribution[], injector?: Injector | undefined);
     /**
      * Plot types offered in the selector for the current image:
      *  - Outside **test mode**, only the curated default set (descriptors with a
@@ -544,9 +586,28 @@ export declare class VisualizerComponent implements OnInit, OnChanges, AfterView
      * the toolbar/context-menu logic relies on, deactivates 2D-only tools when
      * moving to a 3D type, then re-plots.
      */
-    onSelectPlotType(type: PlotType): void;
+    onSelectPlotType(selected: PlotTypeId): 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;
+    /** 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;
+    /** Run change detection; returns what it threw (logged), or null. */
+    private detectChangesSafely;
     /** Deactivate whatever tool is armed and clear every tool mode. */
     private deactivateActiveTool;
-    static ɵfac: i0.ɵɵFactoryDeclaration<VisualizerComponent, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<VisualizerComponent, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }, { optional: true; }]>;
     static ɵcmp: i0.ɵɵComponentDeclaration<VisualizerComponent, "visualizer", never, { "toolbarTools": { "alias": "toolbarTools"; "required": false; }; "testMode": { "alias": "testMode"; "required": false; }; }, { "isStackEvent": "isStackEvent"; "isGrayscaleEvent": "isGrayscaleEvent"; }, never, ["*"], false, never>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jax-data-science/sci-image-visualizer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "engines": {
     "node": ">=20.9.0"
   },