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

package/lib/implementations/region-centroids.d.ts

@@ -0,0 +1,14 @@
+import { Region } from '../models/region';
+/**
+ * Region centroids for the backends' "region centroid" scatter views (napari-js points, Plotly
+ * markers), computed once here instead of in each backend. The centroid is the VERTEX MEAN, not the
+ * area centroid: cheap, and what both views have always shown.
+ */
+/** Vertex mean of one ring, or null when it has no vertices. */
+export declare function polygonCentroid(xs: ArrayLike<number>, ys: ArrayLike<number>): [number, number] | null;
+/**
+ * Centroids of `regions` as flat `[x, y, x, y, …]` data coordinates: a rectangle's centre, a
+ * polygon's vertex mean, and one point per part of a multipolygon. Regions without geometry (or
+ * with an empty ring) contribute nothing.
+ */
+export declare function regionCentroids(regions: ReadonlyArray<Pick<Region, 'bounds'>>): Float32Array;

package/lib/implementations/simple-slice-access.service.d.ts

@@ -24,10 +24,12 @@ import * as i0 from "@angular/core";
  */
 export declare class SimpleSliceAccessService {
     private http;
-    /** raw slice URL → already-fetched blob: URL, so a backend that opens a
-     *  URL (OSD) doesn't repeat the auth round-trip revisiting a slice (scrub
-     *  back, the small→large tier re-fetch). Shared across backends: switching
-     *  plot types on the same file (e.g. Image → Volume) reuses entries. */
+    /** raw slice URL → its (possibly still in-flight) blob: URL, so a backend
+     *  that opens a URL (OSD) doesn't repeat the auth round-trip revisiting a
+     *  slice (scrub back, the small→large tier re-fetch), and two concurrent
+     *  requests for one slice share a fetch (and a blob: URL). Shared across
+     *  backends: switching plot types on the same file (e.g. Image → Volume)
+     *  reuses entries. */
     private readonly blobUrls;
     private currentFileName;
     constructor(http: HttpClient);
@@ -58,6 +60,7 @@ export declare class SimpleSliceAccessService {
      *  via the browser. Only real server URLs go through HttpClient so the auth
      *  interceptor applies. Mirrors {@link fetchAsBlobUrl}'s blob:/data: branch. */
     fetchAsBitmap(rawUrl: string): Promise<ImageBitmap>;
+    /** Revoke every cached blob: URL — an in-flight one once it resolves. */
     private revokeAll;
     static ɵfac: i0.ɵɵFactoryDeclaration<SimpleSliceAccessService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<SimpleSliceAccessService>;

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

@@ -4,6 +4,15 @@ import { SpatialDataPort, TranscriptTileQuery } from '../../contracts/ports/spat
 import { SpatialColumn, SpatialDataset, SpatialDensityRaster, SpatialEmbedding, SpatialPolygonTile, SpatialPolygons, CategoricalColumnMeta, SpatialMarkerGenes, SpatialTranscriptCounts, SpatialTranscriptSummary, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
 import { SpatialDatasetSummary, SpatialManifest } from './spatial-wire';
 import * as i0 from "@angular/core";
+/**
+ * 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);
+}
 /**
  * Reference {@link SpatialDataPort} adapter for the wire format the bundled
  * example server speaks (see `spatial-wire.ts` and
@@ -27,15 +36,6 @@ import * as i0 from "@angular/core";
  * 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 `/`. */
@@ -45,17 +45,24 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     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;
+    /** Advanced by every `selectDataset` and every `clear`, so a selection that
+     *  finishes after a newer intent can tell and drop what it fetched. Cache fills
+     *  take a {@link Supersede.current snapshot} of it, so a vector or tile that lands
+     *  after a switch is returned to its caller but never kept for the next dataset. */
+    private readonly selection;
     /**
      * 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).
+     * afternoon of browsing genes must not grow without limit either.
+     *
+     * Bounded by BYTES as well as entries: one vector is `4·N` bytes — 2 MB at 500k
+     * cells, but 14.8 MB at 3.7M, where 32 entries (an embedding is two or three
+     * vectors) could pin close to half a gigabyte.
      */
     private readonly cache;
+    private cachedBytes;
     private static readonly CACHE_LIMIT;
+    private cacheBytes;
     /** In-flight requests, so double-clicking a gene issues one fetch. */
     private readonly inFlight;
     /**
@@ -64,13 +71,24 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
      */
     private readonly tileCache;
     private static readonly TILE_CACHE_LIMIT;
+    /** Bytes of each RESOLVED tile in {@link tileCache}; a pending one counts once it lands. */
+    private readonly tileBytes;
+    private tileBytesTotal;
+    private tileCacheBytes;
     private volumePromise;
     private polygonsPromise;
     constructor(http: HttpClient);
-    /** Point the adapter at a server. Clears any loaded dataset. */
+    /**
+     * Point the adapter at a server. Clears any loaded dataset.
+     *
+     * `cacheBytes` / `tileCacheBytes` cap the decoded vectors (default 256 MiB) and tiles
+     * (default 128 MiB) kept for reuse; the most recent entry is always kept.
+     */
     configure(options: {
         baseUrl: string;
         timeoutMs?: number;
+        cacheBytes?: number;
+        tileCacheBytes?: number;
     }): void;
     /** Datasets this server offers, for a host-side picker. */
     listDatasets(): Promise<SpatialDatasetSummary[]>;
@@ -83,8 +101,8 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     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.
+     * then, in parallel, 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. */
@@ -99,7 +117,8 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     getTranscriptTile(level: number, gx: number, gy: number, query: TranscriptTileQuery): Promise<SpatialTranscriptTile>;
     getTranscriptGeneBins(level: number, tx: number, ty: number, genes: string[]): Promise<SpatialTranscriptTile>;
     getTranscriptBins(level: number, tx: number, ty: number): Promise<SpatialTranscriptTile>;
-    /** Small JSON answers, keyed by URL — hovering back and forth must not refetch. */
+    /** Small JSON answers, keyed by URL — hovering back and forth must not refetch. Least recently
+     *  USED goes first, so the summary under the pointer stays while others are evicted. */
     private readonly summaryCache;
     getTranscriptSummary(query: {
         box?: [number, number, number, number];
@@ -115,6 +134,9 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     getTranscriptCounts(genes: string[]): Promise<SpatialTranscriptCounts>;
     /** LRU over tile promises, so concurrent asks share one request and a failure is not kept. */
     private cachedTile;
+    /** Oldest first, past the entry cap or the byte budget, keeping the newest. */
+    private evictTiles;
+    private dropTile;
     /**
      * The reference volume's voxels, single-flighted like the polygons.
      *
@@ -141,7 +163,9 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
      * entry a newer request for the same key is already sharing.
      */
     private fetchCached;
+    /** Oldest first, past the entry cap or the byte budget, keeping the newest. */
     private evict;
+    private uncache;
     private getJson;
     private getBinary;
     static ɵfac: i0.ɵɵFactoryDeclaration<SpatialDataHttpService, never>;

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

@@ -23,6 +23,8 @@ import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialDensityMeta, S
  *
  * ENDPOINTS (base = the server root)
  * ----------------------------------
+ * Every route `SpatialDataHttpService` calls. `{id}` is the dataset id; names and
+ * gene lists are URI-encoded.
  * ```
  * GET {base}/spatial/datasets              -> { datasets: [{ id, name, count }] }
  * GET {base}/spatial/{id}/manifest         -> SpatialManifest
@@ -32,19 +34,28 @@ import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialDensityMeta, S
  * 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}/embedding/{name} -> f32[N] per dimension, see decodeEmbedding
  * GET {base}/spatial/{id}/polygons         -> u32 count, u32[count+1] offsets, f32[2*rings] coords
+ * GET {base}/spatial/{id}/volume           -> u8[width*height*depth]   (manifest.volume only)
  * GET {base}/spatial/{id}/polygon-tile/{set}/{level}/{gx}/{gy}
  *                                          -> u32 count, u32[count] obs, u32[count+1] offsets, f32 coords
- * GET {base}/spatial/{id}/transcript-tile/{level}/{gx}/{gy}?genes=A,B&quality=high|all
+ * GET {base}/spatial/{id}/transcript-tile/{level}/{gx}/{gy}?genes=A,B&quality=high|all&box=
  *                                          -> see decodeTranscriptTile
- * GET {base}/spatial/{id}/density?genes=A,B -> f32[rows*cols]
  * GET {base}/spatial/{id}/transcript-bins/{level}/{tx}/{ty}
  *                                          -> transcript-tile layout, one entry per bin
+ * GET {base}/spatial/{id}/gene-bins/{level}/{tx}/{ty}?genes=A,B
+ *                                          -> transcript-tile layout, per-gene bins
+ * GET {base}/spatial/{id}/density?genes=A,B&bin= -> see decodeDensity
+ * GET {base}/spatial/{id}/transcript-summary?box=&genes=&cells= -> SpatialTranscriptSummary
+ * GET {base}/spatial/{id}/transcript-counts?genes=A,B -> SpatialTranscriptCounts
+ * GET {base}/spatial/{id}/markers/{column}?n=  -> SpatialMarkerGenes
+ * POST {base}/spatial/{id}/groups?name=    (text/csv `cell_id,group`)
+ *                                          -> { column: CategoricalColumnMeta, matched }
  * ```
  *
- * The three tiled routes are optional and advertised in the manifest
- * (`polygonTiles`, `transcriptTiles`, `density`); a server without them never
- * sees them requested.
+ * The optional routes are advertised in the manifest (`polygons`, `volume`,
+ * `polygonTiles`, `transcriptTiles`, `transcriptBins`, `transcriptGeneBins`,
+ * `density`); a server without them never sees them requested.
  */
 /** Bumped when the layout changes incompatibly; the client refuses anything else. */
 export declare const SPATIAL_WIRE_VERSION = 1;
@@ -89,7 +100,13 @@ export interface SpatialDatasetSummary {
 }
 /** True on a little-endian host. */
 export declare function isLittleEndian(): boolean;
-/** Reject a manifest this client cannot read, with a message naming the fix. */
+/**
+ * Reject a manifest this client cannot read, with a message naming the fix.
+ *
+ * Besides the version, the values every decoder sizes its views from: an observation
+ * count that is not a non-negative integer, or an embedding that is not 2-D or 3-D, would
+ * otherwise surface later as a RangeError deep inside a renderer.
+ */
 export declare function assertManifestVersion(manifest: SpatialManifest): void;
 /**
  * `GET /coords` → x/y(/z). One request rather than two or three: the vectors
@@ -99,7 +116,6 @@ export declare function assertManifestVersion(manifest: SpatialManifest): void;
 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.
  *
@@ -107,6 +123,7 @@ export declare function decodeRadius(buf: ArrayBuffer, count: number): Float32Ar
  * the renderer as a view with no copy and no stride.
  */
 export declare function decodeEmbedding(buf: ArrayBuffer, meta: SpatialEmbeddingMeta, count: number): SpatialEmbedding;
+/** `GET /feature/{name}` → one gene's expression vector. */
 export declare function decodeFeatureVector(buf: ArrayBuffer, count: number): Float32Array;
 /**
  * `GET /column/{name}` → a loaded column, typed by its descriptor: `u16` codes
@@ -124,14 +141,22 @@ export declare function decodePolygons(buf: ArrayBuffer): SpatialPolygons;
 /**
  * `GET /polygon-tile/...` → one tile of rings with their owning observations. Layout
  * `[u32 count][u32 obs × count][u32 offsets × (count+1)][f32 coords × 2·offsets[count]]`.
+ *
+ * `observations` is the dataset's N; when given, every owner must be below it.
  */
-export declare function decodePolygonTile(buf: ArrayBuffer): SpatialPolygonTile;
+export declare function decodePolygonTile(buf: ArrayBuffer, observations?: number): SpatialPolygonTile;
 /**
  * `GET /transcript-tile/...` → transcripts or aggregates. Layout, 4-byte aligned:
  * `[u32 n][u32 flags][f32 x·n][f32 y·n][f32 z·n][u32 weight·n][u32 obs·n][u16 gene·n, padded]`;
  * flags bit 0 marks an aggregated level.
+ *
+ * `limits` bounds the indices when the caller knows them: `observations` is the dataset's
+ * N, and `genes` the length of the gene list the codes index (omit it for `ALL_GENES`).
  */
-export declare function decodeTranscriptTile(buf: ArrayBuffer): SpatialTranscriptTile;
+export declare function decodeTranscriptTile(buf: ArrayBuffer, limits?: {
+    observations?: number;
+    genes?: number;
+}): SpatialTranscriptTile;
 /**
  * `GET /density?genes=&bin=` → the summed raster. Layout
  * `[u32 rows][u32 cols][f32 cellW][f32 cellH][f32 originX][f32 originY][f32 rows·cols]`:

package/lib/implementations/tile-server/index.d.ts

@@ -0,0 +1,5 @@
+/** Shared jit-service tile client (OSD-PLOTLY-15 / NAPARI-SVC-20). */
+export * from './tile-protocol';
+export * from './transport';
+export * from './poll-descriptor';
+export * from './native-histogram';

package/lib/implementations/tile-server/native-histogram.d.ts

@@ -0,0 +1,25 @@
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { NativeHistogramRequest } from './tile-protocol';
+import { FetchJson } from './transport';
+/** The server's `/histogram` answer (HistogramInfo). */
+export interface NativeHistogramWire {
+    bitDepth: number;
+    rangeMin: number;
+    rangeMax: number;
+    observedMin: number;
+    observedMax: number;
+    binWidth: number;
+    counts: number[];
+}
+/** Map the server's HistogramInfo to an {@link IHistogram} with native bin left-edges
+ *  (`rangeMin + i * binWidth`). */
+export declare function toNativeHistogram(hi: NativeHistogramWire): IHistogram;
+/**
+ * One channel's native-bit-depth histogram from `GET /histogram` (>8-bit images: the 8-bit display
+ * tiles cannot carry 16-bit values). The URL carries the per-app-load cache-buster.
+ *
+ * Resolves null when the server has no answer yet (202 while caching, or another status, or no
+ * counts) — the caller's pane retries. Transport failures propagate, so each backend keeps its
+ * own tagged catch; caching is the caller's too.
+ */
+export declare function nativeHistogram(fetchJson: FetchJson, api: string, infoB64: string, req: NativeHistogramRequest, signal?: AbortSignal): Promise<IHistogram | null>;

package/lib/implementations/tile-server/poll-descriptor.d.ts

@@ -0,0 +1,39 @@
+import { TileDescriptor } from './tile-protocol';
+import { FetchJson } from './transport';
+/** Timing of one {@link pollDescriptor} run. */
+export interface PollDescriptorOptions {
+    /** Give up (resolve null) once this long has passed without a descriptor. */
+    deadlineMs: number;
+    /** Wait between two polls while the server answers 202. */
+    intervalMs: number;
+    /** Per-request timeout, so a hung request cannot outlive the deadline. Default 45 s. */
+    requestTimeoutMs?: number;
+    /** Abort the whole poll: it then rejects with an `AbortError`. */
+    signal?: AbortSignal;
+    /** Log prefix for the poll's warnings, e.g. `[OSD]`. */
+    tag?: string;
+}
+/** Default per-request timeout of {@link pollDescriptor}. */
+export declare const DESCRIPTOR_REQUEST_TIMEOUT_MS = 45000;
+/**
+ * Poll `GET /tiles/info` until the server describes the source.
+ *
+ * The server answers 202 while it is still caching the source (GCS → PVC, which can take minutes
+ * for a cold whole-slide image) and 200 with the descriptor once ready. So:
+ *  - **202** → wait `intervalMs` and poll again, until `deadlineMs`;
+ *  - **200 with levels** → the descriptor;
+ *  - **any other status**, or a 200 without levels → `null` at once: this server will not describe
+ *    the source, and polling it for minutes only delays the caller's fallback (NAPARI-SVC-3);
+ *  - a **transport failure** (network error, per-request timeout) → retried like a 202: a large
+ *    image always passes through a busy window, and one bad poll must not abandon it;
+ *  - the **deadline** passing → `null`.
+ *
+ * The first request is issued synchronously, before the returned promise first awaits. Rejects
+ * with an `AbortError` as soon as `signal` aborts (between polls, or mid-request when the
+ * transport honours the signal).
+ *
+ * These are the napari-js backend's hardened semantics; the OpenSeadragon backend used to throw on
+ * the deadline and to retry every error status. It now shares this answer and turns `null` into
+ * its own load failure (see `OpenSeadragonVisualizerService.load`).
+ */
+export declare function pollDescriptor(fetchJson: FetchJson, url: string, opts: PollDescriptorOptions): Promise<TileDescriptor | null>;

package/lib/implementations/tile-server/tile-protocol.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The jit-service tile protocol, shared by the OpenSeadragon and napari-js backends: the
+ * `/tiles/info` descriptor, and the URLs of `/tiles/info`, `/tile`, `/histogram` and
+ * `/export/tiff`. Each URL shape lives here once — the backends used to string-build them
+ * separately and had already drifted (napari's `/histogram` lacked the cache-buster).
+ */
+/** One pyramid level from `GET /tiles/info` (res 0 = full resolution). */
+export interface TileLevel {
+    res: number;
+    width: number;
+    height: number;
+}
+/** Tile-source descriptor returned by `GET /tiles/info`. */
+export interface TileDescriptor {
+    width: number;
+    height: number;
+    tileSize: number;
+    z: number;
+    channels: number;
+    /** True only for genuine multi-channel composites (indexed/LUT-bearing
+     *  fluorescence stacks) the client should split into per-channel layers. The
+     *  server sets it; an RGB photo read as separated planes has channels>1 but
+     *  multichannel=false, so it stays a single composite tile source. */
+    multichannel?: boolean;
+    /** Real Bio-Formats resolution levels at the front of `levels`; the remaining
+     *  levels are synthetic composited overviews (no per-channel tiles). */
+    realLevels?: number;
+    /** Per-channel metadata (name/color/bitDepth/min-maxAllowed) for native 16-bit
+     *  windowing + histogram; null for plain 8-bit/RGB sources. */
+    channelInfo?: Array<{
+        name?: string;
+        color?: string;
+        bitDepth?: number;
+        minAllowed?: number;
+        maxAllowed?: number;
+    }> | null;
+    levels: TileLevel[];
+    /** Physical pixel size in µm (0 when the format doesn't report it). */
+    mppX?: number;
+    mppY?: number;
+}
+/** 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;
+}
+/** The `/tiles/info` descriptor URL for one source. */
+export declare function tilesInfoUrl(api: string, infoB64: string): string;
+/** Build the `/tile` request URL — the one place its query shape lives (the
+ *  server caches on the exact parameter order). */
+export declare function buildTileUrl(api: string, infoB64: string, c: TileCoords): string;
+/**
+ * Per-app-load cache-buster for `/histogram`. The server marks the response
+ * cacheable for 24 h, and a hard refresh can't bust a post-load XHR. A token
+ * stable within a session (so the backends' in-session caches still dedupe) but
+ * new on each full load always reflects the live backend after a reload.
+ */
+export declare const HISTOGRAM_CACHE_BUSTER: number;
+/** Where one channel's native-bit-depth histogram is read. */
+export interface NativeHistogramRequest {
+    z: number;
+    channel: number;
+    bins: number;
+}
+/** The `/histogram` URL, with the cache-buster (see {@link HISTOGRAM_CACHE_BUSTER}). */
+export declare function nativeHistogramUrl(api: string, infoB64: string, r: NativeHistogramRequest, cacheBuster?: number): string;
+/**
+ * The `/export/tiff` URL for slice `z`. `visible` are the channel indices to
+ * export; the `channels` param is omitted when every one of the `channelCount`
+ * channels is visible (or none is), which is the server default (all).
+ */
+export declare function exportTiffUrl(api: string, infoB64: string, z: number, visible: readonly number[], channelCount: number): string;
+/** The saved name of a native-bit-depth TIFF export of `fileName`. */
+export declare function exportTiffFilename(fileName: string | null | undefined): string;

package/lib/implementations/tile-server/transport.d.ts

@@ -0,0 +1,62 @@
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+/**
+ * Transport for the jit-service tile protocol.
+ *
+ * Two transports exist on purpose, and each backend uses exactly one:
+ *  - **napari-js** fetches with the browser's `fetch` (its tile loader, the worker-free slice
+ *    stitcher and the volume preload all need a `Response`), through {@link fetchWithAuth}: the one
+ *    place the host's `getAuthHeaders()` is resolved, with its "no token → cookie auth" fallback.
+ *  - **OpenSeadragon** keeps Angular's `HttpClient`, so the host's interceptors (auth, retry,
+ *    logging) apply exactly as before; {@link httpFetchJson} adapts it.
+ *
+ * The protocol helpers ({@link pollDescriptor}, {@link nativeHistogram}) take a {@link FetchJson}
+ * and so run the same code over either one.
+ */
+/** Auth header provider — the subset of `TileAccessPort` the transport needs. */
+export interface AuthHeaderSource {
+    getAuthHeaders(): Promise<Record<string, string>>;
+}
+/** Resolve the host's auth headers; a failure means cookie / anonymous auth (`{}`). */
+export declare function resolveAuthHeaders(src: AuthHeaderSource): Promise<Record<string, string>>;
+/** `fetch` with the host's auth headers (merged under any `init.headers`). */
+export declare function fetchWithAuth(auth: AuthHeaderSource, url: string, init?: RequestInit): Promise<Response>;
+/** A JSON GET's status and parsed body (null when there is none, or it is not JSON). */
+export interface JsonResponse<T> {
+    status: number;
+    body: T | null;
+}
+/**
+ * A JSON GET. Resolves with any HTTP status the server answered (2xx or not); rejects on a
+ * transport failure (network error, CORS) and as soon as `signal` aborts.
+ */
+export type FetchJson = <T>(url: string, signal?: AbortSignal) => Promise<JsonResponse<T>>;
+/** {@link FetchJson} over {@link fetchWithAuth}. */
+export declare function fetchJsonWithAuth(auth: AuthHeaderSource): FetchJson;
+/**
+ * {@link FetchJson} over Angular's `HttpClient` (its interceptors apply). An HTTP error status is
+ * resolved, not thrown; status 0 (no response at all) stays a rejection. An abort unsubscribes,
+ * which cancels the XHR.
+ */
+export declare function httpFetchJson(http: HttpClient): FetchJson;
+/**
+ * `firstValueFrom` that unsubscribes (for `HttpClient`, cancels the XHR) and rejects with an
+ * {@link abortError} as soon as `signal` aborts. The subscription is made synchronously.
+ */
+export declare function firstValueFromAbortable<T>(source: Observable<T>, signal?: AbortSignal): Promise<T>;
+/** The error an aborted operation rejects with (`name === 'AbortError'`, as `fetch` uses). */
+export declare function abortError(): Error;
+/** Whether `err` is an abort (from {@link abortError}, `fetch`, or `AbortSignal.reason`). */
+export declare function isAbortError(err: unknown): boolean;
+/** Throw an {@link abortError} when `signal` has aborted. */
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+/** Resolve after `ms`, or reject with an {@link abortError} as soon as `signal` aborts. */
+export declare function abortableDelay(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * A signal that aborts when `parent` does, or after `timeoutMs`. Call `done()` once the guarded
+ * request settles, to clear the timer and the parent listener.
+ */
+export declare function timeoutSignal(parent: AbortSignal | undefined, timeoutMs: number): {
+    signal: AbortSignal;
+    done(): void;
+};

package/lib/intensity/intensity-profile.d.ts

@@ -0,0 +1,66 @@
+import { IntensityProfile } from '../contracts/visualizer.contract';
+import { IImageMetadata } from '../contracts/image.contract';
+import { Region } from '../models/region';
+/**
+ * Pure intensity-profile math: sampling a line through a pixel frame, placing a
+ * new profile line, and the image's physical pixel size. Frames are row-major
+ * matrices: grayscale cells are numbers, RGB cells are `[r, g, b]`.
+ */
+/** Bright, well-separated colours cycled as the user adds profile lines.
+ *  The matching inset trace is drawn in the same colour. */
+export declare const PROFILE_PALETTE: readonly string[];
+/** A sampling line in image (data) coordinates. */
+export interface ProfileLine {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** One frame to sample and how it maps onto the image. */
+export interface SamplingFrame {
+    /** The pixel matrix (row-major). */
+    frame: any[];
+    /** [xRatio, yRatio]: image units per frame pixel. */
+    ratios: number[];
+    /** Image coordinate of the frame's pixel (0,0): [0,0] for the full image, a
+     *  crop's top-left for a zoom crop. */
+    origin: [number, number];
+}
+/** Physical pixel size (microns/pixel), if known. mpp is constant across
+ *  frames/channels, so the first metadata entry with a positive mppX wins. */
+export declare function imageMpp(meta: IImageMetadata[] | undefined): {
+    mppX: number | null;
+    mppY: number | null;
+};
+/**
+ * Sample a frame's intensity (grayscale value or RGB luminance) along `line`.
+ * Positions are the distance along the line, in microns when `mpp` is known
+ * (anisotropic mppX/mppY applied per axis, so diagonals measure their true
+ * length), otherwise in image pixels. One sample per frame pixel along the line.
+ */
+export declare function sampleLine(src: SamplingFrame, line: ProfileLine, mpp: {
+    mppX: number | null;
+    mppY: number | null;
+}): IntensityProfile;
+/** A profile-line region's two endpoints, or null when it has no polyline.
+ *  Duck-typed (not `instanceof Polygon`): after a drag round-trips through the
+ *  store the bounds can be a plain object, so this matches on the point arrays. */
+export declare function profileLineOf(region: Region): ProfileLine | null;
+/** An image-pixel rectangle. */
+export interface PixelRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where the `count`-th profile line goes: a horizontal line spanning 2/3 of
+ * the visible part of the image (`roi`, when it overlaps the image extent
+ * `[x0, x1, y0, y1]`; else the whole image), centred, staggered down the visible
+ * band so successive lines stay distinct.
+ */
+export declare function placeProfileLine(extent: number[], roi: PixelRect | null, count: number): {
+    x0: number;
+    x1: number;
+    y: number;
+};

package/lib/intensity/intensity-profile.service.d.ts

@@ -0,0 +1,108 @@
+import { OnDestroy } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { IIntensityControls, IntensityProfile } from '../contracts/visualizer.contract';
+import { IImageInfo } from '../contracts/image.contract';
+import { TileAccessPort } from '../contracts/ports/tile-access.port';
+import { ImageStatePort } from '../contracts/ports/image-state.port';
+import { Region } from '../models/region';
+import { RegionStore } from '../store/region-store.service';
+import { ProfileLine } from './intensity-profile';
+import * as i0 from "@angular/core";
+/** The pixels the profiles are sampled from, and the image they belong to. */
+export interface IntensityFrames {
+    /** Per-z-plane pixel matrices (grayscale numbers or `[r, g, b]` cells). */
+    frames: any[];
+    /** [xRatio, yRatio]: image units per frame pixel. */
+    ratios: number[];
+    /** Image coordinate of the frames' pixel (0,0); [0,0] unless a zoom crop. */
+    origin?: [number, number];
+}
+/** The image the frames come from: its extent (for line placement) and its
+ *  metadata (pixel size, grayscale). */
+export interface IntensityImage {
+    imageInfo: IImageInfo;
+    /** [x0, x1, y0, y1] in image units. */
+    extent: number[];
+    /** The displayed z-plane, when the frames hold a stack. */
+    frameIndex?: () => number;
+}
+/**
+ * Intensity profiles along line ROIs (PlotType.LINE), for every backend.
+ *
+ * Profile lines are ordinary RegionStore regions tagged `kind: 'profile'`; any
+ * region change re-samples and re-emits every line's profile. The service owns
+ * its OWN sampling frames — a backend's tool readback never doubles as the
+ * profile source (OSD-PLOTLY-2) — filled by Plotly when it renders or high-def
+ * zooms, and fetched here for the other backends: the displayed slice
+ * ({@link ensureIntensitySampling}) and, on zoom/pan, a display-resolution
+ * crop of the visible region ({@link refreshIntensitySamplingForRoi}). Every
+ * sampling write supersedes the async ones before it.
+ *
+ * Per viewer: listed in `provideVisualization()` with the RegionStore it
+ * listens to.
+ */
+export declare class IntensityProfileService implements IIntensityControls, OnDestroy {
+    private readonly http;
+    private readonly tiles;
+    private readonly regionStore;
+    private frames;
+    private image;
+    /** The last visible image-pixel rect a backend reported (new lines go there). */
+    private lastVisibleRoi;
+    /** Palette cursor (never reset on delete, so colours keep cycling). */
+    private colorSeq;
+    /** Bumped by every sampling write request: an async fetch lands only if no
+     *  newer one was requested meanwhile. */
+    private gen;
+    /** The element whose parent sizes a crop request (the viewer's plot div). */
+    private elementId;
+    /** The host's selected file, so a crop for a previous file is dropped. */
+    private fileName;
+    private readonly profiles$;
+    private readonly subs;
+    private readonly utils;
+    constructor(http: HttpClient, tiles: TileAccessPort, state: ImageStatePort, regionStore: RegionStore);
+    ngOnDestroy(): void;
+    /** Every profile line's profile, re-emitted whenever one is added, moved or removed. */
+    getIntensityProfile$(): Observable<IntensityProfile[]>;
+    /** The element (by id) whose size a crop request is made for. */
+    setSamplingElement(id: string): void;
+    /** Supersede every sampling fetch in flight; returns the new generation. */
+    supersede(): number;
+    /** Whether `gen` (from {@link supersede}) is still the latest sampling request. */
+    isCurrent(gen: number): boolean;
+    /** Sample from these frames from now on — of `image`, or of the image already set. */
+    setFrames(frames: IntensityFrames, image?: IntensityImage): void;
+    /**
+     * Fetch the displayed slice's preview for sampling (the same pixels a heatmap
+     * would sample), for a backend that has no frames of its own (OpenSeadragon,
+     * napari-js). Re-emits the profiles once loaded.
+     */
+    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
+    /**
+     * Re-fetch the given image-pixel ROI at the display resolution and sample from
+     * it, so the profile reflects the data at the current zoom level. Also
+     * remembers the ROI, so a new line is placed inside it.
+     */
+    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+    /**
+     * Add another profile line: a horizontal open 2-point polyline in the next
+     * palette colour, placed by {@link placeProfileLine}, added to the shared
+     * store so every backend renders and drags it (and excluded from the Regions
+     * tab and exports by its kind). Null until an image extent is known.
+     */
+    addProfileLine(): Region | null;
+    /** Recompute and broadcast every profile line's profile (tagged with the
+     *  line's id and colour, so the inset trace matches its line). */
+    emitProfiles(): void;
+    /** Sample the active frame along `line` (see sampleLine). */
+    computeIntensityProfile(line: ProfileLine): IntensityProfile;
+    /** The profile-line regions in the store. */
+    private profileRegions;
+    /** Fetch one slice through HttpClient (auth interceptors apply) and decode it. */
+    private loadSlice;
+    private toMatrix;
+    static ɵfac: i0.ɵɵFactoryDeclaration<IntensityProfileService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<IntensityProfileService>;
+}