hazo_images 1.7.0 → 1.8.1

package/CHANGE_LOG.md

@@ -1,5 +1,30 @@
 # hazo_images Change Log
 
+## 1.8.0 — 2026-07-11
+
+### Added
+
+- **`ImageAnnotator`** — new `hazo_images/ui` component: a mobile-first image markup tool built on a Konva `Stage`/`Layer` (via `react-konva`). Loads a source image (`File | Blob | string`), scales it to fit within a `maxWidth`/`maxHeight` viewport, and renders it as the bottom Konva `Image` layer beneath drawn annotations.
+  - Tools: **pen** (freehand `Line`, points collected on pointer move), **arrow** (drag-stamped `Arrow`), **circle** (drag-stamped `Ellipse`, sized by drag distance) — switched via a large-tap-target toolbar.
+  - **Undo** (pops the last shape) and **Clear** (empties the shape list) buttons.
+  - Drawing is driven by pointer events (not mouse-only assumptions), so it works with touch/stylus input as well as a mouse.
+  - `onSave(blob: Blob) => void` — flattens the stage (source image + markup) via `Konva.Stage#toBlob({ mimeType: 'image/png' })` and calls `onSave` with the resulting PNG `Blob`.
+  - `labels` override object (tool names, undo/clear/save, loading text), matching the `ImageEditorDialog` customization pattern.
+  - New export: `ImageAnnotatorProps`.
+- **`image-annotator-shapes.ts`** — pure, framework-free shape-list helpers (`addShape`, `undoShape`, `clearShapes`) that back `ImageAnnotator`'s state transitions; unit-tested directly (no DOM/Konva required). New exports: `AnnotatorTool`, `AnnotatorShape`, `PenShape`, `ArrowShape`, `CircleShape`.
+- **`konva ^10.3.0`** and **`react-konva ^19.2.5`** added as optional peer dependencies (mirroring the existing `hazo_ui`/`react`/`react-dom` optional-peer pattern) — only required when importing `ImageAnnotator` from `hazo_images/ui`; the rest of the package is unaffected.
+- Demo: `test-app /annotator` page and a `hazo_images_annotator` autotest scenario exercising the pen/arrow/circle → flatten-to-blob path.
+
+### Fixed
+
+- **`createImageProcessHandler` save now overwrites.** The handler's `save` step calls `uploadFile(..., { overwrite: true })`, so re-saving an edited image to the same path replaces it instead of failing with `File already exists`. (Previously a second save of the same filename returned `saved: null` + a `saveError`.)
+
+### Test-app
+
+- `test-app/next.config.js` externalises `dropbox` + `googleapis` (pulled transitively by `hazo_files`) so Turbopack no longer tries to bundle their `node-fetch` requires and fail the build.
+
+---
+
 ## 1.7.0 — 2026-06-22
 ### Added
 - `deriveVariant(sourceFileId, deps, opts)` — fileId-in/fileId-out convenience over `processImage` + `uploadProcessedImage`

package/README.md

@@ -138,7 +138,7 @@ try {
 |---|---|
 | `hazo_images` | Shared types + error classes (isomorphic, no Node deps) |
 | `hazo_images/server` | `processImage`, `uploadProcessedImage`, `createImageProcessHandler` (Node.js only) |
-| `hazo_images/ui` | `ImageUploader`, `ImageViewer`, `ImageEditorDialog` + control-schema helpers (React, client-only) |
+| `hazo_images/ui` | `ImageUploader`, `ImageViewer`, `ImageEditorDialog`, `ImageAnnotator` + control-schema helpers (React, client-only) |
 | `hazo_images/runware` | `createRunwareClient`, `assemblePrompts`, 4 error classes (Node.js only) |
 
 ## Supported formats
@@ -346,6 +346,29 @@ import type { ImageEditControl } from 'hazo_images/ui';
 
 ---
 
+## `<ImageAnnotator>` (`hazo_images/ui`)
+
+Mobile-first image markup tool built on a Konva `Stage`/`Layer` (via `react-konva`). Loads a source image (`File | Blob | string`), scales it to fit a `maxWidth`/`maxHeight` viewport, and lets the user draw over it with **pen** (freehand), **arrow**, and **circle** tools. **Undo** pops the last shape; **Clear** empties them. `onSave` flattens the source image + markup to a PNG `Blob`.
+
+> **`"use client"` required** and **optional peer deps** `konva ^10.3.0` + `react-konva ^19.2.5` must be installed to use it (the rest of the package works without them).
+
+```tsx
+'use client';
+import { ImageAnnotator } from 'hazo_images/ui';
+
+<ImageAnnotator
+  source={file}                 // File | Blob | string (URL)
+  maxWidth={800}
+  maxHeight={600}
+  onSave={(blob) => { /* PNG Blob of image + markup */ }}
+  // labels={{ pen: 'Draw', arrow: 'Arrow', circle: 'Circle', undo: 'Undo', clear: 'Clear', save: 'Save', loading: 'Loading…' }}
+/>
+```
+
+Pure, framework-free shape-list helpers back its state and are exported for reuse: `addShape`, `undoShape`, `clearShapes` (+ types `AnnotatorTool`, `AnnotatorShape`, `PenShape`, `ArrowShape`, `CircleShape`).
+
+---
+
 ## Runware (AI image generation)
 
 `hazo_images/runware` wraps the Runware REST API behind a factory client.
@@ -400,6 +423,8 @@ const { positive, negative } = assemblePrompts({
 | `@1.3` | `blur` Gaussian-blur option on `processImage` |
 | `@1.4` | Extended pipeline options (crop / rotate / flip / flop / grayscale / sharpen / brightness / saturation / hue / tint / quality); `createImageProcessHandler` factory; `hazo_images/ui` (`ImageEditorDialog` + helpers) |
 | `@1.5` | `ImageEditorDialog`: instant CSS live preview for geometry + filters (realtime while dragging); interactive crop (drag + 8 handles) with rect / square / circle shapes; rotate 0/90/180/270 presets; tint color picker; Reset button. Server: crop runs before rotate; `crop.shape: 'circle'` masks to a transparent PNG |
+| `@1.7` | `deriveVariant` — fileId-in / fileId-out convenience over `processImage` + `uploadProcessedImage` |
+| `@1.8` | `ImageAnnotator` — Konva-based image markup (pen / arrow / circle → flatten to PNG); `createImageProcessHandler` save now overwrites an existing file at the same path |
 
 ## License
 

package/dist/server/index.js

@@ -121,13 +121,13 @@ async function processImage(buffer, opts = {}) {
   let forcePng = false;
   let cropBaked = false;
   if (autoRotate) {
-    pipeline = pipeline.autoOrient();
+    pipeline = pipeline.rotate();
   }
   if (crop) {
     let imgW = inputMetadata.width;
     let imgH = inputMetadata.height;
     if (autoRotate) {
-      const oriented = await sharpFn(buffer).autoOrient().metadata();
+      const oriented = await sharpFn(buffer).rotate().metadata();
       imgW = oriented.width ?? imgW;
       imgH = oriented.height ?? imgH;
     }
@@ -165,6 +165,11 @@ async function processImage(buffer, opts = {}) {
     cropBaked = true;
   }
   if (typeof rotate === "number" && rotate !== 0) {
+    if (autoRotate && !cropBaked) {
+      const oriented = await pipeline.png().toBuffer();
+      pipeline = sharpFn(oriented);
+      cropBaked = true;
+    }
     pipeline = pipeline.rotate(rotate);
   }
   if (flip) {
@@ -450,7 +455,7 @@ function createImageProcessHandler(opts) {
           const fm = await getFileManager();
           const safeName = sanitizeFilename(desiredFilename, result.metadata.format, !!parsedOptions.webp);
           const savePath = `${savePathPrefix}/${safeName}`;
-          const up = await fm.uploadFile(result.buffer, savePath);
+          const up = await fm.uploadFile(result.buffer, savePath, { overwrite: true });
           if (!up.success) {
             saveError = up.error ?? "Upload failed";
           } else {

package/dist/ui/index.d.ts

@@ -199,6 +199,100 @@ interface ImageEditorDialogProps {
 }
 declare function ImageEditorDialog({ open, onOpenChange, trigger, file: fileProp, controls, defaultOptions, endpoint, onProcess, onSave, labels, className, headerSlot, footerSlot, debounceMs, }: ImageEditorDialogProps): react_jsx_runtime.JSX.Element;
 
+interface ImageAnnotatorProps {
+    /** Source image — a File/Blob (an object URL is created and revoked internally) or a plain URL string. */
+    src: File | Blob | string;
+    /** Called with the flattened annotation (source image + markup) as a PNG Blob. */
+    onSave?: (blob: Blob) => void;
+    /** Initial stroke color for new shapes. Defaults to a visible red. */
+    strokeColor?: string;
+    /** Initial stroke width for new shapes, in stage pixels. */
+    strokeWidth?: number;
+    /** Maximum viewport width the stage is scaled to fit within. */
+    maxWidth?: number;
+    /** Maximum viewport height the stage is scaled to fit within. */
+    maxHeight?: number;
+    className?: string;
+    labels?: {
+        save?: string;
+        loading?: string;
+    };
+}
+/**
+ * Mobile-first image markup tool: draws freehand (pen), arrow, circle, speech
+ * bubble, and text annotations over a source image on a Konva stage, with
+ * undo/redo/clear, a color + stroke-width picker, and a `Save` action that
+ * flattens the stage (image + markup) to a PNG Blob.
+ *
+ * Drawing is driven entirely by pointer events (not mouse-only assumptions)
+ * so it works with touch and stylus input as well as a mouse. Text and speech
+ * bubbles are typed through an inline editor overlaid on the stage.
+ */
+declare function ImageAnnotator({ src, onSave, strokeColor, strokeWidth, maxWidth, maxHeight, className, labels, }: ImageAnnotatorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure, framework-free shape-list helpers for `ImageAnnotator`.
+ * No DOM / Konva / React dependency — this is what the Jest unit tests cover
+ * directly (see `__tests__/image-annotator-shapes.test.ts`); the component
+ * imports these functions for all of its shape-list state transitions.
+ */
+type AnnotatorTool = 'pen' | 'arrow' | 'circle' | 'bubble' | 'text';
+interface BaseAnnotatorShape {
+    id: string;
+    color: string;
+}
+interface PenShape extends BaseAnnotatorShape {
+    tool: 'pen';
+    strokeWidth: number;
+    /** Flat point list `[x0, y0, x1, y1, ...]` in stage-pixel coordinates. */
+    points: number[];
+}
+interface ArrowShape extends BaseAnnotatorShape {
+    tool: 'arrow';
+    strokeWidth: number;
+    /** `[x1, y1, x2, y2]` — drag-start point to drag-end point. */
+    points: [number, number, number, number];
+}
+interface CircleShape extends BaseAnnotatorShape {
+    tool: 'circle';
+    strokeWidth: number;
+    /** Center point (drag-start). */
+    x: number;
+    y: number;
+    radiusX: number;
+    radiusY: number;
+}
+interface BubbleShape extends BaseAnnotatorShape {
+    tool: 'bubble';
+    strokeWidth: number;
+    /** Top-left corner (in stage-pixel coordinates). */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Text rendered inside the bubble (may be empty while first drawn). */
+    text: string;
+    fontSize: number;
+}
+interface TextShape extends BaseAnnotatorShape {
+    tool: 'text';
+    /** Anchor point (top-left of the text block) in stage-pixel coordinates. */
+    x: number;
+    y: number;
+    text: string;
+    fontSize: number;
+}
+type AnnotatorShape = PenShape | ArrowShape | CircleShape | BubbleShape | TextShape;
+/** Appends a shape to the end of the list. Does not mutate `shapes`. */
+declare function addShape(shapes: AnnotatorShape[], shape: AnnotatorShape): AnnotatorShape[];
+/**
+ * Removes the most recently added shape (stack-style undo).
+ * No-ops (returns the same array reference) on an empty list.
+ */
+declare function undoShape(shapes: AnnotatorShape[]): AnnotatorShape[];
+/** Returns a fresh, empty shape list. */
+declare function clearShapes(): AnnotatorShape[];
+
 /**
  * Pure geometry helpers for the resize-handle overlay.
  * Extracted so they can be unit-tested without a DOM/React environment.
@@ -299,4 +393,4 @@ declare function ResizeHandleOverlay({ box, onResize, onResizeEnd, containerWidt
 
 declare function cn(...parts: Array<string | false | null | undefined>): string;
 
-export { DEFAULT_IMAGE_EDIT_CONTROLS, type ImageEditControls, type ImageEditTab, ImageEditorDialog, type ImageEditorDialogProps, type ImageProcessOptions, type ImageProcessResult, type ImageProcessThumbnail, ImageUploader, type ImageUploaderProps, ImageViewer, type ImageViewerProps, type InputOption, type ProcessFn, type ResizeBox, type ResizeHandle, ResizeHandleOverlay, type ResizeHandleOverlayProps, type TabElement, type ValidationError, type ValidationResult, cn, controlValuesToOptions, defaultControlValues, validate_image_edit_controls };
+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 };

package/dist/ui/index.js

@@ -1271,14 +1271,641 @@ function ImageEditorDialog({
     /* @__PURE__ */ jsx4(DialogContent, { className: cn("max-w-5xl", className), children: dialogBody })
   ] });
 }
+
+// src/ui/image-annotator.tsx
+import * as React5 from "react";
+import { Stage, Layer, Image as KonvaImage, Line, Arrow, Ellipse, Rect, Text, Group } from "react-konva";
+import {
+  Pencil,
+  MoveUpRight,
+  Circle as CircleIcon,
+  MessageSquare,
+  Type as TypeIcon,
+  Undo2,
+  Redo2,
+  Trash2,
+  Check,
+  Palette,
+  SlidersHorizontal
+} from "lucide-react";
+import {
+  Button as Button3,
+  Slider as Slider2,
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  TooltipProvider
+} from "hazo_ui";
+
+// src/ui/image-annotator-shapes.ts
+function addShape(shapes, shape) {
+  return [...shapes, shape];
+}
+function undoShape(shapes) {
+  if (shapes.length === 0) return shapes;
+  return shapes.slice(0, -1);
+}
+function clearShapes() {
+  return [];
+}
+function updateShape(shapes, id, patch) {
+  let changed = false;
+  const next = shapes.map((s) => {
+    if (s.id !== id) return s;
+    changed = true;
+    return { ...s, ...patch };
+  });
+  return changed ? next : shapes;
+}
+function removeShape(shapes, id) {
+  const next = shapes.filter((s) => s.id !== id);
+  return next.length === shapes.length ? shapes : next;
+}
+function undo(shapes, redo2) {
+  if (shapes.length === 0) return { shapes, redo: redo2 };
+  const last = shapes[shapes.length - 1];
+  return { shapes: shapes.slice(0, -1), redo: [...redo2, last] };
+}
+function redo(shapes, redoStack) {
+  if (redoStack.length === 0) return { shapes, redo: redoStack };
+  const last = redoStack[redoStack.length - 1];
+  return { shapes: [...shapes, last], redo: redoStack.slice(0, -1) };
+}
+
+// src/ui/image-annotator.tsx
+import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
+var TOOL_IDS = ["pen", "arrow", "circle", "bubble", "text"];
+var DEFAULT_STROKE_COLOR = "#ef4444";
+var DEFAULT_STROKE_WIDTH = 4;
+var DEFAULT_MAX_WIDTH = 720;
+var DEFAULT_MAX_HEIGHT = 640;
+var PRESET_COLORS = [
+  "#ef4444",
+  "#f59e0b",
+  "#eab308",
+  "#22c55e",
+  "#3b82f6",
+  "#a855f7",
+  "#ffffff",
+  "#000000"
+];
+var BUBBLE_PADDING = 10;
+var fontSizeFor = (strokeWidth) => Math.max(12, Math.round(strokeWidth * 4));
+var TOOL_META = {
+  pen: { Icon: Pencil, label: "Pen", hint: "Freehand pen \u2014 draw by dragging" },
+  arrow: { Icon: MoveUpRight, label: "Arrow", hint: "Arrow \u2014 drag from tail to head" },
+  circle: { Icon: CircleIcon, label: "Circle", hint: "Circle \u2014 drag to size an ellipse" },
+  bubble: { Icon: MessageSquare, label: "Speech bubble", hint: "Speech bubble \u2014 drag to size, then type" },
+  text: { Icon: TypeIcon, label: "Text", hint: "Text \u2014 click to place, then type" }
+};
+function bubbleTailPoints(width, height) {
+  const baseX = Math.min(28, width * 0.5);
+  const tipX = Math.min(14, width * 0.25);
+  const tipY = height + Math.min(22, height * 0.4);
+  return [16, height, baseX, height, tipX, tipY];
+}
+function ShapeNode({
+  shape,
+  onDragEnd
+}) {
+  if (shape.tool === "pen") {
+    return /* @__PURE__ */ jsx5(
+      Line,
+      {
+        points: shape.points,
+        stroke: shape.color,
+        strokeWidth: shape.strokeWidth,
+        lineCap: "round",
+        lineJoin: "round",
+        listening: false
+      }
+    );
+  }
+  if (shape.tool === "arrow") {
+    return /* @__PURE__ */ jsx5(
+      Arrow,
+      {
+        points: shape.points,
+        stroke: shape.color,
+        fill: shape.color,
+        strokeWidth: shape.strokeWidth,
+        pointerLength: Math.max(8, shape.strokeWidth * 3),
+        pointerWidth: Math.max(8, shape.strokeWidth * 3),
+        listening: false
+      }
+    );
+  }
+  if (shape.tool === "circle") {
+    return /* @__PURE__ */ jsx5(
+      Ellipse,
+      {
+        x: shape.x,
+        y: shape.y,
+        radiusX: Math.max(shape.radiusX, 1),
+        radiusY: Math.max(shape.radiusY, 1),
+        stroke: shape.color,
+        strokeWidth: shape.strokeWidth,
+        listening: false
+      }
+    );
+  }
+  if (shape.tool === "text") {
+    return /* @__PURE__ */ jsx5(
+      Text,
+      {
+        x: shape.x,
+        y: shape.y,
+        text: shape.text,
+        fontSize: shape.fontSize,
+        fill: shape.color,
+        draggable: !!onDragEnd,
+        onDragEnd: (e) => onDragEnd?.(shape.id, e.target.x(), e.target.y())
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs4(
+    Group,
+    {
+      x: shape.x,
+      y: shape.y,
+      draggable: !!onDragEnd,
+      onDragEnd: (e) => onDragEnd?.(shape.id, e.target.x(), e.target.y()),
+      children: [
+        /* @__PURE__ */ jsx5(
+          Line,
+          {
+            points: bubbleTailPoints(shape.width, shape.height),
+            closed: true,
+            fill: "#ffffff",
+            stroke: shape.color,
+            strokeWidth: shape.strokeWidth
+          }
+        ),
+        /* @__PURE__ */ jsx5(
+          Rect,
+          {
+            width: shape.width,
+            height: shape.height,
+            cornerRadius: Math.min(16, shape.height / 2),
+            fill: "#ffffff",
+            stroke: shape.color,
+            strokeWidth: shape.strokeWidth
+          }
+        ),
+        /* @__PURE__ */ jsx5(
+          Text,
+          {
+            x: BUBBLE_PADDING,
+            y: BUBBLE_PADDING,
+            width: Math.max(1, shape.width - BUBBLE_PADDING * 2),
+            height: Math.max(1, shape.height - BUBBLE_PADDING * 2),
+            text: shape.text,
+            fontSize: shape.fontSize,
+            fill: shape.color,
+            wrap: "word",
+            listening: false
+          }
+        )
+      ]
+    }
+  );
+}
+function ImageAnnotator({
+  src,
+  onSave,
+  strokeColor = DEFAULT_STROKE_COLOR,
+  strokeWidth = DEFAULT_STROKE_WIDTH,
+  maxWidth = DEFAULT_MAX_WIDTH,
+  maxHeight = DEFAULT_MAX_HEIGHT,
+  className,
+  labels
+}) {
+  const [imageEl, setImageEl] = React5.useState(null);
+  const [naturalSize, setNaturalSize] = React5.useState(null);
+  const [tool, setTool] = React5.useState("pen");
+  const [shapes, setShapes] = React5.useState([]);
+  const [redoStack, setRedoStack] = React5.useState([]);
+  const [drawingShape, setDrawingShape] = React5.useState(null);
+  const [color, setColor] = React5.useState(strokeColor);
+  const [width, setWidth] = React5.useState(strokeWidth);
+  const [editing, setEditing] = React5.useState(null);
+  const [draft, setDraft] = React5.useState("");
+  const drawingRef = React5.useRef(null);
+  const stageRef = React5.useRef(null);
+  const editorRef = React5.useRef(null);
+  const idRef = React5.useRef(0);
+  React5.useEffect(() => {
+    let objectUrl = null;
+    let cancelled = false;
+    const url = typeof src === "string" ? src : objectUrl = URL.createObjectURL(src);
+    const img = new window.Image();
+    img.onload = () => {
+      if (cancelled) return;
+      setImageEl(img);
+      setNaturalSize({ w: img.naturalWidth, h: img.naturalHeight });
+    };
+    img.src = url;
+    return () => {
+      cancelled = true;
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [src]);
+  React5.useEffect(() => {
+    if (editing) editorRef.current?.focus();
+  }, [editing]);
+  const scale = React5.useMemo(() => {
+    if (!naturalSize) return 1;
+    return Math.min(1, maxWidth / naturalSize.w, maxHeight / naturalSize.h);
+  }, [naturalSize, maxWidth, maxHeight]);
+  const stageWidth = naturalSize ? Math.round(naturalSize.w * scale) : 0;
+  const stageHeight = naturalSize ? Math.round(naturalSize.h * scale) : 0;
+  function nextId() {
+    idRef.current += 1;
+    return `shape-${idRef.current}`;
+  }
+  function commitShape(shape) {
+    setShapes((prev) => addShape(prev, shape));
+    setRedoStack([]);
+  }
+  function openEditor(shape, state) {
+    commitShape(shape);
+    setDraft("");
+    setEditing(state);
+  }
+  function finishEditing() {
+    if (!editing) return;
+    const value = draft.trim();
+    if (value === "") {
+      setShapes((prev) => removeShape(prev, editing.id));
+      setRedoStack([]);
+    } else {
+      setShapes((prev) => updateShape(prev, editing.id, { text: value }));
+    }
+    setEditing(null);
+    setDraft("");
+  }
+  function cancelEditing() {
+    if (!editing) return;
+    setShapes((prev) => removeShape(prev, editing.id));
+    setRedoStack([]);
+    setEditing(null);
+    setDraft("");
+  }
+  function handlePointerDown(e) {
+    if (editing) {
+      finishEditing();
+      return;
+    }
+    if (e.target !== e.target.getStage()) return;
+    e.evt?.preventDefault?.();
+    const pos = stageRef.current?.getPointerPosition();
+    if (!pos) return;
+    if (tool === "text") {
+      const shape2 = {
+        id: nextId(),
+        tool: "text",
+        x: pos.x,
+        y: pos.y,
+        text: "",
+        color,
+        fontSize: fontSizeFor(width)
+      };
+      openEditor(shape2, { id: shape2.id, kind: "text", x: pos.x, y: pos.y, fontSize: shape2.fontSize });
+      return;
+    }
+    let shape;
+    if (tool === "pen") {
+      shape = { id: nextId(), tool: "pen", points: [pos.x, pos.y], color, strokeWidth: width };
+    } else if (tool === "arrow") {
+      shape = { id: nextId(), tool: "arrow", points: [pos.x, pos.y, pos.x, pos.y], color, strokeWidth: width };
+    } else if (tool === "circle") {
+      shape = { id: nextId(), tool: "circle", x: pos.x, y: pos.y, radiusX: 0, radiusY: 0, color, strokeWidth: width };
+    } else {
+      shape = { id: nextId(), tool: "bubble", x: pos.x, y: pos.y, width: 0, height: 0, text: "", color, strokeWidth: width, fontSize: fontSizeFor(width) };
+    }
+    drawingRef.current = shape;
+    setDrawingShape(shape);
+  }
+  function handlePointerMove(e) {
+    const current = drawingRef.current;
+    if (!current) return;
+    e.evt?.preventDefault?.();
+    const pos = stageRef.current?.getPointerPosition();
+    if (!pos) return;
+    let next;
+    if (current.tool === "pen") {
+      next = { ...current, points: [...current.points, pos.x, pos.y] };
+    } else if (current.tool === "arrow") {
+      next = { ...current, points: [current.points[0], current.points[1], pos.x, pos.y] };
+    } else if (current.tool === "circle") {
+      next = { ...current, radiusX: Math.abs(pos.x - current.x), radiusY: Math.abs(pos.y - current.y) };
+    } else if (current.tool === "bubble") {
+      const x = Math.min(current.x, pos.x);
+      const y = Math.min(current.y, pos.y);
+      next = { ...current, x, y, width: Math.abs(pos.x - current.x), height: Math.abs(pos.y - current.y) };
+    } else {
+      return;
+    }
+    drawingRef.current = next;
+    setDrawingShape(next);
+  }
+  function handlePointerUp() {
+    const current = drawingRef.current;
+    drawingRef.current = null;
+    setDrawingShape(null);
+    if (!current) return;
+    if (current.tool === "pen" && current.points.length < 4) return;
+    if (current.tool === "arrow" && current.points[0] === current.points[2] && current.points[1] === current.points[3]) return;
+    if (current.tool === "circle" && current.radiusX < 2 && current.radiusY < 2) return;
+    if (current.tool === "bubble") {
+      if (current.width < 24 || current.height < 24) return;
+      openEditor(current, {
+        id: current.id,
+        kind: "bubble",
+        x: current.x,
+        y: current.y,
+        width: current.width,
+        height: current.height,
+        fontSize: current.fontSize
+      });
+      return;
+    }
+    commitShape(current);
+  }
+  function handleShapeDragEnd(id, x, y) {
+    setShapes((prev) => updateShape(prev, id, { x, y }));
+  }
+  function handleUndo() {
+    if (editing) cancelEditing();
+    setShapes((prevShapes) => {
+      const { shapes: nextShapes, redo: redo2 } = undo(prevShapes, redoStack);
+      setRedoStack(redo2);
+      return nextShapes;
+    });
+  }
+  function handleRedo() {
+    setShapes((prevShapes) => {
+      const { shapes: nextShapes, redo: redo2 } = redo(prevShapes, redoStack);
+      setRedoStack(redo2);
+      return nextShapes;
+    });
+  }
+  function handleClear() {
+    if (editing) cancelEditing();
+    setShapes(clearShapes());
+    setRedoStack([]);
+  }
+  function handleSave() {
+    const stage = stageRef.current;
+    if (!stage || !onSave) return;
+    if (editing) finishEditing();
+    window.requestAnimationFrame(() => {
+      void stage.toBlob({
+        mimeType: "image/png",
+        callback: (blob) => {
+          if (blob) onSave(blob);
+        }
+      });
+    });
+  }
+  const resolvedLabels = {
+    save: labels?.save ?? "Save",
+    loading: labels?.loading ?? "Loading image\u2026"
+  };
+  const iconBtn = "h-10 w-10";
+  return /* @__PURE__ */ jsx5(TooltipProvider, { delayDuration: 200, children: /* @__PURE__ */ jsxs4("div", { className: cn("flex flex-col gap-3", className), children: [
+    /* @__PURE__ */ jsxs4("div", { className: "flex flex-wrap items-center gap-1.5", role: "toolbar", "aria-label": "Annotation tools", children: [
+      TOOL_IDS.map((id) => {
+        const { Icon, label, hint } = TOOL_META[id];
+        return /* @__PURE__ */ jsxs4(Tooltip, { children: [
+          /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx5(
+            Button3,
+            {
+              type: "button",
+              size: "icon",
+              variant: tool === id ? "default" : "outline",
+              className: iconBtn,
+              "aria-label": label,
+              "aria-pressed": tool === id,
+              onClick: () => setTool(id),
+              children: /* @__PURE__ */ jsx5(Icon, { size: 18 })
+            }
+          ) }),
+          /* @__PURE__ */ jsx5(TooltipContent, { children: hint })
+        ] }, id);
+      }),
+      /* @__PURE__ */ jsx5("span", { className: "mx-1 h-6 w-px self-center bg-gray-300", "aria-hidden": "true" }),
+      /* @__PURE__ */ jsxs4(Tooltip, { children: [
+        /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsxs4(Popover, { children: [
+          /* @__PURE__ */ jsx5(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsx5(Button3, { type: "button", size: "icon", variant: "outline", className: iconBtn, "aria-label": "Color", children: /* @__PURE__ */ jsx5(Palette, { size: 18, style: { color } }) }) }),
+          /* @__PURE__ */ jsx5(PopoverContent, { className: "w-auto p-3", children: /* @__PURE__ */ jsxs4("div", { className: "flex flex-col gap-3", children: [
+            /* @__PURE__ */ jsx5("div", { className: "grid grid-cols-4 gap-2", children: PRESET_COLORS.map((c) => /* @__PURE__ */ jsx5(
+              "button",
+              {
+                type: "button",
+                "aria-label": `Color ${c}`,
+                onClick: () => setColor(c),
+                className: cn(
+                  "h-7 w-7 rounded-full border border-gray-300",
+                  color.toLowerCase() === c.toLowerCase() && "ring-2 ring-offset-2 ring-gray-800"
+                ),
+                style: { backgroundColor: c }
+              },
+              c
+            )) }),
+            /* @__PURE__ */ jsxs4("label", { className: "flex items-center gap-2 text-sm", children: [
+              /* @__PURE__ */ jsx5("span", { className: "text-gray-600", children: "Custom" }),
+              /* @__PURE__ */ jsx5(
+                "input",
+                {
+                  type: "color",
+                  value: color,
+                  onChange: (e) => setColor(e.target.value),
+                  className: "h-7 w-10 cursor-pointer rounded border border-gray-300 bg-transparent p-0"
+                }
+              )
+            ] })
+          ] }) })
+        ] }) }),
+        /* @__PURE__ */ jsx5(TooltipContent, { children: "Color" })
+      ] }),
+      /* @__PURE__ */ jsxs4(Tooltip, { children: [
+        /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsxs4(Popover, { children: [
+          /* @__PURE__ */ jsx5(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsx5(Button3, { type: "button", size: "icon", variant: "outline", className: iconBtn, "aria-label": "Stroke width", children: /* @__PURE__ */ jsx5(SlidersHorizontal, { size: 18 }) }) }),
+          /* @__PURE__ */ jsx5(PopoverContent, { className: "w-56 p-4", children: /* @__PURE__ */ jsxs4("div", { className: "flex flex-col gap-3", children: [
+            /* @__PURE__ */ jsxs4("div", { className: "flex items-center justify-between text-sm text-gray-600", children: [
+              /* @__PURE__ */ jsx5("span", { children: "Size" }),
+              /* @__PURE__ */ jsxs4("span", { className: "font-medium text-gray-900", children: [
+                width,
+                "px"
+              ] })
+            ] }),
+            /* @__PURE__ */ jsx5(
+              Slider2,
+              {
+                min: 1,
+                max: 30,
+                step: 1,
+                value: [width],
+                onValueChange: ([v]) => setWidth(v),
+                "aria-label": "Stroke width"
+              }
+            ),
+            /* @__PURE__ */ jsx5("div", { className: "flex items-center justify-center", children: /* @__PURE__ */ jsx5(
+              "span",
+              {
+                className: "rounded-full",
+                style: { width, height: width, backgroundColor: color, minWidth: 4, minHeight: 4 }
+              }
+            ) })
+          ] }) })
+        ] }) }),
+        /* @__PURE__ */ jsx5(TooltipContent, { children: "Stroke width" })
+      ] }),
+      /* @__PURE__ */ jsx5("span", { className: "mx-1 h-6 w-px self-center bg-gray-300", "aria-hidden": "true" }),
+      /* @__PURE__ */ jsxs4(Tooltip, { children: [
+        /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx5(
+          Button3,
+          {
+            type: "button",
+            size: "icon",
+            variant: "outline",
+            className: iconBtn,
+            "aria-label": "Undo",
+            disabled: shapes.length === 0 && !editing,
+            onClick: handleUndo,
+            children: /* @__PURE__ */ jsx5(Undo2, { size: 18 })
+          }
+        ) }),
+        /* @__PURE__ */ jsx5(TooltipContent, { children: "Undo" })
+      ] }),
+      /* @__PURE__ */ jsxs4(Tooltip, { children: [
+        /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx5(
+          Button3,
+          {
+            type: "button",
+            size: "icon",
+            variant: "outline",
+            className: iconBtn,
+            "aria-label": "Redo",
+            disabled: redoStack.length === 0,
+            onClick: handleRedo,
+            children: /* @__PURE__ */ jsx5(Redo2, { size: 18 })
+          }
+        ) }),
+        /* @__PURE__ */ jsx5(TooltipContent, { children: "Redo" })
+      ] }),
+      /* @__PURE__ */ jsxs4(Tooltip, { children: [
+        /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx5(
+          Button3,
+          {
+            type: "button",
+            size: "icon",
+            variant: "outline",
+            className: iconBtn,
+            "aria-label": "Clear",
+            disabled: shapes.length === 0 && !editing,
+            onClick: handleClear,
+            children: /* @__PURE__ */ jsx5(Trash2, { size: 18 })
+          }
+        ) }),
+        /* @__PURE__ */ jsx5(TooltipContent, { children: "Clear all" })
+      ] }),
+      onSave && /* @__PURE__ */ jsxs4(Tooltip, { children: [
+        /* @__PURE__ */ jsx5(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsxs4(
+          Button3,
+          {
+            type: "button",
+            className: "ml-auto h-10 gap-1.5 px-4",
+            disabled: !imageEl,
+            onClick: handleSave,
+            children: [
+              /* @__PURE__ */ jsx5(Check, { size: 18 }),
+              resolvedLabels.save
+            ]
+          }
+        ) }),
+        /* @__PURE__ */ jsx5(TooltipContent, { children: "Flatten image + markup to PNG" })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx5(
+      "div",
+      {
+        className: "relative flex items-center justify-center overflow-hidden rounded-lg bg-gray-900",
+        style: { minHeight: stageHeight || void 0, touchAction: "none" },
+        children: imageEl ? /* @__PURE__ */ jsxs4("div", { className: "relative", style: { width: stageWidth, height: stageHeight }, children: [
+          /* @__PURE__ */ jsxs4(
+            Stage,
+            {
+              ref: stageRef,
+              width: stageWidth,
+              height: stageHeight,
+              onPointerDown: handlePointerDown,
+              onPointerMove: handlePointerMove,
+              onPointerUp: handlePointerUp,
+              style: { touchAction: "none" },
+              children: [
+                /* @__PURE__ */ jsx5(Layer, { children: /* @__PURE__ */ jsx5(KonvaImage, { image: imageEl, width: stageWidth, height: stageHeight, listening: false }) }),
+                /* @__PURE__ */ jsxs4(Layer, { children: [
+                  shapes.map(
+                    (shape) => (
+                      // Hide the shape currently being typed — the overlay shows its text instead.
+                      editing?.id === shape.id ? null : /* @__PURE__ */ jsx5(ShapeNode, { shape, onDragEnd: handleShapeDragEnd }, shape.id)
+                    )
+                  ),
+                  drawingShape && /* @__PURE__ */ jsx5(ShapeNode, { shape: drawingShape })
+                ] })
+              ]
+            }
+          ),
+          editing && /* @__PURE__ */ jsx5(
+            "textarea",
+            {
+              ref: editorRef,
+              value: draft,
+              onChange: (e) => setDraft(e.target.value),
+              onBlur: finishEditing,
+              onKeyDown: (e) => {
+                if (e.key === "Enter" && !e.shiftKey) {
+                  e.preventDefault();
+                  finishEditing();
+                } else if (e.key === "Escape") {
+                  e.preventDefault();
+                  cancelEditing();
+                }
+              },
+              placeholder: "Type\u2026",
+              className: "absolute resize-none rounded border border-dashed border-gray-400 bg-white/90 p-1 leading-tight shadow-sm outline-none",
+              style: {
+                left: editing.x + (editing.kind === "bubble" ? BUBBLE_PADDING : 0),
+                top: editing.y + (editing.kind === "bubble" ? BUBBLE_PADDING : 0),
+                width: editing.kind === "bubble" ? Math.max(40, (editing.width ?? 0) - BUBBLE_PADDING * 2) : Math.max(120, stageWidth - editing.x - 8),
+                height: editing.kind === "bubble" ? Math.max(24, (editing.height ?? 0) - BUBBLE_PADDING * 2) : void 0,
+                color,
+                fontSize: editing.fontSize
+              }
+            }
+          )
+        ] }) : /* @__PURE__ */ jsx5("span", { className: "p-8 text-sm text-gray-400", children: resolvedLabels.loading })
+      }
+    )
+  ] }) });
+}
 export {
   DEFAULT_IMAGE_EDIT_CONTROLS,
+  ImageAnnotator,
   ImageEditorDialog,
   ImageUploader,
   ImageViewer,
   ResizeHandleOverlay,
+  addShape,
+  clearShapes,
   cn,
   controlValuesToOptions,
   defaultControlValues,
+  undoShape,
   validate_image_edit_controls
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_images",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Image processing pipeline for the hazo ecosystem — Sharp wrapper, thumbnail generation, EXIF handling, and hazo_files integration helper",
   "license": "MIT",
   "type": "module",
@@ -51,28 +51,44 @@
     "zod": "^4.1.12"
   },
   "peerDependencies": {
-    "hazo_core": "^1.2.0",
-    "hazo_files": "^3.0.0",
-    "hazo_ui": "^4.4.0",
+    "hazo_core": "^1.2.1",
+    "hazo_files": "^3.1.1",
+    "hazo_theme": "^1.0.0",
+    "hazo_ui": "^6.0.0",
+    "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": "^18.2.16 || ^19.2.5",
     "sharp": "^0.33.0"
   },
   "peerDependenciesMeta": {
     "hazo_files": {
       "optional": true
     },
+    "lucide-react": {
+      "optional": true
+    },
     "hazo_ui": {
       "optional": true
     },
+    "konva": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
     "react-dom": {
       "optional": true
     },
+    "react-konva": {
+      "optional": true
+    },
     "sharp": {
       "optional": true
+    },
+    "hazo_theme": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -82,6 +98,9 @@
     "hazo_core": "^1.2.1",
     "jest": "^30.2.0",
     "jest-environment-node": "^30.2.0",
+    "konva": "^10.3.0",
+    "lucide-react": "^0.553.0",
+    "react-konva": "^18.2.16",
     "ts-jest": "^29.4.5",
     "tsup": "^8.0.0",
     "typescript": "^5.7.2"