tempest-react-sdk 0.38.2 → 0.39.0

package/dist/vision.d.ts

@@ -11,6 +11,11 @@ import { RefObject } from 'react';
  * @param idxs Class index per box, length `N`. Boxes with different `idxs`
  *   never suppress each other.
  * @param iouThreshold IoU threshold for suppression within a class.
+ * @returns Indices of kept boxes, sorted by descending score across all
+ *   classes. Survivors from different classes that are tied on score are
+ *   ordered lowest-index first — an explicit tie-break, because the order the
+ *   per-class loop emits them in is an implementation detail (here, `Map`
+ *   insertion order; in Python, sorted class order).
  */
 export declare function batchedNms(boxes: Float32Array, scores: Float32Array, idxs: Int32Array, iouThreshold: number): Int32Array;
 
@@ -310,6 +315,38 @@ export declare const COCO_CLASSES: readonly string[];
  */
 export declare function computeImageLuminance(source: LuminanceSource, reusableCanvas?: HTMLCanvasElement): number;
 
+/** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
+/**
+ * The contract a fused pipeline carries inside its own `.onnx` file.
+ *
+ * A pipeline built by the Python SDK's `ort_vision_sdk.compose` is a single
+ * graph that already contains the detector, the crop-and-resize bridge and the
+ * classifier. Everything the runtime needs to drive it — the letterbox
+ * resolution, the crop resolution, where the crops come from, how many
+ * detections the graph emits, the class names of both stages — was decided at
+ * fusion time and written into the model's metadata.
+ *
+ * This module reads it back. It is the browser half of a contract whose other
+ * half lives in `ort_vision_sdk/fusion.py`: the same keys, the same encodings,
+ * the same fallbacks. A pipeline fused once therefore runs identically in
+ * Python and in a browser tab, off the same file.
+ *
+ * Building a pipeline stays a Python-side build step — there is no ONNX
+ * protobuf writer here, and there is no reason for one: fusing is something you
+ * do once next to your export pipeline, not in a page load.
+ */
+/**
+ * Which tensor the bridge crops the detected boxes out of.
+ *
+ * - `"detector_input"`: the letterboxed tensor already fed to the detector.
+ *   The fused graph then has a **single** image input, but a small object is
+ *   cropped out of its downscaled copy.
+ * - `"original"`: a second, full-resolution image input. The bridge undoes the
+ *   letterbox transform in-graph and crops at native resolution. Two tensors to
+ *   feed, still one session and one model load.
+ */
+export declare type CropSource = "detector_input" | "original";
+
 /**
  * One declared dimension: a number when the graph pins it, `null` when the
  * dimension is symbolic (dynamic).
@@ -436,29 +473,6 @@ export declare interface DecodeYoloSegOptions {
     readonly maskThreshold?: number;
 }
 
-/**
- * @deprecated since 0.2.0 — use {@link decodeYolo}. Same behavior; the
- * decoder covers v8/v9/v10/v11/v12 detect heads. Will be removed in 0.4.0.
- */
-export declare function decodeYoloV8(output: Float32Array, outputDims: readonly number[], options: DecodeYoloOptions): DecodedDetection[];
-
-/**
- * @deprecated since 0.2.0 — use {@link decodeYoloAnchors}. Will be removed in 0.4.0.
- */
-export declare function decodeYoloV8Anchors(data: Float32Array, dims: readonly number[], options: DecodeYoloAnchorsOptions): DecodedAnchors;
-
-/** @deprecated since 0.2.0 — use {@link DecodeYoloAnchorsOptions}. */
-export declare type DecodeYoloV8AnchorsOptions = DecodeYoloAnchorsOptions;
-
-/** @deprecated since 0.2.0 — use {@link DecodeYoloOptions}. */
-export declare type DecodeYoloV8Options = DecodeYoloOptions;
-
-/** @deprecated since 0.2.0 — use {@link decodeYoloSeg}. Will be removed in 0.4.0. */
-export declare function decodeYoloV8Seg(perAnchorData: Float32Array, perAnchorDims: readonly number[], prototypeData: Float32Array, prototypeDims: readonly number[], options: DecodeYoloSegOptions): DecodedSegmentation[];
-
-/** @deprecated since 0.2.0 — use {@link DecodeYoloSegOptions}. */
-export declare type DecodeYoloV8SegOptions = DecodeYoloSegOptions;
-
 /**
  * Default execution provider preference order for browser ORT.
  *
@@ -468,1037 +482,1584 @@ export declare type DecodeYoloV8SegOptions = DecodeYoloSegOptions;
 export declare const DEFAULT_PROVIDERS: readonly string[];
 
 /**
- * Infer how many classes a YOLO detection/segmentation head emits.
- *
- * Such a head declares `(B, 4 + nc, N)` — four box coordinates stacked above one
- * score per class, over `N` candidate anchors. `N` is in the thousands and the
- * batch is 1, so the channel axis is the smallest static axis above 1.
- *
- * @param shape Declared shape of the model's first output.
- * @returns The class count, or `null` when the shape leaves it undeterminable —
- *   fully dynamic, or too small to hold boxes plus at least one class.
- */
-export declare function detectionNumClasses(shape: DeclaredShape): number | null;
-
-/**
- * Single detected object produced by an object-detection model.
- */
-export declare interface DetectionResult {
-    readonly classId: number;
-    readonly className: string;
-    readonly confidence: number;
-    readonly bbox: BoundingBox;
-    /** Alias for `classId` (Ultralytics-style). */
-    readonly cls: number;
-    /** Alias for `className`. */
-    readonly name: string;
-    /** Alias for `confidence` (Ultralytics-style). */
-    readonly conf: number;
-    /** Alias for `bbox` (Ultralytics-style). */
-    readonly box: BoundingBox;
-    /**
-     * The original image cropped to `bbox`, HWC RGB uint8. Empty boxes
-     * (zero area) yield a zero-sized `RGBImage`.
-     */
-    readonly croppedImage: RGBImage;
-}
-
-/**
- * Per-image detection envelope (Ultralytics-style `Results`).
- *
- * Iterating yields per-instance {@link DetectionResult} entries, so legacy
- * code that did `for (const d of detector.predict(img))` only needs an
- * extra `[0]` to bridge:
- *
- * ```typescript
- * for (const d of (await detector.predict(img))[0]) {
- *   console.log(d.cls, d.conf, d.box.xyxy);
- * }
- * ```
- *
- * For numpy-style bulk access, use the `boxes` collection.
- */
-export declare class DetectionResults implements Iterable<DetectionResult> {
-    readonly boxes: Boxes;
-    readonly detections: readonly DetectionResult[];
-    readonly names: Readonly<Record<number, string>>;
-    readonly origImg: RGBImage;
-    readonly origShape: readonly [number, number];
-    readonly path: string | null;
-    readonly speed: Readonly<Speed>;
-    constructor(boxes: Boxes, detections: readonly DetectionResult[], names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Speed>);
-    /** Number of surviving detections. */
-    get length(): number;
-    /** Index into the per-instance detections. */
-    get(index: number): DetectionResult | undefined;
-    [Symbol.iterator](): Iterator<DetectionResult>;
-}
-
-/**
- * Object detector for anchor-free YOLO ONNX models (v8/v9/v10/v11/v12).
+ * Resolve a labels specification into an ordered array of class names.
  *
- * `predict()` returns `Promise<DetectionResults[]>` (length 1 for a single
- * image), mirroring Ultralytics' `YOLO("img.jpg")`. Iterate the envelope for
- * per-instance dataclasses, or use the bulk `boxes` view (`.xyxy`, `.xywh`,
- * `.xyxyn`, `.xywhn`, `.cls`, `.conf`).
- *
- * @example
- * ```typescript
- * const det = await Detector.create("/models/yolov8n.onnx");
- * const results = await det.predict("/images/street.jpg");
- * const r = results[0];
- * console.log(r.boxes.xyxy, r.boxes.cls, r.boxes.conf, r.names);
- * for (const d of r) {
- *   console.log(d.cls, d.conf, d.box.xyxy);
- * }
- * ```
- */
-export declare class Detector extends VisionTask {
-    private readonly _head;
-    private readonly _labels;
-    private readonly _names;
-    private readonly _inputSize;
-    private readonly _confThreshold;
-    private readonly _iouThreshold;
-    private readonly _maxDetections;
-    private constructor();
-    /** Load the model and resolve labels. */
-    static create(model: ModelSource, options?: DetectorOptions): Promise<Detector>;
-    /** The decoder family used to interpret the model's output. */
-    get head(): DetectorHead;
-    /** Class labels indexed by class id. */
-    get labels(): readonly string[];
-    /** Class id → class name dict (matches Ultralytics' `model.names`). */
-    get names(): Readonly<Record<number, string>>;
-    /**
-     * The `[width, height]` this task preprocesses to.
-     *
-     * Resolved at creation time from the model's graph when it declares a static
-     * input, so reading it back tells you the resolution inference really runs at
-     * — not merely what was requested.
-     */
-    get inputSize(): readonly [number, number];
-    /** Number of classes the model predicts. */
-    get numClasses(): number;
-    /**
-     * Alias for {@link predict} — call the detector like a torch `nn.Module`.
-     *
-     * Use as `det.call(img)` since JavaScript class instances are not callable;
-     * for direct invocation, prefer `det.predict(img)`. The full
-     * {@link DetectorPredictOptions} (including `classes`) is supported.
-     */
-    call(image: ImageInput, options?: DetectorPredictOptions): Promise<DetectionResults[]>;
-    /**
-     * Run detection on a single image.
-     *
-     * The returned envelope carries a {@link Speed} breakdown in `speed`,
-     * mirroring Ultralytics' `results[0].speed`.
+ * @throws {@link LabelMapError} if the spec is invalid, the preset is unknown,
+     *   or the resolved length disagrees with `numClasses`.
      */
-    predict(image: ImageInput, options?: DetectorPredictOptions): Promise<DetectionResults[]>;
-    private _preprocess;
-    private _buildResult;
-    private _buildBoxes;
-}
-
-/**
- * Decoder family for the model's detection head.
- *
- * - `"yolo"`: anchor-free YOLO head with output shape `[1, 4 + nc, N]` —
- *   covers YOLOv8, v9, v10, v11, v12, v26 detect exports.
- *
- * The SDK does **not** auto-detect the head from the model — the caller is
- * responsible for picking a head that matches their export. Future families
- * (v5/v6/v7 with `[1, N, 5+nc]`) will be added as new literal members.
- */
-export declare type DetectorHead = "yolo";
-
-export declare interface DetectorOptions extends OrtSessionOptions {
-    /**
-     * Decoder family for the detection head. Default `"yolo"` covers
-     * YOLOv8/v9/v10/v11/v12/v26.
-     */
-    readonly head?: DetectorHead;
-    /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */
-    readonly labels?: LabelSpec;
-    /** Number of classes — used to validate the supplied labels. */
-    readonly numClasses?: number;
-    /**
-     * Model input `[width, height]` in pixels for letterboxing.
-     *
-     * Only used when the model's graph leaves its spatial axes dynamic: a graph
-     * that declares a static size always wins, since that is the only shape ONNX
-     * Runtime will accept. Defaults to `[640, 640]`.
-     */
-    readonly inputSize?: readonly [number, number];
-    /** Default minimum class score to keep a candidate. */
-    readonly confThreshold?: number;
-    /** Default IoU threshold for non-maximum suppression. */
-    readonly iouThreshold?: number;
-    /** Maximum number of detections per image. */
-    readonly maxDetections?: number;
-}
-
-export declare interface DetectorPredictOptions {
-    /** Override the default confidence threshold. */
-    readonly confThreshold?: number;
-    /** Override the default IoU threshold. */
-    readonly iouThreshold?: number;
-    /**
-     * If set, keep only detections whose `classId` is in this list.
-     * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.
-     */
-    readonly classes?: readonly number[];
-}
-
-/**
- * Convert an HWC BGR uint8 buffer (OpenCV layout) to the SDK's HWC RGB.
- *
- * Use when you receive image bytes from `cv2.imencode` over the wire and
- * want to feed them to the SDK without going through a canvas decode.
- *
- * @param bgr Flat BGR Uint8Array of length `width * height * 3`.
- */
-export declare function fromCv2(bgr: Uint8Array, width: number, height: number): RGBImage;
+ /**
+  * Pick the fallback label spec for a model that declares no class names.
+  *
+  * The COCO preset is the right default for a stock YOLO export and an
+  * impossible one for anything else: it names exactly 80 classes, so handing it
+  * to a 3-class head makes {@link resolveLabels} throw `Resolved 80 labels but
+  * the model has 3 classes` and the task cannot be created at all. A custom
+  * model without baked-in `names` is an ordinary thing to have — it should come
+  * up as `class_0`, `class_1`, ..., not as a failure.
+  *
+  * @param numClasses Classes the model predicts, or `undefined` when the output
+  *   shape does not say.
+  * @returns `"coco"` when the preset can describe the model, otherwise `null`,
+  *   which makes {@link resolveLabels} generate `class_N` names.
+  */
+ export declare function defaultLabels(numClasses: number | undefined): LabelSpec;
 
-/** Anything {@link loadImage} accepts as an image input. */
-export declare type ImageInput = string | Blob | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap | ImageData | RGBImage;
+ /**
+  * Detector and classifier running as a single ONNX model.
+  *
+  * Everything the pipeline needs to know about itself — the resolution to
+  * letterbox to, whether it wants the full-resolution image as well, whether its
+  * classifier output still needs a softmax, the class names of both stages — was
+  * written into the file at fusion time and is read back here. Nothing is
+  * restated on the JavaScript side, so nothing can drift out of step with the
+  * Python side that built it.
+  *
+  * @example
+  * ```typescript
+  * const pipeline = await DetectClassify.create("/models/pipeline.onnx");
+  * const result = (await pipeline.predict("/images/flock.jpg"))[0];
+  * for (const detection of result) {
+  *   console.log(detection.name, detection.conf, detection.classification?.name);
+  * }
+  * ```
+  */
+ export declare class DetectClassify extends VisionTask {
+     private readonly _spec;
+     private readonly _labels;
+     private readonly _names;
+     private readonly _classifierLabels;
+     private readonly _classifierNames;
+     private readonly _raiseOnEmpty;
+     private constructor();
+     private _pipelineCache;
+     /**
+      * Run the model once on zero-filled inputs, paying one-time costs up front.
+      *
+      * Worth more here than on a single-stage task: a fused pipeline is two models
+      * plus the bridge in one graph, so the first inference compiles shaders for
+      * all of it. Calling this while a loading spinner is still up moves that cost
+      * somewhere the user is already waiting.
+      *
+      * @param runs How many warm-up inferences to run. One is enough for WASM;
+      *   WebGPU sometimes settles on the second.
+      */
+     warmup(runs?: number): Promise<void>;
+     /**
+      * The fused preprocessing pipeline, built on first use.
+      *
+      * Lazily, because constructing it allocates canvases: a pipeline built in an
+      * environment without a canvas implementation stays constructible, and only
+      * fails if it is actually asked to preprocess something.
+      */
+     private get _pipeline();
+     /**
+      * Load a fused pipeline and resolve both label spaces.
+      *
+      * @param model The fused `.onnx` — a URL, an `ArrayBuffer`, or bytes.
+      * @param options Label overrides plus the usual session options.
+      * @throws {@link FusionError} when the model carries no pipeline metadata,
+          *   i.e. it is a plain detector or classifier rather than something
+          *   `ort_vision_sdk.compose` produced.
+          */
+      static create(model: ModelSource, options?: DetectClassifyOptions): Promise<DetectClassify>;
+      /** The pipeline configuration recorded in the model at fusion time. */
+      get spec(): FusionSpec;
+      /** The `[width, height]` the detection stage runs at. */
+      get inputSize(): readonly [number, number];
+      /** Detector class labels indexed by class id. */
+      get labels(): readonly string[];
+      /** Detector class id → class name (matches Ultralytics' `model.names`). */
+      get names(): Readonly<Record<number, string>>;
+      /** Classifier class labels indexed by class id. */
+      get classifierLabels(): readonly string[];
+      /** Classifier class id → class name. */
+      get classifierNames(): Readonly<Record<number, string>>;
+      /**
+       * Alias for {@link predict} — call the pipeline like a torch `nn.Module`.
+       *
+       * Use as `pipeline.call(img)` since JavaScript class instances are not
+       * callable; for direct invocation, prefer `pipeline.predict(img)`.
+       */
+      call(image: ImageInput, options?: DetectClassifyPredictOptions): Promise<DetectClassifyResults[]>;
+      /**
+       * Run the pipeline on a single image.
+       *
+       * The returned envelope carries a {@link Speed} breakdown in `speed`. Its
+       * `inference` figure covers detection *and* classification, since the
+       * pipeline runs them as one graph and no boundary between them is observable
+       * from outside.
+       */
+      predict(image: ImageInput, options?: DetectClassifyPredictOptions): Promise<DetectClassifyResults[]>;
+      /**
+       * Letterbox the image and build the graph's feeds.
+       *
+       * The detector input runs through {@link LetterboxPipeline}, which fuses the
+       * resize, the padding and the HWC-to-CHW float conversion into one
+       * `drawImage` plus one readback, and reuses its output buffer between frames.
+       * That buffer goes straight to ONNX Runtime, so `_pipeline.release()` must not
+       * be called until the run resolves.
+       *
+       * A pipeline fused with `cropSource: "original"` also takes the untouched
+       * image as a second input, plus the scale and padding of the letterbox — that
+       * is what lets the graph undo the letterbox transform internally and crop at
+       * native resolution instead of from the downscaled copy. That one is **not**
+       * letterboxed by definition, so it does not go through the fused path.
+       */
+      private _preprocess;
+      /**
+       * Map one letterboxed xyxy row back onto the original image.
+       *
+       * The graph always reports boxes in the detector's letterboxed pixel space,
+       * whichever crop source it was fused with, so both sources agree here.
+       */
+      private _toOriginal;
+      /**
+       * Turn one row of the classifier output into a result object.
+       *
+       * @param row The output row for this detection.
+       * @param image The crop the row describes, carried so callers can display
+       *   what was classified.
+       * @param k Optional truncation of the probability list.
+       */
+      private _classify;
+     }
+
+     export declare interface DetectClassifyOptions extends OrtSessionOptions {
+         /**
+          * Class label spec for the **detection** stage — see {@link resolveLabels}.
+          * Defaults to the names recorded at fusion time, falling back to the COCO
+          * 80-class preset when the fusion recorded none.
+          */
+         readonly labels?: LabelSpec;
+         /**
+          * Class label spec for the **classification** stage. Defaults to the recorded
+          * names, falling back to generated `class_<id>` names.
+          */
+         readonly classifierLabels?: LabelSpec;
+         /**
+          * If `true`, a run that finds nothing throws {@link NoDetectionsError}
+          * instead of returning an empty envelope. Default `false`, because looking
+          * and finding nothing is a successful inference. Turn it on when an empty
+          * result means the surrounding pipeline should stop rather than carry on with
+          * zero rows. Can be overridden per `predict` call.
+          */
+         readonly raiseOnEmpty?: boolean;
+     }
 
-/** Raised when an input image cannot be decoded into the canonical format. */
-export declare class ImageLoadError extends OrtVisionError {
-}
+     export declare interface DetectClassifyPredictOptions {
+         /**
+          * Drop detections scoring below this. The graph's own NMS threshold was fixed
+          * at fusion time and cannot be lowered here — this only filters further.
+          */
+         readonly confThreshold?: number;
+         /** If set, keep only detections whose detector `classId` is in this list. */
+         readonly classes?: readonly number[];
+         /** Truncate each detection's `classification.probabilities` to its top-k entries. */
+         readonly topK?: number;
+         /** Override the constructor's `raiseOnEmpty` setting for this call. */
+         readonly raiseOnEmpty?: boolean;
+     }
 
-/** Raised when ONNX Runtime fails while executing a model. */
-export declare class InferenceError extends OrtVisionError {
-}
+     /**
+      * Per-image envelope for a fused detect→classify pipeline.
+      *
+      * Structurally a {@link DetectionResults} with a second class map: every
+      * detection it yields carries a populated `classification`, and the two stages
+      * have their own, unrelated label spaces — a detector that finds `sheep`
+      * feeding a classifier that answers `famacha_3` shares no class ids with it.
+      * Merging them into one `names` record would make `cls` and
+      * `classification.cls` look comparable when they are not.
+      *
+      * ```typescript
+      * const result = (await pipeline.predict("flock.jpg"))[0];
+      * for (const detection of result) {
+      *   console.log(detection.name, detection.conf, detection.classification?.name);
+      * }
+      * ```
+      */
+     export declare class DetectClassifyResults implements Iterable<DetectionResult> {
+         readonly boxes: Boxes;
+         readonly detections: readonly DetectionResult[];
+         readonly names: Readonly<Record<number, string>>;
+         readonly classifierNames: Readonly<Record<number, string>>;
+         readonly origImg: RGBImage;
+         readonly origShape: readonly [number, number];
+         readonly path: string | null;
+         readonly speed: Readonly<Speed>;
+         constructor(boxes: Boxes, detections: readonly DetectionResult[], names: Readonly<Record<number, string>>, classifierNames: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Speed>);
+         /** Number of surviving detections. */
+         get length(): number;
+         /** Index into the per-instance detections. */
+         get(index: number): DetectionResult | undefined;
+         [Symbol.iterator](): Iterator<DetectionResult>;
+     }
 
-/**
- * Whether a measured luminance clears a brightness threshold.
- *
- * `threshold` is intentionally required — a sensible value is
- * application-specific (it depends on the model, the lighting the model was
- * trained on, and the acceptable false-reject rate), so the SDK does not bake
- * in a default.
- *
- * @param luminance - measured mean luminance in `0..255`.
- * @param threshold - minimum acceptable luminance in `0..255`.
- * @returns `true` when `luminance >= threshold`.
- */
-export declare function isLuminanceAcceptable(luminance: number, threshold: number): boolean;
+     /**
+      * Infer how many classes a YOLO detection/segmentation head emits.
+      *
+      * Such a head declares `(B, 4 + nc, N)` — four box coordinates stacked above one
+      * score per class, over `N` candidate anchors. `N` is in the thousands and the
+      * batch is 1, so the channel axis is the smallest static axis above 1.
+      *
+      * @param shape Declared shape of the model's first output.
+      * @returns The class count, or `null` when the shape leaves it undeterminable —
+      *   fully dynamic, or too small to hold boxes plus at least one class.
+      */
+     export declare function detectionNumClasses(shape: DeclaredShape): number | null;
 
-/** Raised when class labels cannot be resolved from the supplied spec. */
-export declare class LabelMapError extends OrtVisionError {
-}
+     /**
+      * Single detected object produced by an object-detection model.
+      */
+     export declare interface DetectionResult {
+         readonly classId: number;
+         readonly className: string;
+         readonly confidence: number;
+         readonly bbox: BoundingBox;
+         /** Alias for `classId` (Ultralytics-style). */
+         readonly cls: number;
+         /** Alias for `className`. */
+         readonly name: string;
+         /** Alias for `confidence` (Ultralytics-style). */
+         readonly conf: number;
+         /** Alias for `bbox` (Ultralytics-style). */
+         readonly box: BoundingBox;
+         /**
+          * The original image cropped to `bbox`, HWC RGB uint8. Empty boxes
+          * (zero area) yield a zero-sized `RGBImage`.
+          */
+         readonly croppedImage: RGBImage;
+         /**
+          * What a second, classification stage predicted **for this crop** —
+          * populated only by {@link DetectClassify}, and `null` for a plain detector.
+          *
+          * Kept as its own field rather than folded into `classId`/`className`
+          * because the two answers are different questions: the detector says *what
+          * kind of object this is*, the classifier says *which sub-category the object
+          * belongs to*, and collapsing them would lose one of the two.
+          */
+         readonly classification?: ClassificationResult | null;
+     }
 
-/**
- * Class label resolution: presets, lists, dicts, or auto-generated.
- *
- * Tasks call {@link resolveLabels} once at construction time to turn whatever
- * the caller passed (preset name, array, dict, or `null`) into an ordered
- * array of class names indexed by class id.
- *
- * In the browser there is no filesystem, so this module does not load labels
- * from a path — fetch the file yourself and pass an array.
- */
-/**
- * Anything accepted by {@link resolveLabels}.
- *
- * - `string[]` / `readonly string[]`: explicit names indexed by class id.
- * - `Record<number, string>`: sparse mapping (gaps filled with `class_<id>`).
- * - `string`: a preset name (e.g. `"coco"`).
- * - `null` / `undefined`: auto-generate `class_0` ... `class_{numClasses-1}`.
- */
-export declare type LabelSpec = readonly string[] | Record<number, string> | string | null | undefined;
+     /**
+      * Per-image detection envelope (Ultralytics-style `Results`).
+      *
+      * Iterating yields per-instance {@link DetectionResult} entries, so legacy
+      * code that did `for (const d of detector.predict(img))` only needs an
+      * extra `[0]` to bridge:
+      *
+      * ```typescript
+      * for (const d of (await detector.predict(img))[0]) {
+      *   console.log(d.cls, d.conf, d.box.xyxy);
+      * }
+      * ```
+      *
+      * For numpy-style bulk access, use the `boxes` collection.
+      */
+     export declare class DetectionResults implements Iterable<DetectionResult> {
+         readonly boxes: Boxes;
+         readonly detections: readonly DetectionResult[];
+         readonly names: Readonly<Record<number, string>>;
+         readonly origImg: RGBImage;
+         readonly origShape: readonly [number, number];
+         readonly path: string | null;
+         readonly speed: Readonly<Speed>;
+         constructor(boxes: Boxes, detections: readonly DetectionResult[], names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Speed>);
+         /** Number of surviving detections. */
+         get length(): number;
+         /** Index into the per-instance detections. */
+         get(index: number): DetectionResult | undefined;
+         [Symbol.iterator](): Iterator<DetectionResult>;
+     }
 
-/**
- * Resize preserving aspect ratio, padding to `(targetWidth, targetHeight)`
- * with a constant fill color.
- *
- * Standard YOLO preprocessing — returning `scale` and `padLeft`/`padTop`
- * lets callers map detections back to the original image coordinates.
- */
-export declare function letterbox(image: RGBImage, targetWidth: number, targetHeight: number, fill?: readonly [number, number, number]): LetterboxResult;
+     /**
+      * Object detector for anchor-free YOLO ONNX models (v8/v9/v10/v11/v12).
+      *
+      * `predict()` returns `Promise<DetectionResults[]>` (length 1 for a single
+      * image), mirroring Ultralytics' `YOLO("img.jpg")`. Iterate the envelope for
+      * per-instance dataclasses, or use the bulk `boxes` view (`.xyxy`, `.xywh`,
+      * `.xyxyn`, `.xywhn`, `.cls`, `.conf`).
+      *
+      * @example
+      * ```typescript
+      * const det = await Detector.create("/models/yolov8n.onnx");
+      * const results = await det.predict("/images/street.jpg");
+      * const r = results[0];
+      * console.log(r.boxes.xyxy, r.boxes.cls, r.boxes.conf, r.names);
+      * for (const d of r) {
+      *   console.log(d.cls, d.conf, d.box.xyxy);
+      * }
+      * ```
+      */
+     export declare class Detector extends VisionTask {
+         private readonly _head;
+         private readonly _labels;
+         private readonly _names;
+         private readonly _inputSize;
+         private readonly _confThreshold;
+         private readonly _iouThreshold;
+         private readonly _maxDetections;
+         private readonly _raiseOnEmpty;
+         private constructor();
+         private _pipelineCache;
+         /**
+          * Run the model once on a zero-filled tensor, paying one-time costs up front.
+          *
+          * The first inference of a session is not representative: WebGPU compiles its
+          * shaders on it and the WASM backend faults in its arenas, which on a phone
+          * can turn the first frame into seconds while every later frame is tens of
+          * milliseconds. Calling this while a loading spinner is still up moves that
+          * cost somewhere the user is already waiting.
+          *
+          * @param runs How many warm-up inferences to run. One is enough for WASM;
+          *   WebGPU sometimes settles on the second.
+          */
+         warmup(runs?: number): Promise<void>;
+         /**
+          * The fused preprocessing pipeline, built on first use.
+          *
+          * Lazily, because constructing it allocates canvases: a task built in an
+          * environment without a canvas implementation stays constructible, and only
+          * fails if it is actually asked to preprocess something.
+          */
+         private get _pipeline();
+         /** Load the model and resolve labels. */
+         static create(model: ModelSource, options?: DetectorOptions): Promise<Detector>;
+         /** The decoder family used to interpret the model's output. */
+         get head(): DetectorHead;
+         /** Class labels indexed by class id. */
+         get labels(): readonly string[];
+         /** Class id → class name dict (matches Ultralytics' `model.names`). */
+         get names(): Readonly<Record<number, string>>;
+         /**
+          * The `[width, height]` this task preprocesses to.
+          *
+          * Resolved at creation time from the model's graph when it declares a static
+          * input, so reading it back tells you the resolution inference really runs at
+          * — not merely what was requested.
+          */
+         get inputSize(): readonly [number, number];
+         /** Number of classes the model predicts. */
+         get numClasses(): number;
+         /**
+          * Alias for {@link predict} — call the detector like a torch `nn.Module`.
+          *
+          * Use as `det.call(img)` since JavaScript class instances are not callable;
+          * for direct invocation, prefer `det.predict(img)`. The full
+          * {@link DetectorPredictOptions} (including `classes`) is supported.
+          */
+         call(image: ImageInput, options?: DetectorPredictOptions): Promise<DetectionResults[]>;
+         /**
+          * Run detection on a single image.
+          *
+          * The returned envelope carries a {@link Speed} breakdown in `speed`,
+          * mirroring Ultralytics' `results[0].speed`.
+          */
+         predict(image: ImageInput, options?: DetectorPredictOptions): Promise<DetectionResults[]>;
+         /**
+          * Letterbox and pack the image into the tensor the model expects.
+          *
+          * Runs through {@link LetterboxPipeline}, which fuses the resize, the
+          * padding and the HWC-to-CHW float conversion into one `drawImage` plus one
+          * readback loop, and reuses its output buffer between frames. The buffer is
+          * handed straight to ONNX Runtime, so {@link _pipeline.release} must not be
+          * called until the run resolves.
+          */
+         private _preprocess;
+         private _buildResult;
+         private _buildBoxes;
+     }
 
-export declare interface LetterboxResult {
-    /** The padded image at the target size. */
-    readonly image: RGBImage;
-    /** The factor applied to the original image (`< 1` if downscaled). */
-    readonly scale: number;
-    /** Horizontal padding in pixels (left side; right side has the same or +1). */
-    readonly padLeft: number;
-    /** Vertical padding in pixels (top side). */
-    readonly padTop: number;
-}
+     /**
+      * Decoder family for the model's detection head.
+      *
+      * - `"yolo"`: anchor-free YOLO head with output shape `[1, 4 + nc, N]` —
+      *   covers YOLOv8, v9, v10, v11, v12, v26 detect exports.
+      *
+      * The SDK does **not** auto-detect the head from the model — the caller is
+      * responsible for picking a head that matches their export. Future families
+      * (v5/v6/v7 with `[1, N, 5+nc]`) will be added as new literal members.
+      */
+     export declare type DetectorHead = "yolo";
 
-/**
- * Load an image from any supported source into a HWC uint8 RGB array.
- *
- * @throws {@link ImageLoadError} if the source cannot be decoded or has an unsupported shape.
-     */
- export declare function loadImage(source: ImageInput): Promise<RGBImage>;
+     export declare interface DetectorOptions extends OrtSessionOptions {
+         /**
+          * Decoder family for the detection head. Default `"yolo"` covers
+          * YOLOv8/v9/v10/v11/v12/v26.
+          */
+         readonly head?: DetectorHead;
+         /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */
+         readonly labels?: LabelSpec;
+         /** Number of classes — used to validate the supplied labels. */
+         readonly numClasses?: number;
+         /**
+          * Model input `[width, height]` in pixels for letterboxing.
+          *
+          * Only used when the model's graph leaves its spatial axes dynamic: a graph
+          * that declares a static size always wins, since that is the only shape ONNX
+          * Runtime will accept. Defaults to `[640, 640]`.
+          */
+         readonly inputSize?: readonly [number, number];
+         /** Default minimum class score to keep a candidate. */
+         readonly confThreshold?: number;
+         /** Default IoU threshold for non-maximum suppression. */
+         readonly iouThreshold?: number;
+         /** Maximum number of detections per image. */
+         readonly maxDetections?: number;
+         /**
+          * If `true`, a run that finds nothing throws {@link NoDetectionsError}
+          * instead of returning an empty envelope. Default `false`, because looking
+          * and finding nothing is a successful inference. Turn it on when an empty
+          * result means the surrounding pipeline should stop rather than carry on with
+          * zero rows. Can be overridden per `predict` call.
+          */
+         readonly raiseOnEmpty?: boolean;
+     }
+
+     export declare interface DetectorPredictOptions {
+         /** Override the default confidence threshold. */
+         readonly confThreshold?: number;
+         /** Override the default IoU threshold. */
+         readonly iouThreshold?: number;
+         /**
+          * If set, keep only detections whose `classId` is in this list.
+          * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.
+          */
+         readonly classes?: readonly number[];
+         /** Override the constructor's `raiseOnEmpty` setting for this call. */
+         readonly raiseOnEmpty?: boolean;
+     }
 
- /**
-  * Error raised when a captured frame is too dark to be analysed reliably.
-  * Carries the measured luminance and the threshold it failed so callers can
-  * surface actionable feedback.
-  */
- export declare class LowLuminanceError extends Error {
-     /** Measured mean luminance, `0..255`. */
-     readonly luminance: number;
-     /** Threshold that was checked against, `0..255`. */
-     readonly threshold: number;
      /**
-      * @param luminance - the measured mean luminance in `0..255`.
-      * @param threshold - the threshold the measurement failed to reach.
+      * Convert an HWC BGR uint8 buffer (OpenCV layout) to the SDK's HWC RGB.
+      *
+      * Use when you receive image bytes from `cv2.imencode` over the wire and
+      * want to feed them to the SDK without going through a canvas decode.
+      *
+      * @param bgr Flat BGR Uint8Array of length `width * height * 3`.
       */
-     constructor(luminance: number, threshold: number);
- }
+     export declare function fromCv2(bgr: Uint8Array, width: number, height: number): RGBImage;
+
+     /** Geometry of a letterbox, plus the planar tensor data it produced. */
+     export declare interface FusedLetterboxResult {
+         /** CHW float32 in `[0, 1]`, length `3 * targetHeight * targetWidth`. */
+         readonly data: Float32Array;
+         /** Factor applied to the original image (`< 1` if downscaled). */
+         readonly scale: number;
+         /** Horizontal padding in pixels. */
+         readonly padLeft: number;
+         /** Vertical padding in pixels. */
+         readonly padTop: number;
+         /**
+          * Whether {@link data} is the pipeline's reusable buffer.
+          *
+          * `true` means the next {@link LetterboxPipeline.run} overwrites it, so a
+          * caller keeping the values past its own inference has to copy them.
+          */
+         readonly reused: boolean;
+     }
 
- /**
-  * Longest edge (in pixels) the source is downsampled to before sampling.
-  * Averaging over a small downsample is statistically equivalent for a
-  * brightness threshold and orders of magnitude faster than reading every pixel
-  * of a full-resolution camera frame.
-  */
- export declare const LUMINANCE_SAMPLE_MAX_EDGE = 256;
+     /** Value of the `ovs.kind` metadata key for a detector→classifier pipeline. */
+     export declare const FUSION_KIND_DETECT_CLASSIFY = "detect_classify";
 
- /**
-  * Drawable source we can sample luminance from.
-  *
-  * The list tracks what `CanvasRenderingContext2D.drawImage` accepts and we can
-  * read a pixel size off, which is what the implementation actually needs.
-  * `ImageBitmap` matters for the decode-downscaled path: `createImageBitmap(blob,
-  * { resizeWidth })` is how a caller avoids materialising a full-resolution
-  * phone photo, and the frame it hands back is the frame whose brightness has to
-  * be checked.
-  */
- export declare type LuminanceSource = HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
-
- /**
-  * Single-channel binary or grayscale mask, laid out row-major.
-  *
-  * `data.length` must equal `width * height`. For binary masks, values are
-  * `0` (background) or `255` (foreground); soft masks may use the full
-  * `[0, 255]` range.
-  */
- export declare class Mask {
-     readonly data: Uint8Array;
-     readonly width: number;
-     readonly height: number;
-     constructor(data: Uint8Array, width: number, height: number);
- }
+     /**
+      * Raised when a model cannot be driven as a fused detect→classify pipeline.
+      *
+      * In the browser this means the file carries no `ovs.*` metadata — it is a
+      * plain detector or classifier rather than something `ort_vision_sdk.compose`
+      * produced — or the graph is missing an output the pipeline contract requires.
+      * Building a pipeline is a Python-side build step; the browser only runs one.
+      */
+     export declare class FusionError extends OrtVisionError {
+     }
+
+     /** Everything a fused pipeline declares about how it must be driven. */
+     export declare interface FusionSpec {
+         /** Pipeline family. Only `"detect_classify"` exists today. */
+         readonly kind: string;
+         /** `[width, height]` the detector stage expects — the resolution to letterbox to. */
+         readonly inputSize: readonly [number, number];
+         /** `[width, height]` every crop is resampled to inside the graph. */
+         readonly cropSize: readonly [number, number];
+         /** Which tensor the crops are taken from. */
+         readonly cropSource: CropSource;
+         /**
+          * Fixed number of rows `K` every output carries, surplus zero-padded and
+          * counted by {@link OUTPUT_NUM_DETECTIONS}. `null` means the graph emits
+          * exactly as many rows as survived NMS.
+          */
+         readonly maxDetections: number | null;
+         /** Score threshold baked into the graph's NMS node. */
+         readonly confThreshold: number;
+         /** IoU threshold baked into the graph's NMS node. */
+         readonly iouThreshold: number;
+         /** Whether the classifier stage emits logits that still need a softmax. */
+         readonly applySoftmax: boolean;
+         /** Detector class names in class-id order, or `null` when the fusion recorded none. */
+         readonly detectorNames: readonly string[] | null;
+         /** Classifier class names in class-id order, or `null`. */
+         readonly classifierNames: readonly string[] | null;
+         /** Version of `ort-vision-sdk` that produced the file. */
+         readonly sdkVersion: string;
+         /** Whether driving this pipeline requires feeding the full-resolution input. */
+         readonly needsSourceImage: boolean;
+     }
+
+     /** Anything {@link loadImage} accepts as an image input. */
+     export declare type ImageInput = string | Blob | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap | ImageData | RGBImage;
+
+     /** Raised when an input image cannot be decoded into the canonical format. */
+     export declare class ImageLoadError extends OrtVisionError {
+     }
+
+     /** Raised when ONNX Runtime fails while executing a model. */
+     export declare class InferenceError extends OrtVisionError {
+     }
+
+     /** Name of the fused graph's letterboxed detector input, `[1, 3, H, W]` float32 in `[0, 1]`. */
+     export declare const INPUT_IMAGE = "images";
+
+     /** Name of the `[2]` float32 `[padLeft, padTop]`. Only with `cropSource === "original"`. */
+     export declare const INPUT_PAD = "letterbox_pad";
+
+     /** Name of the `[1]` float32 letterbox scale factor. Only with `cropSource === "original"`. */
+     export declare const INPUT_SCALE = "letterbox_scale";
+
+     /** Name of the full-resolution input. Present only when `cropSource === "original"`. */
+     export declare const INPUT_SOURCE = "source_image";
 
- /**
-  * Per-instance binary masks for a single image.
-  *
-  * Each mask is cropped to its instance's bounding box. To paint masks onto
-  * a full-image canvas, use `xyxy[i]` as the top-left target.
-  */
- export declare class Masks {
-     readonly data: ReadonlyArray<{
-         readonly data: Uint8Array;
-         readonly width: number;
-         readonly height: number;
-     }>;
-     readonly xyxy: Float32Array;
-     readonly origShape: readonly [number, number];
      /**
-      * @param data Per-instance binary masks (`Mask` objects from `types.ts`).
-      * @param xyxy Flat `[N, 4]` of bounding-box coordinates in original pixels.
-      * @param origShape `[height, width]` of the original image.
+      * Whether a measured luminance clears a brightness threshold.
+      *
+      * `threshold` is intentionally required — a sensible value is
+      * application-specific (it depends on the model, the lighting the model was
+      * trained on, and the acceptable false-reject rate), so the SDK does not bake
+      * in a default.
+      *
+      * @param luminance - measured mean luminance in `0..255`.
+      * @param threshold - minimum acceptable luminance in `0..255`.
+      * @returns `true` when `luminance >= threshold`.
       */
-     constructor(data: ReadonlyArray<{
-         readonly data: Uint8Array;
-         readonly width: number;
-         readonly height: number;
-     }>, xyxy: Float32Array, origShape: readonly [number, number]);
-     /** Number of instance masks. */
-     get length(): number;
-     /** `[N]` shape of the masks collection. */
-     get shape(): readonly [number];
-     [Symbol.iterator](): Iterator<{
-         readonly data: Uint8Array;
-         readonly width: number;
-         readonly height: number;
-     }>;
- }
-
- /** Raised when an ONNX model cannot be loaded into an inference session. */
- export declare class ModelLoadError extends OrtVisionError {
- }
+     export declare function isLuminanceAcceptable(luminance: number, threshold: number): boolean;
 
- /**
-  * Read the class names an export baked into the model metadata.
-  *
-  * Ultralytics writes `names` as the Python `repr` of a `dict[int, str]` — e.g.
-  * `"{0: 'deworm', 1: 'not_deworm'}"`. The value is parsed structurally (never
-  * evaluated), and anything unparseable, non-`dict`, or not keyed by contiguous
-  * integers from zero is rejected whole rather than half-applied: a partial name
-  * map would silently mislabel predictions.
-  *
-  * @param metadata A model's custom metadata map.
-  * @returns Class names in class-id order, or `null` when the model carries no
-  *   usable `names` entry.
-  */
- export declare function modelNames(metadata: Readonly<Record<string, string>> | undefined): readonly string[] | null;
+     /** Raised when class labels cannot be resolved from the supplied spec. */
+     export declare class LabelMapError extends OrtVisionError {
+     }
 
- /** Anything `InferenceSession.create` accepts. */
- export declare type ModelSource = string | ArrayBufferLike | Uint8Array;
+     /** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
+     /**
+      * Class label resolution: presets, lists, dicts, or auto-generated.
+      *
+      * Tasks call {@link resolveLabels} once at construction time to turn whatever
+      * the caller passed (preset name, array, dict, or `null`) into an ordered
+      * array of class names indexed by class id.
+      *
+      * In the browser there is no filesystem, so this module does not load labels
+      * from a path — fetch the file yourself and pass an array.
+      */
+     /**
+      * Anything accepted by {@link resolveLabels}.
+      *
+      * - `string[]` / `readonly string[]`: explicit names indexed by class id.
+      * - `Record<number, string>`: sparse mapping (gaps filled with `class_<id>`).
+      * - `string`: a preset name (e.g. `"coco"`).
+      * - `null` / `undefined`: auto-generate `class_0` ... `class_{numClasses-1}`.
+      */
+     export declare type LabelSpec = readonly string[] | Record<number, string> | string | null | undefined;
 
- /**
-  * Greedy non-maximum suppression on axis-aligned bounding boxes.
-  *
-  * Mirrors `torchvision.ops.nms` (keeps boxes with the highest score, drops
-  * any subsequent box whose IoU exceeds the threshold).
-  *
-  * @param boxes Flat array of length `4 * N` in xyxy order: `[x1,y1,x2,y2, ...]`.
-  * @param scores Detection score per box, length `N`.
-  * @param iouThreshold Boxes with IoU above this threshold relative to a kept box are suppressed.
-  * @returns Indices of kept boxes, in descending score order.
-  */
- export declare function nms(boxes: Float32Array, scores: Float32Array, iouThreshold: number): Int32Array;
+     /**
+      * Resize preserving aspect ratio, padding to `(targetWidth, targetHeight)`
+      * with a constant fill color.
+      *
+      * Standard YOLO preprocessing — returning `scale` and `padLeft`/`padTop`
+      * lets callers map detections back to the original image coordinates.
+      */
+     export declare function letterbox(image: RGBImage, targetWidth: number, targetHeight: number, fill?: readonly [number, number, number]): LetterboxResult;
 
- /**
-  * Convert a uint8 image to a normalized float32 array (HWC layout preserved).
-  *
-  * Applies `(pixel * scale - mean) / std` channel-wise.
-  */
- export declare function normalize(image: RGBImage, mean: readonly [number, number, number], std: readonly [number, number, number], scale?: number): Float32Array;
+     /**
+      * Reusable letterbox → tensor pipeline for one target resolution.
+      *
+      * Holds a target canvas and an output buffer across calls, so a steady stream
+      * of frames at the same size allocates nothing. Create one per task, not per
+      * frame.
+      */
+     export declare class LetterboxPipeline {
+         private readonly _targetWidth;
+         private readonly _targetHeight;
+         private readonly _fill;
+         private readonly _target;
+         private readonly _targetContext;
+         private readonly _buffer;
+         private _source;
+         private _sourceContext;
+         private _bufferInUse;
+         /**
+          * @param targetWidth Model input width in pixels.
+          * @param targetHeight Model input height in pixels.
+          * @param fill RGB padding colour; defaults to YOLO grey.
+          */
+         constructor(targetWidth: number, targetHeight: number, fill?: readonly [number, number, number]);
+         /** The `[width, height]` this pipeline letterboxes into. */
+         get targetSize(): readonly [number, number];
+         /**
+          * Letterbox an image and write it as planar float32.
+          *
+          * The returned buffer is reused between calls unless a previous result is
+          * still checked out — {@link release} marks it free again. A second `run`
+          * before the first is released allocates a fresh buffer rather than
+          * corrupting it, so concurrent `predict()` calls on one task stay correct at
+          * the cost of the allocation they were trying to avoid.
+          *
+          * @param image Source image in the SDK's canonical HWC RGB layout.
+          */
+         run(image: RGBImage): FusedLetterboxResult;
+         /**
+          * Mark the reusable buffer free again.
+          *
+          * Call it once the tensor built from a {@link run} result has been handed to
+          * ONNX Runtime and the run has resolved — after that the values are inside
+          * the WASM heap and the buffer can be overwritten.
+          */
+         release(): void;
+         /**
+          * Grow the scratch source canvas to fit an image, reusing it when possible.
+          *
+          * A canvas is only reallocated when a frame arrives at a different size than
+          * the last one, which for a camera or video source is never after the first.
+          *
+          * @param width Source width in pixels.
+          * @param height Source height in pixels.
+          */
+         private _ensureSource;
+     }
+
+     export declare interface LetterboxResult {
+         /** The padded image at the target size. */
+         readonly image: RGBImage;
+         /** The factor applied to the original image (`< 1` if downscaled). */
+         readonly scale: number;
+         /** Horizontal padding in pixels (left side; right side has the same or +1). */
+         readonly padLeft: number;
+         /** Vertical padding in pixels (top side). */
+         readonly padTop: number;
+     }
 
- /**
-  * Wrap an ONNX Runtime Web `InferenceSession` with convenient metadata access.
-  *
-  * The wrapper exposes input/output names and the shapes the graph declares,
-  * manages execution-provider selection, provides a typed {@link OrtSession.run}
-  * method, and releases the native session through {@link OrtSession.release}.
-  */
- export declare class OrtSession {
-     private readonly _session;
-     readonly providers: readonly string[];
-     private readonly _metadata;
-     private constructor();
      /**
-      * Load an ONNX model into an ORT inference session.
+      * Letterbox an image into planar float32 without keeping any state.
       *
-      * The metadata map is read **before** the session is built, and that order is
-      * load-bearing on memory-constrained devices. ORT copies the model into its
-      * WASM heap and then allocates the graph and the weights on top of that copy;
-      * a `readModelMetadata` call placed after `InferenceSession.create` keeps the
-      * JavaScript-side buffer reachable across the whole build, so a 5 MB model
-      * costs 5 MB of JS heap plus 5 MB of WASM heap plus the weights at the same
-      * instant. Reading first makes the buffer collectable as soon as ORT has copied
-      * it — on a phone that was the difference between a session and
-      * `Can't create a session. failed to allocate a buffer of size N`.
+      * The allocation-free path is {@link LetterboxPipeline}; this is the one-shot
+      * form, for a caller who wants the fused behaviour without owning a pipeline.
       *
-      * @param model Either a URL string, or a `Uint8Array`/`ArrayBuffer` containing the model bytes.
-      * @param options Provider list, pass-through `SessionOptions`, and whether to
-      *   read the model's metadata map (see {@link OrtSessionOptions.readMetadata}).
-      * @throws {@link ModelLoadError} if the model cannot be loaded.
+      * @param image Source image in the SDK's canonical HWC RGB layout.
+      * @param targetWidth Model input width in pixels.
+      * @param targetHeight Model input height in pixels.
+      * @param fill RGB padding colour; defaults to YOLO grey.
+      */
+     export declare function letterboxToTensorData(image: RGBImage, targetWidth: number, targetHeight: number, fill?: readonly [number, number, number]): FusedLetterboxResult;
+
+     /**
+      * Load an image from any supported source into a HWC uint8 RGB array.
+      *
+      * @throws {@link ImageLoadError} if the source cannot be decoded or has an unsupported shape.
           */
-      static create(model: ModelSource, options?: OrtSessionOptions): Promise<OrtSession>;
-      /** Names of the model's inputs, in declaration order. */
-      get inputNames(): readonly string[];
-      /** Name of the first (and usually only) input. */
-      get inputName(): string;
-      /** Names of the model's outputs, in declaration order. */
-      get outputNames(): readonly string[];
-      /**
-       * Shapes the graph declares for its inputs, in declaration order.
-       *
-       * Dynamic (symbolic) axes appear as `null`. Empty shapes mean the runtime
-       * reported no metadata — either a non-tensor input, or an `onnxruntime-web`
-       * older than 1.21, which predates input metadata.
-       */
-      get inputShapes(): readonly DeclaredShape[];
+      export declare function loadImage(source: ImageInput): Promise<RGBImage>;
+
       /**
-       * Shape the graph declares for its first input, dynamic axes as `null`.
-       *
-       * Empty when the runtime reports no metadata for it.
+       * Error raised when a captured frame is too dark to be analysed reliably.
+       * Carries the measured luminance and the threshold it failed so callers can
+       * surface actionable feedback.
        */
-      get inputShape(): DeclaredShape;
+      export declare class LowLuminanceError extends Error {
+          /** Measured mean luminance, `0..255`. */
+          readonly luminance: number;
+          /** Threshold that was checked against, `0..255`. */
+          readonly threshold: number;
+          /**
+           * @param luminance - the measured mean luminance in `0..255`.
+           * @param threshold - the threshold the measurement failed to reach.
+           */
+          constructor(luminance: number, threshold: number);
+      }
+
       /**
-       * Shapes the graph declares for its outputs, in declaration order.
-       *
-       * Dynamic (symbolic) axes appear as `null`. Reading them is how a task can
-       * tell how many classes a head emits without being told.
+       * Longest edge (in pixels) the source is downsampled to before sampling.
+       * Averaging over a small downsample is statistically equivalent for a
+       * brightness threshold and orders of magnitude faster than reading every pixel
+       * of a full-resolution camera frame.
        */
-      get outputShapes(): readonly DeclaredShape[];
+      export declare const LUMINANCE_SAMPLE_MAX_EDGE = 256;
+
       /**
-       * Shape the graph declares for its first output, dynamic axes as `null`.
+       * Drawable source we can sample luminance from.
        *
-       * Empty when the runtime reports no metadata for it.
+       * The list tracks what `CanvasRenderingContext2D.drawImage` accepts and we can
+       * read a pixel size off, which is what the implementation actually needs.
+       * `ImageBitmap` matters for the decode-downscaled path: `createImageBitmap(blob,
+       * { resizeWidth })` is how a caller avoids materialising a full-resolution
+       * phone photo, and the frame it hands back is the frame whose brightness has to
+       * be checked.
        */
-      get outputShape(): DeclaredShape;
+      export declare type LuminanceSource = HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
+
       /**
-       * The model's custom metadata map — `names`, `task`, `imgsz`, ... for an
-       * Ultralytics export.
+       * Single-channel binary or grayscale mask, laid out row-major.
        *
-       * Read from the model's bytes at load time, since the runtime does not expose
-       * it. Empty when the session was created with `readMetadata: false`, from a
-       * URL that could not be fetched here, or from a model carrying no metadata.
+       * `data.length` must equal `width * height`. For binary masks, values are
+       * `0` (background) or `255` (foreground); soft masks may use the full
+       * `[0, 255]` range.
        */
-      get metadata(): Readonly<Record<string, string>>;
+      export declare class Mask {
+          readonly data: Uint8Array;
+          readonly width: number;
+          readonly height: number;
+          constructor(data: Uint8Array, width: number, height: number);
+      }
+
       /**
-       * Release the native session and free its memory.
+       * Per-instance binary masks for a single image.
        *
-       * Call it when a session is discarded while the page lives on — rebuilding a
-       * task at a different input size, swapping in a newer model. A failure from
-       * the runtime is ignored: a session being torn down has nothing left to fail
-       * at, and the caller is already moving on.
+       * Each mask is cropped to its instance's bounding box. To paint masks onto
+       * a full-image canvas, use `xyxy[i]` as the top-left target.
        */
-      release(): Promise<void>;
-      /** The underlying `onnxruntime-web` session, for advanced use cases. */
-      get raw(): ort.InferenceSession;
-      /**
-       * Run inference and return all outputs.
-       *
-       * @param feeds Map of input name to `ort.Tensor`. Keys must match {@link inputNames}.
-       * @throws {@link InferenceError} if ORT raises any error during execution.
-           */
-       run(feeds: Record<string, ort.Tensor>): Promise<Record<string, ort.Tensor>>;
-      }
-
-      export declare interface OrtSessionOptions {
-          /** Execution providers in preference order. `undefined` uses {@link DEFAULT_PROVIDERS}. */
-          readonly providers?: readonly string[];
-          /** Optional ORT session options forwarded to `InferenceSession.create`. */
-          readonly sessionOptions?: ort.InferenceSession.SessionOptions;
+      export declare class Masks {
+          readonly data: ReadonlyArray<{
+              readonly data: Uint8Array;
+              readonly width: number;
+              readonly height: number;
+          }>;
+          readonly xyxy: Float32Array;
+          readonly origShape: readonly [number, number];
           /**
-           * Whether to read the model's custom metadata map (`names`, `task`, `imgsz`).
-           * Defaults to `true`.
-           *
-           * The runtime does not expose that map, so it is read from the file itself —
-           * which means a URL model is fetched here and handed to ORT as bytes instead
-           * of letting ORT fetch it. That is the same single download either way, and
-           * it is what lets a task resolve its labels off the model. Set to `false` to
-           * keep the URL path untouched and leave {@link OrtSession.metadata} empty.
-           *
-           * `false` is also the escape hatch when a device cannot afford the bytes: the
-           * fetched buffer is dropped before ORT builds the graph (see
-           * {@link OrtSession.create}), but ORT's own load path still keeps the model out
-           * of reach of anything the SDK holds. A session built this way resolves its
-           * input size from the graph as usual — only the class names are lost, so a
-           * caller taking this route has to pass `labels` itself.
+           * @param data Per-instance binary masks (`Mask` objects from `types.ts`).
+           * @param xyxy Flat `[N, 4]` of bounding-box coordinates in original pixels.
+           * @param origShape `[height, width]` of the original image.
            */
-          readonly readMetadata?: boolean;
+          constructor(data: ReadonlyArray<{
+              readonly data: Uint8Array;
+              readonly width: number;
+              readonly height: number;
+          }>, xyxy: Float32Array, origShape: readonly [number, number]);
+          /** Number of instance masks. */
+          get length(): number;
+          /** `[N]` shape of the masks collection. */
+          get shape(): readonly [number];
+          [Symbol.iterator](): Iterator<{
+              readonly data: Uint8Array;
+              readonly width: number;
+              readonly height: number;
+          }>;
       }
 
       /**
-       * Exceptions raised by the SDK.
+       * Namespace for every metadata key the fusion writes.
        *
-       * All exceptions inherit from {@link OrtVisionError}, so callers can catch
-       * the base class to handle any SDK-originated failure uniformly.
+       * Namespaced on purpose: the detector's own Ultralytics metadata (`names`,
+       * `task`, `imgsz`) is carried over into the fused model, and an un-prefixed key
+       * would either collide with it or be mistaken for it.
        */
-      export declare class OrtVisionError extends Error {
-          constructor(message: string, options?: ErrorOptions);
+      export declare const METADATA_PREFIX = "ovs.";
+
+      /** Raised when an ONNX model cannot be loaded into an inference session. */
+      export declare class ModelLoadError extends OrtVisionError {
       }
 
       /**
-       * Top-k classification probabilities for a single image.
+       * Read the class names an export baked into the model metadata.
+       *
+       * Ultralytics writes `names` as the Python `repr` of a `dict[int, str]` — e.g.
+       * `"{0: 'deworm', 1: 'not_deworm'}"`. The value is parsed structurally (never
+       * evaluated), and anything unparseable, non-`dict`, or not keyed by contiguous
+       * integers from zero is rejected whole rather than half-applied: a partial name
+       * map would silently mislabel predictions.
        *
-       * Mirrors Ultralytics' `Probs` interface.
+       * @param metadata A model's custom metadata map.
+       * @returns Class names in class-id order, or `null` when the model carries no
+       *   usable `names` entry.
        */
-      export declare class Probs {
-          readonly data: Float32Array;
-          /** @param data `[numClasses]` per-class probabilities, indexed by class id. */
-          constructor(data: Float32Array);
-          /** Number of classes. */
-          get length(): number;
-          /** `[numClasses]` shape of the underlying vector. */
-          get shape(): readonly [number];
-          /** Index of the most probable class. */
-          get top1(): number;
-          /** Probability of the top-1 class. */
-          get top1conf(): number;
-          /** Indices of the top-5 most probable classes, descending. */
-          get top5(): Int32Array;
-          /** Probabilities of the top-5 classes, descending. */
-          get top5conf(): Float32Array;
-          private _topK;
-      }
+      export declare function modelNames(metadata: Readonly<Record<string, string>> | undefined): readonly string[] | null;
 
-      /** Raised when a requested execution provider is not available. */
-      export declare class ProviderNotAvailableError extends OrtVisionError {
-      }
+      /** Anything `InferenceSession.create` accepts. */
+      export declare type ModelSource = string | ArrayBufferLike | Uint8Array;
 
       /**
-       * Read the metadata an exporter baked into a `.onnx` file.
+       * Greedy non-maximum suppression on axis-aligned bounding boxes.
        *
-       * `onnxruntime-web` exposes input/output metadata but **not** the model's
-       * custom metadata map, which is where Ultralytics writes `names`, `task` and
-       * `imgsz`. The Python SDK gets it for free from
-       * `InferenceSession.get_modelmeta().custom_metadata_map`; in the browser the
-       * only way to the same information is to read it out of the file, so this
-       * module walks just enough of the ModelProto wire format to collect
-       * `metadata_props`.
+       * Mirrors `torchvision.ops.nms` (keeps boxes with the highest score, drops
+       * any subsequent box whose IoU exceeds the threshold).
        *
-       * It never throws and never allocates unbounded: a truncated, hostile or
-       * simply unexpected file yields an empty map, and every caller treats that as
-       * "the model says nothing", falling back to what it was given.
+       * @param boxes Flat array of length `4 * N` in xyxy order: `[x1,y1,x2,y2, ...]`.
+       * @param scores Detection score per box, length `N`.
+       * @param iouThreshold Boxes with IoU above this threshold relative to a kept box are suppressed.
+       * @returns Indices of kept boxes, in descending score order. Boxes tied on
+       *   score are visited lowest-index first, so the survivor of a tie is
+       *   deterministic and matches both `torchvision` and the Python SDK.
        */
-      /**
-       * Collect a model's custom metadata map straight out of its bytes.
-       *
-       * @param model The `.onnx` file contents.
-       * @returns Key/value metadata — `names`, `task`, `imgsz`, ... for an
-       *   Ultralytics export — or an empty object when the file carries none or
-       *   cannot be walked.
-       */
-      export declare function readModelMetadata(model: Uint8Array | ArrayBufferLike): Readonly<Record<string, string>>;
-
-      /** Resize an image to `(targetWidth, targetHeight)` using high-quality canvas resampling. */
-      export declare function resize(image: RGBImage, targetWidth: number, targetHeight: number): RGBImage;
+      export declare function nms(boxes: Float32Array, scores: Float32Array, iouThreshold: number): Int32Array;
 
       /**
-       * Decide the input size a task will preprocess to.
+       * Raised when a detection task finds nothing and was asked to treat that as an error.
        *
-       * Precedence is graph → caller → fallback. The graph wins over an explicit
-       * `inputSize` because a static shape is not a preference, it is what ORT will
-       * accept: honoring the caller there would only turn a fixable mismatch into a
-       * failed run. A disagreement is a configuration bug in the caller, so it is
-       * reported through `console.warn` instead of being swallowed.
+       * Only raised when the caller opts in with `raiseOnEmpty: true`. The default
+       * stays an empty result, because "the model looked and found nothing" is a
+       * successful inference, not a failure — a photo of an empty field is a valid
+       * photo. What the flag is for is the opposite situation: a pipeline step whose
+       * *precondition* is that something is there, where an empty result means the
+       * caller should stop rather than quietly carry on with zero rows.
        *
-       * @param options Graph shape, requested size and per-task fallback.
-       * @returns The `[width, height]` to preprocess to.
+       * "Nothing was detected" and "nothing was confident enough" are the same
+       * condition here, since the confidence threshold is what decides what counts as
+       * a detection in the first place.
        */
-      export declare function resolveInputSize(options: ResolveInputSizeOptions): readonly [number, number];
-
-      export declare interface ResolveInputSizeOptions {
-          /** Declared shape of the model's image input, from {@link declaredShapesFrom}. */
-          readonly graphShape?: DeclaredShape;
-          /** Size the caller asked for, if any. */
-          readonly requested?: readonly [number, number];
-          /** Size to use when neither the graph nor the caller pins one. */
-          readonly fallback: readonly [number, number];
+      export declare class NoDetectionsError extends OrtVisionError {
       }
 
       /**
-       * Resolve a labels specification into an ordered array of class names.
+       * Convert a uint8 image to a normalized float32 array (HWC layout preserved).
        *
-       * @throws {@link LabelMapError} if the spec is invalid, the preset is unknown,
-           *   or the resolved length disagrees with `numClasses`.
-           */
-       export declare function resolveLabels(spec: LabelSpec, options?: ResolveLabelsOptions): readonly string[];
+       * Applies `(pixel * scale - mean) / std` channel-wise.
+       */
+      export declare function normalize(image: RGBImage, mean: readonly [number, number, number], std: readonly [number, number, number], scale?: number): Float32Array;
 
-       export declare interface ResolveLabelsOptions {
+      /**
+       * Wrap an ONNX Runtime Web `InferenceSession` with convenient metadata access.
+       *
+       * The wrapper exposes input/output names and the shapes the graph declares,
+       * manages execution-provider selection, provides a typed {@link OrtSession.run}
+       * method, and releases the native session through {@link OrtSession.release}.
+       */
+      export declare class OrtSession {
+          private readonly _session;
+          readonly providers: readonly string[];
+          private readonly _metadata;
+          private constructor();
+          /**
+           * Load an ONNX model into an ORT inference session.
+           *
+           * The metadata map is read **before** the session is built, and that order is
+           * load-bearing on memory-constrained devices. ORT copies the model into its
+           * WASM heap and then allocates the graph and the weights on top of that copy;
+           * a `readModelMetadata` call placed after `InferenceSession.create` keeps the
+           * JavaScript-side buffer reachable across the whole build, so a 5 MB model
+           * costs 5 MB of JS heap plus 5 MB of WASM heap plus the weights at the same
+           * instant. Reading first makes the buffer collectable as soon as ORT has copied
+           * it — on a phone that was the difference between a session and
+           * `Can't create a session. failed to allocate a buffer of size N`.
+           *
+           * @param model Either a URL string, or a `Uint8Array`/`ArrayBuffer` containing the model bytes.
+           * @param options Provider list, pass-through `SessionOptions`, and whether to
+           *   read the model's metadata map (see {@link OrtSessionOptions.readMetadata}).
+           * @throws {@link ModelLoadError} if the model cannot be loaded.
+               */
+           static create(model: ModelSource, options?: OrtSessionOptions): Promise<OrtSession>;
+           /** Names of the model's inputs, in declaration order. */
+           get inputNames(): readonly string[];
+           /** Name of the first (and usually only) input. */
+           get inputName(): string;
+           /** Names of the model's outputs, in declaration order. */
+           get outputNames(): readonly string[];
            /**
-            * Expected number of classes.
+            * Shapes the graph declares for its inputs, in declaration order.
             *
-            * - When `spec` is `null`/`undefined`, this is required to auto-generate names.
-            * - When `spec` is provided, it validates that the resolved length matches.
+            * Dynamic (symbolic) axes appear as `null`. Empty shapes mean the runtime
+            * reported no metadata — either a non-tensor input, or an `onnxruntime-web`
+            * older than 1.21, which predates input metadata.
             */
-           readonly numClasses?: number;
-       }
-
-       /**
-        * Resolve the execution providers to pass to `InferenceSession.create`.
-        *
-        * @param requested Explicit provider list in preference order; `undefined` returns the default.
-        */
-       export declare function resolveProviders(requested?: readonly string[]): string[];
-
-       /**
-        * Public output types returned by the SDK's vision tasks.
-        *
-        * These types form the contract between the SDK and its callers. They mirror
-        * the Python `ort-vision-sdk` output dataclasses 1-to-1.
-        *
-        * Naming is intentionally compatible with the Ultralytics / torchvision idiom
-        * (`cls`, `conf`, `box`, `xyxy`, `xywh`, normalized variants) so code ported
-        * from those projects keeps working with minimal edits. The original verbose
-        * names (`classId`, `className`, `confidence`, `bbox`) are still populated for
-        * backwards compatibility.
-        */
-       /**
-        * HWC RGB uint8 image — the canonical image format used across the SDK.
-        *
-        * `data.length` must equal `width * height * 3`. The buffer is laid out row
-        * by row, top-to-bottom, with each pixel as `[R, G, B]`.
-        */
-       export declare class RGBImage {
-           readonly data: Uint8Array;
-           readonly width: number;
-           readonly height: number;
-           constructor(data: Uint8Array, width: number, height: number);
-       }
-
-       /**
-        * Single segmented instance produced by an instance-segmentation model.
-        *
-        * Mirrors {@link DetectionResult} and adds the per-instance binary mask
-        * plus a "ready-to-display" background-removed crop.
-        */
-       export declare interface SegmentationResult {
-           readonly classId: number;
-           readonly className: string;
-           readonly confidence: number;
-           readonly bbox: BoundingBox;
-           /** Alias for `classId` (Ultralytics-style). */
-           readonly cls: number;
-           /** Alias for `className`. */
-           readonly name: string;
-           /** Alias for `confidence` (Ultralytics-style). */
-           readonly conf: number;
-           /** Alias for `bbox` (Ultralytics-style). */
-           readonly box: BoundingBox;
+           get inputShapes(): readonly DeclaredShape[];
            /**
-            * Binary mask cropped to `bbox`. Values are `0` (background) or `255`
-            * (foreground). Empty boxes yield a zero-sized `Mask`.
+            * Shape the graph declares for its first input, dynamic axes as `null`.
+            *
+            * Empty when the runtime reports no metadata for it.
             */
-           readonly mask: Mask;
+           get inputShape(): DeclaredShape;
            /**
-            * The original image cropped to `bbox` with background pixels (where
-            * `mask.data[i] === 0`) zeroed out. Empty boxes yield a zero-sized
-            * `RGBImage`.
+            * Shapes the graph declares for its outputs, in declaration order.
+            *
+            * Dynamic (symbolic) axes appear as `null`. Reading them is how a task can
+            * tell how many classes a head emits without being told.
             */
-           readonly segmentedImage: RGBImage;
-       }
-
-       /**
-        * Per-image instance-segmentation envelope (Ultralytics-style `Results`).
-        *
-        * Iterating yields per-instance {@link SegmentationResult} entries. `boxes`
-        * and `masks` mirror Ultralytics' bulk-array views.
-        */
-       export declare class SegmentationResults implements Iterable<SegmentationResult> {
-           readonly boxes: Boxes;
-           readonly masks: Masks;
-           readonly detections: readonly SegmentationResult[];
-           readonly names: Readonly<Record<number, string>>;
-           readonly origImg: RGBImage;
-           readonly origShape: readonly [number, number];
-           readonly path: string | null;
-           readonly speed: Readonly<Speed>;
-           constructor(boxes: Boxes, masks: Masks, detections: readonly SegmentationResult[], names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Speed>);
-           /** Number of surviving instances. */
-           get length(): number;
-           /** Index into the per-instance results. */
-           get(index: number): SegmentationResult | undefined;
-           [Symbol.iterator](): Iterator<SegmentationResult>;
-       }
-
-       /**
-        * Instance segmenter for YOLO seg ONNX models (v8-seg / v11-seg / ...).
-        *
-        * The model is expected to expose two outputs:
-        *
-        * 1. `output0`: `(1, 4 + numClasses + numMaskCoefs, numAnchors)` — per-anchor
-        *    predictions (boxes, class scores, mask coefficients).
-        * 2. `output1`: `(1, numMaskCoefs, maskH, maskW)` — prototype masks.
-        *
-        * `predict()` returns `Promise<SegmentationResults[]>` (length 1 for a
-        * single image), mirroring Ultralytics' API. The envelope exposes:
-        *
-        * - `boxes`: bulk numpy view (`xyxy`, `xywh`, `xyxyn`, `xywhn`, `cls`, `conf`).
-        * - `masks`: per-instance binary masks cropped to each box.
-        * - per-instance {@link SegmentationResult} via iteration.
-        *
-        * @example
-        * ```typescript
-        * const seg = await Segmenter.create("/models/yolov8n-seg.onnx");
-        * const r = (await seg.predict("/images/street.jpg"))[0];
-        * for (const inst of r) {
-        *   console.log(inst.cls, inst.conf, inst.box.xyxy);
-        * }
-        * ```
-        */
-       export declare class Segmenter extends VisionTask {
-           private readonly _head;
-           private readonly _labels;
-           private readonly _names;
-           private readonly _inputSize;
-           private readonly _confThreshold;
-           private readonly _iouThreshold;
-           private readonly _maxDetections;
-           private readonly _maskThreshold;
-           private constructor();
-           /** Load the model and resolve labels. */
-           static create(model: ModelSource, options?: SegmenterOptions): Promise<Segmenter>;
-           /** The decoder family used to interpret the model's output. */
-           get head(): SegmenterHead;
-           /** Class labels indexed by class id. */
-           get labels(): readonly string[];
-           /** Class id → class name dict (matches Ultralytics' `model.names`). */
-           get names(): Readonly<Record<number, string>>;
+           get outputShapes(): readonly DeclaredShape[];
            /**
-            * The `[width, height]` this task preprocesses to.
+            * Shape the graph declares for its first output, dynamic axes as `null`.
             *
-            * Resolved at creation time from the model's graph when it declares a static
-            * input, so reading it back tells you the resolution inference really runs at
-            * — not merely what was requested.
+            * Empty when the runtime reports no metadata for it.
             */
-           get inputSize(): readonly [number, number];
-           /** Number of classes the model predicts. */
-           get numClasses(): number;
-           /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
-           call(image: ImageInput, options?: SegmenterPredictOptions): Promise<SegmentationResults[]>;
-           /** Run instance segmentation on a single image. */
-           predict(image: ImageInput, options?: SegmenterPredictOptions): Promise<SegmentationResults[]>;
-           private _preprocess;
-           private _splitOutputs;
-           private _buildResult;
-           private _buildBoxes;
-           private _buildMasks;
-       }
-
-       /**
-        * Decoder family for the segmentation head.
-        *
-        * - `"yolo-seg"`: YOLO instance-segmentation head with two outputs —
-        *   `[1, 4 + nc + nm, N]` per-anchor predictions plus `[1, nm, mh, mw]`
-        *   prototype masks. Covers YOLOv8-seg, v11-seg, v26-seg.
-        *
-        * The SDK does **not** auto-detect this — the caller is responsible for
-        * picking a head that matches their export.
-        */
-       export declare type SegmenterHead = "yolo-seg";
-
-       export declare interface SegmenterOptions extends OrtSessionOptions {
+           get outputShape(): DeclaredShape;
            /**
-            * Decoder family for the segmentation head. Default `"yolo-seg"` covers
-            * YOLOv8-seg/v11-seg/v26-seg.
+            * The model's custom metadata map — `names`, `task`, `imgsz`, ... for an
+            * Ultralytics export.
+            *
+            * Read from the model's bytes at load time, since the runtime does not expose
+            * it. Empty when the session was created with `readMetadata: false`, from a
+            * URL that could not be fetched here, or from a model carrying no metadata.
             */
-           readonly head?: SegmenterHead;
-           /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */
-           readonly labels?: LabelSpec;
-           /** Number of classes — used to validate the supplied labels. */
-           readonly numClasses?: number;
+           get metadata(): Readonly<Record<string, string>>;
            /**
-            * Model input `[width, height]` in pixels for letterboxing.
+            * Release the native session and free its memory.
             *
-            * Only used when the model's graph leaves its spatial axes dynamic: a graph
-            * that declares a static size always wins, since that is the only shape ONNX
-            * Runtime will accept. Defaults to `[640, 640]`.
+            * Call it when a session is discarded while the page lives on — rebuilding a
+            * task at a different input size, swapping in a newer model. A failure from
+            * the runtime is ignored: a session being torn down has nothing left to fail
+            * at, and the caller is already moving on.
             */
-           readonly inputSize?: readonly [number, number];
-           /** Default minimum class score to keep a candidate. */
-           readonly confThreshold?: number;
-           /** Default IoU threshold for non-maximum suppression. */
-           readonly iouThreshold?: number;
-           /** Maximum number of instances per image. */
-           readonly maxDetections?: number;
-           /** Probability cutoff applied to soft masks. Defaults to `0.5`. */
-           readonly maskThreshold?: number;
-       }
-
-       export declare interface SegmenterPredictOptions {
-           readonly confThreshold?: number;
-           readonly iouThreshold?: number;
+           release(): Promise<void>;
+           /** The underlying `onnxruntime-web` session, for advanced use cases. */
+           get raw(): ort.InferenceSession;
+           /**
+            * Run inference and return all outputs.
+            *
+            * @param feeds Map of input name to `ort.Tensor`. Keys must match {@link inputNames}.
+            * @throws {@link InferenceError} if ORT raises any error during execution.
+                */
+            run(feeds: Record<string, ort.Tensor>): Promise<Record<string, ort.Tensor>>;
+           }
+
+           export declare interface OrtSessionOptions {
+               /** Execution providers in preference order. `undefined` uses {@link DEFAULT_PROVIDERS}. */
+               readonly providers?: readonly string[];
+               /** Optional ORT session options forwarded to `InferenceSession.create`. */
+               readonly sessionOptions?: ort.InferenceSession.SessionOptions;
+               /**
+                * Whether to read the model's custom metadata map (`names`, `task`, `imgsz`).
+                * Defaults to `true`.
+                *
+                * The runtime does not expose that map, so it is read from the file itself —
+                * which means a URL model is fetched here and handed to ORT as bytes instead
+                * of letting ORT fetch it. That is the same single download either way, and
+                * it is what lets a task resolve its labels off the model. Set to `false` to
+                * keep the URL path untouched and leave {@link OrtSession.metadata} empty.
+                *
+                * `false` is also the escape hatch when a device cannot afford the bytes: the
+                * fetched buffer is dropped before ORT builds the graph (see
+                * {@link OrtSession.create}), but ORT's own load path still keeps the model out
+                * of reach of anything the SDK holds. A session built this way resolves its
+                * input size from the graph as usual — only the class names are lost, so a
+                * caller taking this route has to pass `labels` itself.
+                */
+               readonly readMetadata?: boolean;
+           }
+
+           /** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
            /**
-            * If set, keep only instances whose `classId` is in this list.
-            * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.
+            * Exceptions raised by the SDK.
+            *
+            * All exceptions inherit from {@link OrtVisionError}, so callers can catch
+            * the base class to handle any SDK-originated failure uniformly.
             */
-           readonly classes?: readonly number[];
-       }
-
-       /**
-        * Classification head postprocessing — softmax + top-k.
-        */
-       /** Apply numerically-stable softmax to a 1-D vector of logits. */
-       export declare function softmax(logits: Float32Array | readonly number[]): Float32Array;
-
-       /**
-        * Read the spatial input size out of a declared NCHW shape.
-        *
-        * @param shape The declared shape of the model's image input.
-        * @returns `[width, height]` in pixels, or `null` when the shape is not 4D or
-        *   leaves either spatial axis dynamic — in which case the model accepts more
-        *   than one resolution and there is nothing to correct.
-        */
-       export declare function spatialInputSize(shape: DeclaredShape): readonly [number, number] | null;
-
-       /**
-        * Per-stage timing for a single `predict()` call.
-        *
-        * Populates the `speed` field every `Results` envelope carries, mirroring
-        * Ultralytics' `results[0].speed`. All values are milliseconds measured with
-        * `performance.now()`.
-        */
-       /**
-        * Stage durations of one inference, in milliseconds.
-        *
-        * `preprocess`, `inference` and `postprocess` are the three keys Ultralytics
-        * reports, measured over the same boundaries. `load` is specific to this SDK:
-        * `predict()` accepts a URL, `Blob` or DOM element and decodes it internally,
-        * so the fetch/decode cost would otherwise be invisible — and on a cold cache
-        * it dominates everything else.
-        */
-       export declare interface Speed {
-           /** Fetching and decoding the input into an `RGBImage`. */
-           load: number;
-           /** Letterbox/resize, normalization and tensor packing. */
-           preprocess: number;
-           /** The ONNX Runtime forward pass. */
-           inference: number;
-           /** Decoding raw outputs into results (NMS, mask assembly, top-k). */
-           postprocess: number;
-       }
-
-       /**
-        * Accumulate stage durations while a `predict()` call runs.
-        *
-        * Each `stage()` call closes the previous stage: the elapsed time since the
-        * last boundary is attributed to the name given. This keeps the call sites
-        * free of paired start/stop bookkeeping and guarantees the four stages tile
-        * the whole call without gaps.
-        */
-       export declare class SpeedTimer {
-           private _last;
-           private readonly _speed;
-           constructor();
+           export declare class OrtVisionError extends Error {
+               constructor(message: string, options?: ErrorOptions);
+           }
+
+           /** Name of the `[K, 4]` float32 xyxy output, in **letterboxed** input pixels. */
+           export declare const OUTPUT_BOXES = "boxes";
+
+           /** Name of the `[K]` int64 detector-class output. */
+           export declare const OUTPUT_CLASSES = "classes";
+
+           /** Name of the `[1]` int64 output holding how many of the `K` rows are real. */
+           export declare const OUTPUT_NUM_DETECTIONS = "num_detections";
+
+           /** Name of the `[K, numClassifierClasses]` float32 classifier output, one row per box. */
+           export declare const OUTPUT_PROBS = "probs";
+
+           /** Name of the `[K]` float32 detection-confidence output. */
+           export declare const OUTPUT_SCORES = "scores";
+
            /**
-            * Attribute the time elapsed since the previous boundary to `stage`.
+            * Parse a `repr`-encoded `dict[int, str]` class map.
             *
-            * @param stage Which stage just finished.
+            * Split out of {@link modelNames} because the same encoding is reused by a
+            * fused pipeline, which carries one class map per stage and therefore cannot
+            * store both under the single `names` key Ultralytics uses.
+            *
+            * @param encoded The encoded map — e.g. `"{0: 'deworm', 1: 'not_deworm'}"`.
+            * @returns Class names in class-id order, or `null` when the value is missing,
+            *   unparseable, not a `dict`, or not keyed by contiguous integers from zero.
             */
-           stage(stage: keyof Speed): void;
+           export declare function parseNames(encoded: string | undefined): readonly string[] | null;
+
            /**
-            * The accumulated durations.
+            * Top-k classification probabilities for a single image.
             *
-            * @returns The `speed` object to hand to the `Results` envelope.
+            * Mirrors Ultralytics' `Probs` interface.
             */
-           speed(): Speed;
-       }
-
-       /**
-        * Transpose interleaved HWC data to planar CHW layout.
-        *
-        * @param hwc Source array of length `width * height * channels`.
-        */
-       export declare function toCHW(hwc: Float32Array, width: number, height: number, channels?: number): Float32Array;
-
-       /**
-        * Convert the SDK's HWC RGB image to an HWC BGR `Uint8Array` (OpenCV layout).
-        *
-        * Useful for round-tripping data to a Python OpenCV consumer.
-        */
-       export declare function toCv2(image: RGBImage): Uint8Array;
-
-       /** Convert a uint8 image to a `Float32Array` in `[0, 1]` (HWC layout preserved). */
-       export declare function toFloat32(image: RGBImage, scale?: number): Float32Array;
-
-       /** Wrap a Float32 buffer into an `ort.Tensor`. */
-       export declare function toFloat32Tensor(data: Float32Array, dims: readonly number[]): ort.Tensor;
-
-       /**
-        * Return the top-k entries of a 1-D probability vector, sorted descending.
-        *
-        * @param k Number of entries to return; `null` returns all entries.
-        */
-       export declare function topK(probabilities: Float32Array, k: number | null): TopKResult;
-
-       export declare interface TopKResult {
-           readonly indices: Int32Array;
-           readonly values: Float32Array;
-       }
-
-       /**
-        * Convert an HWC uint8 image to a CHW `Float32Array` scaled to `[0, 1]`.
-        *
-        * Mirrors `torchvision.transforms.ToTensor()` semantics: HWC → CHW,
-        * `uint8 → float32 / 255`. Useful as input to YOLO-style detectors that
-        * don't require ImageNet normalization.
-        *
-        * @returns CHW `Float32Array` of length `width * height * 3`.
-        */
-       export declare function toTensor(image: RGBImage): Float32Array;
-
-       /**
-        * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,
-        * and expose status/error so the page can render permission and error states.
-        * The stream is automatically released on unmount or retry.
-        *
-        * Defaults to the rear ("environment") camera; desktops fall back to whatever
-        * single camera they expose. Pass `options.constraints` to override, or
-        * `options.enabled: false` to render the surface without prompting for the camera
-        * at all.
-        *
-        * Implementation notes:
-        * - Cleanup detaches the stream from a *snapshotted* video node, so it releases
-        *   the same element it attached to even if the page remounts the `<video>`.
-        * - When `getUserMedia` is missing, an insecure context is the usual cause, so
-        *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.
-        * - `video.play()` rejections are swallowed: autoplay may be blocked, but the
-        *   user gesture that opened the camera usually counts and playback resumes on
-        *   the next interaction.
-        *
-        * @param options - optional configuration (see {@link UseCameraStreamOptions}).
-        * @returns The stream status, classified error, a `videoRef` to attach, the live
-        *   `stream` for whatever needs the track itself, and a `retry()` to re-attempt
-        *   acquisition.
-        */
-       export declare function useCameraStream(options?: UseCameraStreamOptions): UseCameraStreamApi;
-
-       /** Value returned by {@link useCameraStream}. */
-       export declare interface UseCameraStreamApi {
-           /** Current lifecycle status. */
-           status: CameraStreamStatus;
-           /** The classified error, or `null` while not in the `error` status. */
-           error: CameraStreamError | null;
-           /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */
-           videoRef: RefObject<HTMLVideoElement | null>;
+           export declare class Probs {
+               readonly data: Float32Array;
+               /** @param data `[numClasses]` per-class probabilities, indexed by class id. */
+               constructor(data: Float32Array);
+               /** Number of classes. */
+               get length(): number;
+               /** `[numClasses]` shape of the underlying vector. */
+               get shape(): readonly [number];
+               /** Index of the most probable class. */
+               get top1(): number;
+               /** Probability of the top-1 class. */
+               get top1conf(): number;
+               /** Indices of the top-5 most probable classes, descending. */
+               get top5(): Int32Array;
+               /** Probabilities of the top-5 classes, descending. */
+               get top5conf(): Float32Array;
+               private _topK;
+           }
+
+           /** Raised when a requested execution provider is not available. */
+           export declare class ProviderNotAvailableError extends OrtVisionError {
+           }
+
            /**
-            * The live stream, or `null`.
+            * Read a pipeline spec out of a model's custom metadata.
             *
-            * Exposed for the things that need the **track** rather than the picture — the LED
-            * torch (`useTorch`), the real frame size from `getSettings()`, recording it with
-            * `useVideoRecorder`. Do not stop it yourself: the hook owns its lifetime and
-            * releases it on unmount and on `retry()`.
+            * Individual malformed entries fall back to the value a fusion would have used
+            * by default — a single bad float is not a reason to reject an otherwise
+            * loadable pipeline. A malformed resolution is fatal, because there is no safe
+            * default for one.
+            *
+            * @param metadata A model's custom metadata map, as read by
+            *   {@link readModelMetadata}.
+            * @returns The decoded spec, or `null` when the model is not a fused pipeline —
+            *   it carries no `ovs.kind` entry, or one naming a pipeline kind this version
+            *   does not know how to drive.
             */
-           stream: MediaStream | null;
-           /** Manually re-attempt after an error (e.g. the user changed permissions). */
-           retry: () => void;
-       }
+           export declare function readFusionSpec(metadata: Readonly<Record<string, string>> | undefined): FusionSpec | null;
 
-       /** Options for {@link useCameraStream}. */
-       export declare interface UseCameraStreamOptions {
+           /** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
            /**
-            * Constraints passed to `getUserMedia`. Defaults to the rear
-            * ("environment") camera at Full-HD ideal resolution with audio off.
-            * Read when the stream (re)starts — change it and call `retry()` to apply.
+            * Read the metadata an exporter baked into a `.onnx` file.
+            *
+            * `onnxruntime-web` exposes input/output metadata but **not** the model's
+            * custom metadata map, which is where Ultralytics writes `names`, `task` and
+            * `imgsz`. The Python SDK gets it for free from
+            * `InferenceSession.get_modelmeta().custom_metadata_map`; in the browser the
+            * only way to the same information is to read it out of the file, so this
+            * module walks just enough of the ModelProto wire format to collect
+            * `metadata_props`.
+            *
+            * It never throws and never allocates unbounded: a truncated, hostile or
+            * simply unexpected file yields an empty map, and every caller treats that as
+            * "the model says nothing", falling back to what it was given.
             */
-           constraints?: MediaStreamConstraints;
            /**
-            * Hold off acquiring the camera until this is `true`. Default `true`.
+            * Collect a model's custom metadata map straight out of its bytes.
             *
-            * The point is to be able to *not* prompt. A permission prompt costs the user a
-            * decision and, if they refuse, costs the app the feature permanently — so a
-            * surface that already knows it cannot do its job (a barcode scanner in a browser
-            * with no decoder) must not open the camera to then say so. Flipping this to `false`
-            * also releases a stream that is already live.
+            * @param model The `.onnx` file contents.
+            * @returns Key/value metadata — `names`, `task`, `imgsz`, ... for an
+            *   Ultralytics export — or an empty object when the file carries none or
+            *   cannot be walked.
             */
-           enabled?: boolean;
-       }
-
-       /**
-        * Sample mean luminance from a `<video>` source on a `requestAnimationFrame`
-        * loop and expose the rolling value. Sampling is throttled by `intervalMs` and
-        * paused whenever `enabled` is `false` or the video is not ready yet
-        * (`readyState < 2` or `videoWidth === 0`).
-        *
-        * One offscreen canvas is reused across frames to avoid GC pressure. Designed
-        * to feed a live brightness bar / border color on a camera page.
-        *
-        * @param videoRef - ref to the `<video>` element to sample.
-        * @param options - optional configuration (see {@link UseLiveLuminanceOptions}).
-        * @returns The rolling mean luminance in `0..255` (`0` until the first sample).
-        */
-       export declare function useLiveLuminance(videoRef: RefObject<HTMLVideoElement | null>, { enabled, intervalMs }?: UseLiveLuminanceOptions): number;
-
-       /** Options for {@link useLiveLuminance}. */
-       export declare interface UseLiveLuminanceOptions {
-           /** When `false` the loop is paused (e.g. while a capture is in flight). Default: `true`. */
-           enabled?: boolean;
-           /** Throttle measurements in milliseconds. Default: `160` (~6 fps), plenty for UX. */
-           intervalMs?: number;
-       }
-
-       export declare const VERSION: string;
-
-       export declare abstract class VisionTask {
-           protected readonly _session: OrtSession;
-           protected constructor(_session: OrtSession);
-           /** The underlying {@link OrtSession} used to run inference. */
-           get session(): OrtSession;
-       }
-
-       export { }
+           export declare function readModelMetadata(model: Uint8Array | ArrayBufferLike): Readonly<Record<string, string>>;
+
+           /**
+            * Turn an empty result into an error, when the caller asked for that.
+            *
+            * Shared by every task that can come back with nothing — {@link Detector},
+            * {@link Segmenter} and {@link DetectClassify} — so the three agree on when
+            * they throw and on what the message says. The message names the two settings
+            * that decide the outcome, because "no detections" on its own leaves the reader
+            * unable to tell a blank image from a threshold set too high.
+            *
+            * @param count How many detections survived every filter.
+            * @param options The flag for this call, the threshold actually applied (after
+            *   any per-call override), the class allowlist if one narrowed the search, and
+            *   the source path when the input was one.
+            * @throws {@link NoDetectionsError} when the flag is set and `count` is zero.
+                */
+            export declare function requireDetections(count: number, options: {
+                readonly raiseOnEmpty: boolean;
+                readonly confThreshold: number;
+                readonly classes: readonly number[] | undefined;
+                readonly path: string | null;
+            }): void;
+
+            /** Resize an image to `(targetWidth, targetHeight)` using high-quality canvas resampling. */
+            export declare function resize(image: RGBImage, targetWidth: number, targetHeight: number): RGBImage;
+
+            /**
+             * Decide the input size a task will preprocess to.
+             *
+             * Precedence is graph → caller → fallback. The graph wins over an explicit
+             * `inputSize` because a static shape is not a preference, it is what ORT will
+             * accept: honoring the caller there would only turn a fixable mismatch into a
+             * failed run. A disagreement is a configuration bug in the caller, so it is
+             * reported through `console.warn` instead of being swallowed.
+             *
+             * @param options Graph shape, requested size and per-task fallback.
+             * @returns The `[width, height]` to preprocess to.
+             */
+            export declare function resolveInputSize(options: ResolveInputSizeOptions): readonly [number, number];
+
+            export declare interface ResolveInputSizeOptions {
+                /** Declared shape of the model's image input, from {@link declaredShapesFrom}. */
+                readonly graphShape?: DeclaredShape;
+                /** Size the caller asked for, if any. */
+                readonly requested?: readonly [number, number];
+                /** Size to use when neither the graph nor the caller pins one. */
+                readonly fallback: readonly [number, number];
+            }
+
+            export declare function resolveLabels(spec: LabelSpec, options?: ResolveLabelsOptions): readonly string[];
+
+            export declare interface ResolveLabelsOptions {
+                /**
+                 * Expected number of classes.
+                 *
+                 * - When `spec` is `null`/`undefined`, this is required to auto-generate names.
+                 * - When `spec` is provided, it validates that the resolved length matches.
+                 */
+                readonly numClasses?: number;
+            }
+
+            /**
+             * Resolve the execution providers to pass to `InferenceSession.create`.
+             *
+             * @param requested Explicit provider list in preference order; `undefined` returns the default.
+             */
+            export declare function resolveProviders(requested?: readonly string[]): string[];
+
+            /** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
+            /**
+             * Public output types returned by the SDK's vision tasks.
+             *
+             * These types form the contract between the SDK and its callers. They mirror
+             * the Python `ort-vision-sdk` output dataclasses 1-to-1.
+             *
+             * Naming is intentionally compatible with the Ultralytics / torchvision idiom
+             * (`cls`, `conf`, `box`, `xyxy`, `xywh`, normalized variants) so code ported
+             * from those projects keeps working with minimal edits. The original verbose
+             * names (`classId`, `className`, `confidence`, `bbox`) are still populated for
+             * backwards compatibility.
+             */
+            /**
+             * HWC RGB uint8 image — the canonical image format used across the SDK.
+             *
+             * `data.length` must equal `width * height * 3`. The buffer is laid out row
+             * by row, top-to-bottom, with each pixel as `[R, G, B]`.
+             */
+            export declare class RGBImage {
+                readonly data: Uint8Array;
+                readonly width: number;
+                readonly height: number;
+                constructor(data: Uint8Array, width: number, height: number);
+            }
+
+            /**
+             * Single segmented instance produced by an instance-segmentation model.
+             *
+             * Mirrors {@link DetectionResult} and adds the per-instance binary mask
+             * plus a "ready-to-display" background-removed crop.
+             */
+            export declare interface SegmentationResult {
+                readonly classId: number;
+                readonly className: string;
+                readonly confidence: number;
+                readonly bbox: BoundingBox;
+                /** Alias for `classId` (Ultralytics-style). */
+                readonly cls: number;
+                /** Alias for `className`. */
+                readonly name: string;
+                /** Alias for `confidence` (Ultralytics-style). */
+                readonly conf: number;
+                /** Alias for `bbox` (Ultralytics-style). */
+                readonly box: BoundingBox;
+                /**
+                 * Binary mask cropped to `bbox`. Values are `0` (background) or `255`
+                 * (foreground). Empty boxes yield a zero-sized `Mask`.
+                 */
+                readonly mask: Mask;
+                /**
+                 * The original image cropped to `bbox` with background pixels (where
+                 * `mask.data[i] === 0`) zeroed out. Empty boxes yield a zero-sized
+                 * `RGBImage`.
+                 */
+                readonly segmentedImage: RGBImage;
+            }
+
+            /**
+             * Per-image instance-segmentation envelope (Ultralytics-style `Results`).
+             *
+             * Iterating yields per-instance {@link SegmentationResult} entries. `boxes`
+             * and `masks` mirror Ultralytics' bulk-array views.
+             */
+            export declare class SegmentationResults implements Iterable<SegmentationResult> {
+                readonly boxes: Boxes;
+                readonly masks: Masks;
+                readonly detections: readonly SegmentationResult[];
+                readonly names: Readonly<Record<number, string>>;
+                readonly origImg: RGBImage;
+                readonly origShape: readonly [number, number];
+                readonly path: string | null;
+                readonly speed: Readonly<Speed>;
+                constructor(boxes: Boxes, masks: Masks, detections: readonly SegmentationResult[], names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Speed>);
+                /** Number of surviving instances. */
+                get length(): number;
+                /** Index into the per-instance results. */
+                get(index: number): SegmentationResult | undefined;
+                [Symbol.iterator](): Iterator<SegmentationResult>;
+            }
+
+            /**
+             * Instance segmenter for YOLO seg ONNX models (v8-seg / v11-seg / ...).
+             *
+             * The model is expected to expose two outputs:
+             *
+             * 1. `output0`: `(1, 4 + numClasses + numMaskCoefs, numAnchors)` — per-anchor
+             *    predictions (boxes, class scores, mask coefficients).
+             * 2. `output1`: `(1, numMaskCoefs, maskH, maskW)` — prototype masks.
+             *
+             * `predict()` returns `Promise<SegmentationResults[]>` (length 1 for a
+             * single image), mirroring Ultralytics' API. The envelope exposes:
+             *
+             * - `boxes`: bulk numpy view (`xyxy`, `xywh`, `xyxyn`, `xywhn`, `cls`, `conf`).
+             * - `masks`: per-instance binary masks cropped to each box.
+             * - per-instance {@link SegmentationResult} via iteration.
+             *
+             * @example
+             * ```typescript
+             * const seg = await Segmenter.create("/models/yolov8n-seg.onnx");
+             * const r = (await seg.predict("/images/street.jpg"))[0];
+             * for (const inst of r) {
+             *   console.log(inst.cls, inst.conf, inst.box.xyxy);
+             * }
+             * ```
+             */
+            export declare class Segmenter extends VisionTask {
+                private readonly _head;
+                private readonly _labels;
+                private readonly _names;
+                private readonly _inputSize;
+                private readonly _confThreshold;
+                private readonly _iouThreshold;
+                private readonly _maxDetections;
+                private readonly _maskThreshold;
+                private readonly _raiseOnEmpty;
+                private constructor();
+                private _pipelineCache;
+                /**
+                 * Run the model once on a zero-filled tensor, paying one-time costs up front.
+                 *
+                 * The first inference of a session is not representative: WebGPU compiles its
+                 * shaders on it and the WASM backend faults in its arenas, which on a phone
+                 * can turn the first frame into seconds while every later frame is tens of
+                 * milliseconds. Calling this while a loading spinner is still up moves that
+                 * cost somewhere the user is already waiting.
+                 *
+                 * @param runs How many warm-up inferences to run. One is enough for WASM;
+                 *   WebGPU sometimes settles on the second.
+                 */
+                warmup(runs?: number): Promise<void>;
+                /**
+                 * The fused preprocessing pipeline, built on first use.
+                 *
+                 * Lazily, because constructing it allocates canvases: a task built in an
+                 * environment without a canvas implementation stays constructible, and only
+                 * fails if it is actually asked to preprocess something.
+                 */
+                private get _pipeline();
+                /** Load the model and resolve labels. */
+                static create(model: ModelSource, options?: SegmenterOptions): Promise<Segmenter>;
+                /** The decoder family used to interpret the model's output. */
+                get head(): SegmenterHead;
+                /** Class labels indexed by class id. */
+                get labels(): readonly string[];
+                /** Class id → class name dict (matches Ultralytics' `model.names`). */
+                get names(): Readonly<Record<number, string>>;
+                /**
+                 * The `[width, height]` this task preprocesses to.
+                 *
+                 * Resolved at creation time from the model's graph when it declares a static
+                 * input, so reading it back tells you the resolution inference really runs at
+                 * — not merely what was requested.
+                 */
+                get inputSize(): readonly [number, number];
+                /** Number of classes the model predicts. */
+                get numClasses(): number;
+                /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
+                call(image: ImageInput, options?: SegmenterPredictOptions): Promise<SegmentationResults[]>;
+                /** Run instance segmentation on a single image. */
+                predict(image: ImageInput, options?: SegmenterPredictOptions): Promise<SegmentationResults[]>;
+                private _preprocess;
+                private _splitOutputs;
+                private _buildResult;
+                private _buildBoxes;
+                private _buildMasks;
+            }
+
+            /**
+             * Decoder family for the segmentation head.
+             *
+             * - `"yolo-seg"`: YOLO instance-segmentation head with two outputs —
+             *   `[1, 4 + nc + nm, N]` per-anchor predictions plus `[1, nm, mh, mw]`
+             *   prototype masks. Covers YOLOv8-seg, v11-seg, v26-seg.
+             *
+             * The SDK does **not** auto-detect this — the caller is responsible for
+             * picking a head that matches their export.
+             */
+            export declare type SegmenterHead = "yolo-seg";
+
+            export declare interface SegmenterOptions extends OrtSessionOptions {
+                /**
+                 * Decoder family for the segmentation head. Default `"yolo-seg"` covers
+                 * YOLOv8-seg/v11-seg/v26-seg.
+                 */
+                readonly head?: SegmenterHead;
+                /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */
+                readonly labels?: LabelSpec;
+                /** Number of classes — used to validate the supplied labels. */
+                readonly numClasses?: number;
+                /**
+                 * Model input `[width, height]` in pixels for letterboxing.
+                 *
+                 * Only used when the model's graph leaves its spatial axes dynamic: a graph
+                 * that declares a static size always wins, since that is the only shape ONNX
+                 * Runtime will accept. Defaults to `[640, 640]`.
+                 */
+                readonly inputSize?: readonly [number, number];
+                /** Default minimum class score to keep a candidate. */
+                readonly confThreshold?: number;
+                /** Default IoU threshold for non-maximum suppression. */
+                readonly iouThreshold?: number;
+                /** Maximum number of instances per image. */
+                readonly maxDetections?: number;
+                /**
+                 * If `true`, a run that finds nothing throws {@link NoDetectionsError}
+                 * instead of returning an empty envelope. Default `false`, because looking
+                 * and finding nothing is a successful inference. Turn it on when an empty
+                 * result means the surrounding pipeline should stop rather than carry on with
+                 * zero rows. Can be overridden per `predict` call.
+                 */
+                readonly raiseOnEmpty?: boolean;
+                /** Probability cutoff applied to soft masks. Defaults to `0.5`. */
+                readonly maskThreshold?: number;
+            }
+
+            export declare interface SegmenterPredictOptions {
+                readonly confThreshold?: number;
+                readonly iouThreshold?: number;
+                /**
+                 * If set, keep only instances whose `classId` is in this list.
+                 * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.
+                 */
+                readonly classes?: readonly number[];
+                /** Override the constructor's `raiseOnEmpty` setting for this call. */
+                readonly raiseOnEmpty?: boolean;
+            }
+
+            /** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
+            /**
+             * Classification head postprocessing — softmax + top-k.
+             */
+            /** Apply numerically-stable softmax to a 1-D vector of logits. */
+            export declare function softmax(logits: Float32Array | readonly number[]): Float32Array;
+
+            /**
+             * Read the spatial input size out of a declared NCHW shape.
+             *
+             * @param shape The declared shape of the model's image input.
+             * @returns `[width, height]` in pixels, or `null` when the shape is not 4D or
+             *   leaves either spatial axis dynamic — in which case the model accepts more
+             *   than one resolution and there is nothing to correct.
+             */
+            export declare function spatialInputSize(shape: DeclaredShape): readonly [number, number] | null;
+
+            /** @generated Vendored from @mauriciobenjamin700/ort-vision-sdk-web. Do not hand-edit — regenerate with `npm run vendor:vision`. */
+            /**
+             * Per-stage timing for a single `predict()` call.
+             *
+             * Populates the `speed` field every `Results` envelope carries, mirroring
+             * Ultralytics' `results[0].speed`. All values are milliseconds measured with
+             * `performance.now()`.
+             */
+            /**
+             * Stage durations of one inference, in milliseconds.
+             *
+             * `preprocess`, `inference` and `postprocess` are the three keys Ultralytics
+             * reports, measured over the same boundaries. `load` is specific to this SDK:
+             * `predict()` accepts a URL, `Blob` or DOM element and decodes it internally,
+             * so the fetch/decode cost would otherwise be invisible — and on a cold cache
+             * it dominates everything else.
+             */
+            export declare interface Speed {
+                /** Fetching and decoding the input into an `RGBImage`. */
+                load: number;
+                /** Letterbox/resize, normalization and tensor packing. */
+                preprocess: number;
+                /** The ONNX Runtime forward pass. */
+                inference: number;
+                /** Decoding raw outputs into results (NMS, mask assembly, top-k). */
+                postprocess: number;
+            }
+
+            /**
+             * Accumulate stage durations while a `predict()` call runs.
+             *
+             * Each `stage()` call closes the previous stage: the elapsed time since the
+             * last boundary is attributed to the name given. This keeps the call sites
+             * free of paired start/stop bookkeeping and guarantees the four stages tile
+             * the whole call without gaps.
+             */
+            export declare class SpeedTimer {
+                private _last;
+                private readonly _speed;
+                constructor();
+                /**
+                 * Attribute the time elapsed since the previous boundary to `stage`.
+                 *
+                 * @param stage Which stage just finished.
+                 */
+                stage(stage: keyof Speed): void;
+                /**
+                 * The accumulated durations.
+                 *
+                 * @returns The `speed` object to hand to the `Results` envelope.
+                 */
+                speed(): Speed;
+            }
+
+            /**
+             * Transpose interleaved HWC data to planar CHW layout.
+             *
+             * @param hwc Source array of length `width * height * channels`.
+             */
+            export declare function toCHW(hwc: Float32Array, width: number, height: number, channels?: number): Float32Array;
+
+            /**
+             * Convert the SDK's HWC RGB image to an HWC BGR `Uint8Array` (OpenCV layout).
+             *
+             * Useful for round-tripping data to a Python OpenCV consumer.
+             */
+            export declare function toCv2(image: RGBImage): Uint8Array;
+
+            /** Convert a uint8 image to a `Float32Array` in `[0, 1]` (HWC layout preserved). */
+            export declare function toFloat32(image: RGBImage, scale?: number): Float32Array;
+
+            /** Wrap a Float32 buffer into an `ort.Tensor`. */
+            export declare function toFloat32Tensor(data: Float32Array, dims: readonly number[]): ort.Tensor;
+
+            /**
+             * Return the top-k entries of a 1-D probability vector, sorted descending.
+             *
+             * @param k Number of entries to return; `null` returns all entries.
+             */
+            export declare function topK(probabilities: Float32Array, k: number | null): TopKResult;
+
+            export declare interface TopKResult {
+                readonly indices: Int32Array;
+                readonly values: Float32Array;
+            }
+
+            /**
+             * Convert an HWC uint8 image to a CHW `Float32Array` scaled to `[0, 1]`.
+             *
+             * Mirrors `torchvision.transforms.ToTensor()` semantics: HWC → CHW,
+             * `uint8 → float32 / 255`. Useful as input to YOLO-style detectors that
+             * don't require ImageNet normalization.
+             *
+             * @returns CHW `Float32Array` of length `width * height * 3`.
+             */
+            export declare function toTensor(image: RGBImage): Float32Array;
+
+            /**
+             * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,
+             * and expose status/error so the page can render permission and error states.
+             * The stream is automatically released on unmount or retry.
+             *
+             * Defaults to the rear ("environment") camera; desktops fall back to whatever
+             * single camera they expose. Pass `options.constraints` to override, or
+             * `options.enabled: false` to render the surface without prompting for the camera
+             * at all.
+             *
+             * Implementation notes:
+             * - Cleanup detaches the stream from a *snapshotted* video node, so it releases
+             *   the same element it attached to even if the page remounts the `<video>`.
+             * - When `getUserMedia` is missing, an insecure context is the usual cause, so
+             *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.
+             * - `video.play()` rejections are swallowed: autoplay may be blocked, but the
+             *   user gesture that opened the camera usually counts and playback resumes on
+             *   the next interaction.
+             *
+             * @param options - optional configuration (see {@link UseCameraStreamOptions}).
+             * @returns The stream status, classified error, a `videoRef` to attach, the live
+             *   `stream` for whatever needs the track itself, and a `retry()` to re-attempt
+             *   acquisition.
+             */
+            export declare function useCameraStream(options?: UseCameraStreamOptions): UseCameraStreamApi;
+
+            /** Value returned by {@link useCameraStream}. */
+            export declare interface UseCameraStreamApi {
+                /** Current lifecycle status. */
+                status: CameraStreamStatus;
+                /** The classified error, or `null` while not in the `error` status. */
+                error: CameraStreamError | null;
+                /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */
+                videoRef: RefObject<HTMLVideoElement | null>;
+                /**
+                 * The live stream, or `null`.
+                 *
+                 * Exposed for the things that need the **track** rather than the picture — the LED
+                 * torch (`useTorch`), the real frame size from `getSettings()`, recording it with
+                 * `useVideoRecorder`. Do not stop it yourself: the hook owns its lifetime and
+                 * releases it on unmount and on `retry()`.
+                 */
+                stream: MediaStream | null;
+                /** Manually re-attempt after an error (e.g. the user changed permissions). */
+                retry: () => void;
+            }
+
+            /** Options for {@link useCameraStream}. */
+            export declare interface UseCameraStreamOptions {
+                /**
+                 * Constraints passed to `getUserMedia`. Defaults to the rear
+                 * ("environment") camera at Full-HD ideal resolution with audio off.
+                 * Read when the stream (re)starts — change it and call `retry()` to apply.
+                 */
+                constraints?: MediaStreamConstraints;
+                /**
+                 * Hold off acquiring the camera until this is `true`. Default `true`.
+                 *
+                 * The point is to be able to *not* prompt. A permission prompt costs the user a
+                 * decision and, if they refuse, costs the app the feature permanently — so a
+                 * surface that already knows it cannot do its job (a barcode scanner in a browser
+                 * with no decoder) must not open the camera to then say so. Flipping this to `false`
+                 * also releases a stream that is already live.
+                 */
+                enabled?: boolean;
+            }
+
+            /**
+             * Sample mean luminance from a `<video>` source on a `requestAnimationFrame`
+             * loop and expose the rolling value. Sampling is throttled by `intervalMs` and
+             * paused whenever `enabled` is `false` or the video is not ready yet
+             * (`readyState < 2` or `videoWidth === 0`).
+             *
+             * One offscreen canvas is reused across frames to avoid GC pressure. Designed
+             * to feed a live brightness bar / border color on a camera page.
+             *
+             * @param videoRef - ref to the `<video>` element to sample.
+             * @param options - optional configuration (see {@link UseLiveLuminanceOptions}).
+             * @returns The rolling mean luminance in `0..255` (`0` until the first sample).
+             */
+            export declare function useLiveLuminance(videoRef: RefObject<HTMLVideoElement | null>, { enabled, intervalMs }?: UseLiveLuminanceOptions): number;
+
+            /** Options for {@link useLiveLuminance}. */
+            export declare interface UseLiveLuminanceOptions {
+                /** When `false` the loop is paused (e.g. while a capture is in flight). Default: `true`. */
+                enabled?: boolean;
+                /** Throttle measurements in milliseconds. Default: `160` (~6 fps), plenty for UX. */
+                intervalMs?: number;
+            }
+
+            export declare const VERSION: string;
+
+            export declare abstract class VisionTask {
+                protected readonly _session: OrtSession;
+                protected constructor(_session: OrtSession);
+                /** The underlying {@link OrtSession} used to run inference. */
+                get session(): OrtSession;
+            }
+
+            /**
+             * Build a zero-filled CHW tensor payload for a warm-up run.
+             *
+             * @param width Model input width in pixels.
+             * @param height Model input height in pixels.
+             */
+            export declare function zeroTensorData(width: number, height: number): Float32Array;
+
+            export { }