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

package/lib/region-editor/region-table/region-table.component.d.ts

@@ -0,0 +1,83 @@
+import { EventEmitter, OnChanges } from '@angular/core';
+import { Region } from '../../models/region';
+import { PresetSet } from '../../models/class-preset';
+import { PixelSize } from '../region-metrics';
+import * as i0 from "@angular/core";
+/** A page change from the paginator. */
+export interface RegionPage {
+    first: number;
+    rows: number;
+}
+/**
+ * The Region Editor's regions table and paginator: one page of rows with a
+ * class dropdown (or an inline label editor), the area, and a delete button.
+ * Presentational and OnPush: the editor owns the rows, the selection, the
+ * paging and the label drafts, and applies every edit through its one
+ * copy-on-write commit path — the table never changes a {@link Region}.
+ */
+export declare class RegionTableComponent implements OnChanges {
+    /** The rows on the current page. */
+    page: Region[];
+    /** Total number of rows (all pages). */
+    total: number;
+    /** Index of the page's first row across all pages. */
+    first: number;
+    /** Rows per page. */
+    rows: number;
+    /** The paginator's rows-per-page choices. */
+    rowsPerPageOptions: number[];
+    /** Ctrl/Cmd-click toggles a row (PrimeNG metaKeySelection). */
+    metaKey: boolean;
+    /** The selected rows. */
+    selection: Region[];
+    /** The table's selection changed (any row click). */
+    selectionChange: EventEmitter<Region[]>;
+    /** A row was selected or unselected (after {@link selectionChange}). */
+    rowSelect: EventEmitter<void>;
+    /** Classes for the per-row dropdown, and their colours. */
+    presetSet: PresetSet;
+    /** Swatch colour of an unlabelled row. */
+    defaultColor: string;
+    /** Pixel size for the area column. */
+    mpp: PixelSize;
+    /** Rows whose label is being edited → the typed draft. A new map per start/stop. */
+    labelDrafts: Map<Region, string>;
+    /** A row's pencil: start editing its label. */
+    labelEditStart: EventEmitter<Region>;
+    /** The inline label editor's text changed. */
+    labelDraftChange: EventEmitter<{
+        region: Region;
+        value: string;
+    }>;
+    /** The inline label editor closed: Enter commits, Escape / close cancels. */
+    labelEditStop: EventEmitter<{
+        region: Region;
+        commit: boolean;
+    }>;
+    /** A class was picked in a row's dropdown. */
+    classPick: EventEmitter<{
+        region: Region;
+        name: string;
+    }>;
+    /** A row's trash button: the row's index across all pages. */
+    deleteRow: EventEmitter<number>;
+    /** The paginator moved or changed its page size. */
+    pageChange: EventEmitter<RegionPage>;
+    /** Per row of {@link page}: its class swatch colour and formatted area, derived when
+     *  an input changes instead of per check (the area walks the region's geometry). */
+    protected rowView: Map<Region, {
+        color: string;
+        area: string;
+    }>;
+    ngOnChanges(): void;
+    private classColor;
+    private area;
+    protected startEdit(region: Region, event: Event): void;
+    protected stopEdit(region: Region, commit: boolean, event: Event): void;
+    protected onPage(event: {
+        first?: number;
+        rows?: number;
+    }): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RegionTableComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RegionTableComponent, "region-table", never, { "page": { "alias": "page"; "required": false; }; "total": { "alias": "total"; "required": false; }; "first": { "alias": "first"; "required": false; }; "rows": { "alias": "rows"; "required": false; }; "rowsPerPageOptions": { "alias": "rowsPerPageOptions"; "required": false; }; "metaKey": { "alias": "metaKey"; "required": false; }; "selection": { "alias": "selection"; "required": false; }; "presetSet": { "alias": "presetSet"; "required": false; }; "defaultColor": { "alias": "defaultColor"; "required": false; }; "mpp": { "alias": "mpp"; "required": false; }; "labelDrafts": { "alias": "labelDrafts"; "required": false; }; }, { "selectionChange": "selectionChange"; "rowSelect": "rowSelect"; "labelEditStart": "labelEditStart"; "labelDraftChange": "labelDraftChange"; "labelEditStop": "labelEditStop"; "classPick": "classPick"; "deleteRow": "deleteRow"; "pageChange": "pageChange"; }, never, never, true, never>;
+}

package/lib/region-editor/save-mask-dialog/save-mask-dialog.component.d.ts

@@ -0,0 +1,36 @@
+import { EventEmitter } from '@angular/core';
+import { MaskMode } from '../mask-export.service';
+import * as i0 from "@angular/core";
+/**
+ * The Region Editor's "Save mask" dialog: filename + mask type while idle, a
+ * progress bar (rasterize, then encode) with a Cancel button while the export
+ * runs. Presentational — the editor owns the state and the export
+ * ({@link MaskExportService}); the dialog only reports edits and clicks.
+ */
+export declare class SaveMaskDialogComponent {
+    /** The dialog is open. */
+    visible: boolean;
+    /** The dialog was closed (`false`); two-way with {@link visible}. */
+    visibleChange: EventEmitter<boolean>;
+    /** The PNG filename. */
+    filename: string;
+    /** The filename was edited; two-way with {@link filename}. */
+    filenameChange: EventEmitter<string>;
+    /** The mask type: binary, or one label value per class. */
+    mode: MaskMode;
+    /** The mask type was changed; two-way with {@link mode}. */
+    modeChange: EventEmitter<MaskMode>;
+    /** True while the export runs (the form is replaced by progress). */
+    busy: boolean;
+    /** 0–100 rasterization progress. */
+    progress: number;
+    /** True once rasterizing is done and the PNG is being encoded. */
+    encoding: boolean;
+    /** Download clicked with a non-blank filename. */
+    confirm: EventEmitter<void>;
+    /** Cancel clicked while the export runs. */
+    cancelExport: EventEmitter<void>;
+    protected close(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SaveMaskDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SaveMaskDialogComponent, "region-save-mask-dialog", never, { "visible": { "alias": "visible"; "required": false; }; "filename": { "alias": "filename"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "busy": { "alias": "busy"; "required": false; }; "progress": { "alias": "progress"; "required": false; }; "encoding": { "alias": "encoding"; "required": false; }; }, { "visibleChange": "visibleChange"; "filenameChange": "filenameChange"; "modeChange": "modeChange"; "confirm": "confirm"; "cancelExport": "cancelExport"; }, never, never, true, never>;
+}

package/lib/region-editor/save-regions-dialog/save-regions-dialog.component.d.ts

@@ -0,0 +1,37 @@
+import { EventEmitter } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * A GeoJSON filename dialog, used by the Region Editor for both "Save Regions
+ * As" (server save: overwrite warning, progress + Cancel while busy) and
+ * "Export Regions" (download). Presentational — the editor owns the state and
+ * the I/O ({@link RegionPersistenceService}).
+ */
+export declare class SaveRegionsDialogComponent {
+    /** The dialog title. */
+    header: string;
+    /** The confirm button's label. */
+    confirmLabel: string;
+    /** The confirm button's PrimeIcons class. */
+    confirmIcon: string;
+    /** id of the filename input (unique per dialog instance). */
+    inputId: string;
+    /** The dialog is open. */
+    visible: boolean;
+    /** The dialog was closed (`false`); two-way with {@link visible}. */
+    visibleChange: EventEmitter<boolean>;
+    /** The GeoJSON filename. */
+    filename: string;
+    /** The filename was edited; two-way with {@link filename}. */
+    filenameChange: EventEmitter<string>;
+    /** Shows the "will be overwritten" warning. */
+    fileExists: boolean;
+    /** True while the save runs (the form is replaced by progress). */
+    busy: boolean;
+    /** Save/Export clicked with a non-blank filename. */
+    confirm: EventEmitter<void>;
+    /** Cancel clicked while the save runs. */
+    cancelSave: EventEmitter<void>;
+    protected close(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SaveRegionsDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SaveRegionsDialogComponent, "region-save-regions-dialog", never, { "header": { "alias": "header"; "required": false; }; "confirmLabel": { "alias": "confirmLabel"; "required": false; }; "confirmIcon": { "alias": "confirmIcon"; "required": false; }; "inputId": { "alias": "inputId"; "required": false; }; "visible": { "alias": "visible"; "required": false; }; "filename": { "alias": "filename"; "required": false; }; "fileExists": { "alias": "fileExists"; "required": false; }; "busy": { "alias": "busy"; "required": false; }; }, { "visibleChange": "visibleChange"; "filenameChange": "filenameChange"; "confirm": "confirm"; "cancelSave": "cancelSave"; }, never, never, true, never>;
+}

package/lib/region-ops.service.d.ts

@@ -1,11 +1,10 @@
 import { Region } from './models/region';
-import { WandService } from './toolbar/wand/wand.service';
 import * as i0 from "@angular/core";
 /**
  * Pure (DOM-free) region set-operations — merge / inverse / ungroup (jit-ui#85).
  *
  * Raster-based, reusing the wand/brush mask pipeline
- * ({@link WandService.rasterizePolygon} → {@link WandService.maskToPolygons}),
+ * ({@link rasterizePolygon} → {@link maskToPolygons}, the pure `geometry/` modules),
  * so "select + merge" yields the same geometry as brushing regions together:
  * one engine, one set of behaviours, holes + multi-part results for free.
  *
@@ -15,7 +14,6 @@ import * as i0 from "@angular/core";
  * image pixels throughout.
  */
 export declare class RegionOpsService {
-    private wand;
     /**
      * Largest raster (in pixels) a region set-op will allocate on the main thread.
      * Selections whose clipped bbox exceeds this are rasterized at a proportional
@@ -25,7 +23,6 @@ export declare class RegionOpsService {
      * large-extent selections (small selections keep full resolution).
      */
     private static readonly MAX_OP_PIXELS;
-    constructor(wand: WandService);
     /**
      * Geometric union of `regions` into a single region: a {@link Polygon} when
      * the union is one connected piece, a {@link MultiPolygon} when it stays
@@ -51,8 +48,6 @@ export declare class RegionOpsService {
      * no full-image buffer is ever allocated.
      */
     inverse(regions: Region[], imageWidth: number, imageHeight: number): Region | null;
-    /** A closed straight-edged Polygon from parallel coord arrays. */
-    private ringPolygon;
     /**
      * Split a region into its disjoint parts — one region per {@link MultiPolygon}
      * part. A single connected {@link Polygon}/{@link Rectangle} has nothing to
@@ -86,7 +81,6 @@ export declare class RegionOpsService {
      *  inheriting colour/label from `proto`. Null when there are no parts. */
     private regionFromParts;
     private makeRegion;
-    private clonePolygon;
     static ɵfac: i0.ɵɵFactoryDeclaration<RegionOpsService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RegionOpsService>;
 }

package/lib/region-overlay/region-geometry.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Region-overlay geometry shared by the OpenSeadragon and napari overlays
+ * (review NAPARI-BOUNDARY-13, OSD-PLOTLY-16).
+ *
+ * Both overlays used to carry their own copy of this code, and the copies had
+ * drifted: napari's hit test ignored holes, multi-part regions and open
+ * polylines, its bézier path drew straight edges without stored handles, and it
+ * rendered nothing for a MultiPolygon. Everything here is pure — no DOM, no
+ * viewer — so the overlays are left with gestures and DOM.
+ *
+ * Coordinates: regions are in WORLD (image-pixel) space. Functions that need a
+ * screen-space tolerance (an open polyline's hit width, a handle's grab
+ * radius) take a {@link ToScreen} projection and measure in its pixels, so they
+ * stay usable at any zoom. Point-in-ring and ring bounds come from
+ * `geometry/ring`.
+ */
+import { Polygon, Region } from '../models/region';
+import { AnchorHandle } from '../models/bezier';
+/** World → screen projection, e.g. image → element pixels. */
+export type ToScreen = (x: number, y: number) => readonly [number, number];
+/** The identity projection: path data stays in world coordinates. */
+export declare const WORLD: ToScreen;
+/** An axis-aligned box (inclusive corners). */
+export interface BBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** Screen-px distance from an open polyline within which a point is on it. */
+export declare const OPEN_PATH_TOL_PX = 6;
+type AnyBounds = Region['bounds'] | Record<string, unknown>;
+/**
+ * Discriminate a region's bounds. Class instances first; plain objects with the
+ * right fields too, so a region that skipped the store's hydration (JSON from a
+ * host) still draws and hit-tests (jit-ui#124).
+ */
+export declare function boundsKind(b: AnyBounds | null | undefined): 'rect' | 'poly' | 'multi' | null;
+/** A polygon's ring as parallel arrays: the exterior for `ring` -1, else hole `ring`. */
+export declare function ringOf(p: Polygon, ring: number): {
+    xs: number[];
+    ys: number[];
+};
+/**
+ * A polygon ring's bézier handles (absolute, world space): the stored offsets
+ * when present, else the Catmull-Rom default the curve is drawn with. Holes are
+ * always closed.
+ */
+export declare function ringHandles(p: Polygon, ring: number): AnchorHandle[];
+/**
+ * A region's axis-aligned bounding box in world coordinates (every part of a
+ * multi-polygon), or null for empty geometry. Loops rather than
+ * `Math.min(...spread)`, which throws on a large imported annotation.
+ */
+export declare function regionBBox(region: Pick<Region, 'bounds'>): BBox | null;
+/** Shortest distance from (px,py) to the segment (ax,ay)–(bx,by), in the units given. */
+export declare function segmentDistance(px: number, py: number, ax: number, ay: number, bx: number, by: number): number;
+/** Options for {@link regionContains}. */
+export interface ContainsOptions {
+    /** Projection the open-polyline tolerance is measured in. Default: world units. */
+    toScreen?: ToScreen;
+    /** Open-polyline hit width, in `toScreen` pixels. Default {@link OPEN_PATH_TOL_PX}. */
+    tolPx?: number;
+}
+/**
+ * Whether world point (x, y) lands on `region`: a rectangle by its (inclusive)
+ * box; a closed polygon by its exterior minus its holes; a multi-polygon by any
+ * part (minus that part's holes); an open polyline — which has no interior —
+ * within `tolPx` screen pixels of its line.
+ */
+export declare function regionContains(region: Pick<Region, 'bounds'>, x: number, y: number, opts?: ContainsOptions): boolean;
+/** Index of the topmost (last) region containing (x, y), or -1. */
+export declare function topmostRegionAt(regions: ReadonlyArray<Pick<Region, 'bounds'>>, x: number, y: number, opts?: ContainsOptions & {
+    skip?: (r: Pick<Region, 'bounds'>) => boolean;
+}): number;
+/**
+ * Indices of every region whose bounding box intersects the world box
+ * [x0,y0]–[x1,y1] (rubber-band selection). `skipProfiles` leaves out
+ * intensity-profile lines.
+ */
+export declare function regionsInRect(regions: ReadonlyArray<Region>, x0: number, y0: number, x1: number, y1: number, opts?: {
+    skipProfiles?: boolean;
+}): number[];
+/** The handle offsets a bézier ring is drawn with; absent arrays fall back to the default. */
+export interface RingHandleOffsets {
+    in?: number[][];
+    out?: number[][];
+}
+/**
+ * SVG path `d` for one ring or polyline, projected through `toScreen`.
+ * Straight edges without `handles`; with `handles`, cubic segments through the
+ * stored offsets, or the Catmull-Rom default when they are missing or do not
+ * match the ring (via `resolveHandles`). Closed rings end in `Z`. '' for fewer
+ * than two vertices.
+ */
+export declare function ringPathD(xs: number[], ys: number[], closed: boolean, toScreen: ToScreen, handles?: RingHandleOffsets): string;
+/**
+ * SVG path `d` for a whole region: a rectangle's four corners; a polygon's
+ * exterior (curved for a bézier region) followed by one subpath per hole
+ * (curved too for a bézier donut); a multi-polygon's parts with their holes.
+ * Holes need `fill-rule: evenodd` (see {@link regionHasHoles}).
+ */
+export declare function regionPathD(region: Pick<Region, 'bounds'>, toScreen?: ToScreen): string;
+/** True when the region draws as several subpaths that need `fill-rule: evenodd`. */
+export declare function regionHasHoles(region: Pick<Region, 'bounds'>): boolean;
+/** What a pointer grabbed on the selected region (see {@link hitHandle}). */
+export type HandleHit = 
+/** A rectangle corner; `anchor` is the opposite (fixed) corner for a resize. */
+{
+    kind: 'corner';
+    index: number;
+    anchor: [number, number];
+}
+/** A polygon vertex: `ring` -1 for the exterior, else the hole index. */
+ | {
+    kind: 'vertex';
+    ring: number;
+    index: number;
+}
+/** A bézier control point of vertex `index` on `ring`. */
+ | {
+    kind: 'bezier';
+    ring: number;
+    index: number;
+    side: 'in' | 'out';
+};
+/**
+ * The handle of `region` under screen point (sx, sy) within `radius` screen
+ * pixels, or null. Rectangles have four corners. Polygons: every bézier
+ * control point first (exterior, then each hole; they sit off the anchors, so
+ * they must win), then the vertices (exterior, then each hole). Pass
+ * `{ bezier: false }` to test vertices only.
+ */
+export declare function hitHandle(region: Pick<Region, 'bounds'>, sx: number, sy: number, toScreen: ToScreen, radius: number, opts?: {
+    bezier?: boolean;
+}): HandleHit | null;
+/**
+ * The polygon edge nearest screen point (sx, sy), across the exterior and every
+ * hole: its ring (-1 = exterior), the index of its start vertex, and the
+ * distance in screen pixels. Null when the region is not a polygon.
+ */
+export declare function nearestEdge(region: Pick<Region, 'bounds'>, sx: number, sy: number, toScreen: ToScreen): {
+    ring: number;
+    segIndex: number;
+    dist: number;
+} | null;
+/**
+ * The polygon vertex nearest world point (x, y), across the exterior and every
+ * hole, with its distance in world units. Null when the region is not a
+ * polygon or has no vertices.
+ */
+export declare function nearestVertex(region: Pick<Region, 'bounds'>, x: number, y: number): {
+    ring: number;
+    index: number;
+    dist: number;
+} | null;
+export {};

package/lib/region-overlay/region-hit-test.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Screen-space hit testing for a selected rectangle's move/resize zones, and the
+ * resize those zones drive. Pure; shared by the SVG region overlays. (Vertex,
+ * bezier-handle and edge hits on polygons live in `region-geometry.ts`:
+ * `hitHandle` and `nearestEdge`.)
+ */
+/** Move/resize zones on the selected rectangle. */
+export type EditZone = 'move' | 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+/** The cursor that advertises each zone. */
+export declare const ZONE_CURSOR: Readonly<Record<EditZone, string>>;
+/** Screen-pixel tolerance for grabbing an edge, corner or vertex handle. */
+export declare const EDIT_TOL_PX = 8;
+/** A screen-space box: left, top, right, bottom. */
+export interface ScreenBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/**
+ * Classify a screen point against a screen-space rectangle: a corner, an edge
+ * (within `tolPx`), the body, or null when outside (beyond the tolerance).
+ */
+export declare function rectZone(px: number, py: number, box: ScreenBox, tolPx?: number): EditZone | null;
+/** An image-space rectangle. */
+export interface RectBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The rectangle `orig` moved or resized through `zone` by the total drag
+ * (`dx`, `dy`), normalised (a drag past the opposite edge flips it) and rounded
+ * to whole pixels. Absolute from the gesture-start box, so applying it on every
+ * frame is idempotent.
+ */
+export declare function resizeRect(orig: RectBox, zone: EditZone, dx: number, dy: number): RectBox;

package/lib/region-overlay/svg-region-renderer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * World-space SVG region renderer shared by the OpenSeadragon and napari
+ * overlays (review NAPARI-BOUNDARY-10, OSD-PLOTLY-11).
+ *
+ * The overlays used to delete and rebuild every region element on every camera
+ * frame, projecting every vertex to screen pixels (napari also read the layout
+ * once per vertex). Here region geometry is drawn ONCE, in world coordinates,
+ * inside a single `<g transform="matrix(a b c d e f)">`, with
+ * `vector-effect: non-scaling-stroke` so strokes keep their pixel width. A
+ * camera change rewrites that one attribute and re-positions the few
+ * screen-sized elements (labels, the selected region's handles, a draft) —
+ * nothing is created or removed. Region nodes are rebuilt only when the
+ * regions or the selection change ({@link render}).
+ *
+ * Layers, bottom to top, each attached only while it has content:
+ *  1. world   — region shapes, in world coordinates (transformed group);
+ *  2. labels  — screen-space text pinned to world anchors, rebuilt with the regions;
+ *  3. overlay — screen-space handles/drafts, rebuilt by the overlay on demand
+ *     ({@link renderOverlay}).
+ */
+import { Region } from '../models/region';
+/** An SVG affine `matrix(a b c d e f)`: x' = a·x + c·y + e, y' = b·x + d·y + f. */
+export type Affine = readonly [number, number, number, number, number, number];
+/** World → svg-local pixel projection. */
+export type Project = (x: number, y: number) => [number, number];
+export declare const IDENTITY_AFFINE: Affine;
+/**
+ * The affine of a projection that is affine (pan/zoom/rotate/flip), read from
+ * where it sends (0,0), (1,0) and (0,1) — how the OSD overlay gets its matrix
+ * from the viewport transform without depending on viewer internals. (napari-js
+ * hands the napari overlay its matrix directly: `Viewer.canvasTransform()`.)
+ */
+export declare function affineFromProjection(project: (x: number, y: number) => readonly [number, number]): Affine;
+/** Apply an affine to a point. */
+export declare function applyAffine(m: Affine, x: number, y: number): [number, number];
+/** How a placed screen element is (re)positioned for the current camera. */
+export type Placement<T extends SVGElement> = (el: T, project: Project) => void;
+/** Options for {@link SvgRegionRenderer}. */
+export interface SvgRegionRendererOptions {
+    /** Draw a {@link Rectangle} as a `<rect>` or as a four-point `<polygon>`. Default polygon. */
+    rectElement?: 'rect' | 'polygon';
+    /** Stroke and fill for one region's shape element. */
+    styleShape(el: SVGElement, region: Region, selected: boolean): void;
+    /** Add a region's screen-space decorations (its label) — once per {@link render}. */
+    decorate?(region: Region, index: number, selected: boolean, layer: ScreenLayer): void;
+    /** Leave a region out entirely (it keeps its index). */
+    skip?(region: Region): boolean;
+}
+/**
+ * A screen-space layer: elements positioned from world anchors through the
+ * current camera, re-positioned (not rebuilt) on every camera change.
+ */
+export declare class ScreenLayer {
+    readonly group: SVGGElement;
+    private readonly project;
+    private readonly placed;
+    constructor(group: SVGGElement, project: Project);
+    /** Append `el`, positioned by `place` now and after every camera change. */
+    place<T extends SVGElement>(el: T, place: Placement<T>): T;
+    /** Append `el` with attributes `x`/`y` (e.g. `'cx'`/`'cy'`) at a world point, offset in pixels. */
+    at<T extends SVGElement>(el: T, wx: number, wy: number, attrs?: {
+        x?: string;
+        y?: string;
+        dx?: number;
+        dy?: number;
+    }): T;
+    /** A `<line>` between two world points. */
+    line(ax: number, ay: number, bx: number, by: number): SVGLineElement;
+    /** A `<polygon>` / `<polyline>` through world points. */
+    poly(tag: 'polygon' | 'polyline', pts: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>): SVGElement;
+    /** Re-position every element for the current camera. */
+    reproject(): void;
+    get isEmpty(): boolean;
+    clear(): void;
+}
+/** Create an SVG element. */
+export declare function svgEl<K extends keyof SVGElementTagNameMap>(tag: K): SVGElementTagNameMap[K];
+export declare class SvgRegionRenderer {
+    private readonly svg;
+    private readonly opts;
+    private camera;
+    private readonly world;
+    private readonly labels;
+    private readonly overlay;
+    /** World → svg-local pixels through the current camera. */
+    readonly project: Project;
+    constructor(svg: SVGSVGElement, opts: SvgRegionRendererOptions);
+    /** The current world → svg-local affine. */
+    get affine(): Affine;
+    /**
+     * Move the camera: rewrite the world group's transform and re-position the
+     * screen-space elements. No element is created or removed. Returns false
+     * (and touches nothing) when the affine did not change.
+     */
+    setCamera(affine: Affine): boolean;
+    /** Rebuild the region shapes (world space) and their decorations. */
+    render(regions: ReadonlyArray<Region>, selected: ReadonlyArray<number>): void;
+    /** Rebuild the overlay layer (the selected region's handles, drafts). */
+    renderOverlay(build: (layer: ScreenLayer) => void): void;
+    /** Remove every layer from the svg. */
+    destroy(): void;
+    private applyCamera;
+    /** Attach the layers that have content (in order) and detach the empty ones. */
+    private sync;
+    /** The world-space element for a region's geometry, or null when it has none. */
+    private shapeOf;
+}

package/lib/render-orchestrator.d.ts

@@ -16,7 +16,8 @@ import { IImageInfo } from './contracts/image.contract';
 export interface TwoPassRenderHost {
     /** Load + plot one phase (the component owns div/screen/plot-type/z and the
      *  newer-click filename guard). `inPlace` updates the existing render so the
-     *  canvas doesn't blank during the small→large swap. */
+     *  canvas doesn't blank during the small→large swap. Rejects when the phase
+     *  could not be drawn (including a backend's `plot()` resolving false). */
     renderPhase(info: IImageInfo, inPlace: boolean): Promise<unknown>;
     /** The small tier is on screen — drop the full loading overlay so the user
      *  sees the blurry preview, and show the sharpening spinner. */
@@ -26,10 +27,13 @@ export interface TwoPassRenderHost {
     /** Rendering finished. `viaSmall` = the overlay was already released by the
      *  small tier (so only release the running guard + apply the ROI); otherwise
      *  do the full finalize (overlay + running + ROI). */
-    finished(viaSmall: boolean, logTag: string): void;
+    finished(viaSmall: boolean): void;
     /** Both large-tier attempts failed; the small tier stays on screen as the
      *  fallback. Surface it to the user and release the running guard + ROI. */
     sharpenFailed(err: unknown): void;
+    /** Nothing could be drawn: the single pass failed, or both tiers did. Called
+     *  after {@link finished} (which releases the overlay), to tell the user. */
+    renderFailed(err: unknown): void;
 }
 export declare class RenderOrchestrator {
     private host;

package/lib/render-session.d.ts

@@ -0,0 +1,75 @@
+import { IImageInfo } from './contracts/image.contract';
+import { PlotType } from './contracts/plot-type';
+import { SpatialDataset } from './contracts/spatial-dataset.contract';
+import { IVisualizer } from './contracts/visualizer.contract';
+/** A user-facing message for a failure: an HttpErrorResponse's server message, an
+ *  Error's message, or the status text, else the value itself. */
+export declare function errorMessage(err: unknown): string;
+/** The viewer a render session draws into, and what it tells the viewer. */
+export interface RenderSessionHost {
+    readonly plotDivName: string;
+    readonly visualizer: IVisualizer;
+    /** The slice to load, read when each phase starts. */
+    zIndex(): number;
+    plotType(): PlotType;
+    /** A 2D view: only it renders the small tier first (the in-place sharpen pass does
+     *  not rebuild a 3D scene, so it blanked one). */
+    isHeatmap(): boolean;
+    /** A server-side cache fill is in progress (keeps the full overlay up). */
+    isCaching(): boolean;
+    /** The view is about to be torn down: end what was bound to it (contributed sessions). */
+    beforeReset(): void;
+    /** Lay the new image out (stack flag, slice bounds, initial slice) once the old view is gone. */
+    prepare(info: IImageInfo): void;
+    /** Drop the loading overlay the render owns (once per render). */
+    releaseOverlay(info: IImageInfo): void;
+    /** The render landed, sharp or as a fallback: apply ROIs, start sessions. */
+    landed(info: IImageInfo): void;
+    setImageLoading(loading: boolean): void;
+    alert(severity: 'warn' | 'error', summary: string, detail: string): void;
+    detectChanges(): void;
+}
+/**
+ * The viewer's render pipeline: one image (or image-less dataset) at a time, the newest
+ * always winning.
+ *
+ * Every render takes a task from a {@link Supersede}: a newer render, a Cancel or
+ * teardown makes the older one stale — its callbacks return early instead of painting,
+ * releasing the newer render's overlay or applying its ROIs — and aborts the signal its
+ * loads were given, so superseded network work stops at the source. Sequencing of the
+ * small→large tiers lives in {@link RenderOrchestrator}; this owns the UI flags it
+ * drives ({@link running}, {@link sharpening}).
+ */
+export declare class ImageRenderSession {
+    private readonly host;
+    /** A render is in flight. */
+    running: boolean;
+    /** The small tier is on screen and the large one is still loading. */
+    sharpening: boolean;
+    /** Set once the plot div exists; an image-less draw before then waits for it. */
+    private viewReady;
+    private pendingDraw;
+    private readonly supersede;
+    constructor(host: RenderSessionHost);
+    /**
+     * Render `info` (which has urls), preempting whatever is in flight. A newer image
+     * ALWAYS preempts: dropping it while the old one finished reported image B as loaded
+     * while image A stayed on screen, and a cold image held the slot for its whole
+     * server-side cache fill.
+     */
+    render(info: IImageInfo): void;
+    /**
+     * Draw a spatial mode with no image behind it: the observations alone, framed on their
+     * own extent. The image info is a placeholder naming the dataset, so regions drawn here
+     * are kept per dataset like any image's. Supersedes (and is superseded by) image renders.
+     */
+    plotWithoutImage(dataset: SpatialDataset): Promise<void>;
+    /**
+     * The plot div exists now: run an image-less draw that arrived before it did — only if
+     * its dataset is still the one on offer (by id: the port may re-emit the same dataset
+     * as a new object, and the current object is the one to draw) and no image has arrived.
+     */
+    viewIsReady(current: SpatialDataset | null, hasImage: boolean): void;
+    /** Cancel the render in flight: abort its loads and make its callbacks inert. */
+    cancel(): void;
+}