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

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

package/lib/toolbar/segmentation/sam-point-tool.service.d.ts

@@ -1,8 +1,32 @@
-import { BehaviorSubject } from 'rxjs';
-import { WandService } from '../wand/wand.service';
-import { WandToolHost } from '../wand/wand-tool.service';
+import { SamSessionService } from './sam-session.service';
 import { ISamSession } from '../../contracts/sam.contract';
+import { AsyncToolStatus } from '../tool-kit/async-tool-status';
+import { CanvasToolHost, ICanvasTool } from '../tool-kit/canvas-tool';
 import * as i0 from "@angular/core";
+/**
+ * The SAM point prompts of one viewer chain: the status feeds the toolbar shows
+ * and the model session. Every backend's `CanvasToolManager` gets its own
+ * {@link SamPointTool} from {@link createTool}, so in-progress points never
+ * cross backends, while all of them report through these feeds and share one
+ * busy guard and one {@link SamSessionService}.
+ */
+export declare class SamPointToolService {
+    private readonly sessions;
+    private readonly state;
+    readonly status$: import("rxjs").BehaviorSubject<string>;
+    readonly busy$: import("rxjs").BehaviorSubject<boolean>;
+    /** Encoder-download progress (0..1) on the first click; -1 when not downloading. */
+    readonly progress$: import("rxjs").BehaviorSubject<number>;
+    constructor(sessions?: SamSessionService);
+    /** Choose the registered model to use (shared with the box tool). */
+    setModel(id: string): void;
+    /** Test seam: inject a fake/alternate session. */
+    useSession(session: ISamSession): void;
+    /** A point tool for one backend, reporting through this service. */
+    createTool(): SamPointTool;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SamPointToolService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SamPointToolService>;
+}
 /** Interactive SAM point-prompt tool (jit-ui#90, P1).
  *
  * Each plain (positive) click segments the clicked object as its OWN new region
@@ -11,36 +35,28 @@ import * as i0 from "@angular/core";
  * the decoder against the (cached) image embedding and updating its live region.
  * `commit()` (Enter) finalises early; `clear()` (Esc) discards the current
  * prompt + its preview region. Mirrors the wand/brush on-canvas tool pattern and
- * reuses WandService.maskToPolygons + the shared region store.
+ * reuses the contour tracer + the shared region store.
  *
- * Inference is behind {@link ISamSession} (lazy onnxruntime-web in production,
- * a fake in tests).
+ * Inference goes through the shared {@link SamSessionService} (one session and
+ * embedding for both SAM tools; lazy onnxruntime-web in production, a fake in
+ * tests). Created by {@link SamPointToolService.createTool}.
  */
-export declare class SamPointToolService {
-    private wandService;
+export declare class SamPointTool implements ICanvasTool<void> {
+    private readonly state;
+    private readonly sessions;
+    readonly id = "samPoint";
     private host;
-    private overlay;
-    private session;
-    /** In-flight session load — dedupes a warm-up preload against the first click. */
-    private sessionLoad;
-    private model;
-    private embedding;
-    private embeddingKey;
+    private readonly overlay;
     /** Accumulated point prompts, in image (matrix) coords. */
     private points;
     /** Id of the in-progress (preview) region being refined, if committed to store. */
     private regionId;
-    readonly status$: BehaviorSubject<string>;
-    readonly busy$: BehaviorSubject<boolean>;
-    /** Encoder-download progress (0..1) on the first click; -1 when not downloading. */
-    readonly progress$: BehaviorSubject<number>;
-    private readonly boundMouseDown;
-    constructor(wandService: WandService);
-    bindHost(host: WandToolHost): void;
-    setModel(id: string): void;
-    /** Test seam: inject a fake/alternate session. */
-    useSession(session: ISamSession): void;
-    setMode(active: boolean): void;
+    constructor(state: AsyncToolStatus, sessions: SamSessionService);
+    private get status$();
+    activate(host: CanvasToolHost): void;
+    deactivate(): void;
+    /** Forget the current prompt (its preview region stays). */
+    reset(): void;
     /** Eagerly load the model in the background (fire-and-forget). Safe to call
      *  repeatedly — it dedupes against an in-flight load and an existing session. */
     preload(): void;
@@ -49,11 +65,9 @@ export declare class SamPointToolService {
     /** Discard the in-progress prompt + its preview region. */
     clear(): void;
     private createOverlay;
-    private destroyOverlay;
-    private onMouseDown;
-    /** Replace (or insert) the in-progress preview region in the shared store. */
+    /** Primary button only (the overlay filters the others). */
+    private onPointerDown;
+    /** Replace (or insert) the in-progress preview region in the shared store,
+     *  against the regions as they are now (the run may have taken a while). */
     private upsertPreview;
-    private ensureSession;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SamPointToolService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<SamPointToolService>;
 }

package/lib/toolbar/segmentation/sam-prompt.d.ts

@@ -1,34 +1,10 @@
-import { CachedImageData } from '../wand/wand-tool.service';
-import { SamPrompt } from '../../contracts/sam.contract';
+import type { CachedImageData } from '../wand/wand-tool.service';
 /**
- * Pure helpers for SAM inference — no DOM, no ORT, no `this` — so they're unit
- * testable. The session uses these to assemble decoder inputs and to convert
- * the cached image frame into the RGBA buffer the encoder preprocesses.
- */
-/**
- * Build an RGBA buffer (the encoder's input image) from a cached image frame.
- * Grayscale frames are replicated across R/G/B; RGB tuples are copied through.
- * Out-of-range/missing pixels become opaque black.
- */
-export declare function frameToRgba(cached: CachedImageData, frameIndex: number): Uint8ClampedArray;
-/**
- * Assemble the SAM decoder's `point_coords` / `point_labels` from a prompt.
+ * Build an RGBA buffer (the SAM encoder's input image) from a cached image
+ * frame: the full-frame case of {@link frameRegionToRgba}. Grayscale frames are
+ * replicated across R/G/B; missing pixels become opaque black.
  *
- * Coordinates are scaled into the encoder's resized space (`scale =
- * inputSize / max(imageW, imageH)`). A box is encoded as two points labelled
- * `2` (top-left) and `3` (bottom-right); positive/negative points use `1`/`0`.
- * When there are points but no box, a padding point `[0,0]` labelled `-1` is
- * appended (the decoder expects the box slots padded when absent).
- */
-export declare function buildDecoderPrompt(prompt: SamPrompt, scale: number): {
-    pointCoords: Float32Array;
-    pointLabels: Float32Array;
-    numPoints: number;
-};
-/**
- * Binarize SAM mask logits (`> threshold`, default 0 per SAM's mask_threshold)
- * into a 0/1 mask the contour tracer (WandService.maskToPolygons) consumes.
+ * The decoder-prompt helpers (`buildDecoderPrompt`, `binarizeMask`,
+ * `bestMaskIndex`) live in `sam-onnx-core`, which both inference paths use.
  */
-export declare function binarizeMask(logits: Float32Array | number[], threshold?: number): Uint8Array;
-/** Index of the highest-scoring mask in a multimask decoder output. */
-export declare function bestMaskIndex(iouPredictions: Float32Array | number[]): number;
+export declare function frameToRgba(cached: CachedImageData, frameIndex: number): Uint8ClampedArray;

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

@@ -0,0 +1,74 @@
+import { OnDestroy } from '@angular/core';
+import type { CachedImageData } from '../wand/wand-tool.service';
+import { ISamSession, SamEmbedding, SamModelDef } from '../../contracts/sam.contract';
+import * as i0 from "@angular/core";
+/** Creates an unloaded inference session. */
+export type SamSessionFactory = () => Promise<ISamSession>;
+/**
+ * The one SAM inference session for the active model, shared by the box- and
+ * point-prompt tools (RT-10): one download, one Worker/GPU session and one
+ * cached image embedding instead of one per tool.
+ *
+ * - Concurrent {@link ensureSession} calls share a single load, and each caller
+ *   receives its download progress.
+ * - A load that fails disposes its half-built session (and Worker) and is not
+ *   cached; the next call retries (RT-7).
+ * - {@link setModel} during a load discards that load's session, and the
+ *   waiting callers get the newly picked model instead (RT-9).
+ *
+ * Scope: root, on purpose, and deliberately NOT in `provideVisualization()`. The
+ * chain-scoped SAM tools of a second viewer (jit-ui's pipeline preview) resolve
+ * this root instance, so the model (14–172 MB) is downloaded and its Worker/GPU
+ * session built once per app, not once per viewer, and the embedding cache is
+ * keyed by image + model so viewers don't confuse each other's images. The cost
+ * is that a model picked in one viewer is the model of all of them. A host that
+ * wants a session per viewer can provide this service at the viewer's component:
+ * {@link ngOnDestroy} then disposes that viewer's session (and Worker) with it.
+ */
+export declare class SamSessionService implements OnDestroy {
+    private model;
+    private session;
+    private loading;
+    /** Bumped on every model switch; a load started under an older value is stale. */
+    private generation;
+    private readonly progressListeners;
+    private createSession;
+    /** Set by {@link ngOnDestroy}: no session is loaded any more. */
+    private destroyed;
+    /** Cached encoder embedding + the key (image identity + model) it was computed for. */
+    private embedding;
+    private embeddingKey;
+    /** The model the next run uses. */
+    getModel(): SamModelDef;
+    /** True when a session is loaded (or injected) for the current model. */
+    hasSession(): boolean;
+    /** Choose the registered model; drops the loaded session and cached embedding. */
+    setModel(id: string): void;
+    /** Drop the cached embedding (e.g. after the image/slice changes). */
+    invalidateEmbedding(): void;
+    /** Test seam: use this session (already loaded) for the current model. */
+    useSession(session: ISamSession): void;
+    /** Test seam: how sessions are created (default: lazy onnxruntime-web). */
+    useSessionFactory(factory: SamSessionFactory): void;
+    /**
+     * The loaded session for the current model, loading it if needed.
+     * `onProgress` receives the download fraction while this call waits.
+     */
+    ensureSession(onProgress?: (fraction: number) => void): Promise<ISamSession>;
+    /**
+     * The encoder embedding of a cached frame, reused while `key` (the image's
+     * identity: file, frame, readback frame) and the model are unchanged.
+     * `onEncode` is called only when the encoder actually runs.
+     */
+    embed(session: ISamSession, cached: CachedImageData, frameIndex: number, key: string, onEncode?: () => void): Promise<SamEmbedding>;
+    /**
+     * Dispose the session (and its Worker), drop the embedding and discard an
+     * in-flight load. Angular calls this when the injector providing the service
+     * is destroyed: the app for the root instance, or a viewer component that
+     * provides its own.
+     */
+    ngOnDestroy(): void;
+    private load;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SamSessionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SamSessionService>;
+}

package/lib/toolbar/segmentation/sam-tool.service.d.ts

@@ -1,50 +1,43 @@
-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 { SamSessionService } from './sam-session.service';
 import { ISamSession } from '../../contracts/sam.contract';
 import * as i0 from "@angular/core";
-/** The SAM tool binds to the same host the wand/brush use, so each backend
- *  reuses its existing pixel readback + coordinate transform + region store. */
-export type SamToolHost = WandToolHost;
+/** @deprecated The SAM tool runs against the backend's canvas-tool host:
+ *  use {@link CanvasToolHost}. */
+export type SamToolHost = CanvasToolHost;
 /**
  * Box-prompted SAM segmentation tool (jit-ui#90, P0). On `segmentBoxes()` it
  * reads every rectangle region, runs the (cached) encoder once for the image,
- * then runs the decoder per box, traces each mask to a polygon (reusing
- * WandService.maskToPolygons) and commits them as regions.
+ * then runs the decoder per box, traces each mask to a polygon and replaces
+ * the prompt rectangles with the masks.
  *
- * Inference is abstracted behind {@link ISamSession}: production uses the
- * onnxruntime-web session (lazy-imported so ORT never loads in unit tests);
- * tests inject a fake via {@link useSession}.
+ * Inference goes through the shared {@link SamSessionService} (one session and
+ * embedding for both SAM tools); tests inject a fake session via
+ * {@link useSession}.
  */
 export declare class SamToolService {
-    private wandService;
-    private host;
-    private session;
-    private model;
-    /** Cached encoder embedding + the key (image identity) it was computed for. */
-    private embedding;
-    private embeddingKey;
+    private readonly sessions;
+    private readonly state;
     /** Status text + busy flag for a spinner / toast in the host. */
-    readonly status$: BehaviorSubject<string>;
-    readonly busy$: BehaviorSubject<boolean>;
+    readonly status$: import("rxjs").BehaviorSubject<string>;
+    readonly busy$: import("rxjs").BehaviorSubject<boolean>;
     /** Encoder-download progress: -1 = not downloading, 0..1 = downloading. */
-    readonly progress$: BehaviorSubject<number>;
-    constructor(wandService: WandService);
-    /** Bind to the active backend's host (called by the backend, like the wand). */
-    bindHost(host: SamToolHost): void;
-    /** Choose the registered model to use; invalidates any cached embedding. */
+    readonly progress$: import("rxjs").BehaviorSubject<number>;
+    constructor(sessions?: SamSessionService);
+    /** Choose the registered model to use (shared with the point tool). */
     setModel(id: string): void;
     /** Drop the cached embedding (e.g. after the image/slice changes). */
     invalidateEmbedding(): void;
     /** Test seam: inject a fake/alternate inference session. */
     useSession(session: ISamSession): void;
     /**
-     * Segment every rectangle region with a box prompt and append the resulting
-     * masks as new polygon regions. Returns how many regions were added.
+     * Segment every rectangle region of the backend behind `host` with a box
+     * prompt and replace each prompt that produced a mask with the mask's polygon
+     * region. Returns how many regions were 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(): Promise<number>;
-    private makeRegion;
-    private ensureSession;
+    segmentBoxes(host: CanvasToolHost): Promise<number>;
     static ɵfac: i0.ɵɵFactoryDeclaration<SamToolService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<SamToolService>;
 }

package/lib/toolbar/segmentation/segmentation-commit.d.ts

@@ -0,0 +1,8 @@
+import { Region } from '../../models/region';
+/**
+ * `regions` minus `remove`, matched by id (identity for a region without one).
+ * Async tools use it to drop their consumed prompts from the *current* region
+ * list at commit time, instead of overwriting the list they read before a long
+ * download or inference (RT-6).
+ */
+export declare function withoutRegions(regions: Region[], remove: Region[]): Region[];

package/lib/toolbar/segmentation/segmentation-runner.d.ts

@@ -0,0 +1,52 @@
+import { Observable } from 'rxjs';
+import { MessageService } from 'primeng/api';
+/** A segmentation tool's live feeds: status line and encoder-download progress (0..1, <0 = none).
+ *  Observables, not subjects, so a contributed tool need not expose its internals. */
+export interface SegmentationProgress {
+    status$: Observable<string>;
+    progress$: Observable<number>;
+}
+/**
+ * One viewer's segmentation runs and their sticky progress toast (jit-ui#90): the
+ * box-prompt SAM and Cellpose tools, contributed whole-view tools, and the
+ * interactive SAM point tool whose feeds it bridges.
+ *
+ * The toast is keyed per viewer (`toastKey`), so a run in a pipeline preview does not
+ * show in the main view; results and failures go to the viewer's `resultKey` outlet,
+ * which the sticky toast's teardown does not clear. The toast template binds
+ * {@link status}, {@link progress}, {@link downloading} and {@link busy}.
+ */
+export declare class SegmentationRunner {
+    private readonly messages;
+    readonly toastKey: string;
+    readonly resultKey: string;
+    /** Re-render the toast (its feeds may fire outside the zone). */
+    private readonly changed;
+    status: string;
+    /** Encoder download, 0..100. */
+    progress: number;
+    downloading: boolean;
+    /** Any segmentation work in flight (the indeterminate spinner). */
+    busy: boolean;
+    /** Whether the sticky toast is up — re-adding it would stack one per point click. */
+    private shown;
+    constructor(messages: Pick<MessageService, 'add' | 'clear'>, toastKey: string, resultKey: string, 
+    /** Re-render the toast (its feeds may fire outside the zone). */
+    changed: () => void);
+    /** Surface the interactive SAM point tool's status and download progress, which runs
+     *  inside the renderer on each click (the first click pulls the encoder). */
+    bindPointTool(tool: SegmentationProgress & {
+        busy$: Observable<boolean>;
+    }, until$: Observable<unknown>): void;
+    /**
+     * Run `op` with the tool's status and download progress in the sticky toast, then
+     * report the outcome: the region count (or the tool's last status line) on success,
+     * the error on failure. The toast stays until the run settles.
+     */
+    run(label: string, tool: SegmentationProgress, op: () => Promise<number>): Promise<void>;
+    /** Show the sticky toast once (idempotent). */
+    show(summary: string): void;
+    /** Dismiss the sticky toast and reset its progress/spinner state. */
+    hide(): void;
+    private onProgress;
+}

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

@@ -0,0 +1,87 @@
+import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import { MenuItem } from 'primeng/api';
+import { ToolbarToolContribution } from '../../contracts/toolbar-tool.contract';
+import * as i0 from "@angular/core";
+/**
+ * The toolbar's segmentation group: SAM box prompt, SAM point prompts and the
+ * shared SAM model picker, cellpose, and the contributed no-prompt tools (run,
+ * pick checkpoint, parameters). Presentational: the host runs every action.
+ */
+export declare class SegmentationToolsComponent implements OnChanges {
+    /** The armed tool's mode (`samPoint` highlights the point-prompt button), or null. */
+    activeDragMode: string | null;
+    /** SAM model picker options + current selection (jit-ui#90 P1). */
+    samModels: {
+        id: string;
+        label: string;
+    }[];
+    /** The selected SAM model id. */
+    samModelId: string;
+    /** Contributed no-prompt tools, already filtered and sorted by the host. */
+    contributedTools: ToolbarToolContribution[];
+    /** Active checkpoint per contributed tool, keyed by tool id. */
+    toolModelIds: Record<string, string>;
+    /** Run box-prompted SAM segmentation on the drawn rectangles (jit-ui#90). */
+    segmentRegions: EventEmitter<void>;
+    /** Run cellpose-SAM (auto) inside each drawn rectangle's crop (jit-ui#90). */
+    segmentCellpose: EventEmitter<void>;
+    /** The SAM point tool's toggle ('samPoint'). */
+    toggleDragMode: EventEmitter<string>;
+    /** A SAM model was picked from the model menu (its id). */
+    samModelChange: EventEmitter<string>;
+    /** Run a contributed tool over the current view (its id). */
+    runTool: EventEmitter<string>;
+    /** A contributed tool's checkpoint was picked. */
+    toolModelChange: EventEmitter<{
+        toolId: string;
+        modelId: string;
+    }>;
+    /** Open a contributed tool's parameter dialog (its id). */
+    openToolParams: EventEmitter<string>;
+    /** Model picker for the Segment button's dropdown menu. The active model
+     *  (`samModelId`) is marked with a check; selecting an item emits
+     *  `samModelChange` (jit-ui#90 P1).
+     *
+     *  Held as a stable array (rebuilt only when `samModels`/`samModelId` change),
+     *  NOT a getter: a getter returns a fresh array with new `command` closures on
+     *  every change-detection tick, which makes the bound `p-menu` overlay rebuild
+     *  its DOM mid-interaction and swallow the click on a menu item.
+     *
+     *  `tooltip` carries the model's description from {@link MODEL_INFO}; the
+     *  menus' shared item template turns it into the hover info icon. p-menu's own
+     *  rendering ignores the field (it reads `item.title`), so it is free to use. */
+    protected samMenuItems: MenuItem[];
+    /**
+     * Model menus for the contributed tools, keyed by tool id. Same stable-array
+     * reasoning as {@link samMenuItems} — and it is why this is a map rebuilt in
+     * `ngOnChanges` rather than a method called from the template, which would
+     * hand `p-menu` a new array every tick.
+     *
+     * A contributed tool supplies its own per-model description, so unlike the
+     * SAM menu these do not consult {@link MODEL_INFO}: this library has no
+     * copy for checkpoints it does not know about.
+     */
+    protected toolMenuItems: Record<string, MenuItem[]>;
+    ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * Strip markup from a model description so it can be read aloud.
+     *
+     * The copy in MODEL_INFO and in a contribution's `ToolModelOption.info` is
+     * written for a visual tooltip rendered with `[escape]="false"`, so it carries
+     * `<b>` and `<br>`. Passed to `aria-label` verbatim a screen reader announces
+     * the tags, so they are removed and `<br>` becomes a sentence break. Entities
+     * used in that copy (`&nbsp;`, `&times;`, `&amp;`) are decoded for the same
+     * reason.
+     */
+    protected plainText(html: string): string;
+    /** The info button's `aria-label` (`infoLabel` on a menu item), built once with the
+     *  menu rather than by a template call on every check; none without a description. */
+    private infoLabel;
+    /** Keeps each contributed tool's `p-menu` overlay alive across CD ticks —
+     *  re-creating it mid-interaction swallows the click on a menu item. */
+    protected trackToolById(_index: number, tool: {
+        id: string;
+    }): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SegmentationToolsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SegmentationToolsComponent, "toolbar-segmentation-tools", never, { "activeDragMode": { "alias": "activeDragMode"; "required": false; }; "samModels": { "alias": "samModels"; "required": false; }; "samModelId": { "alias": "samModelId"; "required": false; }; "contributedTools": { "alias": "contributedTools"; "required": false; }; "toolModelIds": { "alias": "toolModelIds"; "required": false; }; }, { "segmentRegions": "segmentRegions"; "segmentCellpose": "segmentCellpose"; "toggleDragMode": "toggleDragMode"; "samModelChange": "samModelChange"; "runTool": "runTool"; "toolModelChange": "toolModelChange"; "openToolParams": "openToolParams"; }, never, never, true, never>;
+}

package/lib/toolbar/stack-controls/stack-controls.component.d.ts

@@ -0,0 +1,51 @@
+import { EventEmitter, OnDestroy } from '@angular/core';
+import * as i0 from "@angular/core";
+/** A stack-mode choice (`val` 'false' = single image, 'true' = stack). */
+export interface StackOption {
+    name: string;
+    val: string;
+}
+/**
+ * The toolbar's z-stack group: the slice bar, and (Plotly heatmap) the single-image / stack
+ * toggle. The views that swap slices in place follow the bar as it moves; the heatmap's single
+ * image is re-plotted at the slice it settles on. Presentational: the host owns `zIndex`.
+ */
+export declare class StackControlsComponent implements OnDestroy {
+    /** Show the live slice scrubber. */
+    liveScrubber: boolean;
+    /** Show the single-image / stack toggle (Plotly heatmap). */
+    stackToggle: boolean;
+    /** Stack mode is on (the toggle's state). */
+    showStack: boolean;
+    /** The two stack-mode choices of the toggle. */
+    stackOptions: StackOption[];
+    /** The current slice (0-based). */
+    zIndex: number;
+    /** The last slice index. */
+    maxIndex: number;
+    /** The live scrubber moved (fires while dragging). */
+    zScrub: EventEmitter<number | undefined>;
+    /** The live scrubber was released on a slice. */
+    zSlide: EventEmitter<number | undefined>;
+    /** A stack-mode choice was picked. */
+    selectStackOption: EventEmitter<StackOption>;
+    /** The heatmap's slice bar moved to a slice (the host shows its number). */
+    zIndexInput: EventEmitter<number>;
+    /** The heatmap's slice bar settled: re-plot at that slice. */
+    reloadAndPlot: EventEmitter<void>;
+    /** How long key steps on the heatmap's bar pause before the slice is re-plotted. */
+    static readonly REPLOT_DELAY_MS = 400;
+    /** A drag of the bar is under way (its end re-plots the heatmap, not each step). */
+    protected dragging: boolean;
+    private replot;
+    /** The heatmap in single-image mode: its bar re-plots the slice it settles on. */
+    protected get singleImage(): boolean;
+    /** The bar moved: a live view follows it; the heatmap shows the number, and re-plots after key steps pause. */
+    protected onSliceChange(z: number | undefined): void;
+    /** The bar was let go (a drag's end, or a click on its track). */
+    protected onSliceEnd(z: number | undefined): void;
+    private cancelReplot;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<StackControlsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<StackControlsComponent, "toolbar-stack-controls", never, { "liveScrubber": { "alias": "liveScrubber"; "required": false; }; "stackToggle": { "alias": "stackToggle"; "required": false; }; "showStack": { "alias": "showStack"; "required": false; }; "stackOptions": { "alias": "stackOptions"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "maxIndex": { "alias": "maxIndex"; "required": false; }; }, { "zScrub": "zScrub"; "zSlide": "zSlide"; "selectStackOption": "selectStackOption"; "zIndexInput": "zIndexInput"; "reloadAndPlot": "reloadAndPlot"; }, never, never, true, never>;
+}

package/lib/toolbar/tool-kit/async-tool-status.d.ts

@@ -0,0 +1,21 @@
+import { BehaviorSubject } from 'rxjs';
+/**
+ * Status, busy flag and progress of a long-running (download / inference) tool,
+ * plus the re-entrancy guard that goes with them.
+ */
+export declare class AsyncToolStatus {
+    /** Status text for a toast / spinner label. */
+    readonly status$: BehaviorSubject<string>;
+    /** True from the start of a run until it settles. */
+    readonly busy$: BehaviorSubject<boolean>;
+    /** Download progress: -1 = not downloading, 0..1 = downloading. */
+    readonly progress$: BehaviorSubject<number>;
+    get busy(): boolean;
+    /**
+     * Run `job` unless a run is already in flight (then resolve `undefined` at
+     * once). Busy is set *before* the first await — a model download is exactly
+     * the window a second press must not start another run in — and busy and
+     * progress are reset however the job ends.
+     */
+    run<T>(job: () => Promise<T>): Promise<T | undefined>;
+}

package/lib/toolbar/tool-kit/canvas-tool-manager.d.ts

@@ -0,0 +1,36 @@
+import type { CanvasToolId } from '../../contracts/display-types';
+import { CanvasToolHost, ICanvasTool } from './canvas-tool';
+/**
+ * One backend's canvas tools. Each backend (Plotly, OpenSeadragon, napari-js)
+ * creates its own manager with its own {@link CanvasToolHost} and its own tool
+ * instances, so arming a tool never re-binds a tool another backend is using,
+ * and a backend switch never carries a stroke or SAM points across (RT-21).
+ * At most one tool is armed at a time.
+ */
+export declare class CanvasToolManager {
+    private readonly host;
+    private readonly tools;
+    private active;
+    constructor(host: CanvasToolHost, tools: ReadonlyArray<ICanvasTool<never>>);
+    /** The armed tool's id, or null. */
+    get activeId(): CanvasToolId | null;
+    /** Whether this manager has a tool for `id`. */
+    has(id: string | null | undefined): id is CanvasToolId;
+    /** The tool with this id, typed by the caller. */
+    get<T extends ICanvasTool<never>>(id: CanvasToolId): T | undefined;
+    /**
+     * Arm `id` with `options`, disarming the armed tool first. null — or an id
+     * this manager has no tool for, such as a region draw mode — disarms only.
+     * Arming the armed tool again forwards `options` and keeps its work in progress.
+     */
+    activate(id: string | null, options?: unknown): void;
+    /** Disarm the armed tool, if any. */
+    deactivate(): void;
+    /** Forward live options to a tool, armed or not. */
+    setOptions(id: CanvasToolId, options: unknown): void;
+    /** Drop one tool's work in progress (it stays armed). */
+    reset(id: CanvasToolId): void;
+    /** Drop every tool's work in progress — after undo/redo or an image switch,
+     *  where a stroke or prompt no longer matches the regions on screen. */
+    resetAll(): void;
+}