@pracht/image 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jovi De Croock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @pracht/image
+
+Responsive, CLS-safe `<Image>` component for [pracht](https://github.com/JoviDeCroock/pracht)
+apps with pluggable optimization backends per deployment target, mirroring
+next/image's loader pattern.
+
+- Plain `<img>` markup: SSR-safe, no hydration, zero client runtime.
+- Required `width`/`height` (or `fill`) to prevent layout shift, with dev
+  warnings when missing.
+- `srcset` across configurable device-size breakpoints, `sizes` support,
+  `loading="lazy"` + `decoding="async"` by default, `priority` for
+  above-the-fold images.
+- Loaders for the built-in endpoint, Cloudflare Image Resizing, Vercel Image
+  Optimization, or plain passthrough.
+- A Node optimization endpoint (`@pracht/image/node`) backed by
+  [sharp](https://sharp.pixelplumbing.com) (optional peer dependency) with a
+  trusted-local-origin/remote-allowlist security model and revalidated cache
+  headers.
+
+```bash
+pnpm add @pracht/image
+pnpm add sharp # only needed for the built-in endpoint
+```
+
+```tsx
+import { Image } from "@pracht/image";
+
+<Image src="/banner.jpg" alt="Banner" width={1200} height={280} priority />;
+```
+
+```ts
+// src/api/_pracht/image.ts — mounts the optimization endpoint
+import { createImageHandler } from "@pracht/image/node";
+
+const imageHandler = createImageHandler({
+  localOrigin: process.env.PRACHT_ORIGIN,
+});
+
+export const GET = imageHandler;
+export const HEAD = imageHandler;
+```
+
+Set `localOrigin` to the same trusted public origin used by
+`nodeAdapter({ canonicalOrigin })`. It may be omitted for loopback development.
+
+See [docs/IMAGES.md](https://github.com/JoviDeCroock/pracht/blob/main/docs/IMAGES.md)
+for the full guide: loader configuration, endpoint security options, and
+per-adapter guidance.

package/dist/config-BavYkV_M.mjs

@@ -0,0 +1,100 @@
+//#region src/loaders.ts
+const DEFAULT_QUALITY = 75;
+/**
+* The default optimization endpoint. It maps onto an API route file at
+* `src/api/_pracht/image.ts` that re-exports the handler from
+* `@pracht/image/node`, so it works on every adapter without extra wiring.
+*/
+const DEFAULT_IMAGE_ENDPOINT = "/api/_pracht/image";
+/**
+* Build a loader for a pracht image optimization endpoint. Use this when the
+* handler is mounted somewhere other than {@link DEFAULT_IMAGE_ENDPOINT}.
+*/
+function createDefaultLoader(endpoint = DEFAULT_IMAGE_ENDPOINT) {
+	return ({ src, width, quality }) => `${endpoint}?url=${encodeURIComponent(src)}&w=${width}&q=${quality ?? 75}`;
+}
+/**
+* Targets the pracht image endpoint served by `createImageHandler()` from
+* `@pracht/image/node` (mounted as the `src/api/_pracht/image.ts` API route).
+*/
+const defaultLoader = createDefaultLoader();
+/**
+* Cloudflare Image Resizing. Requires the zone to have Image Resizing
+* enabled; `format=auto` lets Cloudflare negotiate WebP/AVIF.
+* https://developers.cloudflare.com/images/transform-images/transform-via-url/
+*/
+const cloudflareLoader = ({ src, width, quality }) => {
+	const source = src.startsWith("/") ? src.slice(1) : src;
+	return `/cdn-cgi/image/width=${width},quality=${quality ?? 75},format=auto/${source}`;
+};
+/**
+* Vercel Image Optimization. Note that Vercel only serves widths listed in
+* the `images.sizes` field of your project configuration.
+* https://vercel.com/docs/image-optimization
+*/
+const vercelLoader = ({ src, width, quality }) => `/_vercel/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality ?? 75}`;
+/**
+* No optimization: the browser fetches the original file. Use for static
+* hosts without an image service. `<Image>` skips `srcset` entirely when
+* every candidate resolves to the same URL.
+*/
+const passthroughLoader = ({ src }) => src;
+//#endregion
+//#region src/config.ts
+/**
+* Device-width breakpoints used for `srcset` candidates when an image is
+* responsive (`fill` or a `sizes` prop). Matches the next/image defaults.
+*/
+const DEFAULT_DEVICE_SIZES = [
+	640,
+	750,
+	828,
+	1080,
+	1200,
+	1920,
+	2048,
+	3840
+];
+/**
+* Additional small widths used to snap fixed-size images to cache-friendly
+* buckets. Matches the next/image defaults.
+*/
+const DEFAULT_IMAGE_SIZES = [
+	16,
+	32,
+	48,
+	64,
+	96,
+	128,
+	256,
+	384
+];
+const defaults = {
+	loader: defaultLoader,
+	deviceSizes: DEFAULT_DEVICE_SIZES,
+	imageSizes: DEFAULT_IMAGE_SIZES,
+	quality: 75
+};
+let current = defaults;
+/**
+* Configure `<Image>` globally. Call once at module scope (for example in
+* `src/routes.ts`) so the configuration applies on the server and in the
+* browser. Individual components can still override via props.
+*/
+function configureImage(overrides) {
+	current = {
+		...current,
+		...overrides,
+		...overrides.deviceSizes ? { deviceSizes: [...overrides.deviceSizes].sort((a, b) => a - b) } : void 0,
+		...overrides.imageSizes ? { imageSizes: [...overrides.imageSizes].sort((a, b) => a - b) } : void 0
+	};
+}
+function getImageConfig() {
+	return current;
+}
+/** Restore the default configuration. Primarily useful in tests. */
+function resetImageConfig() {
+	current = defaults;
+}
+//#endregion
+export { resetImageConfig as a, cloudflareLoader as c, passthroughLoader as d, vercelLoader as f, getImageConfig as i, createDefaultLoader as l, DEFAULT_IMAGE_SIZES as n, DEFAULT_IMAGE_ENDPOINT as o, configureImage as r, DEFAULT_QUALITY as s, DEFAULT_DEVICE_SIZES as t, defaultLoader as u };

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+import { JSX, VNode } from "preact";
+
+//#region src/loaders.d.ts
+/**
+ * A loader turns an image source plus a target width into a concrete URL.
+ * Loaders mirror the next/image loader contract so migration is mechanical.
+ */
+interface ImageLoaderArgs {
+  src: string;
+  width: number;
+  quality?: number;
+}
+type ImageLoader = (args: ImageLoaderArgs) => string;
+declare const DEFAULT_QUALITY = 75;
+/**
+ * The default optimization endpoint. It maps onto an API route file at
+ * `src/api/_pracht/image.ts` that re-exports the handler from
+ * `@pracht/image/node`, so it works on every adapter without extra wiring.
+ */
+declare const DEFAULT_IMAGE_ENDPOINT = "/api/_pracht/image";
+/**
+ * Build a loader for a pracht image optimization endpoint. Use this when the
+ * handler is mounted somewhere other than {@link DEFAULT_IMAGE_ENDPOINT}.
+ */
+declare function createDefaultLoader(endpoint?: string): ImageLoader;
+/**
+ * Targets the pracht image endpoint served by `createImageHandler()` from
+ * `@pracht/image/node` (mounted as the `src/api/_pracht/image.ts` API route).
+ */
+declare const defaultLoader: ImageLoader;
+/**
+ * Cloudflare Image Resizing. Requires the zone to have Image Resizing
+ * enabled; `format=auto` lets Cloudflare negotiate WebP/AVIF.
+ * https://developers.cloudflare.com/images/transform-images/transform-via-url/
+ */
+declare const cloudflareLoader: ImageLoader;
+/**
+ * Vercel Image Optimization. Note that Vercel only serves widths listed in
+ * the `images.sizes` field of your project configuration.
+ * https://vercel.com/docs/image-optimization
+ */
+declare const vercelLoader: ImageLoader;
+/**
+ * No optimization: the browser fetches the original file. Use for static
+ * hosts without an image service. `<Image>` skips `srcset` entirely when
+ * every candidate resolves to the same URL.
+ */
+declare const passthroughLoader: ImageLoader;
+//#endregion
+//#region src/image.d.ts
+interface ImageProps extends Omit<JSX.HTMLAttributes<HTMLImageElement>, "src" | "srcset" | "srcSet" | "width" | "height" | "sizes" | "loading" | "alt" | "style"> {
+  /** Source path (`/hero.jpg`) or absolute URL. Passed to the loader. */
+  src: string;
+  /** Required for accessibility. Use `alt=""` for decorative images. */
+  alt: string;
+  /** Intrinsic width in pixels. Required unless `fill` is set. */
+  width?: number | `${number}`;
+  /** Intrinsic height in pixels. Required unless `fill` is set. */
+  height?: number | `${number}`;
+  /**
+   * Stretch the image to fill its nearest positioned ancestor instead of
+   * reserving intrinsic dimensions. Applies `position: absolute; inset: 0`.
+   */
+  fill?: boolean;
+  /** Standard `sizes` attribute; switches the srcset to `w` descriptors. */
+  sizes?: string;
+  /** Quality hint forwarded to the loader (1-100). */
+  quality?: number;
+  /**
+   * Mark as above-the-fold: loads eagerly with `fetchpriority="high"`.
+   * Everything else defaults to `loading="lazy"` + `decoding="async"`.
+   */
+  priority?: boolean;
+  loading?: "lazy" | "eager";
+  /** Per-component loader override; falls back to the configured loader. */
+  loader?: ImageLoader;
+  style?: string | JSX.CSSProperties;
+}
+/**
+ * Responsive, CLS-safe `<img>`. Renders plain markup — no client runtime, no
+ * hydration requirement — and delegates URL generation to a pluggable
+ * loader (see `configureImage()` and the `loader` prop).
+ */
+declare function Image(props: ImageProps): VNode;
+//#endregion
+//#region src/config.d.ts
+/**
+ * Device-width breakpoints used for `srcset` candidates when an image is
+ * responsive (`fill` or a `sizes` prop). Matches the next/image defaults.
+ */
+declare const DEFAULT_DEVICE_SIZES: readonly number[];
+/**
+ * Additional small widths used to snap fixed-size images to cache-friendly
+ * buckets. Matches the next/image defaults.
+ */
+declare const DEFAULT_IMAGE_SIZES: readonly number[];
+interface ImageConfig {
+  /** Loader used when a component does not pass its own `loader` prop. */
+  loader: ImageLoader;
+  /** Breakpoints used for responsive (`fill`/`sizes`) srcsets, ascending. */
+  deviceSizes: readonly number[];
+  /** Extra small widths merged into the snap list for fixed images. */
+  imageSizes: readonly number[];
+  /** Default quality when a component does not pass `quality`. */
+  quality: number;
+}
+/**
+ * Configure `<Image>` globally. Call once at module scope (for example in
+ * `src/routes.ts`) so the configuration applies on the server and in the
+ * browser. Individual components can still override via props.
+ */
+declare function configureImage(overrides: Partial<ImageConfig>): void;
+declare function getImageConfig(): ImageConfig;
+/** Restore the default configuration. Primarily useful in tests. */
+declare function resetImageConfig(): void;
+//#endregion
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_ENDPOINT, DEFAULT_IMAGE_SIZES, DEFAULT_QUALITY, Image, type ImageConfig, type ImageLoader, type ImageLoaderArgs, type ImageProps, cloudflareLoader, configureImage, createDefaultLoader, defaultLoader, getImageConfig, passthroughLoader, resetImageConfig, vercelLoader };

package/dist/index.mjs

@@ -0,0 +1,129 @@
+import { a as resetImageConfig, c as cloudflareLoader, d as passthroughLoader, f as vercelLoader, i as getImageConfig, l as createDefaultLoader, n as DEFAULT_IMAGE_SIZES, o as DEFAULT_IMAGE_ENDPOINT, r as configureImage, s as DEFAULT_QUALITY, t as DEFAULT_DEVICE_SIZES, u as defaultLoader } from "./config-BavYkV_M.mjs";
+import { h } from "preact";
+//#region src/image.ts
+const FILL_STYLE = {
+	position: "absolute",
+	height: "100%",
+	width: "100%",
+	left: 0,
+	top: 0,
+	right: 0,
+	bottom: 0
+};
+const FILL_STYLE_STRING = "position:absolute;height:100%;width:100%;left:0;top:0;right:0;bottom:0;";
+const warned = /* @__PURE__ */ new Set();
+function getNodeEnv() {
+	return globalThis.process?.env?.NODE_ENV;
+}
+function getImportMetaDev() {
+	const env = import.meta.env;
+	if (env?.MODE === "production") return false;
+	if (typeof env?.DEV === "boolean") return env.DEV;
+	if (typeof env?.MODE === "string") return env.MODE !== "production";
+}
+function isDevWarningsEnabled() {
+	const nodeEnv = getNodeEnv();
+	if (nodeEnv === "production") return false;
+	if (typeof nodeEnv === "string") return true;
+	return getImportMetaDev() ?? false;
+}
+function warnOnce(key, message) {
+	if (!isDevWarningsEnabled() || warned.has(key)) return;
+	warned.add(key);
+	console.error(message);
+}
+function toDimension(value) {
+	if (value == null) return void 0;
+	const parsed = typeof value === "number" ? value : Number.parseFloat(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+/** Snap a target width to the smallest configured size that covers it. */
+function snapToSizes(allSizes, target) {
+	for (const size of allSizes) if (size >= target) return size;
+	return allSizes[allSizes.length - 1];
+}
+function planSrcSet(deviceSizes, imageSizes, width, sizes) {
+	const allSizes = [...imageSizes, ...deviceSizes].sort((a, b) => a - b);
+	if (sizes) {
+		const viewportRatios = [];
+		const vwPattern = /(^|\s)(1?\d?\d)vw/g;
+		let match = vwPattern.exec(sizes);
+		while (match) {
+			viewportRatios.push(Number.parseInt(match[2], 10));
+			match = vwPattern.exec(sizes);
+		}
+		if (viewportRatios.length > 0) {
+			const smallestRatio = Math.min(...viewportRatios) / 100;
+			const floor = deviceSizes[0] * smallestRatio;
+			const widths = allSizes.filter((size) => size >= floor);
+			return {
+				widths: widths.length > 0 ? widths : [...deviceSizes],
+				descriptor: "w"
+			};
+		}
+		return {
+			widths: allSizes,
+			descriptor: "w"
+		};
+	}
+	if (width == null) return {
+		widths: [...deviceSizes],
+		descriptor: "w"
+	};
+	const oneX = snapToSizes(allSizes, width);
+	const twoX = snapToSizes(allSizes, width * 2);
+	return {
+		widths: oneX === twoX ? [oneX] : [oneX, twoX],
+		descriptor: "x"
+	};
+}
+/**
+* Responsive, CLS-safe `<img>`. Renders plain markup — no client runtime, no
+* hydration requirement — and delegates URL generation to a pluggable
+* loader (see `configureImage()` and the `loader` prop).
+*/
+function Image(props) {
+	const { src, alt, width, height, fill = false, sizes, quality, priority = false, loading, loader, style, ...rest } = props;
+	const config = getImageConfig();
+	const resolvedLoader = loader ?? config.loader;
+	const resolvedQuality = quality ?? config.quality;
+	const numericWidth = toDimension(width);
+	const numericHeight = toDimension(height);
+	if (isDevWarningsEnabled()) {
+		if (!fill && (numericWidth == null || numericHeight == null)) warnOnce(`dimensions:${src}`, `[pracht/image] <Image src="${src}"> is missing required "width" and "height" props. Provide the intrinsic dimensions (or use the "fill" prop) so the browser can reserve space and avoid layout shift.`);
+		if (fill && (width != null || height != null)) warnOnce(`fill-dimensions:${src}`, `[pracht/image] <Image src="${src}"> uses "fill" together with "width"/"height". "fill" images size themselves to their positioned parent; remove the explicit dimensions.`);
+	}
+	const effectiveSizes = sizes ?? (fill ? "100vw" : void 0);
+	const plan = planSrcSet(config.deviceSizes, config.imageSizes, numericWidth, effectiveSizes);
+	const candidates = plan.widths.map((candidateWidth) => resolvedLoader({
+		src,
+		width: candidateWidth,
+		quality: resolvedQuality
+	}));
+	const largestSrc = candidates[candidates.length - 1];
+	const optimized = new Set(candidates).size > 1;
+	const srcset = optimized ? candidates.map((url, index) => plan.descriptor === "w" ? `${url} ${plan.widths[index]}w` : `${url} ${index + 1}x`).join(", ") : void 0;
+	let mergedStyle = style;
+	if (fill) mergedStyle = typeof style === "string" ? `${FILL_STYLE_STRING}${style}` : {
+		...FILL_STYLE,
+		...style
+	};
+	const imgProps = {
+		...rest,
+		src: largestSrc,
+		alt,
+		decoding: rest.decoding ?? "async",
+		loading: loading ?? (priority ? "eager" : "lazy")
+	};
+	if (srcset) imgProps.srcset = srcset;
+	if (optimized && effectiveSizes) imgProps.sizes = effectiveSizes;
+	if (!fill) {
+		if (numericWidth != null) imgProps.width = numericWidth;
+		if (numericHeight != null) imgProps.height = numericHeight;
+	}
+	if (priority) imgProps.fetchpriority = "high";
+	if (mergedStyle != null) imgProps.style = mergedStyle;
+	return h("img", imgProps);
+}
+//#endregion
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_ENDPOINT, DEFAULT_IMAGE_SIZES, DEFAULT_QUALITY, Image, cloudflareLoader, configureImage, createDefaultLoader, defaultLoader, getImageConfig, passthroughLoader, resetImageConfig, vercelLoader };

package/dist/node.d.mts

@@ -0,0 +1,83 @@
+//#region src/node.d.ts
+/**
+ * Allowlist entry for remote image sources, mirroring next/image's
+ * `remotePatterns`. Without any patterns only same-origin (relative) `url`
+ * values are accepted, which keeps the endpoint from becoming an open proxy.
+ */
+interface RemotePattern {
+  /** Restrict to a protocol; both http and https match when omitted. */
+  protocol?: "http" | "https";
+  /** Exact hostname, or a `*.example.com` suffix wildcard. */
+  hostname: string;
+  /** Exact port; any port matches when omitted. */
+  port?: string;
+  /** Path prefix (e.g. `/uploads/`); any path matches when omitted. */
+  pathname?: string;
+}
+interface CreateImageHandlerOptions {
+  /** Remote sources to allow. Defaults to none (same-origin only). */
+  remotePatterns?: RemotePattern[];
+  /**
+   * Trusted public origin used to resolve relative image paths in production.
+   * Required for non-loopback requests so an attacker-controlled Host header
+   * cannot turn the endpoint into an open proxy. Loopback origins remain
+   * available without configuration for local development.
+   */
+  localOrigin?: string;
+  /**
+   * Widths the endpoint will produce. Requests for other widths are rejected
+   * so a caller cannot fill caches with arbitrary variants. Defaults to the
+   * union of the default device and image sizes; keep this in sync with
+   * `configureImage({ deviceSizes, imageSizes })` when you customize those.
+   */
+  allowedWidths?: number[];
+  /** Hard cap on the `w` parameter. Defaults to 3840. */
+  maxWidth?: number;
+  /**
+   * Modern formats to negotiate via the `Accept` header, tried in order.
+   * Defaults to `["image/webp"]`; add `"image/avif"` to opt in to AVIF
+   * (smaller files, noticeably slower to encode).
+   */
+  formats?: Array<"image/avif" | "image/webp">;
+  /** Cache-Control for successful responses. Defaults to 4 hours with revalidation. */
+  cacheControl?: string;
+  /** Reject source images larger than this many bytes. Defaults to 25 MiB. */
+  maxSourceBytes?: number;
+  /** Maximum number of validated redirects to follow. Defaults to 3. */
+  maxRedirects?: number;
+  /**
+   * Override how source images are fetched (useful for tests/CDNs). Redirect
+   * responses must be returned without following them; the handler validates
+   * each Location before making the next request.
+   */
+  fetchImage?: (url: URL, request: Request, signal?: AbortSignal) => Promise<Response>;
+  /** Override how sharp is imported (useful for tests). */
+  loadSharp?: () => Promise<unknown>;
+}
+interface ImageHandlerArgs {
+  request: Request;
+  signal?: AbortSignal;
+}
+/**
+ * Create the pracht image optimization endpoint.
+ *
+ * Mount it as an API route so it works with every adapter and in `pracht dev`
+ * without extra wiring:
+ *
+ * ```ts
+ * // src/api/_pracht/image.ts
+ * import { createImageHandler } from "@pracht/image/node";
+ * const imageHandler = createImageHandler();
+ * export const GET = imageHandler;
+ * export const HEAD = imageHandler;
+ * ```
+ *
+ * The handler resizes and re-encodes images with sharp (an optional peer
+ * dependency — install it in your app), negotiates WebP/AVIF via the `Accept`
+ * header, and answers with cacheable responses keyed on the query string.
+ * Relative sources resolve against a trusted `localOrigin` in production;
+ * `remotePatterns` opts specific remote hosts in.
+ */
+declare function createImageHandler(options?: CreateImageHandlerOptions): (args: ImageHandlerArgs) => Promise<Response>;
+//#endregion
+export { CreateImageHandlerOptions, RemotePattern, createImageHandler };

package/dist/node.mjs

@@ -0,0 +1,270 @@
+import { n as DEFAULT_IMAGE_SIZES, t as DEFAULT_DEVICE_SIZES } from "./config-BavYkV_M.mjs";
+//#region src/node.ts
+const SHARP_INSTALL_HINT = "Image optimization requires the optional \"sharp\" dependency. Install it in your app with \"pnpm add sharp\" (or npm install / yarn add) to enable the pracht image endpoint.";
+const DEFAULT_CACHE_CONTROL = "public, max-age=14400, must-revalidate";
+const DEFAULT_MAX_WIDTH = 3840;
+const DEFAULT_MAX_SOURCE_BYTES = 25 * 1024 * 1024;
+const DEFAULT_MAX_REDIRECTS = 3;
+const REDIRECT_STATUSES = new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+function createSharpImporter(load) {
+	let cached;
+	return () => {
+		cached ??= load().then((mod) => mod.default ?? mod, (error) => {
+			cached = void 0;
+			throw error;
+		});
+		return cached;
+	};
+}
+function errorResponse(status, message) {
+	return new Response(message, {
+		status,
+		headers: {
+			"content-type": "text/plain; charset=utf-8",
+			"cache-control": "no-store"
+		}
+	});
+}
+function matchesHostname(hostname, pattern) {
+	const host = hostname.toLowerCase();
+	const expected = pattern.toLowerCase();
+	if (expected.startsWith("*.")) return host.endsWith(expected.slice(1)) && host.length > expected.length - 1;
+	return host === expected;
+}
+function matchesRemotePatterns(url, patterns) {
+	return patterns.some((pattern) => {
+		if (pattern.protocol && `${pattern.protocol}:` !== url.protocol) return false;
+		if (pattern.port !== void 0 && pattern.port !== url.port) return false;
+		if (!matchesHostname(url.hostname, pattern.hostname)) return false;
+		if (pattern.pathname) {
+			const prefix = pattern.pathname.endsWith("/") ? pattern.pathname : `${pattern.pathname}/`;
+			if (url.pathname !== pattern.pathname && !url.pathname.startsWith(prefix)) return false;
+		}
+		return true;
+	});
+}
+function normalizeLocalOrigin(value) {
+	if (value === void 0) return void 0;
+	const url = new URL(value);
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) throw new Error("createImageHandler({ localOrigin }) expects an http(s) origin without a path.");
+	return url.origin;
+}
+function isLoopbackHostname(hostname) {
+	const host = hostname.toLowerCase();
+	return host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+function isAllowedTarget(url, localOrigin, patterns) {
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.username || url.password) return false;
+	return localOrigin !== void 0 && url.origin === localOrigin || matchesRemotePatterns(url, patterns);
+}
+function acceptsFormat(accept, format) {
+	return accept.split(",").some((entry) => {
+		const [mediaType, ...parameters] = entry.split(";");
+		if (mediaType.trim().toLowerCase() !== format) return false;
+		for (const parameter of parameters) {
+			const [name, value] = parameter.trim().split("=");
+			if (name?.toLowerCase() === "q" && Number(value) === 0) return false;
+		}
+		return true;
+	});
+}
+async function readCappedBody(response, maxBytes) {
+	if (!response.body) return new Uint8Array(await response.arrayBuffer());
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			await reader.cancel();
+			return null;
+		}
+		chunks.push(value);
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return body;
+}
+function responseBody(bytes) {
+	const body = new ArrayBuffer(bytes.byteLength);
+	new Uint8Array(body).set(bytes);
+	return body;
+}
+function imageResponseBody(request, bytes) {
+	return request.method === "HEAD" ? null : responseBody(bytes);
+}
+/**
+* Create the pracht image optimization endpoint.
+*
+* Mount it as an API route so it works with every adapter and in `pracht dev`
+* without extra wiring:
+*
+* ```ts
+* // src/api/_pracht/image.ts
+* import { createImageHandler } from "@pracht/image/node";
+* const imageHandler = createImageHandler();
+* export const GET = imageHandler;
+* export const HEAD = imageHandler;
+* ```
+*
+* The handler resizes and re-encodes images with sharp (an optional peer
+* dependency — install it in your app), negotiates WebP/AVIF via the `Accept`
+* header, and answers with cacheable responses keyed on the query string.
+* Relative sources resolve against a trusted `localOrigin` in production;
+* `remotePatterns` opts specific remote hosts in.
+*/
+function createImageHandler(options = {}) {
+	const remotePatterns = options.remotePatterns ?? [];
+	const configuredLocalOrigin = normalizeLocalOrigin(options.localOrigin);
+	const allowedWidths = new Set(options.allowedWidths ?? [...DEFAULT_IMAGE_SIZES, ...DEFAULT_DEVICE_SIZES]);
+	const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+	const formats = options.formats ?? ["image/webp"];
+	const cacheControl = options.cacheControl ?? DEFAULT_CACHE_CONTROL;
+	const maxSourceBytes = options.maxSourceBytes ?? DEFAULT_MAX_SOURCE_BYTES;
+	const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+	if (!Number.isInteger(maxRedirects) || maxRedirects < 0) throw new Error("createImageHandler({ maxRedirects }) expects a non-negative integer.");
+	const fetchImage = options.fetchImage ?? ((url, _request, signal) => fetch(url, {
+		headers: { accept: "image/*,*/*;q=0.8" },
+		redirect: "manual",
+		signal
+	}));
+	const importSharp = createSharpImporter(options.loadSharp ?? (() => import("sharp")));
+	return async function handleImageRequest({ request, signal }) {
+		if (request.method !== "GET" && request.method !== "HEAD") return new Response("Method Not Allowed", {
+			status: 405,
+			headers: { allow: "GET, HEAD" }
+		});
+		const requestUrl = new URL(request.url);
+		const localOrigin = configuredLocalOrigin ?? (isLoopbackHostname(requestUrl.hostname) ? requestUrl.origin : void 0);
+		const source = requestUrl.searchParams.get("url");
+		const widthParam = requestUrl.searchParams.get("w");
+		const qualityParam = requestUrl.searchParams.get("q");
+		if (!source) return errorResponse(400, "Missing required \"url\" query parameter.");
+		if (source.startsWith("//")) return errorResponse(400, "Protocol-relative \"url\" values are not allowed.");
+		let target;
+		if (/^https?:\/\//i.test(source)) {
+			try {
+				target = new URL(source);
+			} catch {
+				return errorResponse(400, `Invalid "url" parameter: ${source}`);
+			}
+			if (target.username || target.password) return errorResponse(400, "The \"url\" parameter may not contain credentials.");
+			if (!matchesRemotePatterns(target, remotePatterns)) return errorResponse(403, `Remote image "${source}" is not allowed. Add its host to the remotePatterns option of createImageHandler() to opt it in.`);
+		} else if (source.startsWith("/")) {
+			if (!localOrigin) return errorResponse(500, "Relative image sources require createImageHandler({ localOrigin }) outside local development.");
+			target = new URL(source, localOrigin);
+		} else return errorResponse(400, "The \"url\" parameter must be a relative path (starting with \"/\") or an absolute http(s) URL.");
+		if (!widthParam) return errorResponse(400, "Missing required \"w\" query parameter.");
+		const width = Number(widthParam);
+		if (!Number.isInteger(width) || width <= 0) return errorResponse(400, "The \"w\" parameter must be a positive integer.");
+		if (width > maxWidth) return errorResponse(400, `The "w" parameter may not exceed ${maxWidth}.`);
+		if (allowedWidths.size > 0 && !allowedWidths.has(width)) return errorResponse(400, `The width ${width} is not allowed. Allowed widths: ${[...allowedWidths].sort((a, b) => a - b).join(", ")}.`);
+		let quality = 75;
+		if (qualityParam !== null) {
+			quality = Number(qualityParam);
+			if (!Number.isInteger(quality) || quality < 1 || quality > 100) return errorResponse(400, "The \"q\" parameter must be an integer between 1 and 100.");
+		}
+		let upstream;
+		let currentTarget = target;
+		let redirectCount = 0;
+		while (true) {
+			try {
+				upstream = await fetchImage(currentTarget, request, signal);
+			} catch {
+				return errorResponse(502, `Failed to fetch source image "${source}".`);
+			}
+			if (!REDIRECT_STATUSES.has(upstream.status)) break;
+			const location = upstream.headers.get("location");
+			if (!location) return errorResponse(502, `Source image "${source}" returned a redirect without Location.`);
+			if (redirectCount >= maxRedirects) return errorResponse(502, `Source image "${source}" exceeded ${maxRedirects} redirects.`);
+			let nextTarget;
+			try {
+				nextTarget = new URL(location, currentTarget);
+			} catch {
+				return errorResponse(502, `Source image "${source}" returned an invalid redirect.`);
+			}
+			if (!isAllowedTarget(nextTarget, localOrigin, remotePatterns)) return errorResponse(403, `Source image "${source}" redirected to a host that is not allowed.`);
+			try {
+				await upstream.body?.cancel();
+			} catch {}
+			currentTarget = nextTarget;
+			redirectCount += 1;
+		}
+		if (upstream.url) {
+			let finalUrl;
+			try {
+				finalUrl = new URL(upstream.url);
+			} catch {
+				finalUrl = void 0;
+			}
+			if (finalUrl && !isAllowedTarget(finalUrl, localOrigin, remotePatterns)) return errorResponse(403, `Source image "${source}" redirected to a host that is not allowed.`);
+		}
+		if (!upstream.ok) return errorResponse(502, `Source image "${source}" responded with ${upstream.status}.`);
+		const sourceType = (upstream.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+		if (!sourceType.startsWith("image/")) return errorResponse(415, `Source "${source}" is not an image (got "${sourceType}").`);
+		const sourceBytes = await readCappedBody(upstream, maxSourceBytes);
+		if (sourceBytes == null) return errorResponse(413, `Source image "${source}" exceeds ${maxSourceBytes} bytes.`);
+		const baseHeaders = {
+			"cache-control": cacheControl,
+			vary: "Accept",
+			"x-content-type-options": "nosniff"
+		};
+		if (sourceType === "image/svg+xml" || sourceType === "image/gif") {
+			const headers = {
+				...baseHeaders,
+				"content-type": sourceType
+			};
+			if (sourceType === "image/svg+xml") headers["content-disposition"] = "attachment";
+			return new Response(imageResponseBody(request, sourceBytes), { headers });
+		}
+		let sharp;
+		try {
+			sharp = await importSharp();
+		} catch {
+			return errorResponse(500, SHARP_INSTALL_HINT);
+		}
+		const accept = request.headers.get("accept") ?? "";
+		let pipeline = sharp(sourceBytes).rotate().resize({
+			width,
+			withoutEnlargement: true
+		});
+		let contentType;
+		if (formats.includes("image/avif") && acceptsFormat(accept, "image/avif")) {
+			pipeline = pipeline.avif({ quality });
+			contentType = "image/avif";
+		} else if (formats.includes("image/webp") && acceptsFormat(accept, "image/webp")) {
+			pipeline = pipeline.webp({ quality });
+			contentType = "image/webp";
+		} else if (sourceType === "image/png") {
+			pipeline = pipeline.png();
+			contentType = "image/png";
+		} else {
+			pipeline = pipeline.jpeg({ quality });
+			contentType = "image/jpeg";
+		}
+		let output;
+		try {
+			output = await pipeline.toBuffer();
+		} catch {
+			return errorResponse(500, `Failed to optimize source image "${source}".`);
+		}
+		return new Response(imageResponseBody(request, output), { headers: {
+			...baseHeaders,
+			"content-type": contentType
+		} });
+	};
+}
+//#endregion
+export { createImageHandler };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pracht/image",
+  "version": "0.0.0",
+  "description": "Responsive, CLS-safe <Image> component for Pracht with pluggable optimization loaders and a Node image endpoint.",
+  "keywords": [
+    "pracht",
+    "preact",
+    "image",
+    "responsive",
+    "srcset",
+    "lazy-loading",
+    "image-optimization",
+    "sharp"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/image",
+  "bugs": {
+    "url": "https://github.com/JoviDeCroock/pracht/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JoviDeCroock/pracht",
+    "directory": "packages/image"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.mts",
+      "default": "./dist/node.mjs"
+    }
+  },
+  "publishConfig": {
+    "provenance": false,
+    "access": "public"
+  },
+  "peerDependencies": {
+    "preact": "^10.0.0",
+    "sharp": "^0.33.0 || ^0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "sharp": "^0.34.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}