@jax-data-science/sci-image-visualizer 0.3.3 → 0.5.0

package/lib/implementations/plotly/omics-trace-builders.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Plotly traces for the 1-D distribution charts over spatial-omics values:
+ * histogram, violin and box.
+ *
+ * Pure, like `plotly-trace-builders.ts` — and deliberately SEPARATE from it,
+ * because that module's `TraceBuildInput` is image-matrix shaped (`frames`,
+ * `width`, `ratios`, `trueImageSize`) and cannot express "one value per
+ * observation". Forcing the two together would make both worse.
+ *
+ * Violin and box need no bundling work: `plotly.js-dist-min` is the full
+ * distribution and already carries both trace types.
+ */
+export type OmicsChartKind = 'histogram' | 'violin' | 'box' | 'counts' | 'heatmap' | 'embedding';
+/** Per-observation grouping for a violin/box, or an overlaid histogram. */
+export interface OmicsGrouping {
+    codes: Uint16Array;
+    categories: string[];
+    /** `#rrggbb` per category, index-aligned — the same colours the map uses. */
+    colors: string[];
+}
+export interface OmicsTraceInput {
+    /** The values being charted (an annotation column or a gene vector). */
+    values: Float32Array;
+    /** Axis label for the value — the column or gene name. */
+    name: string;
+    group?: OmicsGrouping | null;
+    /** `1` marks a selected observation. When present, the charts narrow to it. */
+    selection?: Uint8Array | null;
+    /** Plot `log1p(value)` instead of the raw value. */
+    log?: boolean;
+    /** Colour for the ungrouped trace. */
+    color?: string;
+}
+/**
+ * Traces for one chart kind.
+ *
+ * - **histogram** — the full distribution, plus an overlaid *Selected* trace
+ *   when a selection exists, so the two are directly comparable. That
+ *   comparison is the whole point of linking the chart to the map.
+ * - **violin / box** — one per category when grouped, otherwise a single trace.
+ *   These narrow TO the selection rather than overlaying it: a violin per
+ *   category per selection state is unreadable.
+ */
+export declare function buildOmicsTraces(kind: OmicsChartKind, input: OmicsTraceInput): unknown[];
+/** Layout for a chart kind — axis titles reflect the log toggle. */
+export declare function omicsLayout(kind: OmicsChartKind, input: OmicsTraceInput): unknown;
+/** Whether a chart kind needs a categorical grouping to be worth showing. */
+export declare function benefitsFromGrouping(kind: OmicsChartKind): boolean;
+export interface OmicsCountInput {
+    /** The categorical being counted, with the map's own colours. */
+    group: OmicsGrouping;
+    /** `1` marks a selected observation; when present the bars show the selection
+     *  against the total. */
+    selection?: Uint8Array | null;
+    /** Bars before the tail is aggregated. */
+    max?: number;
+}
+/** Per-category counts, biggest first, with the tail folded into one bar. */
+export declare function countByCategory(input: OmicsCountInput): {
+    labels: string[];
+    colors: string[];
+    totals: number[];
+    selected: number[];
+};
+/**
+ * Bars of per-category cell counts — the distribution a CATEGORICAL colour
+ * source has.
+ *
+ * A histogram of a category code would be meaningless (the codes are labels, not
+ * magnitudes), but "how many cells per class" is a real question, and the same one
+ * the legend implies without answering. Horizontal, because taxonomy labels are
+ * long, and sorted, because rank is what the chart is read for.
+ */
+export declare function buildCountTraces(input: OmicsCountInput): unknown[];
+export declare function countsLayout(input: OmicsCountInput & {
+    name: string;
+}): unknown;
+/**
+ * Genes × groups mean expression, as a Plotly heatmap.
+ *
+ * The matrix itself is computed by the pure `heatmapMatrix` in
+ * `spatial/spatial-heatmap.ts`; this only shapes it for Plotly. Kept in the
+ * matrix's own row-major order and flipped once here, because Plotly draws
+ * `z[0]` at the BOTTOM of the y axis while the caller lists genes top-down.
+ *
+ * The colour scale is its own, NOT the map's `continuousColormap`. This is a
+ * different quantity — a z-scored mean per group, not a per-cell value — so
+ * sharing one scale would invite reading a heatmap cell as if it were a marker
+ * colour. Diverging and centred on zero, because after z-scoring the sign is
+ * the reading: above or below this gene's average across the groups.
+ */
+/**
+ * An embedding scatter — a UMAP, t-SNE or PCA plane over the same observations.
+ *
+ * Answers a different question from the map: the map says WHERE a population sits in the tissue,
+ * the embedding says which populations there are and how close they are in expression. Read side
+ * by side, and selecting in one highlighting the other, is the whole point of having both.
+ */
+export interface OmicsEmbeddingInput {
+    /** Embedding coordinates, index-aligned with the observations. */
+    x: Float32Array;
+    y: Float32Array;
+    /**
+     * Third dimension, when the embedding has one.
+     *
+     * Its presence is what switches the plot to a rotatable 3D scatter. A 3D embedding is
+     * always COMPUTED — every embedding published with a spatial dataset is 2D, because a
+     * UMAP exists to be looked at — so `derived` is expected alongside it.
+     */
+    z?: Float32Array;
+    /** Axis label stem, e.g. "UMAP" — the axes become "UMAP 1" / "UMAP 2". */
+    label: string;
+    /** Colour by a categorical column: per-observation codes plus the category names/colours. */
+    categories?: {
+        codes: Uint16Array;
+        names: readonly string[];
+        colors: readonly string[];
+    };
+    /** Marker diameter in px. */
+    size?: number;
+    /**
+     * Selection mask over the observations. When present, unselected points are dimmed rather than
+     * dropped: the shape of the whole embedding is the context that makes a selection legible, and
+     * removing it would leave a handful of dots floating in an empty plane.
+     */
+    selection?: Uint8Array;
+    /** True when the coordinates were computed here rather than published with the dataset. */
+    derived?: boolean;
+    /**
+     * Fraction of variance per axis, for a LINEAR embedding.
+     *
+     * Present for a PCA and absent for a UMAP, and that difference is the point of showing
+     * a PCA at all: its axes are ordered and each explains a measurable share of the
+     * variance, so "PC1 (23%)" says something a reader can act on. A UMAP's coordinates are
+     * an arbitrary output of an optimisation — unordered, unitless, and reproducible only
+     * up to a rotation — so there is nothing to label them with.
+     */
+    varianceRatio?: number[];
+    /**
+     * The view to keep across a redraw.
+     *
+     * `Plotly.react` resets the 3D scene camera and any zoomed 2D axis range unless the
+     * layout carries them, so recolouring or selecting would throw away an orientation the
+     * user had set up. Rotating a cloud to see a structure and losing it on the next click
+     * makes the plot unusable for the thing it is for.
+     *
+     * `camera` is a 3D scene camera; `ranges` are 2D axis ranges, and are only passed when
+     * the user has actually zoomed — freezing an autoranged axis would stop the plot
+     * re-fitting when the data changes.
+     */
+    view?: {
+        camera?: unknown;
+        ranges?: {
+            x: unknown;
+            y: unknown;
+        };
+    };
+}
+/**
+ * Past this many categories, one trace each stops being worth it.
+ *
+ * A trace per category buys a legend whose entries toggle — click one to isolate a population,
+ * which is how these plots are actually read. But Plotly holds per-trace state, and a legend of
+ * hundreds of entries is unreadable anyway (the ABC atlas has 338 subclasses), so beyond the cap
+ * everything goes into ONE trace with a per-point colour: no legend, but it still draws.
+ */
+export declare const EMBEDDING_MAX_LEGEND_CATEGORIES = 40;
+/**
+ * Categories past which the legend is not DRAWN, though the traces stay split.
+ *
+ * A legend is only worth its space if it fits. seqFISH's 22 cell types stack into one tall
+ * column in a docked panel, overlapping the axis title and running off the bottom — and
+ * the colours already match the map, whose own panel lists them, while hover names the
+ * category under the cursor. So past this the plot takes the whole panel and the legend
+ * is dropped rather than shown badly.
+ */
+export declare const EMBEDDING_MAX_LEGEND_SHOWN = 10;
+export declare function buildEmbeddingTraces(input: OmicsEmbeddingInput): unknown[];
+export declare function embeddingLayout(input: OmicsEmbeddingInput): unknown;
+export interface OmicsHeatmapInput {
+    rows: string[];
+    cols: string[];
+    /** `rows.length × cols.length`, row-major; `NaN` where nothing was measured. */
+    values: Float32Array;
+    /** Cells behind each column, for the hover. */
+    counts?: Uint32Array;
+    /** True when `values` are z-scores, which sets the scale and the labels. */
+    zScored?: boolean;
+    /** Column axis title — the grouping column's name, or "cell". */
+    groupLabel?: string;
+}
+export declare function buildHeatmapTraces(input: OmicsHeatmapInput): unknown[];
+export declare function heatmapLayout(input: OmicsHeatmapInput): unknown;

package/lib/implementations/plotly/plotly.service.d.ts

@@ -62,6 +62,15 @@ export declare class PlotlyService implements IVisualizer {
     private fileName;
     private dragMode;
     private urls;
+    /**
+     * The image currently plotted.
+     *
+     * The `!` is a definite-assignment ASSERTION, not a guarantee: nothing sets this until
+     * an image loads, and a host can clear its image while these paths still run — a
+     * spatial-omics dataset that brings no tissue section does exactly that. So reads here
+     * are optional and assignments guarded; an unguarded one threw
+     * "can't access property isGrayscale" and aborted the load.
+     */
     imageInfo: IImageInfo;
     private plotUtilities;
     private plotType;

package/lib/implementations/spatial-data-http/spatial-data-http.service.d.ts

@@ -0,0 +1,123 @@
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import { SpatialColumn, SpatialDataset, SpatialEmbedding, SpatialPolygons } from '../../contracts/spatial-dataset.contract';
+import { SpatialDatasetSummary, SpatialManifest } from './spatial-wire';
+import * as i0 from "@angular/core";
+/**
+ * Reference {@link SpatialDataPort} adapter for the wire format the bundled
+ * example server speaks (see `spatial-wire.ts` and
+ * `examples/tile-server/lib/spatial.mjs`).
+ *
+ * OPTIONAL AND UNBOUND BY DEFAULT — this service is `@Injectable()` without
+ * `providedIn`, so nothing gets it unless a host explicitly provides it:
+ *
+ * ```ts
+ * providers: [
+ *   SpatialDataHttpService,
+ *   { provide: SPATIAL_DATA_PORT, useExisting: SpatialDataHttpService },
+ * ]
+ * ```
+ *
+ * That mirrors `CellposeSegmenterService`: a concrete implementation the
+ * library ships for convenience, not a default the port inversion is quietly
+ * giving up on. A host with its own backend implements `SpatialDataPort`
+ * directly and never touches this class.
+ *
+ * Requests go through Angular's `HttpClient` (not `fetch`) so the host's
+ * interceptors — auth headers above all — apply, matching `tile-client.ts`.
+ */
+/**
+ * A dataset selection that a newer selection (or a `clear`) overtook.
+ *
+ * Thrown rather than resolved so a caller cannot mistake it for "this dataset is
+ * now loaded": nothing was published, on purpose.
+ */
+export declare class SupersededError extends Error {
+    constructor(id: string);
+}
+export declare class SpatialDataHttpService implements SpatialDataPort {
+    private http;
+    /** Server root, normalised to end with exactly one `/`. */
+    private baseUrl;
+    /** Per-request ceiling. Vectors are small; a hung request should not wedge
+     *  the picker. */
+    private timeoutMs;
+    private readonly dataset$;
+    private manifest;
+    /** Bumped by every `selectDataset` and every `clear`, so a selection that
+     *  finishes after a newer intent can tell and drop what it fetched. */
+    private selectToken;
+    /**
+     * Loaded vectors, keyed `column:<name>` / `feature:<name>`. Bounded LRU:
+     * colouring by cluster → by a gene → back by cluster must not refetch, but an
+     * afternoon of browsing genes must not grow without limit either (one vector
+     * is `4·N` bytes — 2 MB at 500k cells).
+     */
+    private readonly cache;
+    private static readonly CACHE_LIMIT;
+    /** In-flight requests, so double-clicking a gene issues one fetch. */
+    private readonly inFlight;
+    private volumePromise;
+    private polygonsPromise;
+    constructor(http: HttpClient);
+    /** Point the adapter at a server. Clears any loaded dataset. */
+    configure(options: {
+        baseUrl: string;
+        timeoutMs?: number;
+    }): void;
+    /** Datasets this server offers, for a host-side picker. */
+    listDatasets(): Promise<SpatialDatasetSummary[]>;
+    /**
+     * One dataset's manifest, WITHOUT selecting it. Lets a host inspect what a
+     * server offers — column and feature metadata, and which image a dataset
+     * registers onto — while building a picker, rather than having to load each
+     * dataset to find out.
+     */
+    readManifest(id: string): Promise<SpatialManifest>;
+    /**
+     * Load a dataset and publish it on {@link getDataset$}. Fetches the manifest,
+     * then the vectors that are always needed (coordinates, and ids/radius when
+     * the manifest says they exist) — nothing else.
+     */
+    selectDataset(id: string): Promise<SpatialDataset>;
+    /** Drop the loaded dataset and every cached vector. */
+    clear(): void;
+    getDataset$(): Observable<SpatialDataset | null>;
+    getColumn(name: string): Promise<SpatialColumn>;
+    getEmbedding(name: string): Promise<SpatialEmbedding>;
+    getFeatureVector(name: string): Promise<Float32Array>;
+    searchFeatures(query: string, limit?: number): Promise<string[]>;
+    getPolygons(): Promise<SpatialPolygons>;
+    /**
+     * The reference volume's voxels, single-flighted like the polygons.
+     *
+     * Validated against the manifest's declared dimensions before it is handed
+     * back: a short or long buffer read as a 3D texture does not fail, it shears
+     * the anatomy into diagonal streaks, and that is far harder to recognise as a
+     * transport problem than an error is.
+     */
+    getVolume(): Promise<Uint8Array>;
+    private requireManifest;
+    /**
+     * Cache + single-flight around a vector fetch.
+     *
+     * Keys are LOGICAL — `feature:GAPDH`, not `<dataset>/feature:GAPDH` — because `clear()`
+     * empties the maps on every switch, so two datasets never hold entries at once. What
+     * that does not cover is a request still in the air when the switch happens: `clear()`
+     * cannot cancel an HTTP call, so a vector fetched for dataset A can resolve after B has
+     * been selected and write itself into B's cache under a key B would read. Both datasets
+     * having a gene of that name is the common case, not the unlucky one, and the result is
+     * a plot of A's expression over B's cells — which looks like data, not like a fault.
+     *
+     * So the generation is checked after the await, and the in-flight slot is cleared only
+     * when the promise still sitting in it is this one: a late arrival must not evict the
+     * entry a newer request for the same key is already sharing.
+     */
+    private fetchCached;
+    private evict;
+    private getJson;
+    private getBinary;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialDataHttpService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SpatialDataHttpService>;
+}

package/lib/implementations/spatial-data-http/spatial-wire.d.ts

@@ -0,0 +1,115 @@
+import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialEmbedding, SpatialEmbeddingMeta, SpatialFeatureMeta, SpatialImageRef, SpatialObservations, SpatialPolygons, SpatialVolumeMeta } from '../../contracts/spatial-dataset.contract';
+/**
+ * The wire format the bundled example server speaks, and its decoders.
+ *
+ * Pure by design — no Angular, no RxJS, no HTTP — so the format is testable on
+ * its own and reusable by any transport (`SpatialDataHttpService` is one).
+ * Mirrors the split in `plotly-trace-builders.ts`: the shape lives in a pure
+ * module, the service just moves bytes.
+ *
+ * WHY BINARY
+ * ----------
+ * Vectors are one `Float32Array`/`Uint16Array` per request, delivered as raw
+ * little-endian bytes. JSON would cost ~8–12× the size and a parse that
+ * allocates one JS number per value; a typed-array view over the response
+ * buffer is zero-copy and uploads to the GPU directly.
+ *
+ * ENDIANNESS
+ * ----------
+ * Little-endian, asserted at decode. Every platform a browser runs on today is
+ * little-endian, so a `DataView` byte-by-byte read would cost real time for a
+ * case that does not occur — but failing loudly beats rendering transposed
+ * garbage if it ever does.
+ *
+ * ENDPOINTS (base = the server root)
+ * ----------------------------------
+ * ```
+ * GET {base}/spatial/datasets              -> { datasets: [{ id, name, count }] }
+ * GET {base}/spatial/{id}/manifest         -> SpatialManifest
+ * GET {base}/spatial/{id}/coords           -> f32[N] x, f32[N] y, f32[N] z?
+ * GET {base}/spatial/{id}/radius           -> f32[N]           (per-observation radius only)
+ * GET {base}/spatial/{id}/ids              -> { ids: string[] } (hasIds only)
+ * GET {base}/spatial/{id}/column/{name}    -> u16[N] codes | f32[N] values
+ * GET {base}/spatial/{id}/feature/{name}   -> f32[N]
+ * GET {base}/spatial/{id}/features?q=&limit= -> { names: string[] }
+ * GET {base}/spatial/{id}/polygons         -> u32 count, u32[count+1] offsets, f32[2*rings] coords
+ * ```
+ */
+/** Bumped when the layout changes incompatibly; the client refuses anything else. */
+export declare const SPATIAL_WIRE_VERSION = 1;
+/** Per-observation marker radius: one shared value, or a served f32 vector. */
+export type SpatialRadiusSpec = {
+    mode: 'uniform';
+    value: number;
+} | {
+    mode: 'per-observation';
+};
+/** `GET /spatial/{id}/manifest` — everything cheap enough to send up front. */
+export interface SpatialManifest {
+    version: number;
+    id: string;
+    name: string;
+    /** N — observation count; every served vector has exactly this length. */
+    count: number;
+    hasZ?: boolean;
+    hasIds?: boolean;
+    radius?: SpatialRadiusSpec;
+    columns: SpatialColumnMeta[];
+    features?: SpatialFeatureMeta;
+    polygons?: {
+        count: number;
+    };
+    imageRef?: SpatialImageRef;
+    volume?: SpatialVolumeMeta;
+    embeddings?: SpatialEmbeddingMeta[];
+    micronsPerUnit?: number;
+}
+/** `GET /spatial/datasets` */
+export interface SpatialDatasetSummary {
+    id: string;
+    name: string;
+    count: number;
+}
+/** True on a little-endian host. */
+export declare function isLittleEndian(): boolean;
+/** Reject a manifest this client cannot read, with a message naming the fix. */
+export declare function assertManifestVersion(manifest: SpatialManifest): void;
+/**
+ * `GET /coords` → x/y(/z). One request rather than two or three: the vectors
+ * are always fetched together, and a single response keeps them consistent if
+ * the dataset changes underneath.
+ */
+export declare function decodeCoords(buf: ArrayBuffer, count: number, hasZ?: boolean): Pick<SpatialObservations, 'x' | 'y' | 'z'>;
+/** `GET /radius` → per-observation radii in image pixels. */
+export declare function decodeRadius(buf: ArrayBuffer, count: number): Float32Array;
+/** `GET /feature/{name}` → one gene's expression vector. */
+/**
+ * `GET /spatial/{id}/embedding/{name}` — one plane per dimension, same layout as coords.
+ *
+ * Struct of arrays, not interleaved: every dimension is contiguous, so an axis can be handed to
+ * the renderer as a view with no copy and no stride.
+ */
+export declare function decodeEmbedding(buf: ArrayBuffer, meta: SpatialEmbeddingMeta, count: number): SpatialEmbedding;
+export declare function decodeFeatureVector(buf: ArrayBuffer, count: number): Float32Array;
+/**
+ * `GET /column/{name}` → a loaded column, typed by its descriptor: `u16` codes
+ * for a categorical, `f32` values for a continuous. Codes outside the category
+ * list are normalised to {@link NO_CATEGORY} so a renderer can trust the
+ * invariant instead of bounds-checking every point.
+ */
+export declare function decodeColumn(buf: ArrayBuffer, meta: SpatialColumnMeta, count: number): SpatialColumn;
+/**
+ * `GET /polygons` → boundary rings. Layout is
+ * `[u32 count][u32 offsets × (count+1)][f32 coords × 2·offsets[count]]`; every
+ * field is 4-byte wide so each typed-array view stays aligned.
+ */
+export declare function decodePolygons(buf: ArrayBuffer): SpatialPolygons;
+/**
+ * Fold a manifest plus its fetched coordinate/id/radius vectors into the
+ * library-facing {@link SpatialDataset}. Column and feature *values* are not
+ * part of this — they stay lazy behind the port.
+ */
+export declare function datasetFromManifest(manifest: SpatialManifest, coords: Pick<SpatialObservations, 'x' | 'y' | 'z'>, extras?: {
+    ids?: string[];
+    radius?: Float32Array;
+}): SpatialDataset;

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;
+}