hazo_images 1.2.1 → 1.8.0

package/CHANGE_LOG.md

@@ -1,5 +1,95 @@
 # 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`
+- New exports: `DeriveVariantOptions`, `DeriveVariantDeps`, `DeriveVariantResult`
+- Autotest scenario + `/derive-variant` test-app page
+
+---
+
+## 1.5.0 — 2026-06-21
+
+### Added
+
+- **Instant live preview for geometry + filters.** The `ImageEditorDialog` stage now renders **rotate**, **flip**, **flop**, **blur**, **brightness**, **saturation**, **hue**, **grayscale**, and **tint** as a CSS transform/filter/blend on the stage image, so they update truly in realtime while dragging (no server round-trip lag). These controls are omitted from the debounced server preview to avoid double-applying; **Save** still bakes them server-side via Sharp, so output is exact. `sharpen`, crop, and output (webp / quality / max-dimension) remain server-rendered. (Earlier in 1.5.0 every control went through the debounced server preview, which made sliders feel like they only updated on release.)
+  - **Tint preview** uses a `mix-blend-mode: color` overlay (preserves the image's luminance while applying the tint's hue/chroma — approximates Sharp's `tint()`).
+- **Interactive crop with shapes.** Crop is now a toggle mode (**Crop image** / **Done**) with a draggable box and 8 resize handles (4 corners + 4 edges), replacing the draw-only `CropOverlay`. A shape picker offers **rectangle**, **square** (constrained 1:1), and **circle** (constrained 1:1; corners masked transparent → PNG output). The box renders a circular outline for the circle shape.
+- **Rotate quarter-turn presets.** The rotate control shows **0° / 90° / 180° / 270°** buttons beside the slider (active preset highlighted) for one-click quarter turns.
+- **Tint color picker.** New `'color'` control `input_type` (added to the control schema + validator). The `tint` control renders a native color swatch + editable hex field + **Clear** button instead of a plain text box.
+- **Reset button.** Restores every control to its default and clears the crop region / shape, keeping the loaded image; now rendered with an outlined button border. New `labels.reset` / `labels.crop` / `labels.cropDone` overrides.
+- **`crop.shape`** option on `ProcessImageOptions` (`'rect' | 'square' | 'circle'`, default `'rect'`). `'circle'` composites a circular alpha mask and forces PNG output (overrides `webp` / `jpeg`).
+
+### Changed
+
+- **Crop now runs before rotate** in the server pipeline, clamped against the **auto-oriented** input dimensions. The crop is baked to a lossless intermediate buffer first, because Sharp otherwise applies `rotate` before a pre-resize `extract` regardless of call order — which cropped the wrong region for rotate+crop combinations. The crop is the region the user drew on the (auto-oriented) original; rotate/flip apply to the result.
+- **`ImageEditorDialog` — "Studio" side-rail layout.** The dialog body was a single vertical stack with the image preview rendered last (below all controls). It is now a two-pane layout: a large image **stage** on the left (`bg-gray-900`, `min-h` 52–64vh, `object-contain`) and a compact scrollable **controls rail** on the right (`lg:w-80`) holding the Geometry / Filters / Output tabs.
+  - Stage shows the live processed **Preview** when available, else the **Original** (badge top-left); a processing badge appears top-right while a render is in flight.
+  - Control rows are stacked (label above input) to read well in the narrow rail; slider/switch/select behaviour is unchanged.
+  - Dialog widened `max-w-3xl` → `max-w-5xl`; panes stack vertically below `lg`. The standalone `ImageViewer` (before/after grid) is no longer used inside the dialog but remains a separate `hazo_images/ui` export.
+  - Demo: `test-app /editor` exercises the new layout (no API change).
+
+---
+
+## 1.4.0 — 2026-06-20
+
+### Added
+
+- **Extended pipeline options** on `processImage` / `ProcessImageOptions` (all optional, default no-op):
+  - Geometry: `crop` (extract region, clamped to input dims), `rotate` (degrees), `flip` (vertical), `flop` (horizontal).
+  - Filters: `grayscale`, `sharpen` (sigma), `brightness` (modulate multiplier), `saturation` (modulate multiplier), `hue` (degrees), `tint` (hex).
+  - Output: `quality` (1–100, applied to WebP + JPEG output).
+  - Pipeline order documented: autoOrient → rotate → flip/flop → withMetadata? → crop → resize → modulate → grayscale → sharpen/blur → tint → format+quality → thumbnails.
+- **`createImageProcessHandler(opts?)`** — framework-agnostic `(request: Request) => Promise<Response>` factory exported from `hazo_images/server`. Parses multipart `FormData` (`image` File + `options` JSON + `save` flag + optional `filename`). Returns JSON `{ ok, metadata, preview, originalPreview, thumbnails, saved, saveError? }` or `{ ok: false, error, errorType }` (UnsupportedFormatError → 400, ImageProcessingError → 422, other → 500). Exports companion types `CreateImageProcessHandlerOptions` and `ImageProcessHandlerFileManager`.
+- **`hazo_images/ui`** — real React components (was an empty reserved stub):
+  - `ImageUploader` — drag-and-drop / file-picker input component.
+  - `ImageViewer` — before/after preview panel.
+  - `ImageEditorDialog` — headline component: `hazo_ui` Dialog + Geometry / Filters / Output tabs of Slider / Switch / Select / color controls, debounced live preview, Save action (persists via the Phase-2 handler). Customisation: `controls` declarative schema, `defaultOptions`, `endpoint` | `onProcess`, `onSave`, `labels`, `headerSlot` / `footerSlot`, `className`, `debounceMs`.
+  - Helper exports: `DEFAULT_IMAGE_EDIT_CONTROLS`, `defaultControlValues`, `controlValuesToOptions`, `validate_image_edit_controls`.
+  - Control-schema types: `ImageEditControl` and related interfaces (source in `src/ui/controls-schema.ts`).
+- **`hazo_ui ^4.4.0`** added as an optional peer dependency (used only by `hazo_images/ui`; server pipeline + handler never import `hazo_ui`).
+
+### Notes
+
+- `hazo_images/ui` is now a built sub-export with real components. The control-schema types were **copied** (not moved) from the build-excluded `src/components/` into `src/ui/controls-schema.ts`.
+- `src/components/` remains build-excluded and MUST stay in the repo — see "Deferred Components" in `CLAUDE.md`.
+- `createImageProcessHandler` returns a plain `Response` with no hazo_api envelopes — consistent with D-2.1.0-01.
+
+---
+
+## 1.3.0 — 2026-06-20
+
+### Added
+
+- `blur?: number` option on `processImage` — Gaussian blur sigma (applied after `sharpen` in the pipeline, before `tint`).
+
+---
+
 ## 1.2.0 — 2026-05-30
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # hazo_images
 
-Server-side image processing pipeline for the hazo ecosystem. Sharp wrapper with EXIF handling, auto-rotate, resize, and thumbnail generation. Composes with `hazo_files` via an integration helper.
+Image processing pipeline for the hazo ecosystem. Sharp wrapper with EXIF handling, auto-rotate, resize, thumbnail generation, and a full suite of geometry / filter / output controls. Composes with `hazo_files` via an integration helper. Ships a framework-agnostic route-handler factory and, since `@1.4.0`, a real React editor dialog in `hazo_images/ui`.
 
 Image **storage** is owned by `hazo_files`. This package handles **processing only**.
 
@@ -17,6 +17,9 @@ npm install sharp
 
 # Optional — only needed if using uploadProcessedImage
 npm install hazo_files
+
+# Optional — only needed if using hazo_images/ui components
+npm install hazo_ui react react-dom
 ```
 
 ## Usage
@@ -134,8 +137,9 @@ try {
 | Import | Contents |
 |---|---|
 | `hazo_images` | Shared types + error classes (isomorphic, no Node deps) |
-| `hazo_images/server` | `processImage`, `uploadProcessedImage` (Node.js only) |
-| `hazo_images/ui` | Reserved for `@1.1+` UI components (empty in `@1.0`) |
+| `hazo_images/server` | `processImage`, `uploadProcessedImage`, `createImageProcessHandler` (Node.js 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
 
@@ -150,8 +154,220 @@ interface ProcessImageOptions {
   maxDimension?: number;  // default: 4096  — longest side; 0 = disable resize
   webp?: boolean;         // default: false — transcode to WebP
   thumbnails?: number[];  // default: []    — pixel sizes for longest side
+
+  // Geometry (Phase 1)
+  crop?: {                // Extract region — applied BEFORE rotate, clamped to (auto-oriented) input dims
+    left: number; top: number; width: number; height: number;
+    shape?: 'rect' | 'square' | 'circle'; // 'circle' masks corners transparent & forces PNG output
+  };
+  rotate?: number;        // Rotate by degrees (Sharp fills gaps with black)
+  flip?: boolean;         // Flip vertically (top↔bottom)
+  flop?: boolean;         // Flop horizontally (left↔right)
+
+  // Filters (Phase 1)
+  grayscale?: boolean;    // Convert to greyscale
+  sharpen?: number;       // Unsharp-mask sigma (e.g. 1.5)
+  blur?: number;          // Gaussian blur sigma (e.g. 1.0)
+  brightness?: number;    // Modulate multiplier — 1 = unchanged (e.g. 1.2 = +20%)
+  saturation?: number;    // Modulate multiplier — 1 = unchanged (e.g. 0 = greyscale)
+  hue?: number;           // Hue rotation in degrees (e.g. 180 = complementary)
+  tint?: string;          // Hex colour tint applied via Sharp's tint() (e.g. "#ff0000")
+
+  // Output (Phase 1)
+  quality?: number;       // JPEG / WebP quality 1–100 (default: 80)
+}
+```
+
+### Pipeline order
+
+The Sharp pipeline applies operations in this order:
+
+1. `autoOrient` — apply EXIF orientation
+2. `extract` — `crop` region (clamped to the auto-oriented input dims). For `shape: 'circle'` a circular alpha mask is composited (corners → transparent) and output is forced to PNG. The crop is baked to an intermediate buffer so the following rotate is applied **after** the crop (Sharp otherwise reorders `rotate` before a pre-resize `extract`).
+3. `rotate` — explicit rotation (degrees)
+4. `flip` / `flop` — vertical / horizontal mirror
+5. `withMetadata(false)` — strip EXIF (when `stripExif: true`)
+6. `resize` — longest side to `maxDimension` (maintaining aspect ratio)
+7. `modulate` — `brightness`, `saturation`, `hue`
+8. `grayscale`
+9. `sharpen` / `blur`
+10. `tint`
+11. Format encode — `webp` / `jpeg` / `png` with `quality` (PNG forced for circular crops)
+12. Thumbnail generation (each thumbnail runs the same pipeline with a different `resize` target)
+
+## Route handler factory (`createImageProcessHandler`)
+
+`createImageProcessHandler` returns a framework-agnostic `(request: Request) => Promise<Response>` suitable for mounting directly as a Next.js App-Router route handler (or any other WHATWG `Request`/`Response` environment).
+
+```ts
+// app/api/images/process/route.ts
+import { createImageProcessHandler } from 'hazo_images/server';
+import { createInitializedFileManager } from 'hazo_files/server';
+
+export const POST = createImageProcessHandler({
+  getFileManager: async () =>
+    createInitializedFileManager({ config: { provider: 'local', local: { basePath: './uploads' } } }),
+  maxUploadBytes: 15 * 1024 * 1024,  // default: 15 MB
+  allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  previewMaxDimension: 1600,          // default: 1600 — size of preview returned in response
+  savePathPrefix: '/hazo-images',     // default: '/hazo-images'
+});
+```
+
+### Request format (multipart `FormData`)
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `image` | `File` | yes | The source image file |
+| `options` | JSON string | no | `ProcessImageOptions` to apply |
+| `save` | `"true"` | no | Persist via the file manager |
+| `filename` | string | no | Override the stored filename (otherwise uses uploaded filename) |
+
+### Response JSON
+
+**Success:**
+```json
+{
+  "ok": true,
+  "metadata": { "width": 1200, "height": 800, "format": "jpeg" },
+  "preview": "data:image/jpeg;base64,…",
+  "originalPreview": "data:image/jpeg;base64,…",
+  "thumbnails": [{ "size": 256, "format": "jpeg", "dataUrl": "data:image/jpeg;base64,…" }],
+  "saved": { "path": "/hazo-images/photo.jpg", "url": "https://…" }
 }
 ```
+`saved` is `null` when `save` is not `"true"`. `saveError` (string) is present if the file manager threw but the preview still succeeded.
+
+**Error:**
+```json
+{ "ok": false, "error": "Unsupported image format", "errorType": "UnsupportedFormatError" }
+```
+HTTP status: `UnsupportedFormatError` → 400, `ImageProcessingError` → 422, other → 500.
+
+### Types
+
+```ts
+import type {
+  CreateImageProcessHandlerOptions,
+  ImageProcessHandlerFileManager,
+} from 'hazo_images/server';
+```
+
+`ImageProcessHandlerFileManager` is a duck-typed interface (`uploadFile` method) — any `hazo_files` FileManager satisfies it.
+
+---
+
+## `<ImageEditorDialog>` (`hazo_images/ui`)
+
+A full-featured client-side image editor dialog built on `hazo_ui` (shadcn/ui primitives). Requires `hazo_ui ^4.4.0`, `react`, and `react-dom` (all optional peers — install them only if you use this subpath).
+
+> **`"use client"` required.** All exports from `hazo_images/ui` are client components. Import them inside `"use client"` files or dynamic-import with `ssr: false`.
+
+### Minimal usage (uncontrolled, default endpoint)
+
+```tsx
+'use client';
+import { ImageEditorDialog } from 'hazo_images/ui';
+
+export function MyPage() {
+  return (
+    <ImageEditorDialog
+      imageUrl="/uploads/photo.jpg"
+      endpoint="/api/images/process"
+      onSave={(result) => console.log('saved', result.saved?.path)}
+    />
+  );
+}
+```
+
+The dialog talks to the `endpoint` URL with the multipart format expected by `createImageProcessHandler`. A live before/after preview updates after each debounced control change.
+
+### Customised controls
+
+```tsx
+import { ImageEditorDialog, DEFAULT_IMAGE_EDIT_CONTROLS } from 'hazo_images/ui';
+
+<ImageEditorDialog
+  imageUrl="/uploads/photo.jpg"
+  endpoint="/api/images/process"
+  controls={[
+    ...DEFAULT_IMAGE_EDIT_CONTROLS,
+    { key: 'tint', label: 'Tint', type: 'color', tab: 'filters', default: '#ffffff' },
+  ]}
+  defaultOptions={{ quality: 90, maxDimension: 2000 }}
+  debounceMs={400}
+  labels={{ save: 'Export', cancel: 'Discard' }}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `imageUrl` | `string` | — | Source image URL (displayed as "before") |
+| `endpoint` | `string` | — | URL of `createImageProcessHandler` route (use this **or** `onProcess`) |
+| `onProcess` | `(opts: ProcessImageOptions) => Promise<...>` | — | Custom processing callback instead of `endpoint` |
+| `onSave` | `(result) => void` | — | Called after a successful save |
+| `controls` | `ImageEditControl[]` | `DEFAULT_IMAGE_EDIT_CONTROLS` | Declarative control schema (see below) |
+| `defaultOptions` | `ProcessImageOptions` | `{}` | Options pre-applied on open |
+| `debounceMs` | `number` | `300` | Debounce delay (ms) before sending preview request |
+| `labels` | `Partial<EditorLabels>` | — | Override button / tab label strings |
+| `headerSlot` | `React.ReactNode` | — | Extra content in the dialog header |
+| `footerSlot` | `React.ReactNode` | — | Extra content in the dialog footer |
+| `className` | `string` | — | Extra class on the dialog container |
+
+The dialog is organised into three tabs: **Geometry** (crop / rotate / flip / flop), **Filters** (grayscale / sharpen / blur / brightness / saturation / hue / tint), and **Output** (format / quality / resize).
+
+The stage shows a **live preview**. Geometry (**rotate** / **flip** / **flop**) and most filters (**blur** / **brightness** / **saturation** / **hue** / **grayscale** / **tint**) render **instantly** as a CSS transform / filter / blend on the stage image — they update in realtime while you drag, with no server round-trip. These are omitted from the debounced (`debounceMs`) server preview to avoid double-applying; **Save** bakes them server-side via Sharp so output is exact. `sharpen`, crop, and output (format / quality / resize) are reflected via the debounced server preview.
+
+The **rotate** control shows **0° / 90° / 180° / 270°** preset buttons beside the slider for one-click quarter turns. The **tint** control is a native color picker (swatch + editable hex + **Clear**).
+
+**Crop** is a toggle mode on the Geometry tab: click **Crop image** to swap the stage to the original with a draggable box (8 resize handles) and a shape picker — **rectangle**, **square** (1:1), or **circle** (1:1, masked to a transparent-cornered PNG) — then **Done** to return to the live preview. A **Reset** button (outlined) restores every control to its default and clears the crop, keeping the loaded image. Override the `Reset`, `Crop image`, and `Done` strings via `labels.reset` / `labels.crop` / `labels.cropDone`.
+
+### Helper exports
+
+```ts
+import {
+  DEFAULT_IMAGE_EDIT_CONTROLS, // ImageEditControl[] — the default control schema
+  defaultControlValues,        // Record<string, unknown> — zeroed defaults
+  controlValuesToOptions,      // (values) => ProcessImageOptions
+  validate_image_edit_controls // (controls) => string[] — validation errors
+} from 'hazo_images/ui';
+```
+
+### Control schema types
+
+```ts
+import type { ImageEditControl } from 'hazo_images/ui';
+// Each control: { key, label, type, tab, default, min?, max?, step? }
+// type: 'slider' | 'switch' | 'select' | 'color'
+// tab: 'geometry' | 'filters' | 'output'
+```
+
+---
+
+## `<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)
 
@@ -202,8 +418,13 @@ const { positive, negative } = assemblePrompts({
 | Version | Scope |
 |---|---|
 | `@1.0` | Server pipeline: `processImage` + `uploadProcessedImage` |
-| `@1.1+` | UI: redesigned AI-edit component, crop/rotate/filter primitives |
-| `@1.2+` | Face detection via `face-api-node` (speculative, non-committed) |
+| `@1.1` | Wave 2 standardisation: `HazoError` subclasses, structured logging, INI config |
+| `@1.2` | `hazo_images/runware` sub-export (AI image generation) |
+| `@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/index.d.ts

@@ -6,6 +6,82 @@ interface ProcessImageOptions {
     maxDimension?: number;
     webp?: boolean;
     thumbnails?: number[];
+    blur?: number;
+    /**
+     * Crop (extract) a region from the image. Crop is applied BEFORE rotate/flip,
+     * clamped to the auto-oriented input dimensions — out-of-bounds values are
+     * silently adjusted rather than thrown. { left, top, width, height } in pixels.
+     *
+     * `shape` controls the output silhouette (default 'rect'):
+     *   - 'rect'   — free rectangular region.
+     *   - 'square' — caller supplies an equal-sided box; output is a square rectangle.
+     *   - 'circle' — a circular alpha mask is applied (corners become transparent)
+     *                and the output format is forced to PNG (overrides webp/jpeg).
+     */
+    crop?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        shape?: 'rect' | 'square' | 'circle';
+    };
+    /**
+     * Rotate the image by the given number of degrees clockwise.
+     * 0 (or omitting the option) skips rotation.
+     * Note: `autoRotate` already handles EXIF orientation — this is an explicit
+     * additional rotation on top of that.
+     */
+    rotate?: number;
+    /**
+     * Flip the image vertically (mirror across the horizontal axis).
+     * Default: false (no flip).
+     */
+    flip?: boolean;
+    /**
+     * Flop the image horizontally (mirror across the vertical axis).
+     * Default: false (no flop).
+     */
+    flop?: boolean;
+    /**
+     * Convert the image to grayscale.
+     * Default: false.
+     */
+    grayscale?: boolean;
+    /**
+     * Apply an unsharp-mask sharpen with the given sigma value (0.000001–10).
+     * Higher values = stronger sharpening. Omit or 0 to skip.
+     */
+    sharpen?: number;
+    /**
+     * Adjust brightness using Sharp's modulate operation.
+     * Multiplier: 1 = unchanged, <1 = darker, >1 = brighter.
+     * Omit to leave brightness unchanged.
+     */
+    brightness?: number;
+    /**
+     * Adjust saturation (color intensity) using Sharp's modulate operation.
+     * Multiplier: 1 = unchanged, <1 = less saturated, >1 = more saturated.
+     * Omit to leave saturation unchanged.
+     */
+    saturation?: number;
+    /**
+     * Rotate the hue of every pixel using Sharp's modulate operation.
+     * Degrees: 0 = unchanged, positive = clockwise rotation around the color wheel.
+     * Omit to leave hue unchanged.
+     */
+    hue?: number;
+    /**
+     * Tint the image with a hex color string, e.g. "#ff0000" for red.
+     * Omit to skip tinting.
+     */
+    tint?: string;
+    /**
+     * Output quality for lossy formats (1–100).
+     * Applied to WebP output (always) and JPEG output (when input format is jpeg/jpg).
+     * PNG and other lossless formats ignore this option.
+     * Omit to use Sharp's default quality per format.
+     */
+    quality?: number;
 }
 interface ProcessImageResult {
     buffer: Buffer;

package/dist/runware/index.js

@@ -13,31 +13,26 @@ function rng() {
   return rnds8Pool.slice(poolPtr, poolPtr += 16);
 }
 
-// ../node_modules/uuid/dist/esm-node/regex.js
-var regex_default = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i;
-
-// ../node_modules/uuid/dist/esm-node/validate.js
-function validate(uuid) {
-  return typeof uuid === "string" && regex_default.test(uuid);
-}
-var validate_default = validate;
-
 // ../node_modules/uuid/dist/esm-node/stringify.js
 var byteToHex = [];
 for (let i = 0; i < 256; ++i) {
-  byteToHex.push((i + 256).toString(16).substr(1));
+  byteToHex.push((i + 256).toString(16).slice(1));
 }
-function stringify(arr, offset = 0) {
-  const uuid = (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
-  if (!validate_default(uuid)) {
-    throw TypeError("Stringified UUID is invalid");
-  }
-  return uuid;
+function unsafeStringify(arr, offset = 0) {
+  return byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]];
 }
-var stringify_default = stringify;
+
+// ../node_modules/uuid/dist/esm-node/native.js
+import crypto2 from "crypto";
+var native_default = {
+  randomUUID: crypto2.randomUUID
+};
 
 // ../node_modules/uuid/dist/esm-node/v4.js
 function v4(options, buf, offset) {
+  if (native_default.randomUUID && !buf && !options) {
+    return native_default.randomUUID();
+  }
   options = options || {};
   const rnds = options.random || (options.rng || rng)();
   rnds[6] = rnds[6] & 15 | 64;
@@ -49,7 +44,7 @@ function v4(options, buf, offset) {
     }
     return buf;
   }
-  return stringify_default(rnds);
+  return unsafeStringify(rnds);
 }
 var v4_default = v4;
 

package/dist/server/index.d.ts

@@ -6,6 +6,82 @@ interface ProcessImageOptions {
     maxDimension?: number;
     webp?: boolean;
     thumbnails?: number[];
+    blur?: number;
+    /**
+     * Crop (extract) a region from the image. Crop is applied BEFORE rotate/flip,
+     * clamped to the auto-oriented input dimensions — out-of-bounds values are
+     * silently adjusted rather than thrown. { left, top, width, height } in pixels.
+     *
+     * `shape` controls the output silhouette (default 'rect'):
+     *   - 'rect'   — free rectangular region.
+     *   - 'square' — caller supplies an equal-sided box; output is a square rectangle.
+     *   - 'circle' — a circular alpha mask is applied (corners become transparent)
+     *                and the output format is forced to PNG (overrides webp/jpeg).
+     */
+    crop?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        shape?: 'rect' | 'square' | 'circle';
+    };
+    /**
+     * Rotate the image by the given number of degrees clockwise.
+     * 0 (or omitting the option) skips rotation.
+     * Note: `autoRotate` already handles EXIF orientation — this is an explicit
+     * additional rotation on top of that.
+     */
+    rotate?: number;
+    /**
+     * Flip the image vertically (mirror across the horizontal axis).
+     * Default: false (no flip).
+     */
+    flip?: boolean;
+    /**
+     * Flop the image horizontally (mirror across the vertical axis).
+     * Default: false (no flop).
+     */
+    flop?: boolean;
+    /**
+     * Convert the image to grayscale.
+     * Default: false.
+     */
+    grayscale?: boolean;
+    /**
+     * Apply an unsharp-mask sharpen with the given sigma value (0.000001–10).
+     * Higher values = stronger sharpening. Omit or 0 to skip.
+     */
+    sharpen?: number;
+    /**
+     * Adjust brightness using Sharp's modulate operation.
+     * Multiplier: 1 = unchanged, <1 = darker, >1 = brighter.
+     * Omit to leave brightness unchanged.
+     */
+    brightness?: number;
+    /**
+     * Adjust saturation (color intensity) using Sharp's modulate operation.
+     * Multiplier: 1 = unchanged, <1 = less saturated, >1 = more saturated.
+     * Omit to leave saturation unchanged.
+     */
+    saturation?: number;
+    /**
+     * Rotate the hue of every pixel using Sharp's modulate operation.
+     * Degrees: 0 = unchanged, positive = clockwise rotation around the color wheel.
+     * Omit to leave hue unchanged.
+     */
+    hue?: number;
+    /**
+     * Tint the image with a hex color string, e.g. "#ff0000" for red.
+     * Omit to skip tinting.
+     */
+    tint?: string;
+    /**
+     * Output quality for lossy formats (1–100).
+     * Applied to WebP output (always) and JPEG output (when input format is jpeg/jpg).
+     * PNG and other lossless formats ignore this option.
+     * Omit to use Sharp's default quality per format.
+     */
+    quality?: number;
 }
 interface ProcessImageResult {
     buffer: Buffer;
@@ -39,6 +115,42 @@ interface UploadOptions {
 }
 declare function uploadProcessedImage(fm: FileManager, buffer: Buffer, virtualPath: string, opts?: ProcessImageOptions & UploadOptions): Promise<UploadProcessedImageResult>;
 
+/**
+ * Framework-agnostic Web handler factory for the hazo_images processing pipeline.
+ *
+ * Uses only Web-standard Request/Response/FormData — works as a Next.js App-Router
+ * route POST directly. Does NOT import `next`, `hazo_ui`, or `hazo_files`.
+ *
+ * @since 1.4.0
+ */
+/**
+ * Duck-typed FileManager interface — structurally matches hazo_files FileManager
+ * and TrackedFileManager. No compile-time dep on hazo_files.
+ */
+interface ImageProcessHandlerFileManager {
+    uploadFile(source: Buffer | string, remotePath: string, options?: Record<string, unknown>): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: string;
+    }>;
+}
+interface CreateImageProcessHandlerOptions {
+    /**
+     * Provide to enable persistence on `save`.
+     * Returns the FileManager (sync or async).
+     */
+    getFileManager?: () => Promise<ImageProcessHandlerFileManager> | ImageProcessHandlerFileManager;
+    /** Max upload size in bytes. Default 15 MB. */
+    maxUploadBytes?: number;
+    /** Allowed input MIME types. */
+    allowedTypes?: string[];
+    /** Cap the longest side of the base64 preview to bound payload size. Default 1600. */
+    previewMaxDimension?: number;
+    /** Base virtual path prefix used when saving. Default '/hazo-images'. */
+    savePathPrefix?: string;
+}
+declare function createImageProcessHandler(opts?: CreateImageProcessHandlerOptions): (request: Request) => Promise<Response>;
+
 /**
  * hazo_images error classes.
  *
@@ -90,4 +202,43 @@ declare class ImageUploadError extends HazoExternalError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
-export { ImageProcessingError, ImageUploadError, type ProcessImageOptions, type ProcessImageResult, SharpMissingError, UnsupportedFormatError, type UploadProcessedImageResult, processImage, uploadProcessedImage };
+interface DeriveVariantOptions extends ProcessImageOptions {
+    actor_id?: string;
+    /**
+     * Virtual path suffix appended to the source path to form the variant path.
+     * Default: derived from the operation (e.g. '_crop', '_blur3', '_thumb', '_derived').
+     */
+    variantSuffix?: string;
+}
+interface DeriveVariantDeps {
+    /** Must support: uploadFile, downloadFile */
+    fm: {
+        uploadFile(source: Buffer | string, remotePath: string, opts?: Record<string, unknown>): Promise<{
+            success: boolean;
+            data?: unknown;
+            error?: string;
+        }>;
+        downloadFile(fileId: string): Promise<Buffer>;
+    };
+    metadataService?: {
+        findById(id: string): Promise<{
+            virtual_path?: string;
+            file_name?: string;
+        } | null>;
+    };
+}
+interface DeriveVariantResult {
+    /** The file_id of the newly uploaded variant (from fm.uploadFile data.file_id or similar) */
+    file_id: string;
+    /** Optional — not known at this layer; caller resolves URL separately */
+    url?: string;
+}
+/**
+ * deriveVariant — fileId-in/fileId-out convenience over processImage + uploadProcessedImage.
+ *
+ * Downloads the source file by ID, processes it with processImage, uploads the
+ * result via fm.uploadFile, and returns the new file_id.
+ */
+declare function deriveVariant(sourceFileId: string, deps: DeriveVariantDeps, opts?: DeriveVariantOptions): Promise<DeriveVariantResult>;
+
+export { type CreateImageProcessHandlerOptions, type DeriveVariantDeps, type DeriveVariantOptions, type DeriveVariantResult, type ImageProcessHandlerFileManager, ImageProcessingError, ImageUploadError, type ProcessImageOptions, type ProcessImageResult, SharpMissingError, UnsupportedFormatError, type UploadProcessedImageResult, createImageProcessHandler, deriveVariant, processImage, uploadProcessedImage };