@jax-data-science/sci-image-visualizer 0.3.3 → 0.4.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/routing-visualizer.service.d.ts

@@ -6,7 +6,10 @@ import { ClassPreset, PresetSet } from './models/class-preset';
 import { PlotlyService } from './implementations/plotly/plotly.service';
 import { OpenSeadragonVisualizerService } from './implementations/osd/openseadragon-visualizer.service';
 import { PlotType, PlotTypeDescriptor } from './contracts/plot-type';
-import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from './contracts/visualizer.contract';
+import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls, ISpatialControls } from './contracts/visualizer.contract';
+import { SpatialDataPort } from './contracts/ports/spatial-data.port';
+import { RegionStore } from './store/region-store.service';
+import { SpatialSelectionStore } from './store/spatial-selection.service';
 import { ViewerCapabilities } from './contracts/capabilities.contract';
 import { IRegionOverlay } from './contracts/region-overlay.contract';
 import { IRegionEditorApi } from './contracts/region-editor-api.contract';
@@ -21,6 +24,9 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     private napari;
     private store;
     private config;
+    private regionStore;
+    private selectionStore;
+    private spatialData;
     private currentPlotType;
     private lastRendered;
     /** OSD failed for the *current* render cycle (e.g. a fresh file still caching
@@ -32,12 +38,18 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** napari-js failed for the current render cycle → fall back to OSD (then Plotly).
      *  Reset by reset() at the start of every cycle, like {@link osdFellBack}. */
     private napariFellBack;
-    constructor(plotly: PlotlyService, osd: OpenSeadragonVisualizerService, napari: NapariVisualizerService, store: VisualizerStore, config: VizConfig);
+    constructor(plotly: PlotlyService, osd: OpenSeadragonVisualizerService, napari: NapariVisualizerService, store: VisualizerStore, config: VizConfig, regionStore: RegionStore, selectionStore: SpatialSelectionStore, spatialData?: SpatialDataPort | null);
     private isImageType;
-    /** The 2D napari types (image + region-centroid scatter) — a 2D fallback chain (OSD, then Plotly). */
+    /** The 2D napari types (image, region-centroid scatter, spatial omics) — a 2D fallback chain
+     *  (OSD, then Plotly).
+     *
+     *  NOTE for SPATIAL_OMICS: only napari-js draws the observation markers. If it fails (no WebGPU,
+     *  device loss) the fallback renders the tissue image ALONE — the spatial layer is absent, not
+     *  degraded. That is deliberate for now: showing the slide beats showing nothing, and a Plotly
+     *  `scattergl` spatial mode is the planned real fallback (see the plot-mode design doc). */
     private isNapariImageType;
-    /** The 3D napari types (volume/isosurface, either resolution) — no 2D fallback exists (OSD is
-     *  image-only), so they fall straight to Plotly. */
+    /** The 3D napari types (volume/isosurface/surface/scatter, plus the 3D spatial cloud) — no 2D
+     *  fallback exists (OSD is image-only), so they fall straight to Plotly. */
     private isNapari3dType;
     /**
      * Backend to attempt for the current plot type this render. The fallback chains below are
@@ -207,6 +219,33 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** Intensity (line-ROI) controls — always Plotly's, since the line profiles
      *  render their inset on Plotly regardless of which backend draws the image. */
     getIntensityControls(): IIntensityControls | null;
+    /**
+     * Spatial-omics controls, or null when no `SPATIAL_DATA_PORT` is bound.
+     *
+     * Implemented HERE rather than on a backend because the state is
+     * backend-neutral: the view state lives in the shared `VisualizerStore` (like
+     * the colormap), so the controls keep working across a plot-type switch and a
+     * host can drive them before any backend has mounted.
+     */
+    getSpatialControls(): ISpatialControls | null;
+    /**
+     * Whether `dataset` can answer this colour source.
+     *
+     * A column is checkable against the declared list. A gene is checkable only when
+     * the dataset inlines its feature names — a dataset too wide to inline them
+     * (typeahead-only) keeps the source, and a name that turns out not to exist
+     * surfaces as the chart's "could not be charted" rather than as a silent reset.
+     */
+    private canColorBy;
+    /** Memoised so consumers can hold the object across calls. */
+    private spatialControls;
+    /** Latest dataset, mirrored so `selectFromRegions()` can answer synchronously
+     *  — it runs from a button click and must not await a round-trip. */
+    private currentSpatialDataset;
+    /** Displayed slice. Only a volume-backed spatial dataset reads it, to keep a
+     *  region drawn over one section from selecting the whole depth behind it. */
+    private currentZIndex;
+    private spatialDatasetSub;
     /** Load pixel frames for intensity sampling when OpenSeadragon owns the image
      *  (it doesn't feed Plotly's frame cache). No-op needed when Plotly renders. */
     ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
@@ -223,6 +262,6 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
      *  ROI at display resolution (sampling always lives in Plotly). */
     refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
     unsubscribe(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, [null, null, null, null, null, null, null, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RoutingVisualizerService>;
 }

package/lib/spatial/embedding-compute.d.ts

@@ -0,0 +1,73 @@
+import { SpatialEmbedding, SpatialEmbeddingMeta } from '../contracts/spatial-dataset.contract';
+/**
+ * Run a t-SNE in a Web Worker and report progress.
+ *
+ * The panel offers this for a dataset that publishes no t-SNE — a dropped-in `.h5ad`
+ * typically carries one UMAP and nothing else. The server reduces to PCA (it needs the
+ * whole expression matrix, which the browser should not download); this takes those
+ * scores and embeds them here, where the GPU is.
+ *
+ * A thin wrapper on purpose: no Angular, no store. It owns one worker and one run, so a
+ * component can hold it, show a progress bar, and cancel — and so the whole thing can be
+ * tested by substituting a worker.
+ */
+export interface ComputeProgress {
+    /** 0..1, or null before the first report — a run starts with kNN and P, not iterations. */
+    fraction: number | null;
+    /** 'webgpu', 'wasm' or 'cpu' once known: it changes what a long wait means. */
+    backend: string | null;
+    message: string | null;
+}
+export interface ComputeRequest {
+    /** PCA scores, row-major `nObs x nDims`. */
+    scores: Float32Array;
+    nObs: number;
+    nDims: number;
+    dims: 2 | 3;
+    perplexity?: number;
+    iterations?: number;
+    seed?: number;
+}
+/** Factory, so a test can supply a worker without a bundler. */
+export type WorkerFactory = () => Worker;
+export declare class EmbeddingComputeRun {
+    private readonly factory?;
+    private worker;
+    private settled;
+    /**
+     * Settles a run that is still waiting, set for as long as one is.
+     *
+     * `terminate()` is called from outside — a dataset switch, a component being destroyed —
+     * and killing the worker on its own leaves the promise `run()` returned pending FOR
+     * EVER, because the settlement it was waiting for arrives as a worker message. The
+     * awaiting closure, and everything it captured, is retained with it. So termination
+     * settles the run itself.
+     */
+    private abandon;
+    /**
+     * `factory` is optional: without one the real worker module is imported on demand.
+     *
+     * Dynamically, and that is not laziness for its own sake — the module holds an
+     * `import.meta.url`, which ts-jest's CommonJS compile rejects outright, so a static
+     * import here would break every spec that touches this file.
+     */
+    constructor(factory?: WorkerFactory | undefined);
+    /**
+     * Start a run. Resolves with the coordinates, or null if cancelled.
+     *
+     * Rejects only on a real failure. Cancellation is a NULL rather than a rejection: a user
+     * pressing Cancel is not an error, and making callers tell the two apart in a catch
+     * block is how a cancelled run ends up reported as a crash.
+     */
+    run(request: ComputeRequest, meta: SpatialEmbeddingMeta, onProgress: (progress: ComputeProgress) => void): Promise<SpatialEmbedding | null>;
+    /** Ask the run to stop. It resolves with null shortly after. */
+    cancel(): void;
+    /**
+     * Stop immediately, abandoning any result. Safe to call twice.
+     *
+     * Unlike {@link cancel}, this does not wait for the worker to acknowledge — the run is
+     * settled here, with null, because nothing is left to deliver the answer.
+     */
+    terminate(): void;
+    get running(): boolean;
+}

package/lib/spatial/gene-search.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Narrowing a gene list to the handful a picker should actually render.
+ *
+ * A targeted panel has a few hundred genes and can simply be listed. A
+ * whole-transcriptome assay has ~18k-31k, and handing that many options to a dropdown
+ * costs a visible freeze on every keystroke — the control rebuilds and re-filters the
+ * whole array, and the browser lays out what the virtual scroller has not yet clipped.
+ * Measured on the Visium H&E bundle: 18,078 names.
+ *
+ * The names themselves are cheap to hold — strings already parsed from the manifest — so
+ * this does not fetch anything. What it caps is how many OPTION OBJECTS are ever
+ * materialised for the view. The rest of the corpus stays a plain array, searched per
+ * keystroke, which is the work a dropdown was doing anyway; the saving is in not asking
+ * a component to render, diff and re-filter thousands of rows it will never show.
+ *
+ * Ranking is PREFIX FIRST, then substring. Typing "Mb" should surface `Mbp` above
+ * `Adam1b`, which a plain `includes` would not do. It deliberately mirrors the example
+ * server's `/spatial/:id/features?q=` (see `lib/spatial.mjs`) so a dataset that inlines
+ * its names and one that does not order their suggestions the same way — the picker must
+ * not appear to rank differently depending on how the data happens to be served.
+ *
+ * Pure — no Angular, no port, no DOM — like `spatial-heatmap.ts`, and tested the same way.
+ */
+/**
+ * How many options a picker will materialise at once.
+ *
+ * Above the virtual-scroll threshold, so a capped list is still scrolled rather than laid
+ * out in full, and far below the point where rebuilding the array is perceptible.
+ */
+export declare const GENE_OPTIONS_MAX = 500;
+/**
+ * The best `limit` matches for `query`, prefix matches first.
+ *
+ * An empty query returns the head of the list rather than nothing: the dropdown opens
+ * before anything is typed, and an empty menu reads as "no genes" rather than "start
+ * typing". Matching is case-insensitive, because gene symbols are capitalised by
+ * convention and nobody types `Slc17a7` exactly.
+ */
+export declare function searchGeneNames(names: readonly string[], query: string, limit?: number): string[];
+/**
+ * The options a picker should show: the best matches, plus anything already chosen.
+ *
+ * A multi-select whose option list is capped must still carry its SELECTED values, or the
+ * control cannot resolve them — the chips lose their labels and, worse, a value absent
+ * from the options can be dropped from the model on the next change. Selections come
+ * first so they stay visible while a search narrows everything else.
+ */
+export declare function geneOptionsFor(names: readonly string[], query: string, selected?: readonly string[], limit?: number): string[];