hazo_images 1.1.0

package/CHANGE_LOG.md

@@ -0,0 +1,52 @@
+# hazo_images Change Log
+
+## 1.1.0 (2026-05-29) — Wave 2 standardisation
+
+### Changed
+- Error classes now extend `HazoError` subclasses from `hazo_core`:
+  - `ImageProcessingError` → extends `HazoExternalError` (`HAZO_IMAGES_PROCESSING_FAILED`, HTTP 502, retryable)
+  - `UnsupportedFormatError` → extends `HazoValidationError` (`HAZO_IMAGES_UNSUPPORTED_FORMAT`, HTTP 400)
+  - Existing class names + public API preserved — `instanceof` checks and `errorType` discriminators keep working.
+- `processImage` and `uploadProcessedImage` emit structured `log.debug` events
+  (`process_image.started`, `process_image.completed`,
+  `upload_processed_image.completed`) via `hazo_core.createLogger`.
+  Correlation ID is inherited from the caller's AsyncLocalStorage context.
+- `package.json`: `hazo_core@^1.0.0` added as a required peer dependency.
+  Engines block removed (workspace standard). `dist/` files list now
+  includes `config/`.
+
+### Added
+- `SharpMissingError` extends `HazoConfigError` (`HAZO_IMAGES_CONFIG_SHARP_MISSING`)
+  thrown when the optional `sharp` peer dep is not installed at first
+  `processImage` call. Replaces the previous bare `Error` throw.
+- `ImageUploadError` extends `HazoExternalError` (`HAZO_IMAGES_UPLOAD_FAILED`)
+  thrown when a FileManager rejects a buffer upload during
+  `uploadProcessedImage`. Replaces the previous bare `Error` throws and
+  carries `{ virtualPath, fileManagerError }` in `context`.
+- Workspace-standard INI config under `config/hazo_images_config.ini.sample`
+  with `[general]`, `[log.overrides]`, `[processing]` sections. Loader at
+  `src/lib/config/hazo_images_config.ts::getImagesConfig()` wraps
+  `hazo_core.loadConfig` with a Zod schema. Env-var overrides:
+  `HAZO_IMAGES_<SECTION>_<KEY>`.
+- `src/utils/logger.ts` — `get_logger()` / `set_logger()` defaulting to
+  `createLogger('hazo_images')` from `hazo_core`.
+- `src/utils/uuid.ts` — `generateUUID()` wrapping
+  `generateRequestId().slice(4)` so all IDs trace through `hazo_core`.
+- `AGENTS.md` at package root + `src/` + `test-app/` (S13).
+- `design/feature_requests/INDEX.md` (S16).
+
+### Notes
+- No outbound HTTP calls — `fetchWithRequestId` wiring not required.
+- No database tables owned — no `db_setup_*.sql` files.
+- `hazo_images` is in the "Doesn't adopt hazo_api" column per the
+  ecosystem map; no envelope/route wiring in src/.
+
+## 1.0.0 (2026-05-21)
+
+### Added
+- Initial release: server-side image pipeline
+- `processImage(buffer, opts)` — Sharp wrapper with lazy load, EXIF strip, auto-rotate, resize, thumbnail generation
+- `uploadProcessedImage(fm, buffer, path, opts)` — orchestration helper composing with hazo_files FileManager
+- Subpath exports: `hazo_images/server` (pipeline), `hazo_images/ui` (reserved for @1.1+)
+- `ImageProcessingError` and `UnsupportedFormatError` error types
+- Sharp is an optional peer dep — importing the package without Sharp installed does not crash

package/README.md

@@ -0,0 +1,166 @@
+# 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 **storage** is owned by `hazo_files`. This package handles **processing only**.
+
+## Install
+
+```bash
+npm install hazo_images
+
+# Required peer dep — provides errors, correlation IDs, logger, config loader
+npm install hazo_core
+
+# Required peer deps for image processing
+npm install sharp
+
+# Optional — only needed if using uploadProcessedImage
+npm install hazo_files@^2.1.1
+```
+
+## Usage
+
+### processImage — standalone pipeline primitive
+
+```ts
+import { processImage } from 'hazo_images/server';
+
+const fs = await import('node:fs/promises');
+const buffer = await fs.readFile('./photo.jpg');
+
+const result = await processImage(buffer, {
+  stripExif: true,       // default: true — privacy-safe
+  autoRotate: true,      // default: true — corrects EXIF orientation
+  maxDimension: 4096,    // default: 4096 — resize longest side, keep AR
+  webp: false,           // default: false — preserve original format
+  thumbnails: [256, 512, 1024],
+});
+
+console.log(result.metadata);
+// { width: 2400, height: 1600, format: 'jpeg' }
+
+console.log(result.thumbnails.length);
+// 3 — one per requested size
+
+// result.buffer — processed main image as Buffer
+// result.thumbnails[0] — { size: 256, buffer: Buffer, format: 'jpeg' }
+```
+
+### uploadProcessedImage — compose with hazo_files
+
+```ts
+import { uploadProcessedImage } from 'hazo_images/server';
+import { createInitializedFileManager } from 'hazo_files/server';
+
+const fm = await createInitializedFileManager({ config: { provider: 'local', local: { basePath: './uploads' } } });
+const buffer = await fs.readFile('./photo.jpg');
+
+const result = await uploadProcessedImage(fm, buffer, '/photos/wedding.jpg', {
+  thumbnails: [256, 512, 1024],
+  stripExif: true,
+  autoRotate: true,
+  maxDimension: 4096,
+  webp: false,
+});
+
+console.log(result.main);    // FileItem — the processed main image
+console.log(result.thumbs);  // { 256: FileItem, 512: FileItem, 1024: FileItem }
+```
+
+Thumbnails are named `{basename}__thumb_{size}.{ext}` and stored in the same directory as the main file:
+```
+/photos/wedding.jpg
+/photos/wedding__thumb_256.jpg
+/photos/wedding__thumb_512.jpg
+/photos/wedding__thumb_1024.jpg
+```
+
+### WebP transcoding
+
+```ts
+const result = await processImage(buffer, {
+  webp: true,
+  thumbnails: [256, 512],
+});
+// result.metadata.format === 'webp'
+// result.thumbnails[0].format === 'webp'
+// thumbnail extension in uploadProcessedImage: __thumb_256.webp
+```
+
+## Error Types
+
+All errors extend `HazoError` subclasses from `hazo_core` (Wave 2). The
+legacy class names are preserved so existing `instanceof` checks and
+`errorType` discriminators keep working.
+
+```ts
+import {
+  ImageProcessingError,
+  ImageUploadError,
+  SharpMissingError,
+  UnsupportedFormatError,
+} from 'hazo_images';
+import { HazoError } from 'hazo_core';
+
+try {
+  const result = await processImage(badBuffer);
+} catch (err) {
+  if (err instanceof UnsupportedFormatError) {
+    // Buffer was not a recognized image format (e.g. PDF, text)
+    console.error('Not an image:', err.message);
+  } else if (err instanceof ImageProcessingError) {
+    // Sharp failed during processing
+    console.error('Processing failed:', err.message);
+    console.error('Original error:', err.originalError);
+  } else if (HazoError.is(err)) {
+    // Any other hazo_images error — read `err.code` to discriminate
+    console.error(err.code, err.message);
+  }
+}
+```
+
+### Error reference
+
+| Class | Extends | Code | HTTP | When |
+|---|---|---|---|---|
+| `UnsupportedFormatError` | `HazoValidationError` | `HAZO_IMAGES_UNSUPPORTED_FORMAT` | 400 | Buffer is not a recognized image format |
+| `ImageProcessingError`  | `HazoExternalError`   | `HAZO_IMAGES_PROCESSING_FAILED`   | 502 | Sharp failed during processing or thumbnail generation |
+| `SharpMissingError`     | `HazoConfigError`     | `HAZO_IMAGES_CONFIG_SHARP_MISSING` | n/a | Optional `sharp` peer dep is not installed |
+| `ImageUploadError`      | `HazoExternalError`   | `HAZO_IMAGES_UPLOAD_FAILED`       | 502 | Underlying `FileManager.uploadFile` returned `success: false` |
+
+## Subpath exports
+
+| 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`) |
+
+## Supported formats
+
+Passes through whatever Sharp supports: JPEG, PNG, WebP, AVIF, TIFF, GIF (static), SVG (rasterized). HEIC requires the optional `sharp-heic` package installed separately.
+
+## Options reference
+
+```ts
+interface ProcessImageOptions {
+  stripExif?: boolean;    // default: true  — strip all EXIF metadata
+  autoRotate?: boolean;   // default: true  — apply EXIF orientation, then strip tag
+  maxDimension?: number;  // default: 4096  — longest side; 0 = disable resize
+  webp?: boolean;         // default: false — transcode to WebP
+  thumbnails?: number[];  // default: []    — pixel sizes for longest side
+}
+```
+
+## Roadmap
+
+| 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) |
+
+## License
+
+MIT

package/SETUP_CHECKLIST.md

@@ -0,0 +1,83 @@
+# hazo_images Setup Checklist
+
+## 1. Install the package
+
+```bash
+npm install hazo_images
+```
+
+## 1b. Install hazo_core (required peer dep)
+
+`hazo_core` provides the `HazoError` base class, correlation-ID
+propagation, the structured logger factory, and the INI config loader
+used by `hazo_images`. It is a required peer dep — install it once at
+the consuming app's root.
+
+```bash
+npm install hazo_core
+```
+
+## 2. Install Sharp (required for image processing)
+
+Sharp is an optional peer dependency. It is required whenever `processImage` or `uploadProcessedImage` is called. If Sharp is not installed, an error is thrown at call time (not at import time).
+
+```bash
+npm install sharp
+```
+
+Sharp installs platform-specific native bindings (~10 MB). On some CI systems you may need `npm install --ignore-scripts sharp` followed by a rebuild step.
+
+## 3. Install hazo_files (required for uploadProcessedImage)
+
+Only needed if using the `uploadProcessedImage` helper. `processImage` works standalone without `hazo_files`.
+
+```bash
+npm install hazo_files@^2.1.1
+```
+
+## 4. Server-only imports
+
+Always import from `hazo_images/server` in server-side code only. Do NOT import `hazo_images/server` in client-bundled code (components, browser entry points). It has Node.js dependencies.
+
+```ts
+// In API routes, server components, or Node.js scripts:
+import { processImage, uploadProcessedImage } from 'hazo_images/server';
+
+// Safe anywhere (types + errors, no Node deps):
+import { ImageProcessingError, UnsupportedFormatError } from 'hazo_images';
+```
+
+## 5. Next.js apps — transpilePackages
+
+Add `hazo_images` to `transpilePackages` in `next.config.js`:
+
+```js
+const nextConfig = {
+  transpilePackages: ['hazo_images'],
+};
+module.exports = nextConfig;
+```
+
+## 6. (Optional) Drop in `hazo_images_config.ini`
+
+The package ships `config/hazo_images_config.ini.sample` with sections
+for `[general]`, `[log.overrides]`, and `[processing]` defaults. Copy
+to `<consuming-app>/config/hazo_images_config.ini` (or the package root)
+and override what you need. Any unset key falls back to the
+`processImage` defaults. Values may also be overridden at runtime via
+`HAZO_IMAGES_<SECTION>_<KEY>` env vars.
+
+Per `D-020`, a per-environment overlay file at
+`config/hazo_images_config.<HAZO_ENV>.ini` is layered on top of the
+base file when `HAZO_ENV` is set.
+
+## 7. Verify
+
+```ts
+import { processImage } from 'hazo_images/server';
+
+const buffer = Buffer.from('...'); // a valid JPEG buffer
+const result = await processImage(buffer, { thumbnails: [256] });
+console.log(result.metadata); // { width, height, format }
+console.log(result.thumbnails.length); // 1
+```

package/config/hazo_images_config.ini.sample

@@ -0,0 +1,53 @@
+; hazo_images configuration
+;
+; Copy to `hazo_images_config.ini` and customise. Loaded by getImagesConfig()
+; via hazo_core's loadConfig() on first access.
+;
+; Per hazo workspace standard S7, values may also be overridden via env vars:
+;   HAZO_IMAGES_<SECTION>_<KEY>=value
+; e.g. HAZO_IMAGES_PROCESSING_MAX_DIMENSION=2048
+;
+; Per D-020, a per-environment overlay file at
+;   config/hazo_images_config.<HAZO_ENV>.ini
+; is layered on top of this base file when HAZO_ENV is set.
+
+; ============================================================================
+; [general] - Workspace-standard general configuration
+; ============================================================================
+[general]
+
+; Deployment environment label. Falls back to NODE_ENV, then 'development'.
+; env = production
+
+; ============================================================================
+; [log.overrides] - Per-namespace log level overrides (workspace standard)
+; Format: <namespace> = trace|debug|info|warn|error
+; ============================================================================
+[log.overrides]
+
+; hazo_images = info
+; hazo_images/processing = warn
+
+; ============================================================================
+; [processing] - Default processImage option overrides
+; Each key here becomes the implicit default if the caller does not pass
+; an explicit value to processImage(buffer, opts).
+; ============================================================================
+[processing]
+
+; Strip EXIF metadata from output buffers. true | false (default: true)
+; strip_exif = true
+
+; Auto-rotate using EXIF Orientation tag. true | false (default: true)
+; auto_rotate = true
+
+; Resize to fit within max_dimension × max_dimension. 0 disables resize.
+; Default: 4096
+; max_dimension = 4096
+
+; Re-encode to WebP. true | false (default: false)
+; webp = false
+
+; Comma-separated thumbnail sizes in pixels. Empty = no thumbnails.
+; Default: (none)
+; thumbnails = 256, 512, 1024

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { HazoExternalError, HazoConfigError, HazoValidationError } from 'hazo_core';
+
+interface ProcessImageOptions {
+    stripExif?: boolean;
+    autoRotate?: boolean;
+    maxDimension?: number;
+    webp?: boolean;
+    thumbnails?: number[];
+}
+interface ProcessImageResult {
+    buffer: Buffer;
+    thumbnails: {
+        size: number;
+        buffer: Buffer;
+        format: string;
+    }[];
+    metadata: {
+        width: number;
+        height: number;
+        format: string;
+    };
+}
+interface UploadProcessedImageResult {
+    main: any;
+    thumbs: Record<number, any>;
+}
+
+/**
+ * hazo_images error classes.
+ *
+ * Per Wave 2 / D-008: all errors extend a HazoError subclass from hazo_core.
+ * Code namespace: HAZO_IMAGES_*.
+ *
+ * The legacy class names (`ImageProcessingError`, `UnsupportedFormatError`)
+ * are preserved for backward compatibility — existing test-app scenarios
+ * and the @1.0 public API still discriminate by `errorType`/`error.name`.
+ */
+
+/**
+ * Sharp pipeline failure (encode/decode/resize error from the image library).
+ * Maps to HazoExternalError because the underlying failure originates outside
+ * our code path (Sharp / libvips). HTTP status 502, retryable=true.
+ *
+ * Code: HAZO_IMAGES_PROCESSING_FAILED
+ */
+declare class ImageProcessingError extends HazoExternalError {
+    readonly originalError: Error;
+    constructor(originalError: Error, message?: string);
+}
+/**
+ * Caller passed a buffer Sharp couldn't decode (PDF, corrupt JPEG, etc).
+ * Maps to HazoValidationError because it's a bad-input problem on the
+ * caller's side. HTTP status 400.
+ *
+ * Code: HAZO_IMAGES_UNSUPPORTED_FORMAT
+ */
+declare class UnsupportedFormatError extends HazoValidationError {
+    constructor(message?: string);
+}
+/**
+ * Optional peer `sharp` is not installed in the consuming app. Maps to
+ * HazoConfigError because the install/setup is misconfigured; there is no
+ * HTTP status — startup-time concern. Code: HAZO_IMAGES_CONFIG_SHARP_MISSING.
+ */
+declare class SharpMissingError extends HazoConfigError {
+    constructor();
+}
+/**
+ * Underlying FileManager (hazo_files) rejected a buffer upload during
+ * uploadProcessedImage. HazoExternalError because the failure is in the
+ * downstream storage adapter, not in our code.
+ *
+ * Code: HAZO_IMAGES_UPLOAD_FAILED
+ */
+declare class ImageUploadError extends HazoExternalError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+export { ImageProcessingError, ImageUploadError, type ProcessImageOptions, type ProcessImageResult, SharpMissingError, UnsupportedFormatError, type UploadProcessedImageResult };

package/dist/index.js

@@ -0,0 +1,53 @@
+// src/errors.ts
+import {
+  HazoConfigError,
+  HazoExternalError,
+  HazoValidationError
+} from "hazo_core";
+var ImageProcessingError = class extends HazoExternalError {
+  originalError;
+  constructor(originalError, message) {
+    super({
+      code: "HAZO_IMAGES_PROCESSING_FAILED",
+      pkg: "hazo_images",
+      message: message ?? originalError.message,
+      cause: originalError,
+      context: { originalErrorName: originalError.name }
+    });
+    this.originalError = originalError;
+  }
+};
+var UnsupportedFormatError = class extends HazoValidationError {
+  constructor(message = "Buffer is not a recognized image format") {
+    super({
+      code: "HAZO_IMAGES_UNSUPPORTED_FORMAT",
+      pkg: "hazo_images",
+      message
+    });
+  }
+};
+var SharpMissingError = class extends HazoConfigError {
+  constructor() {
+    super({
+      code: "HAZO_IMAGES_CONFIG_SHARP_MISSING",
+      pkg: "hazo_images",
+      message: "[hazo_images] Sharp is not installed. Run: npm install sharp\nSharp is an optional peer dependency required for image processing."
+    });
+  }
+};
+var ImageUploadError = class extends HazoExternalError {
+  constructor(message, context) {
+    super({
+      code: "HAZO_IMAGES_UPLOAD_FAILED",
+      pkg: "hazo_images",
+      message,
+      context
+    });
+  }
+};
+export {
+  ImageProcessingError,
+  ImageUploadError,
+  SharpMissingError,
+  UnsupportedFormatError
+};

package/dist/server/index.d.ts

@@ -0,0 +1,93 @@
+import { HazoExternalError, HazoConfigError, HazoValidationError } from 'hazo_core';
+
+interface ProcessImageOptions {
+    stripExif?: boolean;
+    autoRotate?: boolean;
+    maxDimension?: number;
+    webp?: boolean;
+    thumbnails?: number[];
+}
+interface ProcessImageResult {
+    buffer: Buffer;
+    thumbnails: {
+        size: number;
+        buffer: Buffer;
+        format: string;
+    }[];
+    metadata: {
+        width: number;
+        height: number;
+        format: string;
+    };
+}
+interface UploadProcessedImageResult {
+    main: any;
+    thumbs: Record<number, any>;
+}
+
+declare function processImage(buffer: Buffer, opts?: ProcessImageOptions): Promise<ProcessImageResult>;
+
+interface FileManager {
+    uploadFile(source: Buffer | string, remotePath: string, options?: Record<string, unknown>): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: string;
+    }>;
+}
+interface UploadOptions {
+    actor_id?: string;
+}
+declare function uploadProcessedImage(fm: FileManager, buffer: Buffer, virtualPath: string, opts?: ProcessImageOptions & UploadOptions): Promise<UploadProcessedImageResult>;
+
+/**
+ * hazo_images error classes.
+ *
+ * Per Wave 2 / D-008: all errors extend a HazoError subclass from hazo_core.
+ * Code namespace: HAZO_IMAGES_*.
+ *
+ * The legacy class names (`ImageProcessingError`, `UnsupportedFormatError`)
+ * are preserved for backward compatibility — existing test-app scenarios
+ * and the @1.0 public API still discriminate by `errorType`/`error.name`.
+ */
+
+/**
+ * Sharp pipeline failure (encode/decode/resize error from the image library).
+ * Maps to HazoExternalError because the underlying failure originates outside
+ * our code path (Sharp / libvips). HTTP status 502, retryable=true.
+ *
+ * Code: HAZO_IMAGES_PROCESSING_FAILED
+ */
+declare class ImageProcessingError extends HazoExternalError {
+    readonly originalError: Error;
+    constructor(originalError: Error, message?: string);
+}
+/**
+ * Caller passed a buffer Sharp couldn't decode (PDF, corrupt JPEG, etc).
+ * Maps to HazoValidationError because it's a bad-input problem on the
+ * caller's side. HTTP status 400.
+ *
+ * Code: HAZO_IMAGES_UNSUPPORTED_FORMAT
+ */
+declare class UnsupportedFormatError extends HazoValidationError {
+    constructor(message?: string);
+}
+/**
+ * Optional peer `sharp` is not installed in the consuming app. Maps to
+ * HazoConfigError because the install/setup is misconfigured; there is no
+ * HTTP status — startup-time concern. Code: HAZO_IMAGES_CONFIG_SHARP_MISSING.
+ */
+declare class SharpMissingError extends HazoConfigError {
+    constructor();
+}
+/**
+ * Underlying FileManager (hazo_files) rejected a buffer upload during
+ * uploadProcessedImage. HazoExternalError because the failure is in the
+ * downstream storage adapter, not in our code.
+ *
+ * Code: HAZO_IMAGES_UPLOAD_FAILED
+ */
+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 };

package/dist/server/index.js

@@ -0,0 +1,227 @@
+// src/errors.ts
+import {
+  HazoConfigError,
+  HazoExternalError,
+  HazoValidationError
+} from "hazo_core";
+var ImageProcessingError = class extends HazoExternalError {
+  originalError;
+  constructor(originalError, message) {
+    super({
+      code: "HAZO_IMAGES_PROCESSING_FAILED",
+      pkg: "hazo_images",
+      message: message ?? originalError.message,
+      cause: originalError,
+      context: { originalErrorName: originalError.name }
+    });
+    this.originalError = originalError;
+  }
+};
+var UnsupportedFormatError = class extends HazoValidationError {
+  constructor(message = "Buffer is not a recognized image format") {
+    super({
+      code: "HAZO_IMAGES_UNSUPPORTED_FORMAT",
+      pkg: "hazo_images",
+      message
+    });
+  }
+};
+var SharpMissingError = class extends HazoConfigError {
+  constructor() {
+    super({
+      code: "HAZO_IMAGES_CONFIG_SHARP_MISSING",
+      pkg: "hazo_images",
+      message: "[hazo_images] Sharp is not installed. Run: npm install sharp\nSharp is an optional peer dependency required for image processing."
+    });
+  }
+};
+var ImageUploadError = class extends HazoExternalError {
+  constructor(message, context) {
+    super({
+      code: "HAZO_IMAGES_UPLOAD_FAILED",
+      pkg: "hazo_images",
+      message,
+      context
+    });
+  }
+};
+
+// src/utils/logger.ts
+import { createLogger } from "hazo_core";
+var console_logger = {
+  info: (m, d) => d ? console.log(`[hazo_images] ${m}`, d) : console.log(`[hazo_images] ${m}`),
+  debug: (m, d) => d ? console.debug(`[hazo_images] ${m}`, d) : console.debug(`[hazo_images] ${m}`),
+  warn: (m, d) => d ? console.warn(`[hazo_images] ${m}`, d) : console.warn(`[hazo_images] ${m}`),
+  error: (m, d) => d ? console.error(`[hazo_images] ${m}`, d) : console.error(`[hazo_images] ${m}`)
+};
+function build_default_logger() {
+  try {
+    return createLogger("hazo_images");
+  } catch {
+    return console_logger;
+  }
+}
+var current_logger = null;
+function get_logger() {
+  if (!current_logger) {
+    current_logger = build_default_logger();
+  }
+  return current_logger;
+}
+
+// src/server/process-image.ts
+var sharpPromise = null;
+async function getSharp() {
+  if (!sharpPromise) {
+    sharpPromise = import("sharp").then((m) => m.default ?? m).catch(() => {
+      sharpPromise = null;
+      throw new SharpMissingError();
+    });
+  }
+  return sharpPromise;
+}
+async function processImage(buffer, opts = {}) {
+  const {
+    stripExif = true,
+    autoRotate = true,
+    maxDimension = 4096,
+    webp = false,
+    thumbnails = []
+  } = opts;
+  const log = get_logger();
+  const sharpFn = await getSharp();
+  log.debug("process_image.started", {
+    inputBytes: buffer.byteLength,
+    webp,
+    maxDimension,
+    thumbnailCount: thumbnails.length
+  });
+  let inputMetadata;
+  try {
+    inputMetadata = await sharpFn(buffer).metadata();
+  } catch (err) {
+    throw new UnsupportedFormatError();
+  }
+  if (!inputMetadata.format) {
+    throw new UnsupportedFormatError();
+  }
+  let pipeline = sharpFn(buffer);
+  if (autoRotate) {
+    pipeline = pipeline.autoOrient();
+  }
+  if (!stripExif) {
+    pipeline = pipeline.withMetadata();
+  }
+  if (maxDimension > 0) {
+    pipeline = pipeline.resize({
+      width: maxDimension,
+      height: maxDimension,
+      fit: "inside",
+      withoutEnlargement: true
+    });
+  }
+  let mainBuffer;
+  let outputMetadata;
+  try {
+    if (webp) {
+      const { data, info } = await pipeline.webp().toBuffer({ resolveWithObject: true });
+      mainBuffer = data;
+      outputMetadata = { width: info.width, height: info.height, format: "webp" };
+    } else {
+      const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+      mainBuffer = data;
+      outputMetadata = { width: info.width, height: info.height, format: info.format };
+    }
+  } catch (err) {
+    throw new ImageProcessingError(err);
+  }
+  const thumbResults = [];
+  for (const size of thumbnails) {
+    try {
+      const thumbPipeline = sharpFn(mainBuffer).resize({
+        width: size,
+        height: size,
+        fit: "inside",
+        withoutEnlargement: true
+      });
+      let thumbBuffer;
+      let thumbFormat;
+      if (webp) {
+        const { data } = await thumbPipeline.webp().toBuffer({ resolveWithObject: true });
+        thumbBuffer = data;
+        thumbFormat = "webp";
+      } else {
+        const { data, info } = await thumbPipeline.toBuffer({ resolveWithObject: true });
+        thumbBuffer = data;
+        thumbFormat = info.format;
+      }
+      thumbResults.push({ size, buffer: thumbBuffer, format: thumbFormat });
+    } catch (err) {
+      throw new ImageProcessingError(
+        err,
+        `Thumbnail generation failed for size ${size}`
+      );
+    }
+  }
+  log.debug("process_image.completed", {
+    outputBytes: mainBuffer.byteLength,
+    outputFormat: outputMetadata.format,
+    outputWidth: outputMetadata.width,
+    outputHeight: outputMetadata.height,
+    thumbnailsGenerated: thumbResults.length
+  });
+  return {
+    buffer: mainBuffer,
+    thumbnails: thumbResults,
+    metadata: outputMetadata
+  };
+}
+
+// src/server/upload-processed-image.ts
+import path from "path";
+async function uploadProcessedImage(fm, buffer, virtualPath, opts) {
+  const { actor_id, ...processOpts } = opts ?? {};
+  const log = get_logger();
+  const result = await processImage(buffer, processOpts);
+  const uploadOpts = actor_id !== void 0 ? { actor_id } : void 0;
+  const mainResult = await fm.uploadFile(result.buffer, virtualPath, uploadOpts);
+  if (!mainResult.success) {
+    throw new ImageUploadError(
+      `Failed to upload main image: ${mainResult.error}`,
+      { virtualPath, fileManagerError: mainResult.error }
+    );
+  }
+  const thumbs = {};
+  const ext = path.extname(virtualPath);
+  const basename = path.basename(virtualPath, ext);
+  const dir = path.dirname(virtualPath);
+  const prefix = dir === "/" ? "" : dir;
+  for (const thumb of result.thumbnails) {
+    const thumbExt = thumb.format === "webp" ? ".webp" : ext;
+    const thumbPath = `${prefix}/${basename}__thumb_${thumb.size}${thumbExt}`;
+    const thumbResult = await fm.uploadFile(thumb.buffer, thumbPath, uploadOpts);
+    if (!thumbResult.success) {
+      throw new ImageUploadError(
+        `Failed to upload thumbnail ${thumb.size}px: ${thumbResult.error}`,
+        { virtualPath: thumbPath, thumbSize: thumb.size, fileManagerError: thumbResult.error }
+      );
+    }
+    thumbs[thumb.size] = thumbResult.data;
+  }
+  log.debug("upload_processed_image.completed", {
+    virtualPath,
+    thumbnailCount: result.thumbnails.length
+  });
+  return {
+    main: mainResult.data,
+    thumbs
+  };
+}
+export {
+  ImageProcessingError,
+  ImageUploadError,
+  SharpMissingError,
+  UnsupportedFormatError,
+  processImage,
+  uploadProcessedImage
+};

package/dist/ui/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "hazo_images",
+  "version": "1.1.0",
+  "description": "Image processing pipeline for the hazo ecosystem — Sharp wrapper, thumbnail generation, EXIF handling, and hazo_files integration helper",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js",
+      "default": "./dist/ui/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "config",
+    "README.md",
+    "SETUP_CHECKLIST.md",
+    "CHANGE_LOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ini": "^4.1.0",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "hazo_core": "^1.0.0",
+    "hazo_files": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "sharp": "^0.33.0"
+  },
+  "peerDependenciesMeta": {
+    "hazo_files": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "hazo_core": "^1.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.2"
+  },
+  "sideEffects": false
+}