@mauriciobenjamin700/ort-vision-sdk-web 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,184 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-07
+
+### Added
+
+- **`DetectClassify` runs through the fused letterbox pipeline, and can be
+  warmed up.** It was written against the pre-`LetterboxPipeline` preprocessing
+  and would otherwise have been the only task left on the slow path — and the
+  only one unable to pay its shader compilation up front, which is the task that
+  needs it most: two models plus the bridge compile on the first inference.
+
+- **`raiseOnEmpty` — opt in to treating an empty result as an error.** Mirrors
+  the Python SDK: `Detector`, `Segmenter` and `DetectClassify` resolve to an
+  empty envelope by default, and throw the new `NoDetectionsError` when the flag
+  is set. Available on the construction options and as a per-call override, with
+  the same message — which names the threshold that applied, plus the image and
+  the class filter when either narrowed the search.
+
+  ```typescript
+  const det = await Detector.create("/models/yolov8n.onnx", {
+    confThreshold: 0.7,
+    raiseOnEmpty: true,
+  });
+  await det.predict("/img.jpg");
+  // NoDetectionsError: No detections in /img.jpg: nothing cleared confThreshold=0.7.
+  ```
+
+- **`DetectClassify` — run a fused detect→classify pipeline in the browser.**
+  A pipeline built by the Python SDK's `ort_vision_sdk.compose` (0.7.0) already
+  contains both models plus the crop-and-resize bridge between them. That matters
+  more in a tab than anywhere else: two models mean two `.onnx` downloads, two
+  WASM/WebGPU session initializations, and a per-crop round trip through
+  JavaScript to slice, resize and restack the regions before the second model can
+  see them. A fused pipeline has one download, one session, and no round trip.
+
+  ```typescript
+  import { DetectClassify } from "@mauriciobenjamin700/ort-vision-sdk-web";
+
+  const pipeline = await DetectClassify.create("/models/pipeline.onnx");
+  for (const d of (await pipeline.predict("/images/flock.jpg"))[0]) {
+    console.log(d.name, d.conf, d.classification?.name);
+  }
+  ```
+
+- **`readFusionSpec()` and the pipeline contract** (`FusionSpec`, `CropSource`,
+  the `INPUT_*` / `OUTPUT_*` names, `METADATA_PREFIX`). The letterbox resolution,
+  the crop size, whether the classifier output still needs a softmax and the class
+  names of both stages are read out of the model's own `ovs.` metadata — the same
+  keys, encodings and fallbacks the Python side writes. A pipeline fused once
+  therefore behaves identically in both runtimes, off the same file.
+
+- **`DetectionResult.classification`** (optional, absent for a plain detector) and
+  the `DetectClassifyResults` envelope, which carries `names` and
+  `classifierNames` separately because the two stages have unrelated label spaces.
+
+- **`FusionError`** and `parseNames()`, split out of `modelNames()` so both class
+  maps of a pipeline can be parsed with the same reader.
+
+- **`warmup()` on `Detector` and `Segmenter`.** The first inference of a session
+  is not representative: WebGPU compiles its shaders on it and the WASM backend
+  faults in its arenas, so on a phone the first frame can take seconds while
+  every later frame takes tens of milliseconds. `await det.warmup()` runs the
+  model once on a zero tensor, moving that cost to wherever the user is already
+  watching a spinner.
+
+- **`LetterboxPipeline`, exported.** The fused preprocessing path the tasks now
+  take, available to a custom pipeline that wants the same allocation-free
+  behaviour. `letterboxToTensorData` is the one-shot form.
+
+### Changed
+
+- **Preprocessing is ~2x faster and allocates nothing per frame.** Chaining the
+  composable primitives cost eleven full-buffer passes and six large allocations
+  per frame: `getImageData` → RGBA→RGB → RGB→RGBA → `putImageData` →
+  `drawImage` → `getImageData` → RGBA→RGB → fill → row copies → `toFloat32` →
+  `toCHW`. The tasks now go through `LetterboxPipeline`, which collapses the
+  second half into one `drawImage` — resizing *and* positioning the content
+  inside the padded target in a single accelerated operation — plus one loop
+  that reads the resulting RGBA and writes planar float32 straight into a buffer
+  reused across frames.
+
+  Measured in Chromium, median of 31 runs, letterboxing into 640x640:
+
+  | Source | Before | After | Speedup |
+  | --- | --- | --- | --- |
+  | 1920x1080 | 19.8 ms | 10.7 ms | 1.85x |
+  | 1280x720 | 13.8 ms | 7.8 ms | 1.77x |
+  | 640x480 | 6.8 ms | 3.1 ms | 2.19x |
+
+  **The output is bit-identical**, verified in a real browser against the
+  primitive-chained path across four source sizes — maximum difference 0.
+
+  The primitives are unchanged and still exported: they are what makes a custom
+  pipeline writable. Only the path the built-in tasks take has changed.
+
+- **The preprocessing canvas is created with `willReadFrequently`.** It is read
+  back with `getImageData` on every frame, which is what the hint exists for.
+  Measured effect on speed in Chromium: none beyond noise. What it removes is
+  the `Canvas2D: Multiple readback operations using getImageData are faster with
+  the willReadFrequently attribute set to true` warning the browser was printing
+  into every consumer's console, once per frame.
+
+### Removed
+
+- **`decodeYoloV8`, `decodeYoloV8Anchors`, `decodeYoloV8Seg` and the
+  `DecodeYoloV8*Options` type aliases are gone.** Deprecated in 0.2.0 with
+  "will be removed in 0.4.0", and still shipping at 0.5.1. Use `decodeYolo`,
+  `decodeYoloAnchors`, `decodeYoloSeg` and their `DecodeYolo*Options` types:
+  same functions, honest names, since the decoder covers every anchor-free YOLO
+  head from v8 through v12.
+
+  `test/deprecations.test.ts` now guards the removal rather than the
+  deprecation, so a re-add fails loudly.
+
+### Fixed
+
+- **A custom model with no baked-in `names` no longer fails to create.** Same
+  defect as the Python SDK: the fallback was the 80-name COCO preset, so a
+  3-class detector threw `Resolved 80 labels but the model has 3 classes`.
+  Labels now come up as `class_0`, `class_1`, ..., and the COCO preset applies
+  only when the model really does have 80 classes. `defaultLabels` is exported.
+
+- **A model URL that cannot be fetched for its metadata now says so.** The
+  fallback — hand the URL to ORT and let it load the model itself — is right,
+  but it was silent, and the symptom it produces is remote from the cause:
+  class names come back as `class_0`, `class_1`, ... with nothing explaining
+  why. It warns now, and names `labels` as the way out.
+
+- **Score ties in `nms` and `batchedNms` break by index explicitly.** Both
+  relied on `Array.prototype.sort` being stable to order tied scores. It is, in
+  every engine that matters, but leaning on it left the tie behaviour implicit —
+  and in `batchedNms` the surviving order also depended on `Map` insertion order,
+  which the Python SDK (iterating classes in sorted order) does not share. The
+  comparators now fall back to `a - b`, so a tie resolves to the lowest index on
+  both sides, matching `torchvision`.
+
+  Only exact ties are affected. The Python SDK was the one actually producing a
+  different survivor — it visited ties in descending index order — and this is
+  the other half of that fix.
+
+### Notes
+
+- Fusing models stays a Python-side build step; there is no ONNX protobuf writer
+  here and no reason for one. The browser only loads the result.
+- ORT Web returns `int64` outputs as `BigInt64Array`. The pipeline's class ids and
+  detection count are widened to `number` internally, so no caller has to handle
+  `BigInt`.
+
+### Internal
+
+- **Parity tests against shared fixtures** (`test/parity.test.ts`, reading
+  `fixtures/parity/` at the repository root). They feed the web implementation
+  the same inputs the Python SDK was given and require the same outputs, with
+  mask bitmaps compared pixel for pixel. Two published artifacts promising the
+  same numbers had nothing checking the promise; this is that check, and it
+  found a mask-resampling divergence on its first run (fixed on the Python
+  side, see that package's changelog).
+
+## [0.5.1] - 2026-08-05
+
+### Fixed
+
+- **A model no longer costs twice its size at the peak of session creation.**
+  Reading the metadata map (0.5.0) fetches a URL model into a `Uint8Array`, and
+  that read sat *after* `InferenceSession.create` — so the JavaScript buffer
+  stayed reachable while ORT copied the model into its WASM heap and allocated
+  the graph and the weights on top of it. A 5 MB `.onnx` therefore held 5 MB of
+  JS heap plus 5 MB of WASM heap plus the weights at the same instant. On a phone
+  loading two models that was enough for ORT's allocator to give up with
+  `Can't create a session. failed to allocate a buffer of size 5355557`.
+
+  The metadata is now read before the session is built, so the buffer is
+  collectable as soon as ORT has copied it. `test/session.test.ts` pins the order.
+
+  `readMetadata: false` remains the escape hatch for a device that cannot afford
+  the bytes at all: ORT loads from the URL and nothing in the SDK ever holds the
+  model. Only the class names are lost — the input size still comes from the
+  graph — so that route has to pass `labels` itself.
+
 ## [0.5.0] - 2026-08-03
 
 ### Added

package/README.md

@@ -66,6 +66,54 @@ for (const d of detections) {
 }
 ```
 
+### Fused detect → classify pipeline
+
+A pipeline fused by the Python SDK's `ort_vision_sdk.compose` puts a detector,
+the crop-and-resize bridge and a classifier into **one** `.onnx`. In a browser
+that is one download and one session instead of two, and no per-crop round trip
+through JavaScript.
+
+```typescript
+import { DetectClassify } from "@mauriciobenjamin700/ort-vision-sdk-web";
+
+const pipeline = await DetectClassify.create("/models/pipeline.onnx");
+const result = (await pipeline.predict("/images/flock.jpg"))[0];
+
+for (const d of result) {
+  console.log(d.name, d.conf, d.box.asXyxy());          // what the detector found
+  console.log(d.classification?.name, d.classification?.conf);  // what the classifier said
+}
+```
+
+The resolution, crop size, thresholds and both class maps come out of the file's
+own metadata, so nothing is restated here. Building the pipeline is a Python-side
+step; the browser only loads the result. Full guide:
+[Fused pipelines](https://mauriciobenjamin700.github.io/ort-vision-sdk/en/guia/pipeline/).
+
+### When finding nothing is an error
+
+`predict()` resolves to an empty envelope when nothing is detected. When an
+empty result instead means the surrounding flow should stop, opt in:
+
+```typescript
+import { Detector, NoDetectionsError } from "@mauriciobenjamin700/ort-vision-sdk-web";
+
+const det = await Detector.create("/models/yolov8n.onnx", {
+  confThreshold: 0.7,
+  raiseOnEmpty: true,
+});
+
+try {
+  const result = (await det.predict("/img.jpg"))[0];
+} catch (error) {
+  if (error instanceof NoDetectionsError) console.log(error.message);
+  // No detections in /img.jpg: nothing cleared confThreshold=0.7.
+}
+```
+
+Available on `Detector`, `Segmenter` and `DetectClassify`, and overridable per
+call (`predict(img, { raiseOnEmpty: false })`).
+
 ## Inference speed
 
 Every result envelope carries a per-stage timing breakdown:

package/dist/core/canvas.d.ts

@@ -12,8 +12,17 @@ export type Canvas2D = HTMLCanvasElement | OffscreenCanvas;
 export type Context2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
 /** Allocate a `Canvas2D`, preferring `OffscreenCanvas` when available. */
 export declare function createCanvas(width: number, height: number): Canvas2D;
-/** Get a 2D context from a canvas, throwing a typed error if the browser refuses. */
-export declare function get2DContext(canvas: Canvas2D): Context2D;
+/**
+ * Get a 2D context from a canvas, throwing a typed error if the browser refuses.
+ *
+ * @param canvas The canvas to obtain a context for.
+ * @param options Context attributes, forwarded verbatim. `willReadFrequently`
+ *   tells the browser the canvas is read back with `getImageData` repeatedly,
+ *   which moves the backing store to software: faster readback, slower
+ *   compositing. Whether it pays depends on the surface, so it is the caller's
+ *   call rather than a default here.
+ */
+export declare function get2DContext(canvas: Canvas2D, options?: CanvasRenderingContext2DSettings): Context2D;
 /** Convert RGBA `ImageData` into the canonical HWC RGB `RGBImage`. */
 export declare function imageDataToRGB(imageData: ImageData): RGBImage;
 /** Convert an `RGBImage` into RGBA `ImageData` (alpha forced to 255). */

package/dist/core/canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/core/canvas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,MAAM,QAAQ,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAC3D,MAAM,MAAM,SAAS,GACjB,wBAAwB,GACxB,iCAAiC,CAAC;AAEtC,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAWpE;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAMxD;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAgB7D;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CASzD"}
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/core/canvas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,MAAM,QAAQ,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAC3D,MAAM,MAAM,SAAS,GACjB,wBAAwB,GACxB,iCAAiC,CAAC;AAEtC,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAWpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,QAAQ,EAChB,OAAO,GAAE,gCAAqC,GAC7C,SAAS,CAMX;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAgB7D;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CASzD"}

package/dist/core/canvas.js

@@ -22,9 +22,18 @@ export function createCanvas(width, height) {
     }
     throw new ImageLoadError("No canvas implementation available in this environment.");
 }
-/** Get a 2D context from a canvas, throwing a typed error if the browser refuses. */
-export function get2DContext(canvas) {
-    const ctx = canvas.getContext("2d");
+/**
+ * Get a 2D context from a canvas, throwing a typed error if the browser refuses.
+ *
+ * @param canvas The canvas to obtain a context for.
+ * @param options Context attributes, forwarded verbatim. `willReadFrequently`
+ *   tells the browser the canvas is read back with `getImageData` repeatedly,
+ *   which moves the backing store to software: faster readback, slower
+ *   compositing. Whether it pays depends on the surface, so it is the caller's
+ *   call rather than a default here.
+ */
+export function get2DContext(canvas, options = {}) {
+    const ctx = canvas.getContext("2d", options);
     if (ctx === null) {
         throw new ImageLoadError("Failed to obtain 2D rendering context.");
     }

package/dist/core/canvas.js.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../../src/core/canvas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../../src/core/canvas.ts"],"names":[],"mappings":"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"}

package/dist/core/exceptions.d.ts

@@ -22,4 +22,30 @@ export declare class ImageLoadError extends OrtVisionError {
 /** Raised when class labels cannot be resolved from the supplied spec. */
 export declare class LabelMapError extends OrtVisionError {
 }
+/**
+ * Raised when a detection task finds nothing and was asked to treat that as an error.
+ *
+ * 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.
+ *
+ * "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 class NoDetectionsError extends OrtVisionError {
+}
+/**
+ * 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 {
+}
 //# sourceMappingURL=exceptions.d.ts.map

package/dist/core/exceptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,4EAA4E;AAC5E,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD,8DAA8D;AAC9D,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD,mEAAmE;AACnE,qBAAa,yBAA0B,SAAQ,cAAc;CAAG;AAEhE,8EAA8E;AAC9E,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD,0EAA0E;AAC1E,qBAAa,aAAc,SAAQ,cAAc;CAAG"}
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,4EAA4E;AAC5E,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD,8DAA8D;AAC9D,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD,mEAAmE;AACnE,qBAAa,yBAA0B,SAAQ,cAAc;CAAG;AAEhE,8EAA8E;AAC9E,qBAAa,cAAe,SAAQ,cAAc;CAAG;AAErD,0EAA0E;AAC1E,qBAAa,aAAc,SAAQ,cAAc;CAAG;AAEpD;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;CAAG;AAExD;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,cAAc;CAAG"}

package/dist/core/exceptions.js

@@ -25,4 +25,30 @@ export class ImageLoadError extends OrtVisionError {
 /** Raised when class labels cannot be resolved from the supplied spec. */
 export class LabelMapError extends OrtVisionError {
 }
+/**
+ * Raised when a detection task finds nothing and was asked to treat that as an error.
+ *
+ * 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.
+ *
+ * "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 class NoDetectionsError extends OrtVisionError {
+}
+/**
+ * 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 class FusionError extends OrtVisionError {
+}
 //# sourceMappingURL=exceptions.js.map

package/dist/core/exceptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD,8DAA8D;AAC9D,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD,mEAAmE;AACnE,MAAM,OAAO,yBAA0B,SAAQ,cAAc;CAAG;AAEhE,8EAA8E;AAC9E,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD,0EAA0E;AAC1E,MAAM,OAAO,aAAc,SAAQ,cAAc;CAAG"}
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD,8DAA8D;AAC9D,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD,mEAAmE;AACnE,MAAM,OAAO,yBAA0B,SAAQ,cAAc;CAAG;AAEhE,8EAA8E;AAC9E,MAAM,OAAO,cAAe,SAAQ,cAAc;CAAG;AAErD,0EAA0E;AAC1E,MAAM,OAAO,aAAc,SAAQ,cAAc;CAAG;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAc;CAAG;AAExD;;;;;;;GAOG;AACH,MAAM,OAAO,WAAY,SAAQ,cAAc;CAAG"}

package/dist/core/metadata.d.ts

@@ -36,4 +36,16 @@ export declare function readModelMetadata(model: Uint8Array | ArrayBufferLike):
  *   usable `names` entry.
  */
 export declare function modelNames(metadata: Readonly<Record<string, string>> | undefined): readonly string[] | null;
+/**
+ * Parse a `repr`-encoded `dict[int, str]` class map.
+ *
+ * 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.
+ */
+export declare function parseNames(encoded: string | undefined): readonly string[] | null;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/core/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyIH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,GAAG,eAAe,GAClC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqBlC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GACrD,SAAS,MAAM,EAAE,GAAG,IAAI,CA6B1B"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyIH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,GAAG,eAAe,GAClC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqBlC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GACrD,SAAS,MAAM,EAAE,GAAG,IAAI,CAE1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CA6BhF"}

package/dist/core/metadata.js

@@ -182,7 +182,21 @@ export function readModelMetadata(model) {
  *   usable `names` entry.
  */
 export function modelNames(metadata) {
-    const raw = metadata?.names?.trim();
+    return parseNames(metadata?.names);
+}
+/**
+ * Parse a `repr`-encoded `dict[int, str]` class map.
+ *
+ * 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.
+ */
+export function parseNames(encoded) {
+    const raw = encoded?.trim();
     if (!raw || !raw.startsWith("{") || !raw.endsWith("}"))
         return null;
     const body = raw.slice(1, -1).trim();

package/dist/core/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"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"}

package/dist/core/session.d.ts

@@ -19,6 +19,13 @@ export interface OrtSessionOptions {
      * 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;
 }
@@ -37,6 +44,16 @@ export declare class OrtSession {
     /**
      * 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}).

package/dist/core/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAI5C,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,YAAY,CAAC;AAIpE,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,UAAU,CAAC;AAsBhE,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,cAAc,CAAC;IAC9D;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;aACT,SAAS,EAAE,SAAS,MAAM,EAAE;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAH5B,OAAO;IAMP;;;;;;;OAOG;WACU,MAAM,CACjB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC;IAkCtB,yDAAyD;IACzD,IAAI,UAAU,IAAI,SAAS,MAAM,EAAE,CAElC;IAED,kDAAkD;IAClD,IAAI,SAAS,IAAI,MAAM,CAMtB;IAED,0DAA0D;IAC1D,IAAI,WAAW,IAAI,SAAS,MAAM,EAAE,CAEnC;IAED;;;;;;OAMG;IACH,IAAI,WAAW,IAAI,SAAS,aAAa,EAAE,CAM1C;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,aAAa,CAE9B;IAED;;;;;OAKG;IACH,IAAI,YAAY,IAAI,SAAS,aAAa,EAAE,CAM3C;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,aAAa,CAE/B;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE/C;IAED;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,wEAAwE;IACxE,IAAI,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAE9B;IAED;;;;;OAKG;IACG,GAAG,CACP,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAWvC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAI5C,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,YAAY,CAAC;AAIpE,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,UAAU,CAAC;AA+ChE,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,cAAc,CAAC;IAC9D;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;aACT,SAAS,EAAE,SAAS,MAAM,EAAE;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAH5B,OAAO;IAMP;;;;;;;;;;;;;;;;;OAiBG;WACU,MAAM,CACjB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC;IAkCtB,yDAAyD;IACzD,IAAI,UAAU,IAAI,SAAS,MAAM,EAAE,CAElC;IAED,kDAAkD;IAClD,IAAI,SAAS,IAAI,MAAM,CAMtB;IAED,0DAA0D;IAC1D,IAAI,WAAW,IAAI,SAAS,MAAM,EAAE,CAEnC;IAED;;;;;;OAMG;IACH,IAAI,WAAW,IAAI,SAAS,aAAa,EAAE,CAM1C;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,aAAa,CAE9B;IAED;;;;;OAKG;IACH,IAAI,YAAY,IAAI,SAAS,aAAa,EAAE,CAM3C;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,aAAa,CAE/B;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE/C;IAED;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,wEAAwE;IACxE,IAAI,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAE9B;IAED;;;;;OAKG;IACG,GAAG,CACP,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAWvC"}

package/dist/core/session.js

@@ -19,14 +19,35 @@ import { resolveProviders } from "./providers.js";
 async function fetchModel(url) {
     try {
         const response = await fetch(url);
-        if (!response.ok)
+        if (!response.ok) {
+            warnMetadataUnavailable(url, `HTTP ${response.status} ${response.statusText}`);
             return url;
+        }
         return new Uint8Array(await response.arrayBuffer());
     }
-    catch {
+    catch (err) {
+        warnMetadataUnavailable(url, err.message);
         return url;
     }
 }
+/**
+ * Warn that a model's metadata could not be read, and say what that costs.
+ *
+ * The fallback itself is right — losing the metadata beats failing a load that
+ * ORT could have completed on its own — but it used to be silent, and the
+ * symptom it produces is remote from the cause: class names come back as
+ * `class_0`, `class_1`, ... with nothing anywhere explaining why. Whoever hits
+ * this needs to be told that passing `labels` is the way out.
+ *
+ * @param url The model URL that could not be fetched here.
+ * @param reason What went wrong, as reported by `fetch`.
+ */
+function warnMetadataUnavailable(url, reason) {
+    console.warn(`[@ort-vision-sdk/web] Could not fetch ${url} to read its metadata (${reason}). ` +
+        "Letting ONNX Runtime load it instead: the model will work, but its baked-in " +
+        "class names are unavailable, so labels fall back to class_0, class_1, ... " +
+        "Pass `labels` explicitly to name them.");
+}
 /**
  * Wrap an ONNX Runtime Web `InferenceSession` with convenient metadata access.
  *
@@ -46,6 +67,16 @@ export class OrtSession {
     /**
      * 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}).
@@ -59,6 +90,7 @@ export class OrtSession {
         };
         const wantsMetadata = options.readMetadata !== false;
         const source = typeof model === "string" && wantsMetadata ? await fetchModel(model) : model;
+        const metadata = wantsMetadata && typeof source !== "string" ? readModelMetadata(source) : {};
         let session;
         try {
             if (typeof source === "string") {
@@ -74,7 +106,6 @@ export class OrtSession {
         catch (err) {
             throw new ModelLoadError(`Failed to load ONNX model: ${err.message}`, { cause: err });
         }
-        const metadata = wantsMetadata && typeof source !== "string" ? readModelMetadata(source) : {};
         return new OrtSession(session, providers, metadata);
     }
     /** Names of the model's inputs, in declaration order. */

package/dist/core/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"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"}