@nifrajs/image 2.2.0 → 2.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @nifrajs/image
 
-Image optimization for nifra — a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.
+Image optimization for nifra - a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.
 
-Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework — one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
 
 ## Install
 
@@ -19,7 +19,7 @@ MIT
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/backend.d.ts

@@ -1,21 +1,21 @@
 /**
- * `@nifrajs/image/backends` — the codec seam + the official {@link ImageBackend} implementations, kept
+ * `@nifrajs/image/backends` - the codec seam + the official {@link ImageBackend} implementations, kept
  * **dependency-free and edge-safe** (no `node:` imports), so the WASM backend can run on Workers /
- * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only — it touches the
+ * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only - it touches the
  * filesystem) consumes this seam and owns all request-level security; a backend only
  * decodes/resizes/encodes and translates codec failures into {@link ImageProcessingError}.
  *
  * Pick a backend for your runtime:
- * - {@link bunImageBackend} — `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
- * - {@link sharpImageBackend} — pass your `sharp` import. Node servers.
- * - {@link wasmImageBackend} — pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
+ * - {@link bunImageBackend} - `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
+ * - {@link sharpImageBackend} - pass your `sharp` import. Node servers.
+ * - {@link wasmImageBackend} - pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
  */
-/** Output formats nifra's endpoint can emit. AVIF is intentionally excluded — `Bun.Image` reports
+/** Output formats nifra's endpoint can emit. AVIF is intentionally excluded - `Bun.Image` reports
  * `ERR_IMAGE_FORMAT_UNSUPPORTED` for AVIF encode on common platforms, so offering it would 500. */
 export type OutputFormat = "webp" | "jpeg" | "png";
 export declare const CONTENT_TYPE: Record<OutputFormat, string>;
 /** Header-only probe of a source image: intrinsic dimensions + decoded format. Must be cheap (no full
- * decode) — it gates the decompression-bomb and no-upscale checks before the expensive resize. */
+ * decode) - it gates the decompression-bomb and no-upscale checks before the expensive resize. */
 export interface ImageProbe {
     readonly width: number;
     readonly height: number;
@@ -24,7 +24,7 @@ export interface ImageProbe {
 }
 export interface ResizeInput {
     readonly bytes: Uint8Array;
-    /** Target width in px — already clamped to `[1, maxWidth]` **and** to the source's intrinsic width
+    /** Target width in px - already clamped to `[1, maxWidth]` **and** to the source's intrinsic width
      * (the handler never asks a backend to upscale). Aspect ratio is preserved. */
     readonly width: number;
     /** Encoder quality `1..100` (ignored for lossless `png`). */
@@ -59,7 +59,7 @@ export declare class ImageProcessingError extends Error {
  */
 export declare function bunImageBackend(): ImageBackend;
 /** The slice of a [sharp](https://sharp.pixelplumbing.com) instance this backend uses. Declared
- * structurally so `@nifrajs/image` has no dependency on sharp — pass your own `sharp` import. */
+ * structurally so `@nifrajs/image` has no dependency on sharp - pass your own `sharp` import. */
 export type SharpLike = (input: Uint8Array) => SharpInstance;
 interface SharpInstance {
     metadata(): Promise<{
@@ -82,7 +82,7 @@ interface SharpInstance {
 }
 /**
  * {@link ImageBackend} backed by [sharp](https://sharp.pixelplumbing.com) (libvips) for Node servers.
- * Pass your `sharp` import — `@nifrajs/image` never imports it, so it stays dependency-free and you control
+ * Pass your `sharp` import - `@nifrajs/image` never imports it, so it stays dependency-free and you control
  * the version:
  *
  * ```ts
@@ -91,7 +91,7 @@ interface SharpInstance {
  * ```
  */
 export declare function sharpImageBackend(sharp: SharpLike): ImageBackend;
-/** A decoded image: RGBA pixels + dimensions — the lingua franca of WASM codecs (jSquash, Photon, …). */
+/** A decoded image: RGBA pixels + dimensions - the lingua franca of WASM codecs (jSquash, Photon, …). */
 export interface DecodedImage {
     /** RGBA bytes, length `width * height * 4`. */
     readonly data: Uint8Array;
@@ -99,7 +99,7 @@ export interface DecodedImage {
     readonly height: number;
 }
 /**
- * Pluggable WASM codec set — decode/resize/encode. Declared structurally so `@nifrajs/image` depends on no
+ * Pluggable WASM codec set - decode/resize/encode. Declared structurally so `@nifrajs/image` depends on no
  * WASM library; wire your own (jSquash is the common pure-WASM, edge-safe choice). The handler probes
  * dimensions from the source header (bomb-safe), so `decode` runs only inside `transform`.
  */
@@ -112,7 +112,7 @@ export interface WasmImageCodecs {
     encode(image: DecodedImage, format: OutputFormat, quality: number): Promise<Uint8Array> | Uint8Array;
 }
 /**
- * {@link ImageBackend} backed by injected WASM codecs — the only backend that runs on the **edge**
+ * {@link ImageBackend} backed by injected WASM codecs - the only backend that runs on the **edge**
  * (Workers / Vercel-Edge / Deno-Deploy), where neither `Bun.Image` nor sharp exists. `probe` reads the
  * source header via nifra's dependency-free reader (so decompression bombs are rejected before any
  * decode); `transform` decodes → resizes (aspect-preserving) → encodes through your codecs.

package/dist/backend.js

@@ -1,14 +1,14 @@
 /**
- * `@nifrajs/image/backends` — the codec seam + the official {@link ImageBackend} implementations, kept
+ * `@nifrajs/image/backends` - the codec seam + the official {@link ImageBackend} implementations, kept
  * **dependency-free and edge-safe** (no `node:` imports), so the WASM backend can run on Workers /
- * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only — it touches the
+ * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only - it touches the
  * filesystem) consumes this seam and owns all request-level security; a backend only
  * decodes/resizes/encodes and translates codec failures into {@link ImageProcessingError}.
  *
  * Pick a backend for your runtime:
- * - {@link bunImageBackend} — `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
- * - {@link sharpImageBackend} — pass your `sharp` import. Node servers.
- * - {@link wasmImageBackend} — pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
+ * - {@link bunImageBackend} - `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
+ * - {@link sharpImageBackend} - pass your `sharp` import. Node servers.
+ * - {@link wasmImageBackend} - pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
  */
 import { imageDimensions } from "./dimensions.js";
 export const CONTENT_TYPE = {
@@ -77,7 +77,7 @@ function toBunError(err) {
 }
 /**
  * {@link ImageBackend} backed by [sharp](https://sharp.pixelplumbing.com) (libvips) for Node servers.
- * Pass your `sharp` import — `@nifrajs/image` never imports it, so it stays dependency-free and you control
+ * Pass your `sharp` import - `@nifrajs/image` never imports it, so it stays dependency-free and you control
  * the version:
  *
  * ```ts
@@ -130,7 +130,7 @@ function toSharpError(err) {
     return new ImageProcessingError("decode", "sharp failed to process the image");
 }
 /**
- * {@link ImageBackend} backed by injected WASM codecs — the only backend that runs on the **edge**
+ * {@link ImageBackend} backed by injected WASM codecs - the only backend that runs on the **edge**
  * (Workers / Vercel-Edge / Deno-Deploy), where neither `Bun.Image` nor sharp exists. `probe` reads the
  * source header via nifra's dependency-free reader (so decompression bombs are rejected before any
  * decode); `transform` decodes → resizes (aspect-preserving) → encodes through your codecs.
@@ -144,7 +144,7 @@ function toSharpError(err) {
 export function wasmImageBackend(codecs) {
     return {
         async probe(bytes) {
-            const info = imageDimensions(bytes); // header-only — never allocates a decoded buffer
+            const info = imageDimensions(bytes); // header-only - never allocates a decoded buffer
             if (info === null) {
                 throw new ImageProcessingError("decode", "unrecognized image header");
             }

package/dist/dimensions.d.ts

@@ -1,5 +1,5 @@
 /**
- * Read an image's intrinsic dimensions from its file **header**, in pure JS — no decode, no codec, no
+ * Read an image's intrinsic dimensions from its file **header**, in pure JS - no decode, no codec, no
  * dependency. Supports PNG, JPEG, GIF, and WebP (VP8/VP8L/VP8X). Used to give `<Image>` CLS-safe
  * `width`/`height` (build-time tooling can pre-read them into a manifest).
  */
@@ -14,7 +14,7 @@ export declare function imageDimensions(bytes: Uint8Array): ImageInfo | null;
 /**
  * Read just the leading bytes of an image file (via the platform `Bun.file`/`fetch` blob) and parse its
  * dimensions. Build-time tooling: pre-read dimensions into a manifest so `<Image>` is CLS-safe without
- * hardcoding sizes. Reads at most `maxBytes` (default 64 KB — enough for any header).
+ * hardcoding sizes. Reads at most `maxBytes` (default 64 KB - enough for any header).
  */
 export declare function readImageDimensions(source: {
     arrayBuffer(): Promise<ArrayBuffer>;

package/dist/dimensions.js

@@ -18,7 +18,7 @@ const jpeg = (b, dv) => {
         if (dv.getUint8(offset) !== 0xff)
             return null; // not aligned on a marker → malformed
         const marker = dv.getUint8(offset + 1);
-        // SOF0..SOF15 carry the frame's height/width — except DHT(c4)/DNL(c8)/DAC(cc).
+        // SOF0..SOF15 carry the frame's height/width - except DHT(c4)/DNL(c8)/DAC(cc).
         if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
             return { height: dv.getUint16(offset + 5), width: dv.getUint16(offset + 7), format: "jpeg" };
         }
@@ -64,7 +64,7 @@ export function imageDimensions(bytes) {
 /**
  * Read just the leading bytes of an image file (via the platform `Bun.file`/`fetch` blob) and parse its
  * dimensions. Build-time tooling: pre-read dimensions into a manifest so `<Image>` is CLS-safe without
- * hardcoding sizes. Reads at most `maxBytes` (default 64 KB — enough for any header).
+ * hardcoding sizes. Reads at most `maxBytes` (default 64 KB - enough for any header).
  */
 export async function readImageDimensions(source, maxBytes = 65_536) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {

package/dist/html.d.ts

@@ -12,8 +12,8 @@ export interface HtmlImageAttrs {
     readonly fetchpriority?: "high";
 }
 /**
- * Map a {@link ResolvedImage} to plain lowercase HTML `<img>` attribute names — `srcset` (not React's
- * `srcSet`), `fetchpriority` (not `fetchPriority`) — dropping unset optionals. For the adapters that
+ * Map a {@link ResolvedImage} to plain lowercase HTML `<img>` attribute names - `srcset` (not React's
+ * `srcSet`), `fetchpriority` (not `fetchPriority`) - dropping unset optionals. For the adapters that
  * spread attributes straight onto a host element (Solid / Vue / Svelte / Preact); React consumes
  * `ResolvedImage` directly because it requires the camelCased prop names.
  */

package/dist/html.js

@@ -1,6 +1,6 @@
 /**
- * Map a {@link ResolvedImage} to plain lowercase HTML `<img>` attribute names — `srcset` (not React's
- * `srcSet`), `fetchpriority` (not `fetchPriority`) — dropping unset optionals. For the adapters that
+ * Map a {@link ResolvedImage} to plain lowercase HTML `<img>` attribute names - `srcset` (not React's
+ * `srcSet`), `fetchpriority` (not `fetchPriority`) - dropping unset optionals. For the adapters that
  * spread attributes straight onto a host element (Solid / Vue / Svelte / Preact); React consumes
  * `ResolvedImage` directly because it requires the camelCased prop names.
  */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/image` — image optimization for nifra. A CLS-safe responsive `<Image>` (per-adapter) built on
+ * `@nifrajs/image` - image optimization for nifra. A CLS-safe responsive `<Image>` (per-adapter) built on
  * the pure attribute builder `resolveImage`, pluggable CDN `ImageLoader`s (Cloudflare Images + an
  * identity default), and dependency-free intrinsic-dimension reading. nifra bundles no image codec; the
  * resize is delegated to the edge CDN via the loader. Per-adapter `<Image>` lives in the adapter packages.

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/image` — image optimization for nifra. A CLS-safe responsive `<Image>` (per-adapter) built on
+ * `@nifrajs/image` - image optimization for nifra. A CLS-safe responsive `<Image>` (per-adapter) built on
  * the pure attribute builder `resolveImage`, pluggable CDN `ImageLoader`s (Cloudflare Images + an
  * identity default), and dependency-free intrinsic-dimension reading. nifra bundles no image codec; the
  * resize is delegated to the edge CDN via the loader. Per-adapter `<Image>` lives in the adapter packages.

package/dist/resolve.d.ts

@@ -1,7 +1,7 @@
 /**
- * The pure attribute builder shared by every adapter `<Image>` — turns image props into CLS-safe,
+ * The pure attribute builder shared by every adapter `<Image>` - turns image props into CLS-safe,
  * responsive `<img>` attributes (`src`/`srcSet`/`sizes`/`width`/`height`/`loading`/`decoding`/
- * `fetchpriority`). The actual resize is delegated to an {@link ImageLoader} (a URL builder) — nifra
+ * `fetchpriority`). The actual resize is delegated to an {@link ImageLoader} (a URL builder) - nifra
  * bundles no codec; point the loader at your image CDN.
  */
 /** Builds a variant URL for `src` at a target pixel `width` (and optional `quality`). */
@@ -10,7 +10,7 @@ export type ImageLoader = (args: {
     width: number;
     quality?: number;
 }) => string;
-/** Default loader: return the source unchanged (no transform). Use when there's no image CDN — you
+/** Default loader: return the source unchanged (no transform). Use when there's no image CDN - you
  * still get CLS-safe sizing + lazy loading, just no responsive variants. */
 export declare const identityLoader: ImageLoader;
 export interface CloudflareLoaderOptions {
@@ -18,7 +18,7 @@ export interface CloudflareLoaderOptions {
     readonly base?: string;
 }
 /**
- * Cloudflare Images loader — builds `/cdn-cgi/image/<options>/<source>` URLs that the Cloudflare edge
+ * Cloudflare Images loader - builds `/cdn-cgi/image/<options>/<source>` URLs that the Cloudflare edge
  * resizes on the fly (also emits `format=auto` for webp/avif negotiation). Works on Cloudflare Pages /
  * Workers with Images enabled.
  */
@@ -28,9 +28,9 @@ export interface SelfHostedLoaderOptions {
     readonly endpoint: string;
     /**
      * HMAC secret for **signed URLs**. When set, each URL gets a stable `&s=` signature and the handler
-     * must be configured with the SAME `signing.secret` — it then rejects any unsigned/forged `(src, w, q)`,
+     * must be configured with the SAME `signing.secret` - it then rejects any unsigned/forged `(src, w, q)`,
      * shutting down resize-bombing. ⚠️ The signer holds the secret, so a loader created with it is
-     * **server-only** — inject it like a session secret (from `env`), never import this config into a
+     * **server-only** - inject it like a session secret (from `env`), never import this config into a
      * route/client module. Signatures are stable (no expiry), so SSR-signed URLs hydrate + cache identically.
      */
     readonly secret?: string;
@@ -43,13 +43,13 @@ export interface SelfHostedLoaderOptions {
  */
 export declare function selfHostedLoader(options: SelfHostedLoaderOptions): ImageLoader;
 export interface SignImageUrlOptions {
-    /** HMAC secret — must match the handler's `signing.secret`. */
+    /** HMAC secret - must match the handler's `signing.secret`. */
     readonly secret: string;
     /** Seconds until the URL expires (adds `&exp=`). Omit for a stable, cacheable-forever signed URL. */
     readonly expiresIn?: number;
 }
 /**
- * Mint a **signed** self-hosted image URL on the server — for cases the (stable) `selfHostedLoader`
+ * Mint a **signed** self-hosted image URL on the server - for cases the (stable) `selfHostedLoader`
  * doesn't cover, chiefly **time-limited** access (`expiresIn`) to private images. Server-only (it holds
  * the secret). Pair with a passthrough loader, or use the signed string as a plain `src`.
  *
@@ -64,11 +64,11 @@ export declare function signImageUrl(endpoint: string, image: {
 }, options: SignImageUrlOptions): string;
 export interface ImageProps {
     readonly src: string;
-    /** Intrinsic width (px) — **required**, reserves layout space (no CLS). */
+    /** Intrinsic width (px) - **required**, reserves layout space (no CLS). */
     readonly width: number;
-    /** Intrinsic height (px) — **required** (no CLS). */
+    /** Intrinsic height (px) - **required** (no CLS). */
     readonly height: number;
-    /** Alt text — **required** for accessibility (use `alt=""` for decorative images). */
+    /** Alt text - **required** for accessibility (use `alt=""` for decorative images). */
     readonly alt: string;
     /** `sizes` attribute for responsive selection (e.g. `"(max-width: 600px) 100vw, 600px"`). */
     readonly sizes?: string;

package/dist/resolve.js

@@ -1,15 +1,15 @@
 /**
- * The pure attribute builder shared by every adapter `<Image>` — turns image props into CLS-safe,
+ * The pure attribute builder shared by every adapter `<Image>` - turns image props into CLS-safe,
  * responsive `<img>` attributes (`src`/`srcSet`/`sizes`/`width`/`height`/`loading`/`decoding`/
- * `fetchpriority`). The actual resize is delegated to an {@link ImageLoader} (a URL builder) — nifra
+ * `fetchpriority`). The actual resize is delegated to an {@link ImageLoader} (a URL builder) - nifra
  * bundles no codec; point the loader at your image CDN.
  */
 import { signImageParams } from "./sign.js";
-/** Default loader: return the source unchanged (no transform). Use when there's no image CDN — you
+/** Default loader: return the source unchanged (no transform). Use when there's no image CDN - you
  * still get CLS-safe sizing + lazy loading, just no responsive variants. */
 export const identityLoader = ({ src }) => src;
 /**
- * Cloudflare Images loader — builds `/cdn-cgi/image/<options>/<source>` URLs that the Cloudflare edge
+ * Cloudflare Images loader - builds `/cdn-cgi/image/<options>/<source>` URLs that the Cloudflare edge
  * resizes on the fly (also emits `format=auto` for webp/avif negotiation). Works on Cloudflare Pages /
  * Workers with Images enabled.
  */
@@ -41,7 +41,7 @@ export function selfHostedLoader(options) {
     };
 }
 /**
- * Mint a **signed** self-hosted image URL on the server — for cases the (stable) `selfHostedLoader`
+ * Mint a **signed** self-hosted image URL on the server - for cases the (stable) `selfHostedLoader`
  * doesn't cover, chiefly **time-limited** access (`expiresIn`) to private images. Server-only (it holds
  * the secret). Pair with a passthrough loader, or use the signed string as a plain `src`.
  *
@@ -74,7 +74,7 @@ export function resolveImage(props, loader = identityLoader) {
         props.width <= 0 ||
         !Number.isFinite(props.height) ||
         props.height <= 0) {
-        throw new Error(`[nifra/image] <Image> requires positive width + height (got ${props.width}×${props.height}) — they reserve layout space to prevent CLS.`);
+        throw new Error(`[nifra/image] <Image> requires positive width + height (got ${props.width}×${props.height}) - they reserve layout space to prevent CLS.`);
     }
     const eager = props.priority === true || props.loading === "eager";
     const widths = [...new Set(props.widths ?? [props.width, props.width * 2])].sort((a, b) => a - b);
@@ -85,7 +85,7 @@ export function resolveImage(props, loader = identityLoader) {
     const entries = widths.map((w) => ({ url: at(w), w }));
     const allSame = entries.every((e) => e.url === entries[0]?.url);
     const srcSet = allSame ? undefined : entries.map((e) => `${e.url} ${e.w}w`).join(", ");
-    // `src` is the 1× (intrinsic-width) variant — the fallback for browsers ignoring srcSet.
+    // `src` is the 1× (intrinsic-width) variant - the fallback for browsers ignoring srcSet.
     const base = {
         src: at(props.width),
         width: props.width,

package/dist/server.d.ts

@@ -1,13 +1,13 @@
 /**
- * `@nifrajs/image/server` — nifra's **self-hosted** image resize endpoint. `createImageHandler` returns a
+ * `@nifrajs/image/server` - nifra's **self-hosted** image resize endpoint. `createImageHandler` returns a
  * `(req: Request) => Promise<Response>` you mount at the path your {@link selfHostedLoader} points to
  * (e.g. `"/_image"`). It validates the query, safely resolves the source (local file under a `root`, or
- * a remote URL on an `allowedOrigins` allowlist — both **fail-closed** against SSRF), then decodes →
+ * a remote URL on an `allowedOrigins` allowlist - both **fail-closed** against SSRF), then decodes →
  * resizes (never upscaling) → re-encodes via a pluggable {@link ImageBackend}. The default
  * {@link bunImageBackend} uses `Bun.Image` (libjpeg-turbo / libspng / libwebp, off-thread).
  *
  * This subpath touches the filesystem and a native codec, so it is for **Node/Bun servers**, not the
- * edge. On Workers / Vercel-Edge / Deno-Deploy there is no native codec — use the CDN `cloudflareLoader`
+ * edge. On Workers / Vercel-Edge / Deno-Deploy there is no native codec - use the CDN `cloudflareLoader`
  * from `@nifrajs/image` instead. The dependency-free core (`@nifrajs/image`) never imports this module.
  */
 import { type ImageBackend } from "./backend.js";
@@ -23,7 +23,7 @@ export interface ImageHandlerOptions {
     readonly allowedOrigins?: readonly string[];
     /** Max bytes read from a source before rejecting (413). Default 20 MiB. */
     readonly maxSourceBytes?: number;
-    /** Max source pixels (w×h) before rejecting (413) — decompression-bomb guard. Default 40 MP. */
+    /** Max source pixels (w×h) before rejecting (413) - decompression-bomb guard. Default 40 MP. */
     readonly maxSourcePixels?: number;
     /** Hard cap on the requested width; larger `?w` is clamped down. Default 3840. */
     readonly maxWidth?: number;
@@ -40,7 +40,7 @@ export interface ImageHandlerOptions {
     readonly fetch?: typeof fetch;
     /** Require **signed URLs**: every request must carry a valid `&s=` HMAC over `(src, w, q[, exp])` or
      * it's rejected with `403`. Use the SAME `secret` as your `selfHostedLoader`/`signImageUrl`. This
-     * locks the endpoint to URLs your app minted — the defense against resize-bombing. */
+     * locks the endpoint to URLs your app minted - the defense against resize-bombing. */
     readonly signing?: {
         readonly secret: string;
     };

package/dist/server.js

@@ -1,13 +1,13 @@
 /**
- * `@nifrajs/image/server` — nifra's **self-hosted** image resize endpoint. `createImageHandler` returns a
+ * `@nifrajs/image/server` - nifra's **self-hosted** image resize endpoint. `createImageHandler` returns a
  * `(req: Request) => Promise<Response>` you mount at the path your {@link selfHostedLoader} points to
  * (e.g. `"/_image"`). It validates the query, safely resolves the source (local file under a `root`, or
- * a remote URL on an `allowedOrigins` allowlist — both **fail-closed** against SSRF), then decodes →
+ * a remote URL on an `allowedOrigins` allowlist - both **fail-closed** against SSRF), then decodes →
  * resizes (never upscaling) → re-encodes via a pluggable {@link ImageBackend}. The default
  * {@link bunImageBackend} uses `Bun.Image` (libjpeg-turbo / libspng / libwebp, off-thread).
  *
  * This subpath touches the filesystem and a native codec, so it is for **Node/Bun servers**, not the
- * edge. On Workers / Vercel-Edge / Deno-Deploy there is no native codec — use the CDN `cloudflareLoader`
+ * edge. On Workers / Vercel-Edge / Deno-Deploy there is no native codec - use the CDN `cloudflareLoader`
  * from `@nifrajs/image` instead. The dependency-free core (`@nifrajs/image`) never imports this module.
  */
 import { readFile, realpath, stat } from "node:fs/promises";
@@ -15,7 +15,7 @@ import { resolve as resolvePath, sep } from "node:path";
 import { bunImageBackend, ImageProcessingError, } from "./backend.js";
 import { verifyImageParams } from "./sign.js";
 // The codec seam + every official backend (Bun/sharp/WASM) live in the edge-safe `./backend.ts`
-// (`@nifrajs/image/backends`), importable WITHOUT this module's `node:fs` — so a WASM backend can ship to
+// (`@nifrajs/image/backends`), importable WITHOUT this module's `node:fs` - so a WASM backend can ship to
 // the edge. Re-export them so `@nifrajs/image/server` stays the single import for Node servers.
 export * from "./backend.js";
 const MAX_SRC_LEN = 2048;
@@ -51,11 +51,11 @@ function resolveConfig(options) {
     };
 }
 async function handle(req, cfg) {
-    // 1. Method — only safe reads. (HEAD shares the GET path; the body is stripped at the end.)
+    // 1. Method - only safe reads. (HEAD shares the GET path; the body is stripped at the end.)
     if (req.method !== "GET" && req.method !== "HEAD") {
         return errorResponse(405, "method_not_allowed", { Allow: "GET, HEAD" });
     }
-    // 2. Validate the query at the trust boundary (strict scalar parsing — no Number() coercion).
+    // 2. Validate the query at the trust boundary (strict scalar parsing - no Number() coercion).
     const url = new URL(req.url);
     const src = url.searchParams.get("src");
     if (src === null || src.length === 0 || src.length > MAX_SRC_LEN) {
@@ -75,7 +75,7 @@ async function handle(req, cfg) {
     const width = Math.min(cfg.maxWidth, requestedWidth);
     const wantsWebp = (req.headers.get("accept") ?? "").includes("image/webp");
     // 2b. Signed-URL enforcement (when configured): reject any request we didn't mint. Verifies the
-    //     `&s=` HMAC over the raw (src, w, q[, exp]) — exactly what the loader/`signImageUrl` signed —
+    //     `&s=` HMAC over the raw (src, w, q[, exp]) - exactly what the loader/`signImageUrl` signed -
     //     and the expiry. Done before the ETag/fetch so unsigned/forged requests cost nothing.
     if (cfg.signing !== null) {
         const sig = url.searchParams.get("s");
@@ -136,7 +136,7 @@ async function handle(req, cfg) {
                 return errorResponse(413, "source_too_large");
             return errorResponse(415, "unsupported_media_type"); // decode | unsupported
         }
-        // Unexpected — never leak internals to the client.
+        // Unexpected - never leak internals to the client.
         return errorResponse(500, "internal_error");
     }
     finally {
@@ -165,7 +165,7 @@ async function fetchRemote(url, cfg) {
     let res;
     try {
         res = await cfg.fetchImpl(url, {
-            redirect: "error", // a redirect could bounce to a disallowed origin — refuse it.
+            redirect: "error", // a redirect could bounce to a disallowed origin - refuse it.
             signal: AbortSignal.timeout(cfg.fetchTimeoutMs),
             headers: { Accept: "image/*" },
         });
@@ -186,7 +186,7 @@ async function fetchRemote(url, cfg) {
 async function readLocal(src, cfg) {
     if (cfg.root === null)
         return { ok: false, status: 403, code: "source_not_allowed" };
-    // `src` is already percent-decoded by URLSearchParams — do NOT decode again (double-decode bypass).
+    // `src` is already percent-decoded by URLSearchParams - do NOT decode again (double-decode bypass).
     if (src.includes("\0"))
         return { ok: false, status: 400, code: "invalid_src" };
     // Strip leading slashes so a site-absolute ("/hero.jpg") or protocol-relative ("//evil") path is
@@ -207,7 +207,7 @@ async function readLocal(src, cfg) {
         return { ok: false, status: 404, code: "source_not_found" };
     if (info.size > cfg.maxSourceBytes)
         return { ok: false, status: 413, code: "source_too_large" };
-    // Defense-in-depth: a symlink inside root could point outside it — re-check the real path.
+    // Defense-in-depth: a symlink inside root could point outside it - re-check the real path.
     try {
         const real = await realpath(resolved);
         const realRoot = await realpath(cfg.root);
@@ -221,7 +221,7 @@ async function readLocal(src, cfg) {
     return { ok: true, bytes: new Uint8Array(await readFile(resolved)) };
 }
 /** Read a response body, aborting (→ null) once `limit` bytes are exceeded. Trusts neither the
- * `Content-Length` header (checked as a fast reject) nor an absent one — the running total is the gate. */
+ * `Content-Length` header (checked as a fast reject) nor an absent one - the running total is the gate. */
 async function readBoundedBytes(res, limit) {
     const declared = res.headers.get("content-length");
     if (declared !== null && /^\d+$/.test(declared) && Number(declared) > limit)
@@ -302,7 +302,7 @@ function errorResponse(status, code, extraHeaders = {}) {
     });
 }
 /**
- * Async counting semaphore with direct slot hand-off — a released slot is passed straight to the next
+ * Async counting semaphore with direct slot hand-off - a released slot is passed straight to the next
  * waiter (the active count is never transiently decremented), so a concurrent `acquire()` can't slip
  * past the limit in the microtask gap. Bounds concurrent codec work.
  */

package/dist/sign.d.ts

@@ -1,7 +1,7 @@
 /**
- * Signed image URLs — a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
+ * Signed image URLs - a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
  * URLs inline, on any runtime including the edge (WebCrypto's HMAC is async-only; `node:crypto` isn't on
- * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize —
+ * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize -
  * shutting down resize-bombing (width/quality enumeration) and locking the endpoint to your own images.
  *
  * Pure JS, dependency-free, KAT-tested against the SHA-256 / RFC 4231 HMAC vectors. The secret never

package/dist/sign.js

@@ -1,7 +1,7 @@
 /**
- * Signed image URLs — a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
+ * Signed image URLs - a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
  * URLs inline, on any runtime including the edge (WebCrypto's HMAC is async-only; `node:crypto` isn't on
- * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize —
+ * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize -
  * shutting down resize-bombing (width/quality enumeration) and locking the endpoint to your own images.
  *
  * Pure JS, dependency-free, KAT-tested against the SHA-256 / RFC 4231 HMAC vectors. The secret never
@@ -117,14 +117,14 @@ const hex = (bytes) => {
 export function hmacSha256Hex(key, message) {
     return hex(hmacSha256(encoder.encode(key), encoder.encode(message)));
 }
-/** base64url (RFC 4648 §5, unpadded) of a byte array — URL-safe, compact (43 chars for a 32-byte tag). */
+/** base64url (RFC 4648 §5, unpadded) of a byte array - URL-safe, compact (43 chars for a 32-byte tag). */
 function base64url(bytes) {
     let binary = "";
     for (const b of bytes)
         binary += String.fromCharCode(b);
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-/** Constant-time string compare — length-independent of where the first difference is. */
+/** Constant-time string compare - length-independent of where the first difference is. */
 function safeEqual(a, b) {
     if (a.length !== b.length)
         return false;
@@ -134,7 +134,7 @@ function safeEqual(a, b) {
     return diff === 0;
 }
 const canonical = (p) => `${p.src}\n${p.w}\n${p.q ?? ""}\n${p.exp ?? ""}`;
-// 256-bit secret floor — mirrors @nifrajs/core's HMAC guard. This package is dependency-free (ships
+// 256-bit secret floor - mirrors @nifrajs/core's HMAC guard. This package is dependency-free (ships
 // its own SHA-256), so the constant is inlined rather than imported.
 const MIN_SECRET_BYTES = 32;
 /** Compute the URL signature (base64url HMAC-SHA256) for a set of image params. Guards (and so does

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/image",
-  "version": "2.2.0",
-  "description": "Image optimization for nifra — a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.",
+  "version": "2.4.0",
+  "description": "Image optimization for nifra - a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.",
   "keywords": [
     "bun",
     "typescript",

package/src/backend.ts

@@ -1,19 +1,19 @@
 /**
- * `@nifrajs/image/backends` — the codec seam + the official {@link ImageBackend} implementations, kept
+ * `@nifrajs/image/backends` - the codec seam + the official {@link ImageBackend} implementations, kept
  * **dependency-free and edge-safe** (no `node:` imports), so the WASM backend can run on Workers /
- * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only — it touches the
+ * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only - it touches the
  * filesystem) consumes this seam and owns all request-level security; a backend only
  * decodes/resizes/encodes and translates codec failures into {@link ImageProcessingError}.
  *
  * Pick a backend for your runtime:
- * - {@link bunImageBackend} — `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
- * - {@link sharpImageBackend} — pass your `sharp` import. Node servers.
- * - {@link wasmImageBackend} — pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
+ * - {@link bunImageBackend} - `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
+ * - {@link sharpImageBackend} - pass your `sharp` import. Node servers.
+ * - {@link wasmImageBackend} - pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
  */
 
 import { imageDimensions } from "./dimensions.ts"
 
-/** Output formats nifra's endpoint can emit. AVIF is intentionally excluded — `Bun.Image` reports
+/** Output formats nifra's endpoint can emit. AVIF is intentionally excluded - `Bun.Image` reports
  * `ERR_IMAGE_FORMAT_UNSUPPORTED` for AVIF encode on common platforms, so offering it would 500. */
 export type OutputFormat = "webp" | "jpeg" | "png"
 
@@ -24,7 +24,7 @@ export const CONTENT_TYPE: Record<OutputFormat, string> = {
 }
 
 /** Header-only probe of a source image: intrinsic dimensions + decoded format. Must be cheap (no full
- * decode) — it gates the decompression-bomb and no-upscale checks before the expensive resize. */
+ * decode) - it gates the decompression-bomb and no-upscale checks before the expensive resize. */
 export interface ImageProbe {
   readonly width: number
   readonly height: number
@@ -34,7 +34,7 @@ export interface ImageProbe {
 
 export interface ResizeInput {
   readonly bytes: Uint8Array
-  /** Target width in px — already clamped to `[1, maxWidth]` **and** to the source's intrinsic width
+  /** Target width in px - already clamped to `[1, maxWidth]` **and** to the source's intrinsic width
    * (the handler never asks a backend to upscale). Aspect ratio is preserved. */
   readonly width: number
   /** Encoder quality `1..100` (ignored for lossless `png`). */
@@ -141,7 +141,7 @@ function toBunError(err: unknown): ImageProcessingError {
 // --- sharp backend (Node) ----------------------------------------------------------------------------
 
 /** The slice of a [sharp](https://sharp.pixelplumbing.com) instance this backend uses. Declared
- * structurally so `@nifrajs/image` has no dependency on sharp — pass your own `sharp` import. */
+ * structurally so `@nifrajs/image` has no dependency on sharp - pass your own `sharp` import. */
 export type SharpLike = (input: Uint8Array) => SharpInstance
 interface SharpInstance {
   metadata(): Promise<{ width?: number; height?: number; format?: string }>
@@ -154,7 +154,7 @@ interface SharpInstance {
 
 /**
  * {@link ImageBackend} backed by [sharp](https://sharp.pixelplumbing.com) (libvips) for Node servers.
- * Pass your `sharp` import — `@nifrajs/image` never imports it, so it stays dependency-free and you control
+ * Pass your `sharp` import - `@nifrajs/image` never imports it, so it stays dependency-free and you control
  * the version:
  *
  * ```ts
@@ -208,7 +208,7 @@ function toSharpError(err: unknown): ImageProcessingError {
 
 // --- WASM backend (edge-portable) --------------------------------------------------------------------
 
-/** A decoded image: RGBA pixels + dimensions — the lingua franca of WASM codecs (jSquash, Photon, …). */
+/** A decoded image: RGBA pixels + dimensions - the lingua franca of WASM codecs (jSquash, Photon, …). */
 export interface DecodedImage {
   /** RGBA bytes, length `width * height * 4`. */
   readonly data: Uint8Array
@@ -217,7 +217,7 @@ export interface DecodedImage {
 }
 
 /**
- * Pluggable WASM codec set — decode/resize/encode. Declared structurally so `@nifrajs/image` depends on no
+ * Pluggable WASM codec set - decode/resize/encode. Declared structurally so `@nifrajs/image` depends on no
  * WASM library; wire your own (jSquash is the common pure-WASM, edge-safe choice). The handler probes
  * dimensions from the source header (bomb-safe), so `decode` runs only inside `transform`.
  */
@@ -235,7 +235,7 @@ export interface WasmImageCodecs {
 }
 
 /**
- * {@link ImageBackend} backed by injected WASM codecs — the only backend that runs on the **edge**
+ * {@link ImageBackend} backed by injected WASM codecs - the only backend that runs on the **edge**
  * (Workers / Vercel-Edge / Deno-Deploy), where neither `Bun.Image` nor sharp exists. `probe` reads the
  * source header via nifra's dependency-free reader (so decompression bombs are rejected before any
  * decode); `transform` decodes → resizes (aspect-preserving) → encodes through your codecs.
@@ -249,7 +249,7 @@ export interface WasmImageCodecs {
 export function wasmImageBackend(codecs: WasmImageCodecs): ImageBackend {
   return {
     async probe(bytes) {
-      const info = imageDimensions(bytes) // header-only — never allocates a decoded buffer
+      const info = imageDimensions(bytes) // header-only - never allocates a decoded buffer
       if (info === null) {
         throw new ImageProcessingError("decode", "unrecognized image header")
       }

package/src/dimensions.ts

@@ -1,5 +1,5 @@
 /**
- * Read an image's intrinsic dimensions from its file **header**, in pure JS — no decode, no codec, no
+ * Read an image's intrinsic dimensions from its file **header**, in pure JS - no decode, no codec, no
  * dependency. Supports PNG, JPEG, GIF, and WebP (VP8/VP8L/VP8X). Used to give `<Image>` CLS-safe
  * `width`/`height` (build-time tooling can pre-read them into a manifest).
  */
@@ -29,7 +29,7 @@ const jpeg = (b: Uint8Array, dv: DataView): ImageInfo | null => {
   while (offset + 9 < b.length) {
     if (dv.getUint8(offset) !== 0xff) return null // not aligned on a marker → malformed
     const marker = dv.getUint8(offset + 1)
-    // SOF0..SOF15 carry the frame's height/width — except DHT(c4)/DNL(c8)/DAC(cc).
+    // SOF0..SOF15 carry the frame's height/width - except DHT(c4)/DNL(c8)/DAC(cc).
     if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
       return { height: dv.getUint16(offset + 5), width: dv.getUint16(offset + 7), format: "jpeg" }
     }
@@ -80,7 +80,7 @@ export function imageDimensions(bytes: Uint8Array): ImageInfo | null {
 /**
  * Read just the leading bytes of an image file (via the platform `Bun.file`/`fetch` blob) and parse its
  * dimensions. Build-time tooling: pre-read dimensions into a manifest so `<Image>` is CLS-safe without
- * hardcoding sizes. Reads at most `maxBytes` (default 64 KB — enough for any header).
+ * hardcoding sizes. Reads at most `maxBytes` (default 64 KB - enough for any header).
  */
 export async function readImageDimensions(
   source: { arrayBuffer(): Promise<ArrayBuffer>; stream?: () => ReadableStream<Uint8Array> },

package/src/html.ts

@@ -14,8 +14,8 @@ export interface HtmlImageAttrs {
 }
 
 /**
- * Map a {@link ResolvedImage} to plain lowercase HTML `<img>` attribute names — `srcset` (not React's
- * `srcSet`), `fetchpriority` (not `fetchPriority`) — dropping unset optionals. For the adapters that
+ * Map a {@link ResolvedImage} to plain lowercase HTML `<img>` attribute names - `srcset` (not React's
+ * `srcSet`), `fetchpriority` (not `fetchPriority`) - dropping unset optionals. For the adapters that
  * spread attributes straight onto a host element (Solid / Vue / Svelte / Preact); React consumes
  * `ResolvedImage` directly because it requires the camelCased prop names.
  */

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/image` — image optimization for nifra. A CLS-safe responsive `<Image>` (per-adapter) built on
+ * `@nifrajs/image` - image optimization for nifra. A CLS-safe responsive `<Image>` (per-adapter) built on
  * the pure attribute builder `resolveImage`, pluggable CDN `ImageLoader`s (Cloudflare Images + an
  * identity default), and dependency-free intrinsic-dimension reading. nifra bundles no image codec; the
  * resize is delegated to the edge CDN via the loader. Per-adapter `<Image>` lives in the adapter packages.

package/src/resolve.ts

@@ -1,7 +1,7 @@
 /**
- * The pure attribute builder shared by every adapter `<Image>` — turns image props into CLS-safe,
+ * The pure attribute builder shared by every adapter `<Image>` - turns image props into CLS-safe,
  * responsive `<img>` attributes (`src`/`srcSet`/`sizes`/`width`/`height`/`loading`/`decoding`/
- * `fetchpriority`). The actual resize is delegated to an {@link ImageLoader} (a URL builder) — nifra
+ * `fetchpriority`). The actual resize is delegated to an {@link ImageLoader} (a URL builder) - nifra
  * bundles no codec; point the loader at your image CDN.
  */
 
@@ -10,7 +10,7 @@ import { signImageParams } from "./sign.ts"
 /** Builds a variant URL for `src` at a target pixel `width` (and optional `quality`). */
 export type ImageLoader = (args: { src: string; width: number; quality?: number }) => string
 
-/** Default loader: return the source unchanged (no transform). Use when there's no image CDN — you
+/** Default loader: return the source unchanged (no transform). Use when there's no image CDN - you
  * still get CLS-safe sizing + lazy loading, just no responsive variants. */
 export const identityLoader: ImageLoader = ({ src }) => src
 
@@ -20,7 +20,7 @@ export interface CloudflareLoaderOptions {
 }
 
 /**
- * Cloudflare Images loader — builds `/cdn-cgi/image/<options>/<source>` URLs that the Cloudflare edge
+ * Cloudflare Images loader - builds `/cdn-cgi/image/<options>/<source>` URLs that the Cloudflare edge
  * resizes on the fly (also emits `format=auto` for webp/avif negotiation). Works on Cloudflare Pages /
  * Workers with Images enabled.
  */
@@ -38,9 +38,9 @@ export interface SelfHostedLoaderOptions {
   readonly endpoint: string
   /**
    * HMAC secret for **signed URLs**. When set, each URL gets a stable `&s=` signature and the handler
-   * must be configured with the SAME `signing.secret` — it then rejects any unsigned/forged `(src, w, q)`,
+   * must be configured with the SAME `signing.secret` - it then rejects any unsigned/forged `(src, w, q)`,
    * shutting down resize-bombing. ⚠️ The signer holds the secret, so a loader created with it is
-   * **server-only** — inject it like a session secret (from `env`), never import this config into a
+   * **server-only** - inject it like a session secret (from `env`), never import this config into a
    * route/client module. Signatures are stable (no expiry), so SSR-signed URLs hydrate + cache identically.
    */
   readonly secret?: string
@@ -65,14 +65,14 @@ export function selfHostedLoader(options: SelfHostedLoaderOptions): ImageLoader
 }
 
 export interface SignImageUrlOptions {
-  /** HMAC secret — must match the handler's `signing.secret`. */
+  /** HMAC secret - must match the handler's `signing.secret`. */
   readonly secret: string
   /** Seconds until the URL expires (adds `&exp=`). Omit for a stable, cacheable-forever signed URL. */
   readonly expiresIn?: number
 }
 
 /**
- * Mint a **signed** self-hosted image URL on the server — for cases the (stable) `selfHostedLoader`
+ * Mint a **signed** self-hosted image URL on the server - for cases the (stable) `selfHostedLoader`
  * doesn't cover, chiefly **time-limited** access (`expiresIn`) to private images. Server-only (it holds
  * the secret). Pair with a passthrough loader, or use the signed string as a plain `src`.
  *
@@ -100,11 +100,11 @@ export function signImageUrl(
 
 export interface ImageProps {
   readonly src: string
-  /** Intrinsic width (px) — **required**, reserves layout space (no CLS). */
+  /** Intrinsic width (px) - **required**, reserves layout space (no CLS). */
   readonly width: number
-  /** Intrinsic height (px) — **required** (no CLS). */
+  /** Intrinsic height (px) - **required** (no CLS). */
   readonly height: number
-  /** Alt text — **required** for accessibility (use `alt=""` for decorative images). */
+  /** Alt text - **required** for accessibility (use `alt=""` for decorative images). */
   readonly alt: string
   /** `sizes` attribute for responsive selection (e.g. `"(max-width: 600px) 100vw, 600px"`). */
   readonly sizes?: string
@@ -147,7 +147,7 @@ export function resolveImage(
     props.height <= 0
   ) {
     throw new Error(
-      `[nifra/image] <Image> requires positive width + height (got ${props.width}×${props.height}) — they reserve layout space to prevent CLS.`,
+      `[nifra/image] <Image> requires positive width + height (got ${props.width}×${props.height}) - they reserve layout space to prevent CLS.`,
     )
   }
   const eager = props.priority === true || props.loading === "eager"
@@ -164,7 +164,7 @@ export function resolveImage(
   const allSame = entries.every((e) => e.url === entries[0]?.url)
   const srcSet = allSame ? undefined : entries.map((e) => `${e.url} ${e.w}w`).join(", ")
 
-  // `src` is the 1× (intrinsic-width) variant — the fallback for browsers ignoring srcSet.
+  // `src` is the 1× (intrinsic-width) variant - the fallback for browsers ignoring srcSet.
   const base: ResolvedImage = {
     src: at(props.width),
     width: props.width,

package/src/server.ts

@@ -1,13 +1,13 @@
 /**
- * `@nifrajs/image/server` — nifra's **self-hosted** image resize endpoint. `createImageHandler` returns a
+ * `@nifrajs/image/server` - nifra's **self-hosted** image resize endpoint. `createImageHandler` returns a
  * `(req: Request) => Promise<Response>` you mount at the path your {@link selfHostedLoader} points to
  * (e.g. `"/_image"`). It validates the query, safely resolves the source (local file under a `root`, or
- * a remote URL on an `allowedOrigins` allowlist — both **fail-closed** against SSRF), then decodes →
+ * a remote URL on an `allowedOrigins` allowlist - both **fail-closed** against SSRF), then decodes →
  * resizes (never upscaling) → re-encodes via a pluggable {@link ImageBackend}. The default
  * {@link bunImageBackend} uses `Bun.Image` (libjpeg-turbo / libspng / libwebp, off-thread).
  *
  * This subpath touches the filesystem and a native codec, so it is for **Node/Bun servers**, not the
- * edge. On Workers / Vercel-Edge / Deno-Deploy there is no native codec — use the CDN `cloudflareLoader`
+ * edge. On Workers / Vercel-Edge / Deno-Deploy there is no native codec - use the CDN `cloudflareLoader`
  * from `@nifrajs/image` instead. The dependency-free core (`@nifrajs/image`) never imports this module.
  */
 
@@ -24,7 +24,7 @@ import {
 import { verifyImageParams } from "./sign.ts"
 
 // The codec seam + every official backend (Bun/sharp/WASM) live in the edge-safe `./backend.ts`
-// (`@nifrajs/image/backends`), importable WITHOUT this module's `node:fs` — so a WASM backend can ship to
+// (`@nifrajs/image/backends`), importable WITHOUT this module's `node:fs` - so a WASM backend can ship to
 // the edge. Re-export them so `@nifrajs/image/server` stays the single import for Node servers.
 export * from "./backend.ts"
 
@@ -39,7 +39,7 @@ export interface ImageHandlerOptions {
   readonly allowedOrigins?: readonly string[]
   /** Max bytes read from a source before rejecting (413). Default 20 MiB. */
   readonly maxSourceBytes?: number
-  /** Max source pixels (w×h) before rejecting (413) — decompression-bomb guard. Default 40 MP. */
+  /** Max source pixels (w×h) before rejecting (413) - decompression-bomb guard. Default 40 MP. */
   readonly maxSourcePixels?: number
   /** Hard cap on the requested width; larger `?w` is clamped down. Default 3840. */
   readonly maxWidth?: number
@@ -56,7 +56,7 @@ export interface ImageHandlerOptions {
   readonly fetch?: typeof fetch
   /** Require **signed URLs**: every request must carry a valid `&s=` HMAC over `(src, w, q[, exp])` or
    * it's rejected with `403`. Use the SAME `secret` as your `selfHostedLoader`/`signImageUrl`. This
-   * locks the endpoint to URLs your app minted — the defense against resize-bombing. */
+   * locks the endpoint to URLs your app minted - the defense against resize-bombing. */
   readonly signing?: { readonly secret: string }
 }
 
@@ -114,12 +114,12 @@ function resolveConfig(options: ImageHandlerOptions): ResolvedConfig {
 }
 
 async function handle(req: Request, cfg: ResolvedConfig): Promise<Response> {
-  // 1. Method — only safe reads. (HEAD shares the GET path; the body is stripped at the end.)
+  // 1. Method - only safe reads. (HEAD shares the GET path; the body is stripped at the end.)
   if (req.method !== "GET" && req.method !== "HEAD") {
     return errorResponse(405, "method_not_allowed", { Allow: "GET, HEAD" })
   }
 
-  // 2. Validate the query at the trust boundary (strict scalar parsing — no Number() coercion).
+  // 2. Validate the query at the trust boundary (strict scalar parsing - no Number() coercion).
   const url = new URL(req.url)
   const src = url.searchParams.get("src")
   if (src === null || src.length === 0 || src.length > MAX_SRC_LEN) {
@@ -138,7 +138,7 @@ async function handle(req: Request, cfg: ResolvedConfig): Promise<Response> {
   const wantsWebp = (req.headers.get("accept") ?? "").includes("image/webp")
 
   // 2b. Signed-URL enforcement (when configured): reject any request we didn't mint. Verifies the
-  //     `&s=` HMAC over the raw (src, w, q[, exp]) — exactly what the loader/`signImageUrl` signed —
+  //     `&s=` HMAC over the raw (src, w, q[, exp]) - exactly what the loader/`signImageUrl` signed -
   //     and the expiry. Done before the ETag/fetch so unsigned/forged requests cost nothing.
   if (cfg.signing !== null) {
     const sig = url.searchParams.get("s")
@@ -204,7 +204,7 @@ async function handle(req: Request, cfg: ResolvedConfig): Promise<Response> {
       if (err.kind === "too_large") return errorResponse(413, "source_too_large")
       return errorResponse(415, "unsupported_media_type") // decode | unsupported
     }
-    // Unexpected — never leak internals to the client.
+    // Unexpected - never leak internals to the client.
     return errorResponse(500, "internal_error")
   } finally {
     cfg.release()
@@ -238,7 +238,7 @@ async function fetchRemote(url: URL, cfg: ResolvedConfig): Promise<SourceResult>
   let res: Response
   try {
     res = await cfg.fetchImpl(url, {
-      redirect: "error", // a redirect could bounce to a disallowed origin — refuse it.
+      redirect: "error", // a redirect could bounce to a disallowed origin - refuse it.
       signal: AbortSignal.timeout(cfg.fetchTimeoutMs),
       headers: { Accept: "image/*" },
     })
@@ -256,7 +256,7 @@ async function fetchRemote(url: URL, cfg: ResolvedConfig): Promise<SourceResult>
 
 async function readLocal(src: string, cfg: ResolvedConfig): Promise<SourceResult> {
   if (cfg.root === null) return { ok: false, status: 403, code: "source_not_allowed" }
-  // `src` is already percent-decoded by URLSearchParams — do NOT decode again (double-decode bypass).
+  // `src` is already percent-decoded by URLSearchParams - do NOT decode again (double-decode bypass).
   if (src.includes("\0")) return { ok: false, status: 400, code: "invalid_src" }
   // Strip leading slashes so a site-absolute ("/hero.jpg") or protocol-relative ("//evil") path is
   // treated as root-relative; `resolve` then collapses any "../" and the containment check rejects it.
@@ -273,7 +273,7 @@ async function readLocal(src: string, cfg: ResolvedConfig): Promise<SourceResult
   }
   if (!info.isFile()) return { ok: false, status: 404, code: "source_not_found" }
   if (info.size > cfg.maxSourceBytes) return { ok: false, status: 413, code: "source_too_large" }
-  // Defense-in-depth: a symlink inside root could point outside it — re-check the real path.
+  // Defense-in-depth: a symlink inside root could point outside it - re-check the real path.
   try {
     const real = await realpath(resolved)
     const realRoot = await realpath(cfg.root)
@@ -287,7 +287,7 @@ async function readLocal(src: string, cfg: ResolvedConfig): Promise<SourceResult
 }
 
 /** Read a response body, aborting (→ null) once `limit` bytes are exceeded. Trusts neither the
- * `Content-Length` header (checked as a fast reject) nor an absent one — the running total is the gate. */
+ * `Content-Length` header (checked as a fast reject) nor an absent one - the running total is the gate. */
 async function readBoundedBytes(res: Response, limit: number): Promise<Uint8Array | null> {
   const declared = res.headers.get("content-length")
   if (declared !== null && /^\d+$/.test(declared) && Number(declared) > limit) return null
@@ -371,7 +371,7 @@ function errorResponse(
 }
 
 /**
- * Async counting semaphore with direct slot hand-off — a released slot is passed straight to the next
+ * Async counting semaphore with direct slot hand-off - a released slot is passed straight to the next
  * waiter (the active count is never transiently decremented), so a concurrent `acquire()` can't slip
  * past the limit in the microtask gap. Bounds concurrent codec work.
  */

package/src/sign.ts

@@ -1,7 +1,7 @@
 /**
- * Signed image URLs — a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
+ * Signed image URLs - a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
  * URLs inline, on any runtime including the edge (WebCrypto's HMAC is async-only; `node:crypto` isn't on
- * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize —
+ * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize -
  * shutting down resize-bombing (width/quality enumeration) and locking the endpoint to your own images.
  *
  * Pure JS, dependency-free, KAT-tested against the SHA-256 / RFC 4231 HMAC vectors. The secret never
@@ -124,14 +124,14 @@ export function hmacSha256Hex(key: string, message: string): string {
   return hex(hmacSha256(encoder.encode(key), encoder.encode(message)))
 }
 
-/** base64url (RFC 4648 §5, unpadded) of a byte array — URL-safe, compact (43 chars for a 32-byte tag). */
+/** base64url (RFC 4648 §5, unpadded) of a byte array - URL-safe, compact (43 chars for a 32-byte tag). */
 function base64url(bytes: Uint8Array): string {
   let binary = ""
   for (const b of bytes) binary += String.fromCharCode(b)
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
 }
 
-/** Constant-time string compare — length-independent of where the first difference is. */
+/** Constant-time string compare - length-independent of where the first difference is. */
 function safeEqual(a: string, b: string): boolean {
   if (a.length !== b.length) return false
   let diff = 0
@@ -154,7 +154,7 @@ export interface ImageSignatureParts {
 const canonical = (p: ImageSignatureParts): string =>
   `${p.src}\n${p.w}\n${p.q ?? ""}\n${p.exp ?? ""}`
 
-// 256-bit secret floor — mirrors @nifrajs/core's HMAC guard. This package is dependency-free (ships
+// 256-bit secret floor - mirrors @nifrajs/core's HMAC guard. This package is dependency-free (ships
 // its own SHA-256), so the constant is inlined rather than imported.
 const MIN_SECRET_BYTES = 32