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

package/lib/implementations/osd/simple-source.d.ts

@@ -0,0 +1,161 @@
+import type * as OpenSeadragon from 'openseadragon';
+import { DisplayPipeline } from './display-pipeline';
+import { HistogramSampler } from './histogram-sampler';
+import { TileDescriptor } from '../tile-server';
+import { IImageInfo } from '../../contracts/image.contract';
+import { IChannelState } from '../../contracts/channel-histogram-api.contract';
+import { SimpleSliceAccessService } from '../simple-slice-access.service';
+/** One decoded single-band channel plane (serverless multichannel). */
+export interface SimplePlane {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+/** What `load()` hands to `plot()`. `load()` only computes it: the image on
+ *  screen keeps its own state until `plot()` commits this payload. */
+export interface OsdLoaded {
+    descriptor: TileDescriptor | null;
+    infoB64: string;
+    z: number;
+    /** Mirrors the loaded image's filename — the diagram's render pipeline
+     *  guards on `loaded.filename === phaseInfo.fileName` before calling plot(). */
+    filename: string | undefined;
+    /** Simple (non-tiled) image: `plot()` opens {@link url} directly via OSD's
+     *  single-image source — no tile pyramid, no server. Set when the image
+     *  carries `tiled === false` (see {@link IImageInfo.tiled}). */
+    simple?: boolean;
+    /** The directly-loadable image URL (`blob:`/`data:`/`http`) for simple mode. */
+    url?: string;
+    /** Serverless multichannel only: every slice's per-channel plane URLs, and
+     *  the loaded slice's decoded planes ({@link url} is their composite). */
+    channelUrls?: string[][];
+    channelPlanes?: SimplePlane[];
+}
+/** The service state the simple source reads and drives. */
+export interface SimpleSourceHost {
+    viewer(): OpenSeadragon.Viewer | null;
+    descriptor(): TileDescriptor | null;
+    isGrayscale(): boolean;
+    currentZ(): number;
+    /** Show slice `z`: the service records it and drops its slice-specific readback. */
+    setCurrentZ(z: number): void;
+    sampler(): HistogramSampler;
+    display(): DisplayPipeline;
+    channelStates(): IChannelState[];
+    /** Whether display round `token` is still the current one (see OsdTileRecolorer). */
+    isCurrentDisplay(token: number): boolean;
+    /** Queue a coalesced display round (for the serverless multichannel recomposite). */
+    scheduleInvalidate(): void;
+}
+/**
+ * The "simple" (`tiled: false`) image source: self-contained per-slice URLs and
+ * no tile server — e.g. a numbered image series assembled client-side into a
+ * stack, or the processing-pipeline preview. Each slice is resampled to the
+ * full-resolution size so regions align and opened as OSD's single-image source;
+ * a SERVERLESS multichannel image is composited client-side from its per-channel
+ * planes (kept OFF the tiled per-channel path).
+ *
+ * Owns every piece of simple-mode state and is the single place that resets it,
+ * so none of it can outlive the simple image (OSD-PLOTLY-1).
+ */
+export declare class OsdSimpleSource {
+    private readonly host;
+    private readonly simpleStack;
+    /** True while the mounted image is simple: setZIndex re-opens the viewer on
+     *  the new slice's URL instead of toggling a tiled slice. */
+    active: boolean;
+    /** urls[] of the mounted simple image, for the slice being scrubbed to. */
+    urls: string[];
+    /** preview blob URL → full-res resampled blob URL (see toFullResUrl), so
+     *  re-visiting a slice doesn't re-resample. Revoked on file change. */
+    private readonly fullResUrls;
+    /** SERVERLESS multichannel (tiled:false + channelCount>1): the stack's
+     *  per-slice per-channel plane URLs, the current slice's decoded planes, and
+     *  the displayed composite blob URL. */
+    multichannel: boolean;
+    channelUrls: string[][];
+    channelPlanes: SimplePlane[];
+    compositeUrl: string | null;
+    constructor(host: SimpleSourceHost, simpleStack: SimpleSliceAccessService);
+    /** Forget the simple image's state: mode, slice URLs and the serverless-
+     *  multichannel flag, URLs and decoded planes. Called when a tiled image is
+     *  mounted and on teardown; {@link commit} sets it from an {@link OsdLoaded}. */
+    reset(): void;
+    /** Revoke every blob URL this source created (a different file was selected). */
+    revokeUrls(): void;
+    /** Build the `plot()` payload for a simple (tiled:false) image: a single-level
+     *  descriptor sized from `trueImageSize`, plus the directly-loadable URL —
+     *  resolved and fetched via {@link SimpleSliceAccessService} (shared with
+     *  napari-js; see its docs for why this can't be a raw `fetch()`/`<img>`).
+     *  Those fetches take no signal, so an abort is honoured once they settle. */
+    load(imageInfo: IImageInfo, zIndex: number, signal?: AbortSignal): Promise<OsdLoaded>;
+    /** Commit a mounted image's simple-mode state from its {@link OsdLoaded}
+     *  payload (cleared for a tiled one). */
+    commit(loaded: OsdLoaded, imageInfo: IImageInfo): void;
+    /** The simple image's new viewer is about to open `loaded.url` (the old viewer
+     *  is gone): take ownership of its composite and bin its histograms — after
+     *  the service's destroyViewer, whose last act is clearing the sampler. */
+    mount(loaded: OsdLoaded): void;
+    /**
+     * The in-place (large-tier) pass for a mounted simple image. Simple mode has
+     * no pyramid to fall back on: it displays literally whatever URL was last
+     * opened, so without this swap the small tier's 128px placeholder would stay
+     * on screen forever (pixelated, never "sharpening" like the tiled path).
+     */
+    refreshInPlace(loaded: OsdLoaded, imageInfo: IImageInfo): void;
+    /**
+     * Show slice `z` of the mounted simple image. Each slice is its own complete
+     * image (no pyramid to toggle opacity on), so this re-opens the viewer on the
+     * new slice's URL; the viewer's preserveViewport keeps the current zoom/pan.
+     * Scrubs can resolve out of order: only the current slice may land.
+     */
+    setZIndex(z: number): void;
+    /**
+     * OSD's `{type:'image'}` source sizes its coordinate world to the image's
+     * NATURAL pixels. A folder-stack slice is a server `/preview` whose pixel size
+     * needn't match the full-resolution image — it may be downscaled (large
+     * images) OR larger than the dimensions `/metadata` reports. Either way OSD's
+     * world would differ from the full-res ROI coordinate space (QuPath geojson,
+     * in level-0 pixels): a smaller preview renders ROIs oversized, a larger one
+     * renders them undersized/offset. Resample the preview to EXACTLY the
+     * full-resolution dimensions (blurry but positionally exact — scaling up or
+     * down as needed) so OSD's world matches the ROI coordinate space, while still
+     * using OSD's reliable single-image renderer. Cached per preview URL (revoked
+     * on file change); a no-op when the preview is already exactly full-res (small
+     * images, in-memory pipeline blobs), when the dims are unknown, or when
+     * they're implausibly large (guards against an enormous canvas). (jit-ui#93)
+     */
+    toFullResUrl(previewUrl: string, width: number, height: number): Promise<string>;
+    /** Sample a slice's own decoded pixels into the histogram — the serverless
+     *  analog of the tiled samplers (no tile server). Fire-and-forget; a decode
+     *  failure just leaves the pane empty rather than throwing. */
+    private sampleHistogram;
+    /** Fetch + decode a slice's per-channel planes (single-band grayscale) into
+     *  pixel buffers, for the serverless multichannel compositor. Auth-safe: goes
+     *  through SimpleSliceAccessService (blob:/data: as-is; http via HttpClient).
+     *  The channels are fetched in parallel; plane c stays at index c, and a
+     *  plane that fails to load is empty (the compositor skips it). */
+    loadChannelPlanes(urls: string[] | undefined): Promise<SimplePlane[]>;
+    /** Composite per-channel planes into ONE RGBA image using the current channel
+     *  states (colour/window/gamma/visibility) — the client-side analog of the
+     *  tiled per-channel 'lighter' compositor (same display.channelRgbLut math as
+     *  the channel-tile recolor, applied per-plane). Returns a new blob: URL of the
+     *  composite PNG, owned by the caller (see {@link openComposite}). */
+    composite(planes: SimplePlane[]): Promise<string | undefined>;
+    /** Re-composite the current slice from its cached planes (new channel states)
+     *  and re-open — the serverless analog of the tiled invalidate-on-channel-change.
+     *  Runs from the recolorer's invalidateDisplay, so it is coalesced per frame,
+     *  and drops its composite once a newer display round (`token`) has started. */
+    recompositeAndOpen(token: number): Promise<void>;
+    /** Open a serverless-multichannel composite and take ownership of its URL. The
+     *  previously displayed composite is revoked only once this open settles: an
+     *  `open()` still decoding a revoked blob: URL fails. */
+    private openComposite;
+    /** Commit the serverless-multichannel part of an {@link OsdLoaded} payload. */
+    private commitMultichannel;
+    /** Decode an image URL to RGBA pixels (null for an empty image or no 2d
+     *  context). Throws when the URL can't be decoded. */
+    decodeUrlToRgba(url: string): Promise<ImageData | null>;
+    /** Load a URL into an HTMLImageElement (resolves once decoded). */
+    loadImageEl(url: string): Promise<HTMLImageElement>;
+}

package/lib/implementations/osd/slice-cache.d.ts

@@ -1,3 +1,4 @@
+import { OsdTiledImageLike, OsdViewerLike } from './osd-viewer-like';
 /**
  * Stack-slice cache for the OpenSeadragon backend (refactoring plan, Step 3 —
  * a pure move of the cache cluster out of the visualizer service).
@@ -17,7 +18,7 @@
  *  viewer/descriptor/z — matching the field reads it replaced. */
 export interface SliceCacheHost {
     /** The mounted viewer, or null. */
-    viewer(): any | null;
+    viewer(): OsdViewerLike | null;
     /** True when a viewer, descriptor and infoB64 are all present. */
     hasImage(): boolean;
     /** Stack depth (descriptor.z, 1 for single images). */
@@ -31,7 +32,7 @@ export interface SliceCacheHost {
     /** Channel visibility (drives group reveal opacity). */
     channelVisible(c: number): boolean;
     /** Tile source for slice z (optionally one channel). */
-    buildTileSource(z: number, channel?: number): any;
+    buildTileSource(z: number, channel?: number): string | object;
     /** A composite slice landed in the world — the service samples its window. */
     onCompositeSliceAdded(z: number): void;
 }
@@ -84,9 +85,17 @@ export declare class SliceCache {
     maxSlices(): number;
     /** Drop the per-channel groups (on a fresh plot). */
     clearChannelGroups(): void;
+    /**
+     * Take over the slice the viewer just opened (world item 0). Composite: seed
+     * the cache with it, so scrubbing back to it later is an instant opacity
+     * toggle, not a re-open. Multichannel: drop that single (channel-0) image and
+     * add the slice's channel group instead; the background loader / LRU then
+     * pre-fills the other slices' groups so z-scrub is flicker-free.
+     */
+    adoptOpenedSlice(z: number): void;
     /** Seed the cache with the just-opened composite slice (world item 0), so
      *  scrubbing back to it later is an instant opacity toggle, not a re-open. */
-    seedComposite(z: number, item: any): void;
+    seedComposite(z: number, item: OsdTiledImageLike): void;
     /** Show slice z: reveal it instantly when cached (re-tinting a stale
      *  multichannel group), otherwise add it once. The current slice stays
      *  visible until the new one is in — no white-flicker. */

package/lib/implementations/osd/tile-client.d.ts

@@ -3,26 +3,19 @@ import { HttpClient } from '@angular/common/http';
  * Single source of truth for jit-service `/tile` access from the OSD backend
  * (refactoring plan, Step 2). Before this module the tile URL was string-built
  * in four places and the fetch→decode pipeline copy-pasted in three — every
- * query-param change had to be repeated per site.
+ * query-param change had to be repeated per site. The URL itself now lives in
+ * the shared `tile-server/` client.
  *
  * Error handling is deliberately left to the CALL SITES: these helpers
  * propagate failures so each caller keeps its own tagged catch
  * (`[viz:histogram]`, `[viz:window]`, `[viz:export]`) and its own
  * skip/fallback semantics.
  */
-/** Tile coordinates for one `/tile` request. `channel == null` (or omitted)
- *  requests the server-composited tile; an index (including 0) requests that
- *  single channel as grayscale. */
-export interface TileCoords {
-    res: number;
-    col: number;
-    row: number;
-    z: number;
-    tileSize: number;
-    channel?: number | null;
-}
-/** Build the `/tile` request URL — the one place its query shape lives. */
-export declare function buildTileUrl(api: string, infoB64: string, c: TileCoords): string;
+/** The `/tile` URL shape moved to the backend-neutral jit-service client
+ *  (`implementations/tile-server/`), shared with napari-js; re-exported so the OSD
+ *  modules keep importing it from here. */
+export { buildTileUrl } from '../tile-server/tile-protocol';
+export type { TileCoords } from '../tile-server/tile-protocol';
 /** Fetch a tile PNG and decode it to an ImageBitmap. The caller owns the
  *  bitmap (call `close()` when done). Throws on network/decode failure. */
 export declare function fetchTileBitmap(http: HttpClient, url: string, timeoutMs: number): Promise<ImageBitmap>;
@@ -30,3 +23,7 @@ export declare function fetchTileBitmap(http: HttpClient, url: string, timeoutMs
  *  canvas). Returns null only when a 2d context can't be created; throws on
  *  network/decode failure (the caller's tagged catch handles it). */
 export declare function fetchTileRgba(http: HttpClient, url: string, timeoutMs: number): Promise<ImageData | null>;
+/** Draw a decoded image (bitmap, `<img>`, canvas) onto a scratch canvas and
+ *  read its pixels back as RGBA ImageData. Null when a 2d context can't be
+ *  created. */
+export declare function readRgba(src: CanvasImageSource, width: number, height: number): ImageData | null;

package/lib/implementations/osd/tile-recolor.d.ts

@@ -0,0 +1,141 @@
+import type * as OpenSeadragon from 'openseadragon';
+import { DisplayPipeline } from './display-pipeline';
+import { VisualizerStore } from '../../store/visualizer-store.service';
+import { Rgb } from '../../contracts/colormap-lut';
+import { IChannelState } from '../../contracts/channel-histogram-api.contract';
+/** The service state the recolorer reads — live, so it follows a viewer rebuild. */
+export interface TileRecolorHost {
+    viewer(): OpenSeadragon.Viewer | null;
+    isGrayscale(): boolean;
+    isMultiChannel(): boolean;
+    /** Serverless multichannel: recolor by re-compositing the cached planes. */
+    isSimpleMultichannel(): boolean;
+    currentZ(): number;
+    /** Re-apply the current slice's per-channel visibility (multichannel). */
+    revealChannelSlice(z: number): void;
+    /** Invalidate only the visible slice's channel images (multichannel). */
+    invalidateChannelDisplay(z: number): void;
+    /** Re-composite the serverless-multichannel planes for display round `token`. */
+    recomposite(token: number): void;
+}
+/** The tile-invalidated event's pixel accessors (OSD 5+/6), as used here. */
+interface TileEvent {
+    tile?: {
+        getUrl?: () => string;
+        url?: string;
+    };
+    getData(type: string): Promise<unknown>;
+    setData(data: unknown, type: string): Promise<unknown>;
+}
+/**
+ * Client-side display for OpenSeadragon tiles: window/gamma/colormap/invert and
+ * per-channel tints, applied through OSD's `tile-invalidated` pixel pipeline.
+ *
+ * Owns the display state mirrored from the shared {@link VisualizerStore} (the
+ * LUT, the channel states, invert) and the recolor invariant: invalidations are
+ * coalesced to one per animation frame, and every round captures
+ * {@link displayToken} — a round that a newer one has superseded must not write
+ * its pixels back.
+ */
+export declare class OsdTileRecolorer {
+    private readonly host;
+    private readonly store;
+    /** Pixel display pipeline (window/gamma/invert/colormap + additive tint) —
+     *  shared by tile recoloring, the serverless compositor and the composite
+     *  export so they stay identical (see DisplayPipeline). */
+    readonly display: DisplayPipeline;
+    /** 256-entry RGB LUT for the active colormap, applied to grayscale tiles
+     *  (mirrors Plotly's heatmap colorscale). Null while options resolve;
+     *  recoloring is skipped until it's built. */
+    colorLut: Rgb[] | null;
+    /** Latest per-channel display state (window/gamma/visibility) from the store,
+     *  read synchronously by recolorTile. Channel 0 drives grayscale windowing;
+     *  R/G/B (indices 0-2) drive RGB per-channel windowing. */
+    channelStates: IChannelState[];
+    /** Inverted background (white = zero): inverts the windowed value before the
+     *  gamma and the LUT (grayscale) / per channel before the additive merge (RGB
+     *  and multichannel), as napari-js does. */
+    invertBg: boolean;
+    /** Bumped by every display invalidation. A recolor round captures it and, after
+     *  each `await`, abandons the tile once a newer round has started. Writing a
+     *  superseded context back is not merely wasted work: OSD's conversion sees a
+     *  canvas the newer round already replaced, throws `DOMException`, and
+     *  `_handleConversionError` DESTROYS the cache record and unloads the tile
+     *  (unlike the drawer's rasterBlob path, it does not re-prepare). Enough of
+     *  those and the viewer goes white mid-drag. */
+    displayToken: number;
+    /** Pending coalesced invalidation (see {@link scheduleInvalidate}). */
+    private invalidateHandle;
+    private sub;
+    constructor(host: TileRecolorHost, store: VisualizerStore);
+    /** Whether display round `token` is still the current one. */
+    isCurrent(token: number): boolean;
+    /**
+     * Subscribe to the shared VisualizerStore colormap/reverse so OSD recolors in
+     * lock-step with Plotly. Idempotent and self-healing: the service is a root
+     * singleton, but `unsubscribe()` (called on VisualizerComponent destroy)
+     * tears the subscription down — and the constructor never runs again. So
+     * `plot()` calls this to re-establish it after a component teardown/recreate
+     * (e.g. switching images), otherwise colormap changes would be silently
+     * dropped on every image after the first switch.
+     */
+    ensureSubscription(): void;
+    /** Tear the store subscription down and drop a queued invalidation, so it
+     *  can't fire against a torn-down viewer. */
+    unsubscribe(): void;
+    /** Seed the Intensity channel with a measured auto-window while it's still
+     *  at full range (never clobber the user's manual window); if the user
+     *  already windowed, just re-invalidate so painted tiles pick the LUT up. */
+    seedGrayWindow(min: number, max: number): void;
+    /**
+     * Hook a freshly opened viewer (and its navigator, a separate mini-viewer with
+     * its own tiles that doesn't receive the main viewer's events) into the pixel
+     * pipeline, and paint what is already loaded when there is anything to apply.
+     */
+    attach(viewer: OpenSeadragon.Viewer): void;
+    /** Collapse a burst of display-state changes into ONE invalidation on the next
+     *  frame. Dragging a window slider emits per pixel of travel, and each round
+     *  restores and re-processes every tile of every channel — so the burst is both
+     *  wasted work and the race that breaks cache records (see {@link displayToken}).
+     *  The store write stays live, so the pane itself remains responsive. */
+    scheduleInvalidate(): void;
+    /** Re-apply the display pipeline (window/gamma/colour/invert) after a state change.
+     *  Multichannel invalidates ONLY the visible slice's channel images — invalidating
+     *  the whole world would re-process every hidden/preloaded slice's tiles (hundreds),
+     *  flooding OSD with "[CacheRecord] … InvalidStateError" and wasting work on tiles
+     *  that aren't on screen. The other cached slices are marked stale and re-tinted
+     *  lazily when revealed. Composite/grayscale invalidate the world; serverless
+     *  multichannel re-composites its cached planes. */
+    invalidateDisplay(): void;
+    /** Restore and re-recolor every tile of the main viewer and the navigator. */
+    invalidateWorld(): void;
+    /**
+     * Recolor a grayscale tile through the active colormap LUT, using OSD's
+     * tile-invalidated pixel pipeline (OSD 5+/6). Maps each pixel's grayscale
+     * value (r==g==b) to the LUT's RGB. No-op for RGB images or until the LUT is
+     * built. Handler is async — OSD awaits it (raiseEventAwaiting).
+     */
+    recolorTile(event: TileEvent): Promise<void>;
+    /**
+     * Tint a single channel's tile in place. Each channel is its own OpenSeadragon
+     * TiledImage (a single-band grayscale tile); OSD composites the N images
+     * additively ('lighter') in its drawer — so this just maps the tile's intensity
+     * through the channel's window/gamma and its pseudo-colour. Synchronous (no
+     * cross-tile fetch) → no race, no seams. Channel is parsed from the tile URL.
+     */
+    recolorChannelTile(event: TileEvent): Promise<void>;
+    /**
+     * Read a tile's pixels for recoloring. Prefers the tile's rendering context,
+     * but some tile caches (ajax PNG blobs) convert to an *empty* context2d —
+     * recoloring that would blank the tile (white canvas). So if the context has
+     * no opaque pixels, the tile's own bitmap/image is drawn to a scratch canvas
+     * and read instead. Null when no pixels can be read: leave the tile untouched.
+     */
+    private readTilePixels;
+    /** Write recolored pixels back to the tile — unless a newer display round
+     *  (`token`, see {@link displayToken}) has already restored it: writing a
+     *  superseded context back makes OSD's conversion throw DOMException, which
+     *  destroys the cache record and unloads the tile. */
+    private writeTilePixels;
+}
+export {};

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

@@ -18,6 +18,12 @@ export interface OmicsGrouping {
     /** `#rrggbb` per category, index-aligned — the same colours the map uses. */
     colors: string[];
 }
+/**
+ * What {@link buildOmicsTraces} / {@link omicsLayout} chart: one value per
+ * observation (cell/spot), with the optional grouping and selection
+ * index-aligned to it. Non-finite values (NaN for a missing measurement) are
+ * left out of every chart.
+ */
 export interface OmicsTraceInput {
     /** The values being charted (an annotation column or a gene vector). */
     values: Float32Array;
@@ -34,7 +40,7 @@ export interface OmicsTraceInput {
 /**
  * Traces for one chart kind.
  *
- * - **histogram** — the full distribution, plus an overlaid *Selected* trace
+ * - **histogram** — the full distribution as pre-binned bars, 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.
@@ -55,13 +61,15 @@ export interface OmicsCountInput {
     /** 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): {
+/** What {@link countByCategory} returns. */
+export interface CategoryCounts {
     labels: string[];
     colors: string[];
     totals: number[];
     selected: number[];
-};
+}
+/** Per-category counts, biggest first, with the tail folded into one bar. */
+export declare function countByCategory(input: OmicsCountInput): CategoryCounts;
 /**
  * Bars of per-category cell counts — the distribution a CATEGORICAL colour
  * source has.
@@ -71,24 +79,14 @@ export declare function countByCategory(input: OmicsCountInput): {
  * 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;
+export declare function buildCountTraces(input: OmicsCountInput, counts?: CategoryCounts): 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.
+ * Layout for {@link buildCountTraces}. Pass the same `counts` to both rather than letting
+ * each run its own full pass over the codes.
  */
+export declare function countsLayout(input: OmicsCountInput & {
+    name: string;
+}, counts?: CategoryCounts): unknown;
 /**
  * An embedding scatter — a UMAP, t-SNE or PCA plane over the same observations.
  *
@@ -189,5 +187,19 @@ export interface OmicsHeatmapInput {
     /** Column axis title — the grouping column's name, or "cell". */
     groupLabel?: string;
 }
+/**
+ * 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.
+ */
 export declare function buildHeatmapTraces(input: OmicsHeatmapInput): unknown[];
 export declare function heatmapLayout(input: OmicsHeatmapInput): unknown;

package/lib/implementations/plotly/plotly-image-loader.d.ts

@@ -0,0 +1,49 @@
+import { HttpClient } from '@angular/common/http';
+import { BehaviorSubject } from 'rxjs';
+import { Image } from 'image-js';
+import { IImageInfo } from '../../contracts/image.contract';
+/** What Plotly's `load()` hands to `plot()`: per-slice pixel matrices. */
+export interface PlotlyLoaded {
+    /** One row-major matrix per slice: grayscale numbers or `[r, g, b]` cells. */
+    data: any[];
+    /** [xRatio, yRatio]: image units per decoded pixel. */
+    ratios: number[];
+    /** [width, height] of a decoded slice. */
+    sizes: number[];
+    filename: string | undefined;
+    /** A serverless multichannel stack's raw channel planes (one byte per pixel), per loaded
+     *  slice (aligned with `data`) and channel — what its `image` trace is composited from. */
+    channelPlanes?: Uint8Array[][];
+}
+/**
+ * Plotly's image source: fetches slices through HttpClient (so the auth
+ * interceptors apply — a raw fetch() fails behind an OAuth2 proxy), decodes
+ * them with image-js into pixel matrices, and loads a stack through a small
+ * worker pool, reporting progress. Owns the stack-loading flag and progress.
+ */
+export declare class PlotlyImageLoader {
+    private readonly http;
+    /** Whether the whole stack is (to be) loaded; switching it off stops a stack load. */
+    readonly stackLoading$: BehaviorSubject<boolean>;
+    /** Stack load progress, 0–100 (0 when idle). */
+    readonly stackLoadingProgress$: BehaviorSubject<number>;
+    private readonly utils;
+    constructor(http: HttpClient);
+    /** Fetch one image via HttpClient and decode it. */
+    loadImage(url: string, signal?: AbortSignal): Promise<Image>;
+    /**
+     * Load slice `zIndex` — or, for a shown stack, every slice (in parallel,
+     * keeping slice order). `onProbe` runs once the displayed slice has decoded;
+     * the stack load stops early when `stillWanted()` turns false (another file),
+     * stack loading is switched off, or `signal` aborts (it then rejects with an
+     * `AbortError`). A stopped load keeps the contiguous run of slices from the start.
+     */
+    load(imageInfo: IImageInfo, zIndex: number, signal: AbortSignal | undefined, onProbe: () => void, stillWanted: () => boolean): Promise<PlotlyLoaded>;
+    /** A slice's channel planes (`channelUrls[z]`), fetched in parallel and decoded to one byte per
+     *  pixel (a 16-bit plane to its high byte, as a canvas decodes it for OSD). */
+    private loadChannelPlanes;
+    /** Grayscale: the scalar matrix. Colour: `[r, g, b]` cells in 0..255, the only range an
+     *  `image` trace draws — a 16-bit image keeps each sample's high byte, as the browser decodes
+     *  it for OSD and napari-js (its full values saturated every cell). */
+    private toMatrix;
+}

package/lib/implementations/plotly/plotly-image-recolor.d.ts

@@ -0,0 +1,75 @@
+import { IChannelState } from '../../contracts/channel-histogram-api.contract';
+import { IImageInfo } from '../../contracts/image.contract';
+import { PixelData } from '../../contracts/visualizer.contract';
+/** How the Plotly `image` trace of an image follows the Channels & Histogram dialog. */
+export type RecolorKind = 'rgb' | 'multichannel';
+/** RGBA8 pixels → an `image` trace's `source` (a `data:image/…;base64,` URI). */
+export type ImageEncoder = (rgba: Uint8ClampedArray, width: number, height: number) => Promise<string>;
+/** A serverless multichannel stack's per-channel plane URLs (`channelUrls[z][c]`), or null: the
+ *  criterion OSD's simple source and napari-js's stitch path use. */
+export declare function channelPlaneUrls(info: IImageInfo | undefined): string[][] | null;
+/**
+ * Which channel display the `image` trace of `info` gets: `multichannel` when the slices'
+ * channel planes were loaded, `rgb` for an RGB image (its channels are R, G and B — the store's
+ * channel model for `rgbChannels ≥ 3`), else none. A tiled multichannel image is plotted from
+ * the server's flat composite preview, with no per-channel pixels to recolour: none.
+ */
+export declare function recolorKind(info: IImageInfo | undefined, hasPlanes: boolean): RecolorKind | null;
+/** A Plotly `image` frame (rows of `[r, g, b(, a)]` cells) as opaque RGBA8 pixels. */
+export declare function matrixToRgba(frame: number[][][], width: number, height: number): Uint8ClampedArray;
+/** The browser's PNG encoder, off the main thread where it can be (`convertToBlob`/`toBlob`
+ *  encode asynchronously), read back as a data URI. */
+export declare const encodePng: ImageEncoder;
+/**
+ * The channel display of Plotly's colour `image` trace (#46 browser testing): what OSD's
+ * {@link DisplayPipeline} does to its tiles, run on the CPU over the frames Plotly plots, so one
+ * channel state draws the same picture on both (window → invert → gamma → tint, additive merge).
+ *  - multichannel (a serverless stack's `channelUrls`): the slice's raw channel planes merged by
+ *    `compositeChannels`;
+ *  - RGB: the raw frame's R, G and B through their channels (`applyToRgba`) — the raw frame as it
+ *    is while the channel states leave it so ({@link rgbNeedsRecolor}).
+ *
+ * Always from the RAW pixels the plot was built from, never from a recoloured frame, so repeated
+ * edits never compound. The raw frames stay what the pixel tools, the profiles and the histogram
+ * read; only the trace's picture changes.
+ *
+ * The trace draws a PNG `source`, not a `z` matrix: Plotly paints a `z` image one `fillRect` per
+ * pixel (~0.7 s for a 1-megapixel slice, on every edit), while a `source` is drawn by the browser
+ * and encoded off the main thread. A stack recolours the slice on screen, and each other slice
+ * when it is shown ({@link frame} reports a stale one).
+ */
+export declare class PlotlyImageRecolor {
+    private readonly host;
+    private readonly encode;
+    private kind;
+    private frames;
+    private planes;
+    /** Per frame: the display key of the latest picture asked for it. */
+    private shown;
+    /** Bumped by every plot/clear: a picture encoded for an older plot is dropped. */
+    private generation;
+    private readonly pipeline;
+    constructor(host: {
+        channelStates(): IChannelState[];
+        invert(): boolean;
+    }, encode?: ImageEncoder);
+    /** Whether the traces on screen follow the channel states. */
+    get active(): boolean;
+    /**
+     * Start following the channel states for the `image` traces about to be plotted from `frames`
+     * (raw, one per slice) and, for `multichannel`, each slice's raw channel `planes`. Resolves to
+     * each slice's `source` in the current display; null for `kind` null (the traces draw `z`), or
+     * when a newer plot superseded this one.
+     */
+    plot(kind: RecolorKind | null, frames: number[][][][], planes?: Array<Uint8Array[] | undefined>): Promise<string[] | null>;
+    /** Stop following (the plot was replaced by a non-image one, or purged). */
+    clear(): void;
+    /** Slice `index`'s `source` in the current channel display, or null when the picture asked for
+     *  last already shows it, or a newer picture or plot superseded this one. */
+    frame(index: number): Promise<string | null>;
+    /** Slice `index`'s displayed pixels (`getDisplayedPixelData` of a trace drawn from its `source`),
+     *  as `[r, g, b]` like a `z` trace's; null when no trace follows the channel states. */
+    displayedPixels(index: number): PixelData | null;
+    /** Slice `index` in the current channel display, as RGBA8, from its raw pixels. */
+    private pixels;
+}

package/lib/implementations/plotly/plotly-intensity-inset.d.ts

@@ -0,0 +1,8 @@
+import { IntensityProfile } from '../../contracts/visualizer.contract';
+/**
+ * Render the floating intensity-profile inset chart into `divId` — one line
+ * trace per profile line, each drawn in its line's colour. The x axis is in
+ * microns when the sampler tagged the profiles so (the image carries a pixel
+ * size), otherwise in pixels. A no-op when the element is missing.
+ */
+export declare function renderIntensityInset(divId: string, profiles: IntensityProfile[]): void;

package/lib/implementations/plotly/plotly-isosurface-controls.d.ts

@@ -0,0 +1,38 @@
+import { IIsosurfaceControls } from '../../contracts/visualizer.contract';
+/** Min/max intensity over every voxel of the frames (RGB → luminance), or null
+ *  for empty or flat input. */
+export declare function measureIntensityRange(frames: any[], isGrayscale: boolean): [number, number] | null;
+/**
+ * The ISOSURFACE intensity band. The slider is a fixed 0–255, but a stack often
+ * occupies only a narrow sub-range (e.g. an EDOF volume at ~2–50 with structure
+ * near 6–10), so the band is mapped onto the volume's measured range: every
+ * intensity is easy to reach and the band always lands inside the data — a
+ * small inset keeps the extreme surfaces off the exact data edges, which are
+ * degenerate and draw nothing.
+ */
+export declare class PlotlyIsosurfaceControls implements IIsosurfaceControls {
+    private readonly isLive;
+    private readonly restyle;
+    /** The band as 0–255 slider positions. Defaults to the full range so the
+     *  first render shows the whole structure. */
+    private isoMin;
+    private isoMax;
+    /** The measured [min, max] of the volume on screen; null until measured. */
+    private dataRange;
+    /**
+     * @param isLive whether an isosurface is on screen now
+     * @param restyle restyles the live isosurface's `isomin`/`isomax`
+     */
+    constructor(isLive: () => boolean, restyle: (update: {
+        isomin: number[];
+        isomax: number[];
+    }) => void);
+    /** Measure the volume about to be rendered, so the band maps onto its range. */
+    measure(frames: any[], isGrayscale: boolean): void;
+    /** The current band in data units, for the next render. */
+    band(): [number, number];
+    /** Update the band; a live isosurface is restyled in place (no volume rebuild). */
+    setIsoRange(isoMin: number, isoMax: number): void;
+    /** Slider band → data units, through the measured range (as-is before one). */
+    private mapBand;
+}