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

package/lib/toolbar/brush/brush-tool.service.d.ts

@@ -1,6 +1,5 @@
-import { WandService } from '../wand/wand.service';
-import { WandToolHost } from '../wand/wand-tool.service';
-import * as i0 from "@angular/core";
+import { UndoGestureTarget } from '../tool-kit/undo-gesture';
+import { CanvasToolHost, ICanvasTool } from '../tool-kit/canvas-tool';
 /** Brush parameters. `size` is the brush *diameter* in matrix (image) pixels. */
 export interface BrushOptions {
     size?: number;
@@ -14,14 +13,9 @@ export interface BrushOptions {
     label?: string;
     color?: string;
 }
-/**
- * The brush host is identical to the wand's — both need the cached-image
- * coordinate frame, the overlay container, the coordinate transform, and
- * read/write access to the shared region list. The brush ignores the wand's
- * pixel values (it paints a geometric disc rather than flood-filling by colour),
- * so reusing {@link WandToolHost} lets each backend bind the same host object.
- */
-export type BrushToolHost = WandToolHost;
+/** @deprecated One host serves every canvas tool: use {@link CanvasToolHost}. The
+ *  brush reads only the readback's coordinate frame, not its pixel values. */
+export type BrushToolHost = CanvasToolHost;
 /**
  * QuPath-style brush tool. Painting a stroke unions a disc of the configured
  * size into the active region as the cursor drags; holding <kbd>Shift</kbd>
@@ -33,37 +27,26 @@ export type BrushToolHost = WandToolHost;
  * No pixel sampling and no cursor indicator: the painted stroke itself shows the
  * brush size. The overlay canvas only captures the pointer.
  *
- * Lifecycle mirrors the wand: a backend binds its host once, then toggles the
- * tool with `setMode(true | false, options)`.
+ * Lifecycle mirrors the wand: a plain class, one instance per backend's
+ * `CanvasToolManager`, armed with `activate(host, options)` / `deactivate()`.
  *
  * Holes / donuts (jit-ui#85): brushing a ring that encloses an unpainted area
- * keeps the enclosed hole — {@link WandService.maskToPolygons} traces interior
+ * keeps the enclosed hole — the contour tracer (`geometry/contour`) traces interior
  * rings into {@link Polygon.holes}, which adopt/merge preserve (the re-rasterize
  * punches the holes back out). The OpenSeadragon overlay renders them with
  * even-odd fill and GeoJSON round-trips them as extra Polygon rings. The Plotly
  * (Heatmap) backend currently renders the filled exterior only.
  */
-export declare class BrushToolService {
-    private wandService;
+export declare class BrushTool implements ICanvasTool<BrushOptions> {
+    readonly id = "brush";
     private host;
-    private overlay;
-    private active;
+    private readonly overlay;
     /**
-     * Accumulated brush region (bbox-relative mask). Persists across mouseup so a
-     * subsequent stroke extends the *same* region until the user switches tool —
-     * matching QuPath, and the wand.
+     * Accumulated brush region (bbox-relative mask), shared logic with the wand.
+     * Persists across mouseup so a subsequent stroke extends the *same* region
+     * until the user switches tool — matching QuPath, and the wand.
      */
-    private stroke;
-    /** Id of the region this stroke is editing (null = a fresh region). For an
-     *  erase that splits the region, this tracks the largest resulting piece. */
-    private strokeRegionId;
-    /** Readback ratio/origin signature the active stroke is tied to; a change (zoom/pan) invalidates
-     *  it so it isn't re-committed at a different scale (jit-ui#102). */
-    private strokeRatioSig;
-    /** Ids of the extra regions produced when an erase stroke splits a region
-     *  into disconnected pieces — reused across drag ticks so the split pieces
-     *  keep stable identities instead of being recreated each tick. */
-    private strokeExtraIds;
+    private readonly editor;
     /** Previous cursor position (matrix coords) within the current drag, so fast
      *  drags paint a continuous stroke rather than disconnected dabs. */
     private lastMatrix;
@@ -71,14 +54,17 @@ export declare class BrushToolService {
     private size;
     /** The class being painted ({@link BrushOptions.label} / `color`); null = plain brush. */
     private paintClass;
-    private readonly boundMouseDown;
-    private readonly boundMouseMove;
-    private readonly boundMouseUp;
-    constructor(wandService: WandService);
-    /** Wire the tool to its host. Must be called once before `setMode(true)`. */
-    bindHost(host: BrushToolHost): void;
-    /** Toggle the brush on/off. */
-    setMode(active: boolean, options?: BrushOptions): void;
+    /** Makes each drag one undo step, however long the user pauses (RT-12). */
+    private readonly gesture;
+    /** @param gestureTarget the region store, so each drag is one undo step. */
+    constructor(gestureTarget?: UndoGestureTarget | null);
+    /** Arm the brush on `host`. Arming sets the class in full: no label/color
+     *  means the plain brush; a missing size keeps the previous one. */
+    activate(host: CanvasToolHost, options?: BrushOptions): void;
+    /** Disarm: remove the overlay, drop the active region and the class. */
+    deactivate(): void;
+    /** Drop the active brush region so the next stroke starts a new one. */
+    reset(): void;
     /**
      * Update size and/or class while armed. The class changes only when `label`
      * or `color` is passed (as a key, even `undefined`), so a size-only update
@@ -88,13 +74,10 @@ export declare class BrushToolService {
     setOptions(options?: BrushOptions): void;
     /** Live-update the brush size (matrix-pixel diameter). */
     setSize(size: number): void;
-    /** Drop the active brush region so the next stroke starts a new one. */
-    clearActiveRegion(): void;
     private createOverlay;
-    private destroyOverlay;
-    private onMouseDown;
-    private onMouseMove;
-    private onMouseUp;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
     private resetStroke;
     /**
      * Paint (or erase) a disc — or a swept line of discs since the previous
@@ -104,61 +87,11 @@ export declare class BrushToolService {
     private applyAtClient;
     /**
      * OR (add) or AND-NOT (erase) a filled disc of `radius` matrix-pixels centred
-     * at (cx, cy) into the accumulator, growing its bbox to fit when adding.
+     * at (cx, cy) into the accumulator, growing its bbox (clipped to the
+     * readback) to fit when adding.
      */
     private stampDisc;
-    /**
-     * Ensure the accumulator's bbox covers [px0,py0,px1,py1) (clamped to the
-     * image), allocating/copying a larger mask when it must grow. Returns false if
-     * the requested box is empty after clamping.
-     */
-    private ensureStrokeCovers;
-    /** True if (matrixX, matrixY) lies inside the current stroke accumulator. */
-    private pointInStroke;
-    /**
-     * Remove the region(s) referenced by the stroke and reset it — used when an
-     * erase stroke deletes every pixel.
-     */
-    private dropActiveShape;
     /** Whether the stroke may adopt or merge `region`: always for the plain brush,
      *  otherwise only a region of the class being painted. */
     private paintsInto;
-    /** A region's closed-polygon vertices (image/data coords), or null when it
-     *  isn't a fillable closed polygon (rectangles, open polylines). */
-    private regionVerts;
-    /** Whether a region can be faithfully rasterized at this zoom (rx/ry = data units per matrix px).
-     *  Editing rasterizes + re-traces the region, so one whose matrix-space bbox exceeds the
-     *  rasterizer cap would come back rescaled/corrupted (e.g. a whole-slide annotation while zoomed
-     *  out) — skip adopt/merge for those and only edit them near native zoom (jit-ui#102). */
-    private fitsForEdit;
-    /** Convert a region's hole rings from image/data coords into matrix coords so
-     *  they line up with the stroke accumulator (jit-ui#85). */
-    private holesToMatrix;
-    /**
-     * If (matrixX, matrixY) falls inside an existing region, rasterize it into the
-     * stroke accumulator so subsequent brush input extends it rather than starting
-     * a new region.
-     */
-    private tryAdoptShapeAt;
-    /**
-     * Fold every region whose rasterized mask overlaps the stroke mask into the
-     * stroke and remove it from the list, so brushing across regions merges them.
-     */
-    private mergeOverlappingShapes;
-    /**
-     * Commit the stroke's connected pieces as regions — the largest keeps the
-     * stroke's region identity, additional pieces (from an erase that split the
-     * region) become their own regions tracked in `strokeExtraIds` so they keep
-     * stable identities across drag ticks. The store mints ids on commit, which
-     * we read back so subsequent ticks replace the same regions.
-     */
-    private commitComponents;
-    /**
-     * Build a Region for one component and insert it into `regions`: replace the
-     * region with `id` in place if it exists, otherwise append a new one. Returns
-     * the Region instance (its id is minted later by the store when new).
-     */
-    private upsertComponent;
-    static ɵfac: i0.ɵɵFactoryDeclaration<BrushToolService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<BrushToolService>;
 }

package/lib/toolbar/canvas-tools.d.ts

@@ -0,0 +1,20 @@
+import { WandService } from './wand/wand.service';
+import { SamPointToolService } from './segmentation/sam-point-tool.service';
+import { CanvasToolHost } from './tool-kit/canvas-tool';
+import { CanvasToolManager } from './tool-kit/canvas-tool-manager';
+import { UndoGestureTarget } from './tool-kit/undo-gesture';
+/** What a backend supplies to build its canvas tools — all from its own injector. */
+export interface CanvasToolDeps {
+    /** The (stateless) wand patch sampler. */
+    wandService: WandService;
+    /** The chain's region store: makes each wand/brush/eraser drag one undo step. */
+    regionStore: UndoGestureTarget | null;
+    /** The chain's SAM point feeds; the point tool reports through them. */
+    samPoint: SamPointToolService;
+}
+/**
+ * A backend's canvas-tool manager: fresh wand, brush, vertex eraser,
+ * zoom-to-box and SAM point tools over `host`. Each backend calls this once, so
+ * no tool instance — and no tool state — is shared between backends (RT-21).
+ */
+export declare function createCanvasToolManager(host: CanvasToolHost, deps: CanvasToolDeps): CanvasToolManager;

package/lib/toolbar/crop/slide-crop.d.ts

@@ -1,4 +1,4 @@
-import { CachedImageData } from '../wand/wand-tool.service';
+import type { CachedImageData } from '../wand/wand-tool.service';
 /** A client-side crop of the loaded image — the browser equivalent of the JIT
  *  server slide-crop, taken from the pixels already in the viewer. */
 export interface CroppedImage {
@@ -19,12 +19,18 @@ export interface DataBox {
 }
 /**
  * Browser "slide crop": extract the box region (data coords) from a cached image
- * frame as an RGBA image, clamped to the image bounds. Grayscale frames are
- * replicated across R/G/B; RGB tuples are copied through. Returns null when the
- * box is empty/outside the image.
+ * frame as an RGBA image, clamped to the image bounds. Returns null when the box
+ * is empty/outside the image.
  *
  * The output feeds an automatic segmenter (e.g. cellpose-SAM): run it on the
  * crop, then offset the resulting masks by (matrixX0, matrixY0) to place them
  * back on the full frame.
  */
 export declare function cropImageRegion(cached: CachedImageData, frameIndex: number, box: DataBox): CroppedImage | null;
+/**
+ * RGBA pixels of the `w`×`h` matrix window at (x0, y0) of a cached frame,
+ * nested or packed (see `tool-kit/frame-pixels`). Grayscale frames are
+ * replicated across R/G/B; RGB tuples are copied through. Missing pixels become
+ * opaque black.
+ */
+export declare function frameRegionToRgba(cached: CachedImageData, frameIndex: number, x0: number, y0: number, w: number, h: number): Uint8ClampedArray;

package/lib/toolbar/plot-type-selector/plot-type-selector.component.d.ts

@@ -0,0 +1,38 @@
+import { EventEmitter } from '@angular/core';
+import { PlotTypeId } from '../../contracts/plot-type';
+import { PlotTypeOption } from '../../contracts/plot-type-contribution.contract';
+import * as i0 from "@angular/core";
+/**
+ * The toolbar's plot-type group: the plot-type dropdown, the isosurface band
+ * slider for the isosurface modes, and the add-intensity-line button for the
+ * views that draw profile lines. Presentational: the host owns the values.
+ */
+export declare class PlotTypeSelectorComponent {
+    /** Plot types the active backend advertises, then any contributed modes. */
+    options: PlotTypeOption[];
+    /** The selected built-in type or contributed mode id. */
+    selected: PlotTypeId;
+    /** An isosurface mode: show the iso band slider. */
+    isosurface: boolean;
+    /** Isosurface band as a 0–255 slider position. */
+    isoRange: number[];
+    /** The view draws intensity profile lines: show the add-line button. */
+    intensityLines: boolean;
+    /** A plot type or contributed mode was picked from the dropdown. */
+    selectPlotType: EventEmitter<string>;
+    /** The iso band slider moved: the new `[low, high]` pair (or nothing). */
+    isoRangeChange: EventEmitter<number[] | undefined>;
+    /** Add another coloured intensity line ROI + inset trace. */
+    addProfileLine: EventEmitter<void>;
+    /** Iso slider bounds — UI constants (the band is host-owned). */
+    protected readonly isoValueMin = 0;
+    protected readonly isoValueMax = 255;
+    protected readonly isoValueStep = 1;
+    /** A plot-type icon is a PrimeNG font glyph (e.g. `pi pi-image`) rather than an
+     *  SVG asset path — drives which element the item template renders. */
+    protected isPiIcon(icon: string | undefined): boolean;
+    /** The iso band slider reports its `[low, high]` pair (or nothing). */
+    protected onIsoRange(value: number | number[] | undefined): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PlotTypeSelectorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PlotTypeSelectorComponent, "toolbar-plot-type-selector", never, { "options": { "alias": "options"; "required": false; }; "selected": { "alias": "selected"; "required": false; }; "isosurface": { "alias": "isosurface"; "required": false; }; "isoRange": { "alias": "isoRange"; "required": false; }; "intensityLines": { "alias": "intensityLines"; "required": false; }; }, { "selectPlotType": "selectPlotType"; "isoRangeChange": "isoRangeChange"; "addProfileLine": "addProfileLine"; }, never, never, true, never>;
+}

package/lib/toolbar/region-tools/region-tool-buttons.d.ts

@@ -0,0 +1,21 @@
+/** A drawing tool's toggle button in the toolbar's region group. */
+export interface RegionToolButton {
+    /** The drag mode the button toggles. */
+    mode: string;
+    /** Accessible name. */
+    label: string;
+    /** Tooltip (HTML). */
+    tooltip: string;
+    /** A PrimeNG glyph (`pi pi-…`), or else {@link img}. */
+    icon?: string;
+    /** An SVG under `assets/plotting/`, recoloured for its on/off state. */
+    img?: string;
+    /** `not3d`: absent from the 3D cloud's screen-space lasso (no raster to
+     *  sample / an open polyline is no region); `vertex`: needs a backend with a
+     *  vertex-editing overlay (OSD + napari-js image). */
+    gate?: 'not3d' | 'vertex';
+    /** The tool's parameter slider, shown while it is active. */
+    slider?: 'brush' | 'wand' | 'eraser';
+}
+/** The region drawing tools, in toolbar order. */
+export declare const REGION_TOOL_BUTTONS: readonly RegionToolButton[];

package/lib/toolbar/region-tools/region-tools.component.d.ts

@@ -0,0 +1,60 @@
+import { EventEmitter } from '@angular/core';
+import { RegionToolButton } from './region-tool-buttons';
+import * as i0 from "@angular/core";
+/**
+ * The toolbar's region group: open the Region Editor, the drawing tools (one
+ * table-driven toggle per {@link REGION_TOOL_BUTTONS} entry, with the active
+ * tool's parameter slider), undo / redo and delete. Presentational: the host
+ * owns the active mode and every value.
+ */
+export declare class RegionToolsComponent {
+    /** The armed drawing tool's mode, or null. */
+    activeDragMode: string | null;
+    /** The 3D cloud's screen-space lasso: no brush or polyline. */
+    is3dRegions: boolean;
+    /** The backend has a vertex-editing overlay (OSD + napari-js image). */
+    vertexTools: boolean;
+    /** Magic-wand sensitivity (the wand's slider value). */
+    wandSensitivity: number;
+    /** Brush diameter in image pixels. */
+    brushSize: number;
+    /** Vertex-eraser radius in image pixels. */
+    vertexEraserRadius: number;
+    /** A region action can be undone (enables Undo). */
+    canUndo: boolean;
+    /** An undone region action can be redone (enables Redo). */
+    canRedo: boolean;
+    /** Open the Region Editor dialog. */
+    openRegionEditor: EventEmitter<void>;
+    /** A drawing tool's button was clicked (its mode). */
+    toggleDragMode: EventEmitter<string>;
+    /** Undo the last region action. */
+    undoRegion: EventEmitter<void>;
+    /** Redo the last undone region action. */
+    redoRegion: EventEmitter<void>;
+    /** Delete the selected region. */
+    deleteRegion: EventEmitter<void>;
+    /** The wand sensitivity slider moved. */
+    wandSensitivityChange: EventEmitter<number | undefined>;
+    /** The brush size slider moved. */
+    brushSizeChange: EventEmitter<number | undefined>;
+    /** The vertex-eraser radius slider moved. */
+    vertexEraserRadiusChange: EventEmitter<number | undefined>;
+    protected readonly buttons: readonly RegionToolButton[];
+    /** Slider bounds — toolbar UI constants (the values are host-owned). */
+    protected readonly wandSensitivityMin = 0.5;
+    protected readonly wandSensitivityMax = 10;
+    protected readonly wandSensitivityStep = 0.1;
+    protected readonly brushSizeMin = 5;
+    protected readonly brushSizeMax = 300;
+    protected readonly brushSizeStep = 5;
+    protected readonly vertexEraserRadiusMin = 5;
+    protected readonly vertexEraserRadiusMax = 300;
+    protected readonly vertexEraserRadiusStep = 5;
+    protected readonly trackByMode: (_: number, b: RegionToolButton) => string;
+    protected shown(b: RegionToolButton): boolean;
+    /** A single slider's value (a range slider never feeds these). */
+    protected asNumber(v: number | number[] | undefined): number | undefined;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RegionToolsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RegionToolsComponent, "toolbar-region-tools", never, { "activeDragMode": { "alias": "activeDragMode"; "required": false; }; "is3dRegions": { "alias": "is3dRegions"; "required": false; }; "vertexTools": { "alias": "vertexTools"; "required": false; }; "wandSensitivity": { "alias": "wandSensitivity"; "required": false; }; "brushSize": { "alias": "brushSize"; "required": false; }; "vertexEraserRadius": { "alias": "vertexEraserRadius"; "required": false; }; "canUndo": { "alias": "canUndo"; "required": false; }; "canRedo": { "alias": "canRedo"; "required": false; }; }, { "openRegionEditor": "openRegionEditor"; "toggleDragMode": "toggleDragMode"; "undoRegion": "undoRegion"; "redoRegion": "redoRegion"; "deleteRegion": "deleteRegion"; "wandSensitivityChange": "wandSensitivityChange"; "brushSizeChange": "brushSizeChange"; "vertexEraserRadiusChange": "vertexEraserRadiusChange"; }, never, never, true, never>;
+}

package/lib/toolbar/segmentation/cell-segment-tool.service.d.ts

@@ -1,6 +1,4 @@
-import { BehaviorSubject } from 'rxjs';
-import { WandService } from '../wand/wand.service';
-import { WandToolHost } from '../wand/wand-tool.service';
+import { CanvasToolHost } from '../tool-kit/canvas-tool';
 import { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
 import * as i0 from "@angular/core";
 /**
@@ -14,19 +12,17 @@ import * as i0 from "@angular/core";
  * box prompt, so the box just bounds the crop it segments automatically.
  */
 export declare class CellSegmentToolService {
-    private wandService;
-    private host;
-    readonly status$: BehaviorSubject<string>;
-    readonly busy$: BehaviorSubject<boolean>;
-    readonly progress$: BehaviorSubject<number>;
-    constructor(wandService: WandService);
-    bindHost(host: WandToolHost): void;
+    private readonly state;
+    readonly status$: import("rxjs").BehaviorSubject<string>;
+    readonly busy$: import("rxjs").BehaviorSubject<boolean>;
+    readonly progress$: import("rxjs").BehaviorSubject<number>;
     /**
-     * Crop + cellpose-segment every rectangle; append the cell regions and drop
-     * the prompt rectangles that produced cells. Returns the number of regions added.
+     * Crop + cellpose-segment every rectangle of the backend behind `host`; append
+     * the cell regions and drop the prompt rectangles that produced cells. Returns
+     * the number of regions added; 0 (ignored) while a previous run is still going.
+     * The host is passed per run, so no backend's host outlives its call.
      */
-    segmentBoxes(segmenter: ICellSegmenter): Promise<number>;
-    private makeRegion;
+    segmentBoxes(host: CanvasToolHost, segmenter: ICellSegmenter): Promise<number>;
     static ɵfac: i0.ɵɵFactoryDeclaration<CellSegmentToolService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<CellSegmentToolService>;
 }

package/lib/toolbar/segmentation/cellpose-segmenter.service.d.ts

@@ -17,8 +17,17 @@ import * as i0 from "@angular/core";
 export declare class CellposeSegmenterService implements ICellSegmenter {
     private instance;
     private loading;
+    /** Bumped by {@link setModelUrl}, so a load of the previous URL is discarded. */
+    private generation;
     private modelUrl;
-    /** Point the segmenter at a different hosted CPSAM ONNX (before first use). */
+    /** Every in-flight caller's callbacks: one shared load reports to all of them. */
+    private readonly progressListeners;
+    private readonly statusListeners;
+    /**
+     * Point the segmenter at a different hosted CPSAM ONNX. Changing the URL after
+     * the model loaded (or while it loads) disposes it, so the next run loads the
+     * new model instead of silently keeping the old one.
+     */
     setModelUrl(url: string): void;
     segmentCells(image: {
         data: Uint8ClampedArray;
@@ -27,7 +36,8 @@ export declare class CellposeSegmenterService implements ICellSegmenter {
     }, progress?: CellSegmentProgress): Promise<CellSegmentation>;
     /**
      * The shared Cellpose instance, lazily created on first use and reused
-     * thereafter (deduped across concurrent callers). Exposed so a host pipeline
+     * thereafter (deduped across concurrent callers, each of which receives the
+     * load's progress). A failed load is retried on the next call. Exposed so a host pipeline
      * engine can run richer `segment()` options on the same instance. `onProgress`
      * reports raw downloaded/total bytes (`total` is null when unknown); `onStatus`
      * reports worker-init phase strings.

package/lib/toolbar/segmentation/onnx-sam-session.d.ts

@@ -1,15 +1,30 @@
 import { ISamSession, SamEmbedding, SamMaskResult, SamModelDef, SamPrompt } from '../../contracts/sam.contract';
+/**
+ * onnxruntime-web implementation of {@link ISamSession} (jit-ui#90), with two
+ * execution modes chosen per model:
+ *
+ *  - **in-process** (main thread) — for small WASM models flagged `inProcess`
+ *    (e.g. micro-sam ViT-T). Fast load + inference with no Web Worker spawn /
+ *    second ORT runtime / message round-trips; the brief encode runs on the main
+ *    thread (fine for a tiny model).
+ *  - **worker** — for WebGPU models (e.g. ViT-B, patho-sam fp16) whose heavy
+ *    encode would otherwise freeze the tab. Runs in {@link ./onnx-sam.worker} so
+ *    the UI stays responsive (the spinner animates).
+ *
+ * Both modes share their inference math via {@link ./sam-onnx-core}. Lazy-imported
+ * by the SAM tools so onnxruntime-web / the worker never load in unit tests or
+ * the initial bundle.
+ */
 export declare class OnnxSamSession implements ISamSession {
     private mode;
     private loaded;
-    private model;
     private inputSize;
     private worker;
-    private seq;
-    private readonly pending;
+    private readonly calls;
     private encoder;
     private decoder;
     private nextToken;
+    /** The few most recently used embeddings, by token (one per recently viewed image). */
     private readonly embeddings;
     loadModel(model: SamModelDef, onProgress?: (fraction: number) => void): Promise<void>;
     isLoaded(): boolean;
@@ -19,7 +34,11 @@ export declare class OnnxSamSession implements ISamSession {
         height: number;
     }): Promise<SamEmbedding>;
     decode(embedding: SamEmbedding, prompt: SamPrompt): Promise<SamMaskResult>;
+    /** Release the worker / ORT sessions. Calls still in flight reject (RT-8), so
+     *  their callers' `finally` blocks run (e.g. a tool's busy flag clears). */
     dispose(): void;
     private ensureWorker;
+    /** Terminate the worker (if any) and reject every call still waiting on it. */
+    private dropWorker;
     private call;
 }

package/lib/toolbar/segmentation/pending-calls.d.ts

@@ -0,0 +1,31 @@
+/** A reply from the SAM worker: progress for, or the result of, call `id`. */
+export interface WorkerReply {
+    id: number;
+    type: string;
+    /** Present on `type: 'progress'` replies. */
+    fraction?: number;
+    /** Present on `type: 'error'` replies. */
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Request/response bookkeeping for a worker RPC: each call gets an id and a
+ * promise that its reply settles. Every exit path (dispose, a worker crash)
+ * must {@link rejectAll}, or awaiting callers never reach their `finally` and a
+ * tool's busy flag sticks forever (RT-8).
+ */
+export declare class PendingCalls {
+    private seq;
+    private readonly pending;
+    /** Calls still awaiting a reply. */
+    get size(): number;
+    /** Register a new call; post the message with the returned id. */
+    open(onProgress?: (fraction: number) => void): {
+        id: number;
+        promise: Promise<WorkerReply>;
+    };
+    /** Route a worker reply to its call: progress, error or result. */
+    handle(reply: WorkerReply): void;
+    /** Reject every pending call with `err` and forget them. */
+    rejectAll(err: Error): void;
+}

package/lib/toolbar/segmentation/sam-model-registry.d.ts

@@ -13,7 +13,12 @@ import { SamModelDef } from '../../contracts/sam.contract';
  * cellpose default). A host can repoint them at its own hosting (e.g. a GCS
  * bucket) at runtime via {@link setSamModelUrls}; an empty URL disables a model
  * (the session throws a clear "not configured" error). Export/quantization
- * tooling: the sibling `browser-onnx-tools` project; see docs/sam-segmentation-design.md.
+ * tooling: the sibling `browser-onnx-tools` project; see
+ * docs/design/sam-segmentation-design.md.
+ *
+ * Downloads are cached in the browser by URL and `revision`: when a model's files are
+ * re-exported under the same URLs, set (or bump) its `revision` so browsers fetch the
+ * new files instead of serving the old ones from cache.
  */
 export declare const SAM_MODELS: SamModelDef[];
 /** Initial default model id (overridden at runtime once the host configures a
@@ -31,6 +36,7 @@ export declare function isSamModelReady(model: SamModelDef): boolean;
 /**
  * Point a registered model at its hosted ONNX pair (HF / GCS). Called by the
  * host's composition root once hosting is decided, keeping deployment URLs out
- * of the library.
+ * of the library. Pass `revision` when the files at those URLs can be replaced in
+ * place, and change it whenever they are (see {@link SamModelDef.revision}).
  */
-export declare function setSamModelUrls(id: string, encoderUrl: string, decoderUrl: string): void;
+export declare function setSamModelUrls(id: string, encoderUrl: string, decoderUrl: string, revision?: string): void;

package/lib/toolbar/segmentation/sam-onnx-core.d.ts

@@ -4,11 +4,18 @@ import type { SamPrompt } from '../../contracts/sam.contract';
  * Shared, DOM-free SAM inference primitives used by BOTH inference backends:
  * the in-process session (`OnnxSamSession`, main thread) and the dedicated
  * Web Worker (`onnx-sam.worker`). Keeping these here avoids duplicating the
- * preprocessing / decoder-prompt math and keeps the worker DOM-free (it can't
- * import sam-prompt.ts, which pulls in DOM types).
+ * preprocessing / decoder-prompt math; nothing here may import Angular or the
+ * DOM, since the worker bundles it.
  */
+/** SAM's per-channel (RGB) pixel mean, subtracted before the encoder. */
 export declare const PIXEL_MEAN: number[];
+/** SAM's per-channel (RGB) pixel standard deviation, divided out before the encoder. */
 export declare const PIXEL_STD: number[];
+/**
+ * Delete every downloaded SAM model (several hundred MB per origin). Resolves
+ * to true when something was removed; false where the Cache API is unavailable.
+ */
+export declare function clearSamModelCache(): Promise<boolean>;
 /** Encoder output for one image, reused across prompts. */
 export interface CoreEmbedding {
     data: Float32Array;
@@ -24,10 +31,16 @@ export interface CoreMask {
     height: number;
     iou: number;
 }
+/**
+ * The Cache API key a model file is stored under: its URL, plus the model's
+ * `SamModelDef.revision` as a query parameter when it has one, so a bumped revision
+ * misses the cache and downloads the re-exported file.
+ */
+export declare function modelCacheKey(url: string, revision?: string): string;
 /** Fetch a model as an ArrayBuffer, streaming progress and caching in the Cache
- *  API (so it isn't re-downloaded). Cache hit → progress jumps to 1. Works on
- *  the main thread and in a worker (both have `fetch` + `caches`). */
-export declare function fetchModel(url: string, onProgress?: (f: number) => void): Promise<ArrayBuffer>;
+ *  API (so it isn't re-downloaded) under {@link modelCacheKey}. Cache hit → progress
+ *  jumps to 1. Works on the main thread and in a worker (both have `fetch` + `caches`). */
+export declare function fetchModel(url: string, onProgress?: (f: number) => void, revision?: string): Promise<ArrayBuffer>;
 /** Resize (long side → size, bilinear), pad to size×size, SAM-normalize → CHW float32. */
 export declare function preprocess(data: Uint8ClampedArray, width: number, height: number, size: number, scale: number): Float32Array;
 /** Assemble decoder `point_coords`/`point_labels` from a prompt, in encoder