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

package/lib/implementations/napari-js/napari-helpers.d.ts

@@ -0,0 +1,129 @@
+import type { ChannelView } from 'napari-js';
+import { IImageInfo } from '../../contracts/image.contract';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+/**
+ * Pure helpers and constants of the napari-js backend: no viewer, no store, no network. Shared by
+ * the service and its scenes (review Appendix B, step 1).
+ */
+/**
+ * A short, stable id for a colormap value, for cache keys.
+ *
+ * Half the library's colormaps are NAMES and half are inline `[stop, colour]`
+ * arrays of 256 entries. Stringifying the array kind would put 6 KB in a key that
+ * is rebuilt and compared on every view change; hashing it keeps the key small,
+ * and it only has to distinguish one colormap from another.
+ */
+export declare function colormapId(value: unknown): string;
+export declare const VOLUME_MAX_SLICE = 1024;
+/** Reference in-plane world size (long side) for the volume/axes box, in arbitrary world units.
+ *  The box is anchored to this reference regardless of the chosen decimate factor, so changing the
+ *  resolution changes DETAIL, not the volume's proportions (Z no longer appears to shrink when the
+ *  in-plane sampling grows). Set to the DEFAULT decimate's in-plane cap so the default view is
+ *  unchanged; higher/lower resolutions keep that same shape. */
+export declare const VOLUME_WORLD_INPLANE_REF: number;
+/** Max concurrent slice fetches when assembling a volume — keeps the connection pool busy
+ *  without flooding it (browsers cap ~6/host) on a deep stack. */
+export declare const VOLUME_FETCH_CONCURRENCY = 8;
+/** Volume/isosurface sampling for a decimate factor `scale` (1 = Full 1024, 2 = ½ 512, 4 = ¼ 256
+ *  default, 8 = ⅛ 128): the in-plane cap halves each step; slices stay un-subsampled until ⅛, then
+ *  subsample. */
+export declare function volumeResolutionFor(scale: number): {
+    maxSlice: number;
+    sliceStep: number;
+};
+/** Fully-normalized intensity height as a fraction of the in-plane extent — matches the Plotly
+ *  SURFACE z-aspect (~0.4) so the relief isn't exaggerated. */
+export declare const SURFACE_Z_ASPECT = 0.4;
+/** "Full" mesh grid cap; the decimate factor divides it (default ¼ → 220, ½ → 440, Full → 880). */
+export declare const SURFACE_MAX_GRID = 880;
+/** Coefficient scaling the pyramid tile budget with the target resolution — a higher target pulls a
+ *  finer pyramid level (more real detail). Shared by the surface plane fetch + volume assembly. */
+export declare const STITCH_BUDGET_COEFF = 16;
+/** Surface mesh target grid for a decimate factor `scale`: the grid cap shrinks by `scale` (every
+ *  slice is kept — the z-slider needs them all). The source is fetched at a matching resolution. */
+export declare function surfaceResolutionFor(scale: number): {
+    maxGrid: number;
+};
+/** 3D scatter: in-plane cap for the assembled voxel grid, and the max number of points emitted
+ *  (the grid is flat-strided down to this) — keeps the billboard count interactive. */
+export declare const SCATTER3D_MAX_XY = 64;
+export declare const SCATTER3D_MAX_POINTS = 150000;
+/** How long a pan/zoom must settle before the viewport (and, for pixel tools, the canvas
+ *  readback) is refreshed — coalesces the camera's per-frame changes. */
+export declare const READBACK_DEBOUNCE_MS = 250;
+export declare const TILE_SIZE = 512;
+/** Max tiles stitched for one displayed slice (512px tiles → up to ~6144² at full res). Beyond
+ *  this we step to a coarser pyramid level so a large image stays tractable. */
+export declare const MAX_STITCH_TILES = 144;
+/** WebGPU default `maxTextureDimension2D` — a stitched slice's longest side must fit a texture. */
+export declare const MAX_TEXTURE_DIM = 8192;
+/** Concurrent tile requests per stitched slice. Firing a whole grid at once (hundreds of requests
+ *  for a large level) overwhelmed the tile server (504s); a small pool keeps the pipe full without
+ *  flooding it — and slice-level workers already run several stitches in parallel on top of this. */
+export declare const TILE_FETCH_CONCURRENCY = 6;
+/** Split RGB tiles kept for a band that asks after the other two (see
+ *  `NapariTileClient.rgbBandSources`): ~3 × 256 KB per 512px tile. */
+export declare const RGB_BAND_CACHE_TILES = 16;
+/** How long to poll `/tiles/info` (202 while the server caches the source) before falling back to
+ *  a single tile. Generous like the OSD backend — a cold whole-slide can take minutes to cache. */
+export declare const DESCRIPTOR_TIMEOUT_MS = 120000;
+/** Wait between two `/tiles/info` polls while the server answers 202. */
+export declare const DESCRIPTOR_POLL_INTERVAL_MS = 1200;
+/** A decoded single-channel uint8 plane. */
+export interface LumaPlane {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}
+/**
+ * `IChannelState.gamma` → the `gamma` a napari-js layer or view takes.
+ *
+ * The shared channel state follows the ImageJ/Fiji convention the OSD backend draws
+ * (`osd/display-pipeline.ts`: output = t^(1/γ), so γ > 1 BRIGHTENS the midtones), while
+ * napari-js's shaders apply `pow(t, gamma)` (napari's convention: γ > 1 darkens). Every gamma
+ * handed to napari-js goes through here, so one slider in the Channels & Histogram dialog moves
+ * both backends the same way. Both backends apply window → invert → gamma, per channel before
+ * an additive merge (NAPARI-BOUNDARY-2; pinned by `osd/display-pipeline.cross-backend.spec.ts`).
+ */
+export declare function toNapariGamma(gamma: number | undefined): number;
+/** A 2D canvas (an `OffscreenCanvas` where available) and its context; throws, naming `what`,
+ *  when no 2D context can be had. */
+export declare function create2dCanvas(width: number, height: number, what: string): {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+};
+/**
+ * Run `fn` over `items` with at most `concurrency` in flight — keeps the connection pool busy
+ * without flooding the server — starting no further item once `stop()` says so.
+ */
+export declare function mapPool<T>(items: readonly T[], concurrency: number, fn: (item: T) => Promise<void>, stop?: () => boolean): Promise<void>;
+/** A serverless multichannel stack (`tiled:false` + `channelUrls`): no tile descriptor, so its
+ *  channel count comes from `imageMeta`, and each band is fetched from its own plane URLs. */
+export declare function isServerlessMultichannel(simple: boolean, info: IImageInfo | undefined): boolean;
+/** The stack's declared slice count (`imageMeta.z`, else one URL per slice); 0 when unknown. */
+export declare function stackDepth(info: IImageInfo | undefined): number;
+/** The R, G and B bands of RGBA8 pixels as three uint8 planes (alpha dropped). */
+export declare function splitRgbBands(px: {
+    data: ArrayLike<number>;
+    width: number;
+    height: number;
+}): LumaPlane[];
+/** A decoded single-channel uint8 plane as a napari-js typed image source. */
+export declare function typedPlane(d: LumaPlane): ChannelView['source'];
+/** Default tint for a channel index, cycling the Fiji palette. */
+export declare function tintFor(channel: number): string;
+/** Convert a napari-js `Histogram` (bin count + min/max) to the pane's `IHistogram` (bin edges). */
+export declare function toIHistogram(h: {
+    counts: Uint32Array;
+    bins: number;
+    min: number;
+    max: number;
+}): IHistogram;
+/**
+ * Additively composite grayscale channel images, each tinted with its display colour —
+ * the navigator's picture of a multichannel image.
+ */
+export declare function tintedComposite(images: Array<CanvasImageSource & {
+    width: number;
+    height: number;
+}>, colors: string[]): HTMLCanvasElement;

package/lib/implementations/napari-js/napari-image-2d-scene.d.ts

@@ -0,0 +1,162 @@
+import type { TiledSource } from 'napari-js';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { TileDescriptor } from '../tile-server';
+import type { NapariScene, SceneContext } from './napari-scene';
+/** What the scenes built over the 2D image add to it. */
+export interface Image2dOptions {
+    /** Draw the loaded image (false: an image-less spatial dataset, the observations alone). */
+    image?: boolean;
+    /** Whether to fit the camera to the image once it is drawn (default: when there is one). */
+    fit?: () => boolean;
+    /** After a slice change. `rerendered` when the stitched path re-rendered the image — which
+     *  CLEARS the layer list, taking every other layer with it. */
+    onSlice?: (rerendered: boolean) => void;
+    /** The pointer entered the navigator (e.g. to hide a hover tooltip over the canvas). */
+    onNavigatorInteract?: () => void;
+}
+/**
+ * The 2D image (review Appendix B, cluster E): pyramidal `TiledSource`s against the `/tile`
+ * endpoint when `/tiles/info` describes the image, else a single stitched level (`tiled:false`
+ * stacks fetch each slice's own URL, a serverless multichannel stack each channel's own plane);
+ * multichannel additive tints, grayscale colormap or RGB (recoloured per band, see
+ * {@link syncRgbBands}); the coarse histogram samples of the tiled path, the scale bar, the
+ * overview navigator and the 2D interaction stack (region overlay + pixel tools). The
+ * region-centroid scatter and the spatial 2D scene are built over it.
+ */
+export declare class Image2dScene implements NapariScene {
+    private readonly ctx;
+    private readonly opts;
+    /** How the image is composited (drives the histogram and the display-state updates). */
+    imageMode: 'grayscale' | 'multichannel' | 'rgb';
+    /** True when the image is rendered via pyramidal TiledSources (descriptor available). */
+    tiled: boolean;
+    /** napari-js high-level view owning the per-channel layer set for {@link imageMode}. */
+    private channelView;
+    /** Latest wins for a stitched slice: a slow older slice can't clobber a newer one. */
+    private sliceReq;
+    /** RGB: the R, G and B bands as layer sources (typed planes, or band `TiledSource`s that share
+     *  one request per tile) and the stitched level's scale — what {@link syncRgbBands} draws. */
+    private rgbBands;
+    /** RGB: the three additive band layers while the channel states recolour the image; null while
+     *  the RGB layer draws it as it is. */
+    private bandLayers;
+    /** Coarse per-channel luminance sample (keyed by channel index) for the histogram in tiled mode,
+     *  where the layers have no full in-memory pixels — and an RGB image's raw bands in either mode.
+     *  Refreshed on mount + slice change. */
+    readonly histSamples: Map<number, Uint8Array>;
+    /** Latest-wins token for {@link refreshHistogramSamples}. */
+    private histGen;
+    /** Physical scale bar overlay (null when the image has no µm/pixel). */
+    private scaleBar;
+    /** Overview minimap (bottom-right), as OSD's navigator. */
+    private navigator;
+    /** Bumped per thumbnail request, so a slow one cannot overwrite a newer slice's. */
+    private navigatorToken;
+    /** The current slice's per-channel thumbnail bitmaps (multichannel only), kept so a tint or
+     *  visibility change recolours the thumbnail without re-fetching it. */
+    private navigatorChannels;
+    /** The tints/visibility the thumbnail was last composited with — see {@link recolorNavigator}. */
+    private navigatorTintKey;
+    private displaySub;
+    constructor(ctx: SceneContext, opts?: Image2dOptions);
+    private get hasImage();
+    mount(): Promise<void>;
+    setZ(z: number): void;
+    histogram(channel: number, bins: number): IHistogram | null;
+    setImageSmoothing(enabled: boolean): void;
+    setNavigatorVisible(visible: boolean): void;
+    /** Show the navigator only for a dataset that brings pixels of its own (and when the user
+     *  wants it): with no image of its own there is nothing for an overview to show. */
+    showNavigatorFor(datasetHasPixels: boolean): void;
+    dispose(): void;
+    /**
+     * Render slice `z`. With a server pyramid descriptor each layer is a pyramidal
+     * {@link TiledSource}, so the view refines to higher resolution on zoom (like OSD) and sits
+     * naturally in full-resolution coordinates; without one, the single-level stitch. Three display
+     * modes either way: multichannel additive tint, grayscale colormap, RGB.
+     */
+    render(z: number, token?: number): Promise<void>;
+    /** Single-level stitch fallback (no descriptor): the pre-tiling path. */
+    private renderStitched;
+    /**
+     * Render with pyramidal {@link TiledSource}s — the view refines to higher resolution as you
+     * zoom in (the visual fetches the level whose texels ≈ screen pixels) and sits in full-res
+     * coordinates so regions align. Same three modes as the stitch path. Per-channel layers use the
+     * REAL pyramid levels (per-channel tiles only exist there); the composite uses all levels.
+     */
+    private renderTiled;
+    /** A pyramidal TiledSource whose tiles count on the loading badge while `scene` (the render that
+     *  asked for it, taken before its awaits) is current. */
+    tiledSource(desc: TileDescriptor, channel: number | undefined, channels: 1 | 4, scene: AbortSignal): TiledSource;
+    /** Channel `c`'s layer in the additive multichannel composite: tinted by its display colour
+     *  (store, else descriptor, else the Fiji palette), with its window, gamma and visibility. */
+    private tintedChannelView;
+    /** The single grayscale layer: the selected colormap, with the channel's window and gamma. */
+    private grayscaleChannelView;
+    /** (Re)fetch a coarse per-channel luminance sample for the histogram (tiled mode has no full
+     *  in-memory pixels). One cheap overview tile per channel, fetched together; cached by channel
+     *  index. Latest wins: a scrub fires one refresh per slice, and an older slice's samples that
+     *  land after a newer one's are dropped rather than shown as the current distribution. */
+    refreshHistogramSamples(z: number, desc: Pick<TileDescriptor, 'channels'>): Promise<void>;
+    /** Channel states + grayscale colormap → live-apply to the rendered layers (no re-fetch; only z
+     *  changes re-fetch), and recolour the navigator thumbnail. */
+    private followDisplayState;
+    /** Apply the current channel states / colormap to the live layers (no re-fetch), delegating the
+     *  per-channel layer mutations to the {@link MultiChannelImageView}. */
+    private applyDisplayState;
+    /**
+     * RGB: draw the image as it is while its channel states leave it so (default R/G/B tints, full
+     * window, γ 1, all shown, no invert: {@link rgbNeedsRecolor}) — the RGB layer, unchanged, with
+     * the coarse underlay a tiled one keeps while it pans. Otherwise draw its R, G and B bands as
+     * three additive layers, each with its channel's window, invert, gamma, tint and visibility —
+     * what OSD's RGB recolour computes per pixel (the merge order of `osd/display-pipeline`). The
+     * band layers sit just above the hidden RGB layer, so whatever is drawn over the image stays
+     * over it. A host with no R/G/B channel model (fewer than three states) gets only the invert.
+     */
+    private syncRgbBands;
+    /** (Re)install the physical scale bar (napari-js's `ScaleBarOverlay` on the 2D camera's zoom),
+     *  sized from the image's µm/pixel (`/tiles/info` mppX, falling back to the image metadata).
+     *  No-op without a physical size. */
+    installScaleBar(): void;
+    /**
+     * The overview navigator (napari-js's `NavigatorOverlay`): a coarse thumbnail of the whole
+     * image with the viewport on it; click or drag to pan at the current zoom (as OSD).
+     */
+    private installNavigator;
+    /**
+     * Draw the navigator's thumbnail from the coarsest pyramid level. A multichannel image
+     * is composited from its channels in their display colours (see {@link recolorNavigator}),
+     * so the overview looks like the view rather than like channel 0 in grey.
+     */
+    private refreshNavigatorImage;
+    /** Replace the per-channel thumbnail bitmaps (closing the previous ones). */
+    private setNavigatorChannels;
+    /**
+     * Composite the multichannel thumbnail in the channels' CURRENT display tints, skipping hidden
+     * channels — the store's channel states, as the 2D layers use, not the server's defaults.
+     * Re-run on every display-state change; it only redraws (never re-fetches), and only when a
+     * tint or a visibility actually changed, so a window/gamma drag costs a string compare.
+     */
+    private recolorNavigator;
+}
+/**
+ * NAPARI_SCATTER (review Appendix B, cluster H): the slice image with a points layer at each
+ * region's centroid (the napari-js analog of Plotly's region-centroid scatter), rebuilt live as
+ * regions change. This mode plots REGION centroids, so the image's region tools come with it —
+ * drawing a region adds a point at once.
+ */
+export declare class ScatterRegionsScene implements NapariScene {
+    private readonly ctx;
+    readonly image: Image2dScene;
+    private points;
+    private regionSub;
+    constructor(ctx: SceneContext);
+    mount(): Promise<void>;
+    setZ(z: number): void;
+    histogram(channel: number, bins: number): IHistogram | null;
+    setImageSmoothing(enabled: boolean): void;
+    setNavigatorVisible(visible: boolean): void;
+    dispose(): void;
+    /** (Re)build the point layer at the current region centroids. */
+    private rebuildPoints;
+}

package/lib/implementations/napari-js/napari-loading-badge.d.ts

@@ -1,19 +1,20 @@
 /**
  * "Transcripts reloading…" at the bottom of the canvas while a layer's data is in flight: one
  * line naming every layer still loading, on a semi-opaque backing so it reads over any tissue.
+ * Longer work names itself ("Building HPF in 3D…") and joins the line.
  *
  * Shown only once something has been loading for {@link SHOW_AFTER_MS}, so a redraw served from
  * cache does not flash it.
  */
 export declare const SHOW_AFTER_MS = 150;
 export declare class NapariLoadingBadge {
-    private readonly host;
     private readonly el;
     private names;
+    private tasks;
     private timer;
     constructor(host: HTMLElement);
-    /** The layers loading now; empty hides the badge. */
-    set(names: readonly string[]): void;
+    /** The layers loading now, and the tasks running (their messages); both empty hides the badge. */
+    set(names: readonly string[], tasks?: readonly string[]): void;
     /** The text currently set (shown or about to be). */
     get text(): string;
     destroy(): void;

package/lib/implementations/napari-js/napari-loading-state.d.ts

@@ -0,0 +1,37 @@
+/** What the service itself counts on the badge; the spatial tile layers report their own names. */
+export type LoadingSource = 'Image' | 'Observations';
+/**
+ * "x reloading…" at the bottom of the canvas, aggregated over everything that loads into one
+ * scene: image tiles (the tile client), observation colourings (the spatial scenes) and the
+ * spatial tile layers' own loads (which report a list of layer names).
+ *
+ * Each load is a {@link begin} that hands back its own `end`. {@link reset} starts a new scene:
+ * the counts are dropped, and an `end` from a load that began before it is a no-op, so a load
+ * that settles after a re-plot can neither un-count the new scene's work nor drive a count below
+ * zero (which hid the next scene's "Observations reloading…" until a second load overlapped it).
+ *
+ * A {@link beginTask} is work that outlives a scene (a region's 3D reconstruction, built for
+ * whichever volume is on screen when it is done): its message stays across a reset.
+ */
+export declare class LoadingBadgeState {
+    private host;
+    private badge;
+    private readonly counts;
+    private tileLayers;
+    private generation;
+    private readonly tasks;
+    /** The element the badge is drawn into (the plot host); set per plot. */
+    attach(host: HTMLElement): void;
+    /** One load of `source` started; call the returned function once it settles. */
+    begin(source: LoadingSource): () => void;
+    /** A task started, shown by its `message` ("Building HPF in 3D…"); call the returned function
+     *  once it settles. */
+    beginTask(message: string): () => void;
+    /** The spatial tile layers still loading (their own names, in their order). */
+    setTileLayers(layers: readonly string[]): void;
+    /** The text the badge has set (shown, or about to be once the show delay passes). */
+    get text(): string;
+    /** A new scene: forget every count and remove the badge (tasks show again on the next attach). */
+    reset(): void;
+    private show;
+}

package/lib/implementations/napari-js/napari-region-mesh-pointer.d.ts

@@ -0,0 +1,32 @@
+import type { RegionMesh3D } from './napari-volume-region-meshes';
+export interface RegionMeshPointerOptions {
+    /** The surface under canvas point (`x`, `y`) (CSS px), or null. */
+    pickAt(x: number, y: number): RegionMesh3D | null;
+    /** Whether a click picks (the selection tool armed, surfaces shown); otherwise clicks are left alone. */
+    active(): boolean;
+    /** Whether hovering names the surface under the pointer (surfaces shown, whatever the tool). */
+    hoverable(): boolean;
+    /** A click on a surface (its key), or on none (null); `additive` with Shift / Ctrl / ⌘. */
+    onPick(key: string | null, additive: boolean): void;
+}
+/**
+ * Clicks and hover on the region surfaces of a volume view: a click (a press that does not orbit)
+ * picks the surface under it, or none; resting over a surface shows its name in a tooltip (and a
+ * pointer cursor when a click would pick it). Listens on the canvas without stopping events, so the
+ * camera still orbits.
+ */
+export declare class RegionMeshPointer {
+    private readonly canvas;
+    private readonly opts;
+    private readonly tip;
+    private down;
+    private hoverTimer;
+    constructor(canvas: HTMLElement, host: HTMLElement, opts: RegionMeshPointerOptions);
+    destroy(): void;
+    private local;
+    private readonly onDown;
+    private readonly onUp;
+    private readonly onMove;
+    private readonly onLeave;
+    private hide;
+}

package/lib/implementations/napari-js/napari-region-overlay.d.ts

@@ -1,16 +1,29 @@
 import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
 import { RegionStore } from '../../store/region-store.service';
+import type { Affine } from '../../region-overlay/svg-region-renderer';
 /**
  * The slice of the napari Viewer the overlay needs (coord transforms + control gating).
  *
+ * COORDINATE SPACES: `canvasToWorld` takes CLIENT pixels (viewport coordinates, as a pointer
+ * event's `clientX/Y`), exactly as napari-js `Viewer.canvasToWorld` does. `canvasTransform` is
+ * the camera's world → CANVAS-LOCAL CSS-pixel affine, napari-js `Viewer.canvasTransform`, which
+ * reads no layout: drawing and following the camera use it, so a camera frame costs one
+ * `matrix(...)` and no `getBoundingClientRect()` (review NAPARI-BOUNDARY-10). The svg covers the
+ * plot host and the canvas is the host's in-flow child at its top-left, so canvas-local and
+ * svg-local pixels are the same; a pointer's client pixels are mapped into the svg by the
+ * overlay itself.
+ *
  * Exported because the 3D spatial mode supplies a SCREEN-SPACE implementation of it: there the
  * drawn shape is a lasso in canvas pixels, not a rectangle in image space, so "world" is the
- * canvas itself and both transforms collapse to identity. That lets the 3D view reuse this whole
- * overlay — every tool, the handles, the store round-trip — with no 3D-specific drawing code.
+ * canvas itself — `canvasToWorld` is the client → canvas offset and `canvasTransform` the
+ * identity. That lets the 3D view reuse this whole overlay — every tool, the handles, the store
+ * round-trip — with no 3D-specific drawing code.
  */
 export interface OverlayViewer {
+    /** Client px → world. */
     canvasToWorld(clientX: number, clientY: number): [number, number];
-    worldToCanvas(worldX: number, worldY: number): [number, number];
+    /** World → canvas-local (= svg-local) CSS px, as an SVG affine `[a, b, c, d, e, f]`. */
+    canvasTransform(): Affine;
     setControlsEnabled(enabled: boolean): void;
     readonly camera: {
         readonly changed: {
@@ -20,22 +33,34 @@ export interface OverlayViewer {
 }
 /**
  * SVG region overlay for the napari-js WebGPU image view (jit-ui#102), mirroring the OSD backend's
- * {@link OsdRegionOverlay} but driven by napari's `canvasToWorld`/`worldToCanvas` transforms.
+ * {@link OsdRegionOverlay} but driven by napari's `canvasToWorld`/`canvasTransform` transforms
+ * (see {@link OverlayViewer} for their coordinate spaces).
  * Vector shapes are drawn in an absolutely-positioned `<svg>` over the canvas (no need to push
- * them through WebGPU). It writes completed shapes to the shared {@link RegionStore} (so save /
- * undo / export work identically to OSD) and re-renders from the store on every camera move,
- * region change, and selection change.
+ * them through WebGPU) by {@link NapariRegionSvgRenderer} over the shared `SvgRegionRenderer`:
+ * in world coordinates inside one transformed group, rebuilt on a region or selection change,
+ * while a camera move only rewrites the transform (napari-js's `canvasTransform`, the camera
+ * centre/zoom) and the few screen-space handles and labels. This class is
+ * the gesture controller: pointer handlers, the tool mode, and the edit/draft/marquee state.
+ * It writes completed shapes to the shared {@link RegionStore} (so save / undo / export work
+ * identically to OSD).
  *
  * Supports (jit-ui#102): rectangle / polygon / freehand path drawing, click-select and rubber-band
  * marquee select, pan/zoom gating via `setControlsEnabled`, body move, vertex move/add/delete,
- * bezier handle editing, and donut holes (including hole vertex + hole-bezier-handle editing) —
- * full parity with {@link OsdRegionOverlay}.
+ * bezier handle editing, and donut holes (including hole vertex + hole-bezier-handle editing).
+ * Hit-testing shares `region-overlay/region-geometry` with the OSD overlay, so both follow
+ * the same rules (multi-part regions, holes, open polylines, handle-less bezier curves).
  */
 export declare class NapariRegionOverlay implements IRegionOverlay {
     private readonly host;
     private readonly viewer;
     private readonly store;
     private readonly svg;
+    private readonly renderer;
+    /** The image's region source, drawn under the regions at the zoom's level of detail; null
+     *  where world is not the image (the 3D view's screen-space lassos). */
+    private readonly sourceLayer;
+    /** Client ↔ svg-local ↔ world conversions, with the svg origin read once per gesture/redraw. */
+    private readonly projection;
     private readonly subs;
     private readonly disconnectCamera;
     private mode;
@@ -44,15 +69,15 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     private draftRect;
     /** In-progress rubber-band selection marquee (select mode), image-space. */
     private marquee;
-    /** Dedicated marquee rect element, updated directly during the drag (no full region redraw). */
-    private marqueeEl;
     private draftPath;
     private drawing;
     private regionsVisible;
     /** In-progress manipulation (select/move modes): dragging a body, a polygon vertex, or a
      *  rectangle corner. `anchor` is the fixed opposite corner for a rectangle resize. */
     private edit;
-    constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore);
+    constructor(host: HTMLElement, viewer: OverlayViewer, store: RegionStore, opts?: {
+        regionSource?: boolean;
+    });
     /**
      * Whether a region tool currently owns the pointer.
      *
@@ -65,88 +90,60 @@ export declare class NapariRegionOverlay implements IRegionOverlay {
     setMode(mode: RegionToolMode): void;
     setSelectedBezier(bezier: boolean): void;
     /**
-     * How finely a drawn vertex may be placed, in world units.
-     *
-     * One by default, because for an image the world IS pixels and a region should align to
-     * them. A dataset whose coordinates are not pixels sets it finer — seqFISH's whole
-     * sample spans about 5 x 7 units, where whole-unit vertices leave roughly six by eight
-     * placeable positions and no ROI can be drawn at all.
+     * How finely a drawn vertex may be placed, in world units: one (an image's pixels) by
+     * default, finer for a dataset whose coordinates are not pixels (see OverlayProjection).
      */
-    private worldQuantum;
     setWorldQuantum(quantum: number): void;
     destroy(): void;
-    /** Pointer client coords → world coords, snapped to {@link worldQuantum}. */
-    private toImage;
-    /**
-     * World units spanned by one screen pixel, measured through the viewer's own transform.
-     *
-     * Read from the transform rather than from the camera, so it holds for both the 2D and
-     * the 3D screen-space adapters without either having to expose a zoom. Falls back to 1
-     * if the transform gives nothing usable, which keeps the established pixel behaviour
-     * rather than collapsing the threshold to zero and recording a point per event.
-     */
-    private worldPerCanvasPixel;
-    /** Image coords → SVG-local px (the svg overlays the canvas at the same client rect). */
-    private toLocal;
     private readonly onPointerDown;
+    private pointerDown;
     private readonly onPointerMove;
     private readonly onPointerUp;
+    /**
+     * The pointer gesture ended without a pointerup (the browser cancelled it, or capture was
+     * lost): end it without committing. Also fires after every normal release, when nothing
+     * is live any more.
+     */
+    private readonly onPointerCancel;
+    /**
+     * End whatever pointer gesture is live without committing it: close the store batch a drag
+     * opened (so later edits are emitted again) and forget the drag (so a bare hover no longer
+     * moves the region), and drop the marquee and a rectangle/freehand draft. A click-placed
+     * polygon is not a pointer gesture and survives.
+     */
+    private endGesture;
     /** Click-to-place polygon: add a vertex, or close when clicking near the first one. */
     private handlePolygonClick;
     private readonly onDblClick;
     /** The currently-selected region (single selection), or null. */
     private selectedRegion;
-    /** Screen distance (px) between a client point and an image coord. */
-    private screenDist;
     /**
      * Start a select/move interaction: grab a handle (rectangle corner) or vertex of the already-
      * selected region first; otherwise select the topmost region under the cursor and drag its body.
      */
     private beginManipulation;
-    /** Create/update the marquee rect element directly (avoids a full region redraw per move). */
+    /** Show the marquee where it is now (only the marquee element: no full region redraw). */
     private updateMarqueeEl;
-    /** Remove the marquee element from the SVG. */
-    private clearMarqueeEl;
-    /** Test whether a client point grabs a rectangle corner or a polygon vertex of `region`. */
-    private hitHandle;
-    /** Apply the live drag for the active manipulation (image coords `ix,iy`). */
-    private applyManipulation;
-    /** addpoint mode: insert a vertex on the selected polygon's nearest edge at the click. */
+    /** addpoint mode: insert a vertex at the click on the selected polygon's nearest edge
+     *  (exterior or a hole ring). */
     private handleAddPoint;
-    /** deletepoint mode: remove the selected polygon's vertex nearest the click. */
+    /** deletepoint mode: remove the selected polygon's vertex nearest the click (exterior or a
+     *  hole ring). */
     private handleDeletePoint;
-    /** Distance from point (px,py) to segment (ax,ay)-(bx,by), in image units. */
-    private pointSegDist;
-    /** Finalize a rubber-band marquee: select every region whose bounding box it overlaps (a tiny
-     *  marquee is treated as a click on empty space → clear the selection). */
+    /** Finalize a rubber-band marquee: select every region whose bounding box it overlaps (a
+     *  marquee under {@link MIN_MARQUEE_PX} is a click on empty space → clear the selection). */
     private finishMarquee;
-    /** A region's bounding box in image coords (rectangle, polygon, or multipolygon), or null. */
-    private regionBBox;
     private commitRectangle;
     private commitPolygon;
-    private hitTest;
     /** Show or hide the drawn regions. A region being drawn stays visible either way. */
     setRegionsVisible(visible: boolean): void;
+    /** Follow a camera move: one transform attribute plus the screen-space elements. */
+    private updateCamera;
+    /**
+     * Rebuild every element from the store: the regions in world coordinates (one transformed
+     * group), their labels, and the overlay. Reads no layout: the camera affine is the viewer's.
+     */
     redraw(): void;
-    /** Draw a region's classification label at its top-left, when labels are enabled (matches OSD). */
-    private drawLabel;
-    /** Draw grab handles for the selected region: rectangle corners or polygon vertices. */
-    private drawHandles;
-    /** Draw one bezier control point (anchor + handle offset) as a small circle connected to its
-     *  anchor by a tangent line. `handle` is the [dx,dy] offset from the anchor in image space. */
-    private drawBezierHandle;
-    private buildRegionEl;
-    /** Path data for a polygon: the exterior ring (bezier or straight) plus any holes (bezier when
-     *  the donut carries hole handles, else straight) as sub-paths — even-odd fill cuts them out. */
-    private polygonPathData;
-    /** SVG path data for a straight ring/polyline in image coords (closed appends `Z`). */
-    private straightPath;
-    /** SVG cubic-bezier path data for any ring (exterior or hole): anchors joined by cubic segments
-     *  whose control points are `anchor + handleOut` (leaving) and `nextAnchor + handleIn` (arriving),
-     *  in image space. Used for both the exterior and (donut) hole rings. */
-    private ringBezierPath;
-    private style;
-    /** Draw the in-progress rectangle / path preview. */
-    private drawDraft;
-    private styleDraft;
+    /** Rebuild the screen-space overlay only: the selected regions' handles and the draft. */
+    private renderOverlay;
 }