hazo_images 1.8.0 → 1.9.0

package/CHANGE_LOG.md

@@ -1,5 +1,15 @@
 # hazo_images Change Log
 
+## 1.9.0 — 2026-07-21
+
+### Added
+
+- **`bboxIoU(a, b)`** — new root export (`hazo_images`, isomorphic). Computes Intersection-over-Union for two normalized (0..1) axis-aligned bounding boxes. Returns `0` when either input is `null`/`undefined`/malformed instead of throwing — callers commonly iterate user-tagged boxes that may legitimately be missing a region. New export: `BBox` type. Ported from a downstream app's photo face-tag dedup logic; pure, no dependencies.
+- **`canDecodeImage(file)`** — new `hazo_images/ui` export (client-only). Probes whether the current browser can decode a given `File` by loading it into an `Image` and resolving `true`/`false` on `load`/`error` (revoking the created object URL either way). Ported from a downstream app's crop-dialog gating logic (e.g. skip the cropper and fall back to direct upload for formats like HEIC that some browsers can't render). Not a React component — plain function, no `hazo_ui`/React import.
+- Demo: `test-app /bbox-and-decode` page exercising both utilities (draggable-value box overlay for `bboxIoU`, file-picker probe for `canDecodeImage`).
+
+---
+
 ## 1.8.0 — 2026-07-11
 
 ### Added

package/README.md

@@ -91,6 +91,39 @@ const result = await processImage(buffer, {
 // thumbnail extension in uploadProcessedImage: __thumb_256.webp
 ```
 
+### bboxIoU — bounding-box overlap (isomorphic)
+
+```ts
+import { bboxIoU } from 'hazo_images';
+import type { BBox } from 'hazo_images';
+
+const a: BBox = { x: 0.1, y: 0.1, w: 0.4, h: 0.4 };
+const b: BBox = { x: 0.3, y: 0.3, w: 0.4, h: 0.4 };
+
+bboxIoU(a, b); // 0..1, where 1 = perfect overlap
+bboxIoU(a, null); // 0 — null/undefined/malformed input never throws
+```
+
+Coordinates are normalized `0..1` relative to the containing image. Useful
+for deduping or matching user-tagged regions (e.g. face-tag boxes) against
+detector output.
+
+### canDecodeImage — browser decode probe (client-only)
+
+```ts
+import { canDecodeImage } from 'hazo_images/ui';
+
+const ok = await canDecodeImage(file); // File → Promise<boolean>
+if (!ok) {
+  // e.g. HEIC on a non-Safari browser — skip the crop dialog and
+  // fall back to direct upload instead.
+}
+```
+
+Loads the file into an `Image` and resolves `true`/`false` based on
+`load`/`error`; the created object URL is revoked either way. Browser-only —
+relies on global `Image`/`URL`/`File`, so it must run in a client component.
+
 ## Error Types
 
 All errors extend `HazoError` subclasses from `hazo_core` (Wave 2). The
@@ -136,9 +169,9 @@ try {
 
 | Import | Contents |
 |---|---|
-| `hazo_images` | Shared types + error classes (isomorphic, no Node deps) |
+| `hazo_images` | Shared types + error classes + `bboxIoU` (isomorphic, no Node deps) |
 | `hazo_images/server` | `processImage`, `uploadProcessedImage`, `createImageProcessHandler` (Node.js only) |
-| `hazo_images/ui` | `ImageUploader`, `ImageViewer`, `ImageEditorDialog`, `ImageAnnotator` + control-schema helpers (React, client-only) |
+| `hazo_images/ui` | `ImageUploader`, `ImageViewer`, `ImageEditorDialog`, `ImageAnnotator`, `canDecodeImage` + control-schema helpers (client-only; React components require `hazo_ui`, `canDecodeImage` does not) |
 | `hazo_images/runware` | `createRunwareClient`, `assemblePrompts`, 4 error classes (Node.js only) |
 
 ## Supported formats

package/dist/index.d.ts

@@ -152,4 +152,25 @@ declare class ImageUploadError extends HazoExternalError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
-export { ImageProcessingError, ImageUploadError, type ProcessImageOptions, type ProcessImageResult, SharpMissingError, UnsupportedFormatError, type UploadProcessedImageResult };
+/**
+ * Normalized axis-aligned bounding box: coordinates and dimensions in the
+ * 0..1 range relative to the containing image.
+ */
+type BBox = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Compute Intersection over Union for two axis-aligned bounding boxes.
+ * All coordinates are normalized 0..1.
+ *
+ * Returns a value in [0..1] where 1 means perfect overlap. Returns 0 when
+ * either input is null/undefined or otherwise malformed — callers commonly
+ * iterate user-tagged bboxes that may legitimately be null (e.g. a tag
+ * created without a drawn region carries no bbox).
+ */
+declare function bboxIoU(a: BBox | null | undefined, b: BBox | null | undefined): number;
+
+export { type BBox, ImageProcessingError, ImageUploadError, type ProcessImageOptions, type ProcessImageResult, SharpMissingError, UnsupportedFormatError, type UploadProcessedImageResult, bboxIoU };

package/dist/index.js

@@ -45,9 +45,36 @@ var ImageUploadError = class extends HazoExternalError {
     });
   }
 };
+
+// src/bbox-iou.ts
+function isValidBBox(b) {
+  if (!b || typeof b !== "object") return false;
+  const r = b;
+  return typeof r.x === "number" && typeof r.y === "number" && typeof r.w === "number" && typeof r.h === "number";
+}
+function bboxIoU(a, b) {
+  if (!isValidBBox(a) || !isValidBBox(b)) return 0;
+  const ax2 = a.x + a.w;
+  const ay2 = a.y + a.h;
+  const bx2 = b.x + b.w;
+  const by2 = b.y + b.h;
+  const interX1 = Math.max(a.x, b.x);
+  const interY1 = Math.max(a.y, b.y);
+  const interX2 = Math.min(ax2, bx2);
+  const interY2 = Math.min(ay2, by2);
+  const interW = interX2 - interX1;
+  const interH = interY2 - interY1;
+  if (interW <= 0 || interH <= 0) return 0;
+  const intersection = interW * interH;
+  const areaA = a.w * a.h;
+  const areaB = b.w * b.h;
+  const union = areaA + areaB - intersection;
+  return union <= 0 ? 0 : intersection / union;
+}
 export {
   ImageProcessingError,
   ImageUploadError,
   SharpMissingError,
-  UnsupportedFormatError
+  UnsupportedFormatError,
+  bboxIoU
 };

package/dist/ui/index.d.ts

@@ -393,4 +393,17 @@ declare function ResizeHandleOverlay({ box, onResize, onResizeEnd, containerWidt
 
 declare function cn(...parts: Array<string | false | null | undefined>): string;
 
-export { type AnnotatorShape, type AnnotatorTool, type ArrowShape, type CircleShape, DEFAULT_IMAGE_EDIT_CONTROLS, ImageAnnotator, type ImageAnnotatorProps, type ImageEditControls, type ImageEditTab, ImageEditorDialog, type ImageEditorDialogProps, type ImageProcessOptions, type ImageProcessResult, type ImageProcessThumbnail, ImageUploader, type ImageUploaderProps, ImageViewer, type ImageViewerProps, type InputOption, type PenShape, type ProcessFn, type ResizeBox, type ResizeHandle, ResizeHandleOverlay, type ResizeHandleOverlayProps, type TabElement, type ValidationError, type ValidationResult, addShape, clearShapes, cn, controlValuesToOptions, defaultControlValues, undoShape, validate_image_edit_controls };
+/**
+ * Probes whether the current browser can decode a given image File.
+ *
+ * Resolves `true` if the browser loads the file successfully, `false` if
+ * it fires an error (e.g. HEIC on non-Safari). Callers use this to decide
+ * whether to open a crop/edit dialog or fall back to direct upload.
+ *
+ * Browser-only — relies on the global `Image`, `URL.createObjectURL`, and
+ * `File` APIs. Never call this from server code or Node.js tests without
+ * stubbing those globals first.
+ */
+declare function canDecodeImage(file: File): Promise<boolean>;
+
+export { type AnnotatorShape, type AnnotatorTool, type ArrowShape, type CircleShape, DEFAULT_IMAGE_EDIT_CONTROLS, ImageAnnotator, type ImageAnnotatorProps, type ImageEditControls, type ImageEditTab, ImageEditorDialog, type ImageEditorDialogProps, type ImageProcessOptions, type ImageProcessResult, type ImageProcessThumbnail, ImageUploader, type ImageUploaderProps, ImageViewer, type ImageViewerProps, type InputOption, type PenShape, type ProcessFn, type ResizeBox, type ResizeHandle, ResizeHandleOverlay, type ResizeHandleOverlayProps, type TabElement, type ValidationError, type ValidationResult, addShape, canDecodeImage, clearShapes, cn, controlValuesToOptions, defaultControlValues, undoShape, validate_image_edit_controls };

package/dist/ui/index.js

@@ -1894,6 +1894,23 @@ function ImageAnnotator({
     )
   ] }) });
 }
+
+// src/ui/can-decode-image.ts
+function canDecodeImage(file) {
+  return new Promise((resolve) => {
+    const url = URL.createObjectURL(file);
+    const img = new Image();
+    img.onload = () => {
+      URL.revokeObjectURL(url);
+      resolve(true);
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      resolve(false);
+    };
+    img.src = url;
+  });
+}
 export {
   DEFAULT_IMAGE_EDIT_CONTROLS,
   ImageAnnotator,
@@ -1902,6 +1919,7 @@ export {
   ImageViewer,
   ResizeHandleOverlay,
   addShape,
+  canDecodeImage,
   clearShapes,
   cn,
   controlValuesToOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_images",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Image processing pipeline for the hazo ecosystem — Sharp wrapper, thumbnail generation, EXIF handling, and hazo_files integration helper",
   "license": "MIT",
   "type": "module",
@@ -51,15 +51,15 @@
     "zod": "^4.1.12"
   },
   "peerDependencies": {
-    "hazo_core": "^1.2.1",
+    "hazo_core": "^1.3.0",
     "hazo_files": "^3.1.1",
-    "hazo_theme": "^1.0.0",
-    "hazo_ui": "^6.0.0",
+    "hazo_theme": "^1.0.1",
+    "hazo_ui": "^6.3.1",
     "konva": "^10.3.0",
     "lucide-react": "^0.553.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "react-konva": "^19.2.5",
+    "react-konva": "^18.2.16 || ^19.2.5",
     "sharp": "^0.33.0"
   },
   "peerDependenciesMeta": {
@@ -95,12 +95,12 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^22.10.0",
     "@types/react": "^18.3.3",
-    "hazo_core": "^1.2.1",
+    "hazo_core": "^1.3.0",
     "jest": "^30.2.0",
     "jest-environment-node": "^30.2.0",
     "konva": "^10.3.0",
     "lucide-react": "^0.553.0",
-    "react-konva": "^19.2.5",
+    "react-konva": "^18.2.16",
     "ts-jest": "^29.4.5",
     "tsup": "^8.0.0",
     "typescript": "^5.7.2"