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

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

@@ -1,13 +1,15 @@
+import { OnDestroy } from '@angular/core';
 import { Observable } from 'rxjs';
 import { Image } from 'image-js';
 import { IImageInfo, IImageMetadata } from './contracts/image.contract';
-import { Region } from './models/region';
+import { Polygon, Region } from './models/region';
 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, ISpatialControls } from './contracts/visualizer.contract';
+import { IVisualizer, LoadedImage, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls, ISpatialControls, IIntensitySampling, IOsdViewOptions, IVolumeResolution } from './contracts/visualizer.contract';
 import { SpatialDataPort } from './contracts/ports/spatial-data.port';
+import { CanvasToolOptions, ColormapNode, IBrushOptions, IWandOptions } from './contracts/display-types';
 import { RegionStore } from './store/region-store.service';
 import { SpatialSelectionStore } from './store/spatial-selection.service';
 import { ViewerCapabilities } from './contracts/capabilities.contract';
@@ -18,8 +20,30 @@ 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 { IntensityProfileService } from './intensity/intensity-profile.service';
 import * as i0 from "@angular/core";
-export declare class RoutingVisualizerService implements IVisualizer, IRegionEditorApi, IChannelHistogramApi {
+/**
+ * The visualizer chain's front door: implements `IVisualizer`, `IRegionEditorApi`
+ * and `IChannelHistogramApi` (bound to the `VISUALIZER` / `REGION_EDITOR_API` /
+ * `CHANNEL_HISTOGRAM_API` tokens) over three rendering backends, chosen per plot type:
+ *  - **Image** renders through OpenSeadragon (natively tiled, region tools,
+ *    client-side colormap), or through napari-js when `VizConfig.useNapariRenderer`
+ *    opts in; the napari image types and the 2D spatial-omics mode render through
+ *    napari-js. A failed load falls back napari-js → OSD → Plotly for that image only
+ *    (see `napariFellBack` / `osdFellBack`, cleared by `reset()`).
+ *  - the napari 3D types (volume, isosurface, surface, 3D scatter, the 3D spatial
+ *    cloud) render through napari-js, falling back to Plotly.
+ *  - every other plot type (heatmap, contour, surface, scatter, line, …) renders
+ *    through Plotly.
+ *
+ * Only rendering and the viewport are routed to the backend on screen. Region state
+ * lives in the shared `RegionStore` and display state (colormap, channels, presets,
+ * spatial view) in the shared `VisualizerStore`, so every backend sees the same
+ * values; the backends subscribe to them to redraw.
+ *
+ * Package-internal: hosts depend on the tokens, not on this class.
+ */
+export declare class RoutingVisualizerService implements IVisualizer, IRegionEditorApi, IChannelHistogramApi, OnDestroy {
     private plotly;
     private osd;
     private napari;
@@ -27,6 +51,7 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     private config;
     private regionStore;
     private selectionStore;
+    private intensity;
     private spatialData;
     private currentPlotType;
     private lastRendered;
@@ -39,7 +64,11 @@ 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, regionStore: RegionStore, selectionStore: SpatialSelectionStore, spatialData?: SpatialDataPort | null);
+    /** The file name of the image last plotted (names a GeoJSON export). */
+    private plottedFileName;
+    /** The div the backends render into (every backend shares it); '' before the first plot. */
+    private plotDiv;
+    constructor(plotly: PlotlyService, osd: OpenSeadragonVisualizerService, napari: NapariVisualizerService, store: VisualizerStore, config: VizConfig, regionStore: RegionStore, selectionStore: SpatialSelectionStore, intensity: IntensityProfileService, spatialData?: SpatialDataPort | null);
     private isImageType;
     /** The 2D napari types (image, region-centroid scatter, spatial omics) — a 2D fallback chain
      *  (OSD, then Plotly).
@@ -64,19 +93,33 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     /** Backend currently on screen — what ongoing zoom/tool/region ops act on. */
     private renderer;
     get capabilities(): ViewerCapabilities;
-    load(imageInfo: IImageInfo, zIndex: number): Promise<any>;
+    load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<LoadedImage>;
     /** Try OSD; on failure fall back to Plotly for this image (not permanent — see reset()). */
     private loadViaOsdThenPlotly;
-    plot(plotDiv: string, imageLoaded: any, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
+    plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, inPlace?: boolean): Promise<boolean>;
     reloadAndPlot(): void;
     reset(): void;
     relayout(trueImageSize?: number[]): void;
     resetAxes(): void;
+    fitToView(): void;
+    /** @deprecated Use {@link fitToView}. */
     autoscale(): void;
     zoomIn(): void;
     zoomOut(): void;
     setDragMode(mode: string | false): void;
+    /** Every backend, on screen or not. */
+    private backends;
+    /**
+     * The navigator / smoothing options, applied to EVERY backend that has them (not
+     * just the active renderer): consumers set them before the first render, when
+     * `renderer()` is still the Plotly default, and OSD/napari-js must receive them
+     * to honour them at viewer creation.
+     */
+    getOsdViewOptions(): IOsdViewOptions;
+    private readonly viewOptions;
+    /** @deprecated Use `getOsdViewOptions().setNavigatorVisible()`. */
     setNavigatorVisible(visible: boolean): void;
+    /** @deprecated Use `getOsdViewOptions().setImageSmoothingEnabled()`. */
     setImageSmoothingEnabled(enabled: boolean): void;
     setShowStack(showstack: boolean): void;
     setZIndex(zIndex: number): void;
@@ -95,9 +138,15 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     downloadImage(): void;
     exportComposite(): void;
     setPlotType(plotType: PlotType): void;
+    /** @deprecated Use `getSurface3dControls()`. */
     setSurfaceDragMode(mode: string): void;
+    /** @deprecated Use `getSurface3dControls()`. */
     resetSurfaceCamera(): void;
+    /** The 3D decimate factor of the backend on screen (napari-js), else null. */
+    getVolumeResolution(): IVolumeResolution | null;
+    /** @deprecated Use `getVolumeResolution()?.set()`. */
     setResolutionScale(scale: number): void;
+    /** @deprecated Use `getVolumeResolution()?.get()`. */
     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). */
@@ -107,13 +156,14 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     cancelLoading(): void;
     isStackLoading(): Observable<boolean>;
     getStackLoadingProgress(): Observable<number>;
-    getAutoscaleEvent(): Observable<any>;
+    getAutoscaleEvent(): Observable<void>;
+    /** The line-ROI profiles: sampled by the backend-neutral IntensityProfileService. */
     getIntensityProfile$(): Observable<IntensityProfile[]>;
     renderIntensityInset(divId: string, profiles: IntensityProfile[]): void;
     setRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string, append?: boolean): void;
     getRegions(): Region[];
-    getRegionPolygons(): any[];
-    getRegionUpdateEvent(): Observable<any[]>;
+    getRegionPolygons(): Polygon[];
+    getRegionUpdateEvent(): Observable<Region[]>;
     setSelectedShapeIndices(indices: number[]): void;
     selectRegion(region: Region): void;
     getSelectedShapeIndices$(): Observable<number[]>;
@@ -129,9 +179,6 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     upsertClass(preset: ClassPreset): void;
     removeClass(name: string): void;
     resetPresets(): void;
-    plotPreviousShapes(): void;
-    setPreviousShapes(shapes: any[]): void;
-    getPreviousShapes(): any[];
     undo(): void;
     redo(): void;
     canUndo(): boolean;
@@ -140,6 +187,7 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     getCanRedo$(): Observable<boolean>;
     resetUndoHistory(): void;
     importRegions(geoJsonStr: string): Region[];
+    /** Download `regions` as GeoJSON, named after the image last plotted. */
     exportRegions(regions: Region[]): void;
     getGeoJsonString(regions: Region[]): string;
     enterStackMode(slices: Map<number, Region[]>, initialZ?: number, saveLayout?: 'combined' | 'per-slice-file'): void;
@@ -170,26 +218,32 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
     setAnnotationRegions(regions: Region[], showRegionLabel?: boolean, isRegionSaveOn?: boolean, fillColor?: string): void;
     getSelectedRegions$(): Observable<Region[]>;
     setSelectedRegions(regions: Region[]): void;
-    setWandMode(active: boolean, options?: any): void;
-    setWandOptions(options: any): void;
+    setActiveTool(id: string | null, options?: CanvasToolOptions): void;
+    /** @deprecated Use {@link setActiveTool}. */
+    setWandMode(active: boolean, options?: IWandOptions): void;
+    setWandOptions(options: IWandOptions): void;
     clearActiveWandRegion(): void;
-    setBrushMode(active: boolean, options?: any): void;
-    setBrushOptions(options: any): void;
+    /** @deprecated Use {@link setActiveTool}. */
+    setBrushMode(active: boolean, options?: IBrushOptions): void;
+    setBrushOptions(options: IBrushOptions): void;
+    /** @deprecated Use {@link setActiveTool}. */
     setVertexEraserMode(active: boolean): void;
     setVertexEraserRadius(radius: number): void;
+    /** @deprecated Use {@link setActiveTool}. */
     setZoomToBoxMode(active: boolean): void;
     segmentRectangles(): Promise<number>;
     segmentRectanglesCellpose(): Promise<number>;
     setSamModel(id: string): void;
+    /** @deprecated Use {@link setActiveTool}. */
     setSamPointMode(active: boolean): void;
     commitSamPoints(): void;
     clearSamPoints(): void;
-    getColormap(): Observable<any>;
-    setColormap(colormap: any): void;
-    getColormapOptions(): any;
+    getColormap(): Observable<ColormapNode | null>;
+    setColormap(colormap: ColormapNode): void;
+    getColormapOptions(): ColormapNode[];
     getReverseScale(): Observable<boolean>;
-    setReverseScale(reverscale: any): void;
-    setImageMeta(imageMeta: IImageMetadata[]): void;
+    setReverseScale(reverse: boolean): void;
+    setImageMeta(imageMeta: IImageMetadata[], imageKey?: string): void;
     getImageMeta(): Observable<IImageMetadata[]>;
     getHistogram(channelIndex: number, bins: number): IHistogram | null;
     getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
@@ -212,60 +266,58 @@ export declare class RoutingVisualizerService implements IVisualizer, IRegionEdi
      * usable overlay.
      */
     getRegionOverlay(): IRegionOverlay;
-    /**
-     * Isosurface controls when available — always Plotly's, since the isosurface
-     * plot type renders on Plotly (OSD only handles the image type).
-     */
+    /** Isosurface controls of the backend on screen, when it renders isosurfaces. */
     getIsosurfaceControls(): IIsosurfaceControls | null;
-    /** 3D scene controls — always Plotly's, since the 3D plot types render on
-     *  Plotly (OSD only handles the image type). */
+    /** 3D scene controls of the backend on screen (Plotly or napari-js), or null on a
+     *  2D-only one. */
     getSurface3dControls(): ISurface3dControls | null;
-    /** Intensity (line-ROI) controls — always Plotly's, since the line profiles
-     *  render their inset on Plotly regardless of which backend draws the image. */
+    /** Intensity (line-ROI) controls, whichever backend draws the image: the
+     *  IntensityProfileService adds the line to the store, and every backend
+     *  (Plotly included) draws it from the store's update event. */
     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.
+     * Spatial-omics controls, or null when no `SPATIAL_DATA_PORT` is bound. Served by a
+     * backend-neutral {@link SpatialControlsFacade} (state in the shared stores), so the
+     * controls work across a plot-type switch and 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;
+    /** Created on first use; owns the dataset subscription. */
+    private spatialFacade;
     /** 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. */
+    /** Angular calls this when the injector providing the router is destroyed — the host
+     *  component for a `provideVisualization()` chain. The dataset subscription would
+     *  otherwise keep the whole isolated chain reachable from the root data port. */
+    ngOnDestroy(): void;
+    /**
+     * Intensity-profile sampling, whichever backend is on screen: the sampling is the
+     * backend-neutral IntensityProfileService's; the viewport changes come from every
+     * backend that reports them (OpenSeadragon, napari-js), merged into one stable
+     * stream the inset subscribes to once.
+     */
+    getIntensitySampling(): IIntensitySampling;
+    private readonly intensitySampling;
+    /** @deprecated Use `getIntensitySampling().ensureIntensitySampling()`. */
     ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
-    /** Visible-region changes from the OpenSeadragon viewer (image-pixel coords),
-     *  so the intensity inset can re-sample at the current zoom level. Plotly's own
-     *  high-def zoom updates the sampling cache inline, so only OSD feeds this. */
+    /** Crops for sampling are sized from the plot div (whichever backend renders into it). */
+    private pointSamplingAtPlot;
+    /** @deprecated Use `getIntensitySampling().getViewportChange$()`. */
     getViewportChange$(): Observable<{
         x: number;
         y: number;
         width: number;
         height: number;
     }>;
-    /** Re-sample the intensity profiles from a fresh crop of the given image-pixel
-     *  ROI at display resolution (sampling always lives in Plotly). */
+    /** @deprecated Use `getIntensitySampling().refreshIntensitySamplingForRoi()`. */
     refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+    /** The visualizer view is going away: detach every backend — dropping their view-bound
+     *  subscriptions and disposing the napari-js viewer, whose canvas, render loop and GPU
+     *  buffers would otherwise outlive the view (for a component-scoped chain, forever).
+     *  Nothing is on screen afterwards, so the next plot starts from the default backend. */
+    detach(): void;
+    /** @deprecated Use {@link detach}. */
     unsubscribe(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, [null, null, null, null, null, null, null, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RoutingVisualizerService, [null, null, null, null, null, null, null, null, { optional: true; }]>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RoutingVisualizerService>;
 }

package/lib/spatial/density-raster.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The transcript-density raster's window. Its default colour scale is matplotlib's
+ * inferno (`INFERNO_LUT` from napari-js/colormaps), as in Xenium Explorer.
+ */
+/** A density window from the non-empty bins: 1st to 99th percentile. */
+export declare function densityAutoRange(values: ArrayLike<number>): [number, number];

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

@@ -0,0 +1,123 @@
+import { BehaviorSubject } from 'rxjs';
+import type { SpatialEmbedding, SpatialEmbeddingMeta } from '../contracts/spatial-dataset.contract';
+/** Where a browser-side embedding computation stands, for the progress bar and messages. */
+export interface EmbeddingComputeState {
+    /** True while a run is going. */
+    running: boolean;
+    /** 0..1 while running, or null before the first report. */
+    fraction: number | null;
+    /** Which backend the worker got — 'webgpu', 'wasm' or 'cpu'. */
+    backend: string | null;
+    message: string | null;
+    error: string | null;
+}
+/** Where the PCA scores come from: a port that serves embeddings by name. */
+export type EmbeddingSource = (name: string) => Promise<SpatialEmbedding>;
+/**
+ * Largest dataset a t-SNE is offered for in the browser.
+ *
+ * t-SNE is O(N²) per iteration — vectorised on the GPU, but not approximated — so the cost
+ * is quadratic in observations. Measured end to end in Firefox on WebGPU: 2,688 points took
+ * 95 s. That scales to roughly five and a half minutes at this threshold, and to about 76
+ * minutes at seqFISH's 19,416, which was also measured offline.
+ *
+ * Past this the option is WITHDRAWN rather than offered with a warning. An hour-long job
+ * started from a button is not a choice a reader can meaningfully consent to in a dialog,
+ * and a t-SNE that large belongs in the offline pipeline, where it can run once and be
+ * served to everyone.
+ */
+export declare const BROWSER_TSNE_MAX_OBSERVATIONS = 5000;
+/**
+ * A t-SNE the dataset does not publish, offered so it can be computed here.
+ *
+ * A dropped-in `.h5ad` typically carries one UMAP and a PCA, and no t-SNE — the two views
+ * answer different questions, so having only one is a real gap. Computing it needs no
+ * expression data: t-SNE runs on the PCA scores, which is why this can happen in the
+ * browser at all while PCA cannot.
+ */
+export declare const COMPUTABLE_EMBEDDINGS: readonly SpatialEmbeddingMeta[];
+/** Roughly how long a t-SNE of `n` observations takes, in seconds, from the measured anchor. */
+export declare function tsneEstimateSeconds(n: number): number;
+/** A duration as something to put on a button: `~42s`, `~6 min`. */
+export declare function estimateLabel(seconds: number): string;
+/**
+ * The browser-side embedding computation behind the charts' Embedding tab: which
+ * embeddings to offer for a dataset, the t-SNE run itself (PCA scores from the port, then a
+ * worker), its progress, and the results computed this session.
+ *
+ * A run is several awaits long — the PCA scores arrive over HTTP, then the worker takes a
+ * minute or more — and the dataset can change at any of them, including before the run
+ * exists to be terminated. Every await is checked against a {@link Supersede} that a
+ * dataset switch ({@link setDataset}) or teardown ({@link abandon}) cancels, so the scores
+ * fetched for one dataset are never embedded and drawn over another's observations.
+ *
+ * Plain class: the owner renders {@link state} (or {@link state$}).
+ */
+export declare class EmbeddingComputeCoordinator {
+    readonly state$: BehaviorSubject<EmbeddingComputeState>;
+    /** True when a t-SNE is missing but the dataset is too big to embed here. */
+    tooLarge: boolean;
+    /** Observations in the live dataset, kept for the cost estimate. */
+    observationCount: number;
+    /** Coordinates computed in this browser, by name. Not persisted: a reload recomputes. */
+    private readonly computed;
+    /** The live run, when one is going. */
+    private run;
+    private readonly load;
+    get state(): EmbeddingComputeState;
+    get running(): boolean;
+    /**
+     * A new dataset: drop everything computed or computing for the previous one, and return
+     * the embeddings to offer — the published ones, plus a t-SNE to compute where the dataset
+     * has a PCA to embed, no t-SNE of its own, and is small enough. Otherwise the menu would
+     * advertise work that cannot start, or duplicate what is already served.
+     */
+    setDataset(published: readonly SpatialEmbeddingMeta[], observationCount: number): SpatialEmbeddingMeta[];
+    /** Whether `meta` is one this browser would have to compute. */
+    isComputable(meta: SpatialEmbeddingMeta | null): boolean;
+    /** Whether `meta` has already been computed this session. */
+    isComputed(meta: SpatialEmbeddingMeta | null): boolean;
+    /** The coordinates computed for `name`, if any. */
+    result(name: string): SpatialEmbedding | undefined;
+    /** Roughly how long a run would take here, in seconds. Shown before the click: a progress
+     *  bar tells you a job is going; only an estimate tells you whether to start it. */
+    get estimateSeconds(): number;
+    /** {@link estimateSeconds} as something to put on a button. */
+    get estimateLabel(): string;
+    /** Why the option is absent, when a dataset is past the threshold. */
+    get tooLargeNote(): string;
+    /**
+     * Compute `meta` here, in a worker, from the dataset's PCA among `embeddings`.
+     *
+     * The PCA scores come from the port as an ordinary embedding — the server derives them,
+     * because PCA needs the whole expression matrix (185 MB for a Visium dataset) while
+     * t-SNE needs only the scores (0.51 MB). Sending the matrix to the browser to save a few
+     * seconds of arithmetic would be a far slower answer.
+     *
+     * @returns the coordinates, to draw — or null when there is nothing to draw: cancelled,
+     *   abandoned, failed (see {@link state}), or already running.
+     */
+    start(meta: SpatialEmbeddingMeta, embeddings: readonly SpatialEmbeddingMeta[], getEmbedding: EmbeddingSource): Promise<SpatialEmbedding | null>;
+    /** The user's Cancel: ask the worker to stop. The run settles shortly after, with nothing. */
+    cancel(): void;
+    /**
+     * Drop any computation in progress, because what it is computing no longer applies.
+     *
+     * Distinct from {@link cancel}: this does not wait — the run is settled and the worker
+     * killed, so a dataset switch or a teardown cannot leave a t-SNE grinding on in the
+     * background over observations nothing is showing any more.
+     */
+    abandon(): void;
+    private patch;
+}
+/**
+ * The dataset's PCA, as row-major scores.
+ *
+ * Assembled from whichever PCA the source offers, widest first — a 3-D one gives t-SNE
+ * three components instead of two for the same request.
+ */
+export declare function loadPcaScores(embeddings: readonly SpatialEmbeddingMeta[], getEmbedding: EmbeddingSource): Promise<{
+    scores: Float32Array;
+    nObs: number;
+    nDims: number;
+} | null>;

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

@@ -18,6 +18,7 @@ export interface ComputeProgress {
     backend: string | null;
     message: string | null;
 }
+/** One t-SNE to compute: the PCA scores to embed and the run's parameters. */
 export interface ComputeRequest {
     /** PCA scores, row-major `nObs x nDims`. */
     scores: Float32Array;
@@ -28,12 +29,30 @@ export interface ComputeRequest {
     iterations?: number;
     seed?: number;
 }
-/** Factory, so a test can supply a worker without a bundler. */
-export type WorkerFactory = () => Worker;
+/**
+ * Factory, so a test can supply a worker without a bundler. May be asynchronous, as the
+ * default one is: it imports the worker module on demand.
+ */
+export type WorkerFactory = () => Worker | Promise<Worker>;
+/**
+ * One t-SNE run in its own worker: start it, follow its progress, cancel it. Single use —
+ * a new computation takes a new run.
+ */
 export declare class EmbeddingComputeRun {
     private readonly factory?;
     private worker;
     private settled;
+    /**
+     * Between `run()` being called and the worker existing.
+     *
+     * The default factory imports the worker module first, and a dataset switch or a
+     * teardown can call {@link terminate} in that window. With no worker yet there is
+     * nothing to kill, so terminating bumps {@link generation} instead and the run stops
+     * itself the moment the worker arrives, before posting it any work.
+     */
+    private starting;
+    /** Bumped by {@link terminate}; a run that finds it changed across its await gives up. */
+    private generation;
     /**
      * Settles a run that is still waiting, set for as long as one is.
      *

package/lib/spatial/glyphs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Transcript "icon" mode: the marker shapes, and their outlines for the panel's previews.
+ * The napari view draws them as napari-js point symbols (`GLYPH_SYMBOLS` in
+ * `spatial-tiles/transcript-layers.ts`), with these outlines' proportions.
+ */
+/** Marker shapes for the transcript "icon" mode. */
+export declare const TRANSCRIPT_GLYPHS: readonly ["circle", "star", "triangle", "square", "diamond", "cross", "hexagon", "triangle-down", "pentagon", "x"];
+/** One of the marker shapes in {@link TRANSCRIPT_GLYPHS}. */
+export type TranscriptGlyph = (typeof TRANSCRIPT_GLYPHS)[number];
+/**
+ * Unit outline of a glyph, radius ≈ 1, centred on the origin, as `[x0, y0, x1, y1, …]` — the
+ * panel's preview of the point symbol the canvas draws.
+ */
+export declare function glyphOutline(glyph: TranscriptGlyph): Float32Array;
+/** The glyph a gene gets by default: by its position in the selected list. */
+export declare function defaultGlyphFor(slot: number): TranscriptGlyph;

package/lib/spatial/lod.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Level-of-detail planning for tiled spatial geometry — cell outlines and transcripts.
+ *
+ * The renderer knows its camera (a world-space centre, a zoom in canvas pixels per world
+ * unit, a canvas size); a tiled dataset knows its grids (one per level, in observation
+ * units). This module is the bridge: which level the zoom calls for and which tiles are on
+ * screen. Everything here is pure, so the policy — the part that decides whether the view
+ * is fast and legible — is testable without a GPU.
+ *
+ * Observation units map onto world units through the dataset's `imageRef` affine
+ * (`world = data · scale + translate`), so "pixels per observation unit" is
+ * `zoom · scale`. For a Xenium bundle the data unit is the micron and the world unit the
+ * morphology pixel.
+ */
+import type { SpatialBounds, SpatialDataset, SpatialImageRef, SpatialTileLevel } from '../contracts/spatial-dataset.contract';
+import type { SpatialViewState } from '../contracts/display-types';
+/** A rectangle in observation coordinates. */
+export interface DataRect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** Tile address. */
+export interface TileKey {
+    level: number;
+    gx: number;
+    gy: number;
+}
+/** Whether cell outlines are drawn: the user's choice, else on when the dataset has any. */
+export declare function cellsShown(dataset: Pick<SpatialDataset, 'polygonTiles' | 'polygons'> | null, view: Pick<SpatialViewState, 'showCells'>): boolean;
+/** A column holding a hand-curated cell-type annotation, by naming convention. */
+export declare function isCuratedColumn(name: string): boolean;
+/**
+ * The categorical column that names each cell's type: the view's choice when it is a
+ * column of this dataset, else the first categorical column that is not a curated
+ * annotation (a pipeline's clustering is the default; curation is opted into), else
+ * any categorical column.
+ */
+export declare function cellTypeColumnFor(dataset: SpatialDataset, view: Pick<SpatialViewState, 'cellTypeColumn'>): string | null;
+/** A stable string id for a tile key, `level/gx/gy` — usable as a Map key. */
+export declare function tileId(k: TileKey): string;
+/** Canvas pixels per observation unit along x, for a camera zoom and a data→world affine. */
+export declare function pixelsPerDataUnit(zoom: number, ref?: SpatialImageRef | null): number;
+/**
+ * The part of observation space the camera shows, padded by `margin` (a fraction of the
+ * viewport) so tiles just off screen are already there when a pan brings them in: napari-js's
+ * `worldViewport`, mapped back through the inverse of the data→world affine.
+ */
+export declare function visibleDataRect(center: readonly [number, number], zoom: number, canvasW: number, canvasH: number, ref?: SpatialImageRef | null, margin?: number): DataRect | null;
+/**
+ * Tiles of one level intersecting `rect`, clipped to the dataset's `bounds` (so zooming
+ * out over empty canvas does not ask for tiles that cannot exist). Ordered from the
+ * rectangle's centre outward, so the middle of the screen fills in first.
+ *
+ * Tile `g` covers `[g·s, (g+1)·s)`. The view's far edge is open — a tile starting exactly
+ * at `rect.x1` shows nothing — but the bounds' far edge is closed: the bounds are the
+ * extreme observations' coordinates, so one sits exactly on `bounds[2]`, in the tile
+ * starting there.
+ */
+export declare function tilesInRect(rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
+/** {@link tilesInRect} for a grid whose tile (0, 0) starts at `origin`. */
+export declare function tilesInRectFrom(origin: readonly [number, number], rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
+/** Area of `rect` inside `bounds` (the whole rect when there are none). */
+export declare function visibleArea(rect: DataRect, bounds?: SpatialBounds | null): number;
+/**
+ * Typical cell diameter, in observation units, used to judge how large cells appear.
+ * Derived from the per-observation radius when there is one; 12 µm otherwise.
+ */
+export declare function typicalCellDiameter(radius: Float32Array | number | undefined, fallback?: number): number;
+/**
+ * On-screen cell diameter (px) at or above which each polygon level is used. A level
+ * halves the vertices of the one below, so each should take over when the cell is about
+ * half as large on screen. Below the last finite threshold outlines are not drawn at
+ * all — a cell a few pixels wide is a dot, and the observation markers already draw it
+ * as one.
+ *
+ * Xenium's fourth level (3 vertices per cell) is deliberately never used: seen on
+ * screen it is a field of triangles, which reads as an artefact rather than as cells.
+ * The dots below 8 px say the same thing more honestly.
+ */
+export declare const POLYGON_LEVEL_MIN_CELL_PX: number[];
+/**
+ * Which polygon level suits this zoom, or -1 for "too small to outline".
+ * `detail` > 1 prefers finer levels (sharper, slower); < 1 coarser.
+ */
+export declare function polygonLevelFor(pxPerUnit: number, cellDiameter: number, levelCount: number, detail?: number): number;
+/**
+ * Which transcript level suits this zoom: the one whose tiles come out closest to
+ * `targetTilePx` on screen. Coarser levels aggregate more, so this keeps the number of
+ * markers per screen roughly constant however far out the camera is — the property that
+ * keeps the view fast.
+ */
+export declare function transcriptLevelFor(pxPerUnit: number, levels: readonly SpatialTileLevel[], targetTilePx?: number): number;

package/lib/spatial/spatial-controls.facade.d.ts

@@ -0,0 +1,64 @@
+import { Observable } from 'rxjs';
+import { PlotType } from '../contracts/plot-type';
+import { SpatialDataPort } from '../contracts/ports/spatial-data.port';
+import { SpatialObservations } from '../contracts/spatial-dataset.contract';
+import { ISpatialControls } from '../contracts/visualizer.contract';
+import { RegionStore } from '../store/region-store.service';
+import { SpatialSelectionStore } from '../store/spatial-selection.service';
+import { VisualizerStore } from '../store/visualizer-store.service';
+/** The renderer-side spatial readouts the controls surface (the napari-js backend). */
+export interface SpatialRendererFeeds {
+    readonly transcriptEstimate$: {
+        asObservable(): Observable<{
+            points: number;
+            max: number;
+        } | null>;
+    };
+    readonly geneCountsInView$: {
+        asObservable(): Observable<Record<string, number> | null>;
+    };
+    readonly densityStats$: {
+        asObservable(): Observable<{
+            lo: number;
+            hi: number;
+            max: number;
+        } | null>;
+    };
+    /** Observations projected to canvas pixels by the 3D camera, or null when the cloud is not mounted. */
+    getSpatialScreenProjection(obs: SpatialObservations): Float32Array | null;
+}
+/** What the facade works over: the shared stores, the renderer feeds and the router's view state. */
+export interface SpatialControlsContext {
+    readonly store: VisualizerStore;
+    readonly regionStore: RegionStore;
+    readonly selectionStore: SpatialSelectionStore;
+    readonly napari: SpatialRendererFeeds;
+    /** The plot type on screen (the 3D cloud selects in screen space). */
+    plotType(): PlotType;
+    /** The displayed slice (a volume-backed dataset selects within one section). */
+    zIndex(): number;
+}
+/**
+ * The spatial-omics controls (`ISpatialControls`) over a host's `SPATIAL_DATA_PORT`.
+ *
+ * Backend-neutral: the view state lives in the shared `VisualizerStore` (like the
+ * colormap) and the selection in the `SpatialSelectionStore`, so the controls keep
+ * working across a plot-type switch and a host can drive them before any backend has
+ * mounted. Owns its mirror of the port's dataset — dropping a stale selection and an
+ * unsatisfiable colour source when the dataset changes — and the subscription behind
+ * it, released by {@link dispose} (review CORE-30).
+ */
+export declare class SpatialControlsFacade {
+    private readonly port;
+    private readonly ctx;
+    /** The controls; one object for the facade's life, so consumers can hold it. */
+    readonly controls: ISpatialControls;
+    /** Latest dataset, mirrored so `selectFromRegions()` can answer synchronously — it
+     *  runs from a button click and must not await a round-trip. */
+    private dataset;
+    private readonly sub;
+    constructor(port: SpatialDataPort, ctx: SpatialControlsContext);
+    /** Release the port subscription (the router's injector is being destroyed). */
+    dispose(): void;
+    private build;
+}