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

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

@@ -17,3 +17,10 @@ import * as OpenSeadragon from 'openseadragon';
  * it real named exports and plain member access works.)
  */
 export declare const OSD: typeof OpenSeadragon;
+/**
+ * Run an operation on an OSD tiled image, navigator or viewer that may already
+ * have been torn down (a slice evicted mid-load, the viewer destroyed during an
+ * animation or a timed refit). A throw there is expected and harmless, so it is
+ * only logged at debug level instead of being swallowed silently.
+ */
+export declare function quiet(fn: () => void): void;

package/lib/implementations/osd/osd-navigator-chrome.d.ts

@@ -0,0 +1,69 @@
+import type * as OpenSeadragon from 'openseadragon';
+/** The service state the chrome reads — live, so it follows a viewer rebuild. */
+export interface OsdChromeHost {
+    viewer(): OpenSeadragon.Viewer | null;
+    /** The DOM id OSD is mounted in. */
+    plotDiv(): string;
+}
+/**
+ * The viewer chrome and its browser workarounds: the overview navigator
+ * (visibility, sizing, corner pinning), image smoothing, the initial
+ * fit-to-view as the host layout settles, and the docked-toolbar repaint nudge.
+ *
+ * `navigatorVisible` and `smoothingEnabled` are read when a viewer is created
+ * (see buildViewerOptions) and applied live to a mounted one.
+ */
+export declare class OsdNavigatorChrome {
+    private readonly host;
+    /** Whether the overview navigator (minimap) is shown. A consumer that doesn't
+     *  want it (e.g. a small embedded preview) sets it off before the first render. */
+    navigatorVisible: boolean;
+    /** Image smoothing (bilinear). `false` → nearest-neighbour, so zoomed-in pixels
+     *  render as crisp blocks (pixel inspection). Defaults to `false` so the image
+     *  opens showing raw pixels. */
+    smoothingEnabled: boolean;
+    /** The host's docked toolbar (see nudgeToolbarRepaint): undefined until looked
+     *  up for the current mount, null when there is none. */
+    private toolbarDock;
+    private lastToolbarNudge;
+    static readonly TOOLBAR_NUDGE_INTERVAL_MS = 100;
+    constructor(host: OsdChromeHost);
+    /** A new image is being mounted: the toolbar is looked up again for it. */
+    onMount(): void;
+    /**
+     * Wire the chrome onto a freshly opened viewer: the toolbar nudges, the
+     * fit-to-view retries as the layout settles, and the navigator re-sizing.
+     */
+    attach(viewer: OpenSeadragon.Viewer, plotDiv: string): void;
+    /** Show/hide the overview navigator. Stored for the next viewer creation, and
+     *  applied live when a viewer is already mounted (hides/reveals its element —
+     *  the navigator instance itself only exists when created with showNavigator). */
+    setNavigatorVisible(visible: boolean): void;
+    /** Toggle bilinear smoothing vs nearest-neighbour (crisp pixels). Stored for the
+     *  next viewer creation, and applied live (with a redraw) to a mounted viewer. */
+    setImageSmoothingEnabled(enabled: boolean): void;
+    /**
+     * Fit-to-home once `el` first has a non-zero size. If it's already sized we
+     * rely on the timed refits the caller scheduled; otherwise a one-shot
+     * ResizeObserver runs `refit` the moment the container is laid out (then
+     * disconnects), so the initial fit doesn't depend on the render's start time
+     * relative to the diagram container's layout. No-op without a container or
+     * ResizeObserver (the timed refits remain the fallback). One-shot + only
+     * attached on a fresh mount, so slice-scrub re-opens keep the user's zoom.
+     */
+    fitWhenContainerSized(el: HTMLElement | null, refit: () => void): void;
+    /** Size the navigator from the CURRENT container (navigatorSizeRatio of the
+     *  viewer element) and keep it pinned to the corner. OSD computes the size
+     *  once in the Viewer constructor — before the host flex layout settles —
+     *  and never corrects it, leaving a stale-size element whose visible minimap
+     *  floats above the bottom-right corner. */
+    resizeNavigator(): void;
+    /** Force the docked toolbar to repaint after an OSD zoom. Chrome leaves it
+     *  laid-out-but-unpainted (the canvas's compositing churn strands the toolbar's
+     *  raster). A synchronous display toggle re-rasters it with no visible gone-frame
+     *  and no layout shift. Located via the DOM since the service doesn't own the
+     *  toolbar; a no-op when there's no toolbar (e.g. embedded without one). The
+     *  element is looked up once per mount. `throttled` (animation frames) nudges
+     *  at most every {@link TOOLBAR_NUDGE_INTERVAL_MS}: each nudge forces a layout. */
+    nudgeToolbarRepaint(throttled?: boolean): void;
+}

package/lib/implementations/osd/osd-pixel-readback.d.ts

@@ -0,0 +1,22 @@
+import type * as OpenSeadragon from 'openseadragon';
+import { CachedImageData } from '../../toolbar/tool-kit/canvas-tool';
+import { PixelData } from '../../contracts/visualizer.contract';
+/**
+ * The currently displayed pixels — the rendered viewport (what the user sees,
+ * including the current zoom and any colormap recolor), as RGBA. Null until
+ * tiles are drawn.
+ */
+export declare function readDrawerPixels(viewer: OpenSeadragon.Viewer | null): PixelData | null;
+/**
+ * Read back the *currently rendered* OSD canvas as the pixel tools' frame.
+ * The frame covers only the visible viewport at screen resolution, so when
+ * the user is zoomed into a sub-region the wand samples that region's detail
+ * (rather than the whole image at preview resolution). `originX/originY` and
+ * `ratios` map image coords <-> readback-pixel coords for the wand's
+ * data/ratio/origin model. The RGBA readback is the frame as-is (packed,
+ * RT-17 / OSD-PLOTLY-12): no per-pixel arrays.
+ */
+export declare function readbackViewportFrame(viewer: OpenSeadragon.Viewer | null): CachedImageData | null;
+/** Save the rendered view (the drawer canvas) as `<stem>.png`; a no-op before
+ *  anything is drawn. */
+export declare function saveDrawerSnapshot(viewer: OpenSeadragon.Viewer | null, save: (blob: Blob) => void): void;

package/lib/implementations/osd/osd-region-overlay-draw.d.ts

@@ -0,0 +1,37 @@
+import { Region } from '../../models/region';
+import { ScreenLayer } from '../../region-overlay/svg-region-renderer';
+/**
+ * The OpenSeadragon region overlay's look: region stroke/fill, labels, the
+ * selected region's handles, the marquee and the in-progress drawing. Pure SVG
+ * builders over the shared {@link ScreenLayer} (image points in, screen-space
+ * elements out), so the overlay itself keeps only lifecycle and gestures.
+ */
+type Pt = {
+    x: number;
+    y: number;
+};
+/** `color` with `alpha`; a colour that doesn't parse (a named one) is used as-is. */
+export declare function rgba(color: string, alpha: number): string;
+/** Stroke/fill for a region shape (drawn in image coordinates by the renderer). */
+export declare function styleRegionShape(el: SVGElement, region: Region, selected: boolean, shapeColor: string): void;
+/**
+ * The class label (legend) just above the region's top-left — mirrors Plotly's
+ * per-shape label, drawn in the region's colour. region.label is restored from
+ * the shape's legend in getRegion().
+ */
+export declare function drawRegionLabel(layer: ScreenLayer, region: Region, shapeColor: string): void;
+/** A small vertex handle (filled when emphasised, hollow otherwise) at an image point. */
+export declare function vertexMarker(layer: ScreenLayer, x: number, y: number, emphasised: boolean, color: string): void;
+/**
+ * The selected region's handles, in its own colour: every vertex of every ring
+ * of a polygon (so a donut's inner outline shows its vertices — jit-ui#85), the
+ * bezier anchors and control handles of a curved one, or a rectangle's corners.
+ */
+export declare function drawSelectionHandles(layer: ScreenLayer, region: Region, color: string): void;
+/** Marquee rectangle for rubber-band multi-select (dashed outline + faint fill). */
+export declare function drawSelectionBand(layer: ScreenLayer, a: Pt, b: Pt): void;
+/** The rectangle being dragged out ('drawrect'). */
+export declare function drawDraftRect(layer: ScreenLayer, a: Pt, b: Pt, color: string): void;
+/** The path traced or placed so far (freehand, polyline, click-to-place polygon). */
+export declare function drawDraftPath(layer: ScreenLayer, pts: Pt[], color: string): void;
+export {};

package/lib/implementations/osd/osd-region-overlay.d.ts

@@ -1,6 +1,7 @@
 import { IRegionStore } from '../../contracts/visualizer.contract';
 import { IRegionEditApi } from '../../contracts/region-store.contract';
 import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
+import { OsdViewerLike } from './osd-viewer-like';
 /**
  * The shared region store as the overlay needs it: the cross-backend
  * {@link IRegionStore} (read regions, selection, colours) plus the Region-native
@@ -29,7 +30,6 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
     private store;
     private readonly svg;
     private readonly subs;
-    private readonly osd;
     private selected;
     private mode;
     private tracker;
@@ -55,7 +55,18 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
     private bandCurrent;
     private bandDragged;
     private readonly redrawHandler;
-    constructor(viewer: any, store: RegionEditStore);
+    /** A camera move ('update-viewport', raised on every redrawn frame, animated ones
+     *  included; 'resize'; 'rotate'). The regions are drawn in image coordinates, so
+     *  only the renderer's transform and its few screen-space elements follow; nothing
+     *  is rebuilt (OSD-PLOTLY-11). A tile-only frame (loading, recolor) leaves the
+     *  projection, and so the DOM, untouched. */
+    private readonly cameraHandler;
+    private readonly renderer;
+    /** OSD's MouseTracker drops a cancelled pointer (touch interrupted, pointer
+     *  capture lost to the browser) without calling releaseHandler, so the
+     *  gesture is ended here instead. */
+    private readonly pointerCancelHandler;
+    constructor(viewer: OsdViewerLike, store: RegionEditStore);
     /** Switch drawing/selection mode; toggles OSD navigation accordingly. */
     setMode(mode: RegionToolMode): void;
     /** Drive OSD zoom from the wheel while any tool owns the pointer.
@@ -80,37 +91,24 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
     destroy(): void;
     /** Image-pixel point -> element pixel point. */
     private toPx;
-    /** Element pixel point (from a MouseTracker event) -> image-pixel point. */
+    /** Element pixel point (from a MouseTracker event) -> image-pixel point, rounded
+     *  to whole pixels (where a drawn vertex lands). */
     private toImage;
+    /** Element pixel point -> exact image point, for hit tests. */
+    private toWorld;
+    /** Image point -> element px, as the shared region geometry wants it. */
+    private readonly toScreen;
+    /** Follow the current image→element projection: the renderer rewrites one transform
+     *  and re-positions its screen-space elements, or does nothing when it did not move. */
+    private updateCamera;
+    /** Rebuild everything: the regions (in image coordinates), their labels and the overlay. */
     redraw(): void;
-    /** A small vertex handle (filled for an emphasised marker, hollow otherwise).
-     *  Colour defaults to the global shape colour (used by the in-progress draw
-     *  preview); selected-region handles pass the region's own colour. */
-    private vertexMarker;
-    private buildRegionEl;
-    /** Marquee rectangle for rubber-band multi-select (dashed outline + faint fill). */
-    private selectionBand;
-    private rectPreview;
-    private polyPreview;
-    /** SVG path `d` (element-pixel coords) for a straight-edged ring/polyline. */
-    private straightPathD;
-    /** SVG path `d` (element-pixel coords) for the smooth cubic bezier through a
-     *  polygon's anchors — the paper.js-equivalent curve. */
-    private bezierPathD;
-    /** SVG cubic-bezier path `d` (element px) for any ring (exterior or hole). Uses the stored
-     *  per-vertex handle offsets when present, else the Catmull-Rom default (resolveHandles). */
-    private ringBezierPathD;
     /**
-     * Draw the bezier editing handles for the selected region, paper.js-style:
-     * each anchor as a small square, with tangent lines out to its two control
-     * points (drawn as small circles).
+     * Rebuild the screen-space overlay only: the selected region's handles, the rubber band
+     * and any in-progress drawing. Drawing and marquee drags call this rather than
+     * {@link redraw}, so the regions are not rebuilt per pointer move.
      */
-    private drawBezierHandles;
-    /** A tangent line from an anchor to a control point, with a circle at the end. */
-    private drawHandle;
-    /** A filled-white anchor square (the editable vertex). */
-    private anchorSquare;
-    private rgba;
+    private renderOverlay;
     private get isFreehand();
     private onPress;
     /** Begin an edit gesture (move/resize or single-vertex drag) and open a store
@@ -138,17 +136,13 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
     private editZoneAt;
     /** The currently-selected region (the last one selected), or null. */
     private selectedRegionInfo;
-    /** The vertex of the selected polygon under the cursor (screen-pixel
-     *  tolerance), or null. Rectangles have no editable vertices. */
-    private hitVertex;
-    /** The bezier control handle of the selected region under the cursor (which
-     *  anchor, and whether the in- or out-handle), or null. */
-    private hitBezierHandle;
+    /** The bezier control handle (when `bezier`) or vertex of the selected polygon
+     *  under the cursor (screen-pixel tolerance), or null. Rectangles have no
+     *  editable vertices (their corners are resize zones, see {@link rectZone}). */
+    private hitPolygonHandle;
     /** The edge of `region`'s polygon nearest the cursor (within tolerance), with
      *  the clicked point in image coords as the insertion position, or null. */
     private hitEdge;
-    /** Classify a screen point against a screen-space rectangle into a zone. */
-    private rectZone;
     /** Snapshot the selected region's geometry at the start of an edit. */
     private snapshot;
     /**
@@ -158,19 +152,13 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
      */
     private applyEdit;
     private selectAt;
-    /** Indices of every region whose bounding box intersects the image-space
-     *  rectangle [x0,y0]–[x1,y1] (rubber-band multi-select). */
-    private regionsInRect;
-    /** Axis-aligned bounding box of a region in image coords, or null if empty. */
-    private regionBBox;
-    /** Index of the topmost region under a point, or -1. */
+    /** Index of the topmost region under an image point, or -1. */
     private regionIndexAt;
+    /** Whether the element-pixel `position` lands on `region` (see `regionContains`). */
     private containsPoint;
-    /** Point-in-closed-polygon (image coords) honouring interior rings (holes):
-     *  inside the exterior AND outside every hole (even-odd). */
-    private closedPolygonContains;
-    /** Shortest distance from point p to segment a–b, all in screen pixels. */
-    private distToSegmentPx;
+    /** Abandon whatever pointer gesture is in progress (drawing, edit drag,
+     *  rubber band) and close its store batch. */
+    private endGesture;
     private resetInProgress;
     private commitRectangle;
     private commitPolygon;

package/lib/implementations/osd/osd-scale-bar.d.ts

@@ -1,17 +1,19 @@
+import { OsdViewerLike } from './osd-viewer-like';
 /**
- * A physical scale bar drawn over an OpenSeadragon viewer. Recomputes on every
- * pan/zoom from the viewport's image→screen scale and the image's µm/pixel
- * (`mppX`, from Bio-Formats). Hidden when the image has no physical pixel size.
+ * A physical scale bar drawn over an OpenSeadragon viewer. The length maths (the nice 1/2/5 × 10ⁿ
+ * length nearest the target, and its unit) are napari-js's `scaleBarFor` / `formatLength`, which
+ * also size the napari backend's `ScaleBarOverlay`, so the two bars agree; the DOM is the same
+ * label-over-a-bracketed-line. Recomputes on every pan/zoom from the image→screen scale and the
+ * image's µm/pixel (`mppX`, from Bio-Formats). Hidden when the image has no physical pixel size.
  */
 export declare class OsdScaleBar {
     private viewer;
     private mppX;
-    private readonly osd;
     private readonly bar;
-    private readonly line;
     private readonly label;
+    private readonly line;
     private readonly redrawHandler;
-    constructor(viewer: any, mppX: number);
+    constructor(viewer: OsdViewerLike, mppX: number);
     private update;
     destroy(): void;
 }

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

@@ -0,0 +1,49 @@
+import { TileDescriptor } from '../tile-server';
+/**
+ * Per-channel fit-view tile budget (tiles at the coarsest real level × channels).
+ * Above it, a multichannel image renders server-composited instead of per-channel
+ * — its full-res reads (it has no overview pyramid) would be too many × N channels.
+ * 64 (e.g. a 4x4 single-FOV z-stack × 4ch) stays per-channel; a whole-slide
+ * (hundreds–thousands) falls back.
+ */
+export declare const MAX_MULTICHANNEL_FIT_TILES = 256;
+/** How a tiled image is drawn, decided once per mount by {@link planTiledMount}. */
+export interface TiledMountPlan {
+    /** Real Bio-Formats resolution levels (per-channel tiles exist only here). */
+    realLevels: number;
+    /** Composite client-side from one TiledImage per channel. */
+    multiChannel: boolean;
+    /** Tiles covering the whole image at the coarsest real level. */
+    coarseTiles: number;
+}
+/**
+ * Decide how to draw a tiled image. Multichannel fluorescence (indexed/LUT-bearing
+ * stacks) composite client-side from per-channel tiles. Trust the server's explicit
+ * `multichannel` flag — the old `channels>1 && grayscale` heuristic also matched RGB
+ * photos Bio-Formats reads as separated planes (channels>1, rgbChannels==1),
+ * splitting them into N per-channel TiledImages that flooded the tile endpoint and
+ * hung on load.
+ */
+export declare function planTiledMount(d: TileDescriptor, maxFitTiles?: number): TiledMountPlan;
+/** Where the tiles of one slice (and optionally one channel) come from. */
+export interface TileSourceSpec {
+    api: string;
+    infoB64: string;
+    z: number;
+    /** Fetch this channel's single-band tiles (per-channel multichannel rendering). */
+    channel?: number;
+    /** Drive OSD off the first N (real) levels only — see {@link buildOsdTileSource}. */
+    realLevelsOnly?: number;
+}
+/**
+ * Custom tile source built from the descriptor. OSD numbers levels
+ * coarsest-first; the backend numbers resolutions full-res-first, so
+ * `res = (levels-1) - osdLevel`. Overriding getLevelScale/getNumTiles lets us
+ * honour Bio-Formats' actual per-level dimensions (not assume power-of-two).
+ *
+ * Multichannel images composite from per-channel tiles, which only exist at
+ * real Bio-Formats resolutions — so `realLevelsOnly` drives OSD off the real
+ * levels alone and skips the synthetic (server-composited) overviews. Every
+ * displayed tile is then per-channel-fetchable at any zoom.
+ */
+export declare function buildOsdTileSource(d: TileDescriptor, spec: TileSourceSpec): Record<string, unknown>;

package/lib/implementations/osd/osd-viewer-like.d.ts

@@ -0,0 +1,100 @@
+import type * as OpenSeadragon from 'openseadragon';
+/**
+ * The slice of an OpenSeadragon `Viewer` that the OSD helpers (osd-coords, the
+ * coordinate transform, the scale bar, the region overlay and the slice cache)
+ * actually use — and nothing more (OSD-PLOTLY-27).
+ *
+ * The real `OpenSeadragon.Viewer` is assignable to it as is, so the service
+ * passes its viewer straight through; the specs build a small fake (see
+ * `testing/fake-osd-viewer.ts`) instead of casting a partial object. Points and
+ * rectangles are structural where the helpers only read `x`/`y`/`width`/`height`;
+ * `OpenSeadragon.Rect` is kept only where the result goes back into OSD
+ * (`imageToViewportRectangle` → `viewport.fitBounds`).
+ */
+export interface OsdViewerLike {
+    /** The element OSD draws into; overlays (scale bar, region SVG) are appended
+     *  here and its client rect anchors client↔element conversions. */
+    canvas: HTMLElement;
+    /** The viewer's root element (an ancestor of the canvas and of the tool
+     *  overlays) — the wheel-zoom listener is bound here. */
+    element: HTMLElement;
+    viewport: {
+        viewerElementToViewportCoordinates(p: OsdXY): OsdXY;
+        viewportToViewerElementCoordinates(p: OsdXY): OsdXY;
+        /** Image conversions on the viewport — ambiguous once the world holds
+         *  several images; used only as the empty-world fallback. */
+        viewerElementToImageCoordinates(p: OsdXY): OsdXY;
+        imageToViewerElementCoordinates(p: OsdXY): OsdXY;
+        imageToViewportRectangle(r: OpenSeadragon.Rect): OpenSeadragon.Rect;
+        viewportToImageRectangle(r: OsdRectLike): OsdRectLike;
+        /** Viewer-element pixel → viewport point (the wheel-zoom anchor). */
+        pointFromPixel(p: OsdXY): OsdXY;
+        zoomBy(factor: number, refPoint?: OsdXY): unknown;
+        applyConstraints(immediately?: boolean): unknown;
+    };
+    world: {
+        getItemCount(): number;
+        /** `undefined` past the end of the world (OSD returns it at runtime). */
+        getItemAt(index: number): OsdTiledImageLike | undefined;
+        /** -1 when the item is no longer in the world (evicted / removed). */
+        getIndexOfItem(item: OsdTiledImageLike): number;
+        removeItem(item: OsdTiledImageLike): void;
+    };
+    /** Queue a tiled image into the world; `success` fires once it is added (not
+     *  once its tiles have loaded). */
+    addTiledImage(options: OsdAddTiledImageOptions): void;
+    addHandler(event: OsdViewerEventName, handler: () => void): unknown;
+    removeHandler(event: OsdViewerEventName, handler: () => void): unknown;
+    /** OSD's own pan/zoom (drag + wheel); region tools switch it off. */
+    setMouseNavEnabled(enabled: boolean): unknown;
+    isMouseNavEnabled(): boolean;
+}
+/** A point in any OSD space (viewer-element px, viewport units or image px —
+ *  the method it comes from says which). */
+export interface OsdXY {
+    x: number;
+    y: number;
+}
+/** An axis-aligned rectangle, in the space of the method that produced it. */
+export interface OsdRectLike {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The members of an OSD `TiledImage` (one world item: an image, a stack slice
+ *  or one channel layer) the helpers use. */
+export interface OsdTiledImageLike {
+    viewportToImageCoordinates(p: OsdXY): OsdXY;
+    imageToViewportCoordinates(p: OsdXY): OsdXY;
+    imageToViewportRectangle(r: OpenSeadragon.Rect): OpenSeadragon.Rect;
+    viewportToImageRectangle(r: OsdRectLike): OsdRectLike;
+    setOpacity(opacity: number): void;
+    /** False while any of the image's tiles are still loading. */
+    getFullyLoaded(): boolean;
+    /** Re-run the tile pipeline (restore + re-process) for this image's tiles;
+     *  tiles already stamped at `>= tStamp` are skipped. Optional: the slice
+     *  cache feature-tests it. */
+    requestInvalidate?(restoreTiles?: boolean, viewportOnly?: boolean, tStamp?: number): unknown;
+}
+/** The `addTiledImage` options the slice cache passes. Image placement is in
+ *  viewport units (`width: 1` = the primary image's normalized width). */
+export interface OsdAddTiledImageOptions {
+    tileSource: string | object;
+    x?: number;
+    y?: number;
+    width?: number;
+    opacity?: number;
+    /** Load tiles even while hidden (opacity 0). */
+    preload?: boolean;
+    /** Canvas composite operation, e.g. `'lighter'` for additive channels. */
+    compositeOperation?: string;
+    /** Fires once the image is in the world. OSD types the payload as a DOM
+     *  `Event`; at runtime it carries the added `item`. */
+    success?(event: Event & {
+        item?: OsdTiledImageLike;
+    }): void;
+    error?(): void;
+}
+/** The viewer events the helpers subscribe to. */
+export type OsdViewerEventName = 'update-viewport' | 'animation' | 'resize' | 'rotate';

package/lib/implementations/osd/osd-viewer-mount.d.ts

@@ -0,0 +1,14 @@
+import type * as OpenSeadragon from 'openseadragon';
+/** How long a mount waits for OSD's `open`/`open-failed` before giving up. */
+export declare const OSD_OPEN_TIMEOUT_MS = 8000;
+/** Create an OpenSeadragon viewer (synchronously: a throwing factory throws here). */
+export declare function createViewer(options: Record<string, unknown>): OpenSeadragon.Viewer;
+/**
+ * Open `tileSource` in `viewer`. `onOpen` wires the freshly opened viewer
+ * (overlays, handlers); the promise resolves true once it ran, false on
+ * `open-failed` — and ALWAYS settles: if OSD never emits either (a bad tile
+ * source, a viewer torn down mid-open), the render pipeline must not hang, since
+ * a hang leaves imageLoading=true, sticking the spinner and the 500ms
+ * cache-progress poll forever (NS_BINDING_ABORTED storm).
+ */
+export declare function openViewer(viewer: OpenSeadragon.Viewer, tileSource: unknown, onOpen: (viewer: OpenSeadragon.Viewer) => void): Promise<boolean>;

package/lib/implementations/osd/osd-viewport.d.ts

@@ -0,0 +1,77 @@
+import { Subject } from 'rxjs';
+import type * as OpenSeadragon from 'openseadragon';
+import { OsdCoordinateTransform } from './osd-coordinate-transform';
+import { PlotModeRect, PlotModeViewport } from '../../contracts/plot-type-contribution.contract';
+import { TileDescriptor } from '../tile-server';
+/** The service state the viewport adapter reads — live, so it follows a viewer rebuild. */
+export interface OsdViewportHost {
+    viewer(): OpenSeadragon.Viewer | null;
+    descriptor(): TileDescriptor | null;
+    coordTransform(): OsdCoordinateTransform | null;
+    overlayContainer(): HTMLElement | null;
+}
+/**
+ * The OpenSeadragon viewport as the rest of the library sees it: the visible
+ * image rect (settled, and per animation frame), the {@link PlotModeViewport} a
+ * contributed plot mode draws over, and the zoom/fit commands.
+ *
+ * Every member reads the CURRENT viewer through the host, so one instance lives
+ * as long as the service and stays valid across viewer rebuilds.
+ */
+export declare class OsdViewportAdapter {
+    private readonly host;
+    /** Visible image region (full-image pixel coords) emitted when the view
+     *  settles, so the intensity inset can re-sample at the current zoom level. */
+    readonly viewportChange$: Subject<PlotModeRect>;
+    /** The visible rect on every redraw, coalesced to one emission per animation
+     *  frame. Feeds {@link PlotModeViewport.frame$}. */
+    private readonly frame$;
+    private frameRaf;
+    private plotModeViewport;
+    constructor(host: OsdViewportHost);
+    /** Compute the current viewport's image-pixel rectangle (clamped to the image)
+     *  and broadcast it. */
+    emitViewportChange(): void;
+    /** The current viewport's image-pixel rectangle, clamped to the image, or
+     *  null when there is no laid-out viewport. */
+    visibleImageRect(): PlotModeRect | null;
+    /**
+     * Image-pixel rectangle the drawer canvas currently covers. Unlike
+     * {@link visibleImageRect}, this is NOT clamped to the image bounds: the canvas
+     * maps 1:1 to the viewport rectangle, so leaving it unclamped keeps
+     * `canvasPx -> imagePx` an exact affine map (clamping would skew coordinates
+     * near the image edges). Routed through world item 0 (see
+     * {@link viewportRectToImage}) for multi-layer accuracy.
+     */
+    displayedSourceRect(): PlotModeRect | null;
+    /** Coalesce redraws into one {@link frame$} emission per animation frame.
+     *  Skipped entirely while nothing listens. */
+    scheduleFrame(): void;
+    /** Drop a pending {@link scheduleFrame} (the viewer is going away). */
+    cancelFrame(): void;
+    /**
+     * The viewport a contributed plot mode draws over. One stable object per
+     * service: every method reads the CURRENT viewer, so it stays valid across a
+     * viewer rebuild and reports `isReady() === false` while none is mounted
+     * (conversions then return NaN rather than throwing).
+     */
+    plotModeViewportFor(): PlotModeViewport;
+    /** `source`, preceded by the current visible rect for each subscriber (when ready). */
+    private withCurrentRect;
+    /**
+     * Keep the user's current view across a container/split resize instead of
+     * snapping home. Viewport bounds are image-relative (image width = 1), so
+     * they're independent of the container's pixel size — capture the visible
+     * region now and re-fit it once the new size has settled. OSD's autoResize
+     * fires asynchronously and the angular-split transition animates the width
+     * over a few hundred ms, so restore on the next frame and again after the
+     * transition completes.
+     */
+    keepViewAcrossResize(): void;
+    goHome(): void;
+    /** Zoom by one button step about the centre (`factor` > 1 zooms in). */
+    zoomBy(direction: 1 | -1): void;
+    /** Fit the OSD viewport to an image-space rectangle (coords ordered
+     *  [xMin, xMax, yMax, yMin]). */
+    applyZoomToBox(coordinates: number[]): void;
+}

package/lib/implementations/osd/osd-zoom.d.ts

@@ -17,3 +17,9 @@
  * zoom visibly changing pace when a tool is picked up is the bug this constant prevents.
  */
 export declare const OSD_ZOOM_PER_SCROLL = 1.03;
+/**
+ * Zoom factor per zoom-button press / +/- key, shared by every backend (OpenSeadragon, napari-js
+ * and Plotly's axis-range zoom) so a button press zooms the same amount whichever renderer is
+ * drawing. Unlike {@link OSD_ZOOM_PER_SCROLL} it is one deliberate step per press, not per event.
+ */
+export declare const ZOOM_BUTTON_STEP = 1.3;