# @wrnexus/image

Secure responsive-image planning, loader adapters, picture sources, preload hints, placeholders, and performance auditing for WRNexusJS.

Build-time conversion is available through `optimizeImage`. It normalizes and
bounds width/format variants, prevents variant explosions, writes deterministic
filenames, and returns a manifest with dimensions and byte sizes:

```ts
import { optimizeImage } from "@wrnexus/image";

const manifest = await optimizeImage("public/hero.jpg", {
  outputDir: "public/generated/images",
  widths: [480, 960, 1440],
  formats: ["avif", "webp"],
  quality: 80,
});
```

Install the optional `sharp` peer (`bun add sharp`) for the default AVIF/WebP
processor. Build systems can instead supply an `ImageProcessor` adapter, which
also makes transformation pipelines deterministic in tests.

## Helper API

```ts
import {
  createResponsiveImage,
  createPicture,
  createCdnImageLoader,
  createPathImageLoader,
  createBlurPlaceholder,
  imagePreload,
  auditImage,
} from "@wrnexus/image";

const loader = createCdnImageLoader("https://images.example.com/transform");
const picture = createPicture({
  src: "/hero.jpg",
  alt: "Product dashboard",
  width: 1600,
  height: 900,
  widths: [480, 768, 1200, 1600],
  formats: ["avif", "webp"],
  sizes: "(max-width: 768px) 100vw, 1200px",
  fetchPriority: "high",
  loader,
});
```

Remote loaders require HTTPS. Source URLs are validated, dimensions and quality are bounded, placeholder colors are restricted to safe CSS colors, and preload attributes are escaped.

## Components

Enable `imagePlugin()` and use:

- `<OptimizedImage />`
- `<Picture />`
- `<ImageCard />`

The package-owned blocks compose `@wrnexus/ui` where a complete UI block is appropriate while keeping the low-level image element lightweight.