@pracht/image 0.1.0 → 0.2.0

package/README.md

@@ -16,10 +16,14 @@ next/image's loader pattern.
   [sharp](https://sharp.pixelplumbing.com) (optional peer dependency) with a
   trusted-local-origin/remote-allowlist security model and revalidated cache
   headers.
+- Build-time `?pracht` image imports (`@pracht/image/vite`): Vite-managed asset
+  URL (hashed source assets or stable `publicDir` URLs), intrinsic dimensions
+  (EXIF-orientation aware), and a tiny inline `blurDataURL` for CSS-only
+  `placeholder="blur"`.
 
 ```bash
 pnpm add @pracht/image
-pnpm add sharp # only needed for the built-in endpoint
+pnpm add sharp # only needed for the built-in endpoint and ?pracht imports
 ```
 
 ```tsx
@@ -28,6 +32,13 @@ import { Image } from "@pracht/image";
 <Image src="/banner.jpg" alt="Banner" width={1200} height={280} priority />;
 ```
 
+```tsx
+// vite.config.ts: plugins: [pracht({ … }), prachtImage()] (from "@pracht/image/vite")
+import hero from "./hero.jpg?pracht"; // { src, width, height, blurDataURL }
+
+<Image src={hero} alt="Hero" placeholder="blur" />;
+```
+
 ```ts
 // src/api/_pracht/image.ts — mounts the optimization endpoint
 import { createImageHandler } from "@pracht/image/node";
@@ -40,8 +51,10 @@ 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.
+Set `localOrigin` to the same trusted origin used by
+`nodeAdapter({ canonicalOrigin })` in development and production. Relative
+sources fail closed when it is omitted; request and Host-derived origins are
+never trusted, even when they look like loopback addresses.
 
 See [docs/IMAGES.md](https://github.com/JoviDeCroock/pracht/blob/main/docs/IMAGES.md)
 for the full guide: loader configuration, endpoint security options, and

package/client.d.ts

@@ -0,0 +1,19 @@
+// Type declarations for build-time `?pracht` image imports (enabled by the
+// `prachtImage()` Vite plugin from "@pracht/image/vite").
+//
+// Reference this file once in your app, either with a triple-slash directive
+// in any .d.ts file:
+//
+//   /// <reference types="@pracht/image/client" />
+//
+// or via tsconfig: `"types": ["@pracht/image/client"]`.
+
+declare module "*?pracht" {
+  const metadata: import("@pracht/image").PrachtImageMetadata;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  /** Undefined for SVG sources (vectors scale cleanly without a blur). */
+  export const blurDataURL: string | undefined;
+  export default metadata;
+}

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { t as PrachtImageMetadata } from "./metadata-CA97TjOR.mjs";
 import { JSX, VNode } from "preact";
 
 //#region src/loaders.d.ts
@@ -48,9 +49,13 @@ declare const vercelLoader: ImageLoader;
 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;
+interface ImageProps extends Omit<JSX.HTMLAttributes<HTMLImageElement>, "src" | "srcset" | "srcSet" | "width" | "height" | "sizes" | "loading" | "alt" | "style" | "placeholder"> {
+  /**
+   * Source path (`/hero.jpg`), absolute URL, or the metadata object from a
+   * build-time `?pracht` import (which supplies `width`, `height`, and
+   * `blurDataURL` automatically).
+   */
+  src: string | PrachtImageMetadata;
   /** Required for accessibility. Use `alt=""` for decorative images. */
   alt: string;
   /** Intrinsic width in pixels. Required unless `fill` is set. */
@@ -74,6 +79,22 @@ interface ImageProps extends Omit<JSX.HTMLAttributes<HTMLImageElement>, "src" |
   loading?: "lazy" | "eager";
   /** Per-component loader override; falls back to the configured loader. */
   loader?: ImageLoader;
+  /**
+   * `"blur"` paints a tiny inline preview behind the image while it loads.
+   * Requires a `blurDataURL` — supplied automatically when `src` is a
+   * `?pracht` import, or pass it by hand. The placeholder is pure CSS
+   * (a `background-image` on the `<img>` itself), so it needs no hydration
+   * and works with `hydration: "none"`; the real image simply covers it once
+   * it paints. Note: images with transparency show the placeholder through
+   * transparent regions — prefer `placeholder="empty"` for those.
+   */
+  placeholder?: "blur" | "empty";
+  /**
+   * `data:image/…` URI painted behind the image when `placeholder="blur"`.
+   * Values that are not well-formed image data URIs are ignored (they could
+   * otherwise inject CSS via the style attribute).
+   */
+  blurDataURL?: string;
   style?: string | JSX.CSSProperties;
 }
 /**
@@ -114,4 +135,4 @@ 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 };
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_ENDPOINT, DEFAULT_IMAGE_SIZES, DEFAULT_QUALITY, Image, type ImageConfig, type ImageLoader, type ImageLoaderArgs, type ImageProps, type PrachtImageMetadata, cloudflareLoader, configureImage, createDefaultLoader, defaultLoader, getImageConfig, passthroughLoader, resetImageConfig, vercelLoader };

package/dist/index.mjs

@@ -11,15 +11,29 @@ const FILL_STYLE = {
 	bottom: 0
 };
 const FILL_STYLE_STRING = "position:absolute;height:100%;width:100%;left:0;top:0;right:0;bottom:0;";
+const BLUR_DATA_URL_PATTERN = /^data:image\/[a-z0-9.+-]+(?:;[a-z0-9=+-]+)*,[a-z0-9+/=._%-]*$/i;
+function blurBackground(blurDataURL) {
+	const image = `url("${blurDataURL}")`;
+	return {
+		styleString: `background-image:${image};background-size:cover;background-position:50% 50%;background-repeat:no-repeat;`,
+		styleObject: {
+			backgroundImage: image,
+			backgroundSize: "cover",
+			backgroundPosition: "50% 50%",
+			backgroundRepeat: "no-repeat"
+		}
+	};
+}
 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";
+	const mode = import.meta.env?.MODE;
+	if (mode === "production") return false;
+	const dev = import.meta.env?.DEV;
+	if (typeof dev === "boolean") return dev;
+	if (typeof mode === "string") return mode !== "production";
 }
 function isDevWarningsEnabled() {
 	const nodeEnv = getNodeEnv();
@@ -83,31 +97,42 @@ function planSrcSet(deviceSizes, imageSizes, width, sizes) {
 * 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 { src, alt, width, height, fill = false, sizes, quality, priority = false, loading, loader, placeholder = "empty", blurDataURL, style, ...rest } = props;
+	const metadata = typeof src === "string" ? void 0 : src;
+	const srcString = typeof src === "string" ? src : src.src;
 	const config = getImageConfig();
 	const resolvedLoader = loader ?? config.loader;
 	const resolvedQuality = quality ?? config.quality;
-	const numericWidth = toDimension(width);
-	const numericHeight = toDimension(height);
+	const numericWidth = toDimension(width) ?? (fill ? void 0 : metadata?.width);
+	const numericHeight = toDimension(height) ?? (fill ? void 0 : metadata?.height);
+	const resolvedBlurDataURL = placeholder === "blur" ? blurDataURL ?? metadata?.blurDataURL : void 0;
+	const safeBlurDataURL = resolvedBlurDataURL != null && BLUR_DATA_URL_PATTERN.test(resolvedBlurDataURL) ? resolvedBlurDataURL : void 0;
 	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.`);
+		if (!fill && (numericWidth == null || numericHeight == null)) warnOnce(`dimensions:${srcString}`, `[pracht/image] <Image src="${srcString}"> 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:${srcString}`, `[pracht/image] <Image src="${srcString}"> uses "fill" together with "width"/"height". "fill" images size themselves to their positioned parent; remove the explicit dimensions.`);
+		if (placeholder === "blur" && resolvedBlurDataURL == null) warnOnce(`blur-missing:${srcString}`, `[pracht/image] <Image src="${srcString}"> uses placeholder="blur" without a blurDataURL. Import the image with the "?pracht" query (via prachtImage() from "@pracht/image/vite") or pass a blurDataURL prop. Rendering without a placeholder.`);
+		if (resolvedBlurDataURL != null && safeBlurDataURL == null) warnOnce(`blur-invalid:${srcString}`, `[pracht/image] <Image src="${srcString}"> received a blurDataURL that is not a well-formed "data:image/…" URI. It was ignored because interpolating arbitrary strings into the style attribute could inject CSS.`);
 	}
 	const effectiveSizes = sizes ?? (fill ? "100vw" : void 0);
 	const plan = planSrcSet(config.deviceSizes, config.imageSizes, numericWidth, effectiveSizes);
 	const candidates = plan.widths.map((candidateWidth) => resolvedLoader({
-		src,
+		src: srcString,
 		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;
+	const blur = safeBlurDataURL != null ? blurBackground(safeBlurDataURL) : void 0;
 	let mergedStyle = style;
-	if (fill) mergedStyle = typeof style === "string" ? `${FILL_STYLE_STRING}${style}` : {
-		...FILL_STYLE,
-		...style
-	};
+	if (blur || fill) {
+		const baseString = `${blur?.styleString ?? ""}${fill ? FILL_STYLE_STRING : ""}`;
+		mergedStyle = typeof style === "string" ? `${baseString}${style}` : {
+			...blur?.styleObject,
+			...fill ? FILL_STYLE : void 0,
+			...style
+		};
+	}
 	const imgProps = {
 		...rest,
 		src: largestSrc,

package/dist/metadata-CA97TjOR.d.mts

@@ -0,0 +1,29 @@
+//#region src/metadata.d.ts
+/**
+ * Metadata produced by a build-time `?pracht` image import (see
+ * `prachtImage()` from `@pracht/image/vite`).
+ *
+ * ```ts
+ * import hero from "./hero.jpg?pracht";
+ * // hero: { src, width, height, blurDataURL }
+ * ```
+ *
+ * Pass the whole object to `<Image src={hero} …>` to get intrinsic sizing and
+ * `placeholder="blur"` support without repeating dimensions by hand.
+ */
+interface PrachtImageMetadata {
+  /** Final asset URL (hashed in production builds, dev-served in dev). */
+  src: string;
+  /** Intrinsic width in pixels, after applying EXIF orientation. */
+  width: number;
+  /** Intrinsic height in pixels, after applying EXIF orientation. */
+  height: number;
+  /**
+   * Tiny inline preview (`data:image/webp;base64,…`, ~8px wide) for
+   * `placeholder="blur"`. Undefined for SVG sources: vectors scale cleanly,
+   * so a raster blur adds bytes without adding information.
+   */
+  blurDataURL?: string;
+}
+//#endregion
+export { PrachtImageMetadata as t };

package/dist/node.d.mts

@@ -18,10 +18,9 @@ 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.
+   * Trusted origin used to resolve relative image paths. Required whenever
+   * relative sources are served so an attacker-controlled Host header cannot
+   * turn the endpoint into an open proxy.
    */
   localOrigin?: string;
   /**
@@ -67,7 +66,9 @@ interface ImageHandlerArgs {
  * ```ts
  * // src/api/_pracht/image.ts
  * import { createImageHandler } from "@pracht/image/node";
- * const imageHandler = createImageHandler();
+ * const imageHandler = createImageHandler({
+ *   localOrigin: process.env.PRACHT_ORIGIN,
+ * });
  * export const GET = imageHandler;
  * export const HEAD = imageHandler;
  * ```
@@ -75,7 +76,7 @@ interface ImageHandlerArgs {
  * 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;
+ * Relative sources resolve only against a configured, trusted `localOrigin`;
  * `remotePatterns` opts specific remote hosts in.
  */
 declare function createImageHandler(options?: CreateImageHandlerOptions): (args: ImageHandlerArgs) => Promise<Response>;

package/dist/node.mjs

@@ -55,10 +55,6 @@ function normalizeLocalOrigin(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);
@@ -114,7 +110,9 @@ function imageResponseBody(request, bytes) {
 * ```ts
 * // src/api/_pracht/image.ts
 * import { createImageHandler } from "@pracht/image/node";
-* const imageHandler = createImageHandler();
+* const imageHandler = createImageHandler({
+*   localOrigin: process.env.PRACHT_ORIGIN,
+* });
 * export const GET = imageHandler;
 * export const HEAD = imageHandler;
 * ```
@@ -122,7 +120,7 @@ function imageResponseBody(request, bytes) {
 * 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;
+* Relative sources resolve only against a configured, trusted `localOrigin`;
 * `remotePatterns` opts specific remote hosts in.
 */
 function createImageHandler(options = {}) {
@@ -147,7 +145,6 @@ function createImageHandler(options = {}) {
 			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");
@@ -163,8 +160,9 @@ function createImageHandler(options = {}) {
 			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);
+			if (!configuredLocalOrigin) return errorResponse(500, "Relative image sources require createImageHandler({ localOrigin }).");
+			target = new URL(source, configuredLocalOrigin);
+			if (target.origin !== configuredLocalOrigin) return errorResponse(400, "Relative \"url\" values must remain on the configured 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);
@@ -195,7 +193,7 @@ function createImageHandler(options = {}) {
 			} 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.`);
+			if (!isAllowedTarget(nextTarget, configuredLocalOrigin, remotePatterns)) return errorResponse(403, `Source image "${source}" redirected to a host that is not allowed.`);
 			try {
 				await upstream.body?.cancel();
 			} catch {}
@@ -209,7 +207,7 @@ function createImageHandler(options = {}) {
 			} 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 (finalUrl && !isAllowedTarget(finalUrl, configuredLocalOrigin, 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();

package/dist/vite.d.mts

@@ -0,0 +1,88 @@
+/**
+ * Vite plugin enabling build-time image imports:
+ *
+ * ```ts
+ * // vite.config.ts — add it next to pracht(); it is not included by default.
+ * import { prachtImage } from "@pracht/image/vite";
+ * export default { plugins: [pracht({ … }), prachtImage()] };
+ * ```
+ *
+ * ```tsx
+ * import hero from "./hero.jpg?pracht";
+ * <Image src={hero} alt="…" placeholder="blur" />;
+ * ```
+ *
+ * The import yields `{ src, width, height, blurDataURL }`: `src` goes through
+ * Vite's normal asset pipeline (hashed source assets, stable publicDir URLs,
+ * `base`, dev server), dimensions come from sharp metadata with EXIF
+ * orientation applied, and `blurDataURL` is a tiny inline WebP generated at
+ * build time. Add
+ * `/// <reference types="@pracht/image/client" />` (or `"types":
+ * ["@pracht/image/client"]` in tsconfig) so TypeScript understands the query.
+ */import { t as PrachtImageMetadata } from "./metadata-CA97TjOR.mjs";
+import { Plugin } from "vite";
+
+//#region src/vite.d.ts
+/**
+ * Options for the `?pracht` image import plugin.
+ */
+interface PrachtImageOptions {
+  /**
+   * Width in pixels of the generated blur placeholder. Kept tiny on purpose:
+   * the placeholder is inlined as a base64 data URI in HTML and JS.
+   * Defaults to 8.
+   */
+  blurWidth?: number;
+  /** WebP quality (1-100) of the blur placeholder. Defaults to 70. */
+  blurQuality?: number;
+  /** Override how sharp is imported (useful for tests). */
+  loadSharp?: () => Promise<unknown>;
+}
+/** Minimal structural typing for the parts of sharp used at build time. */
+interface SharpMetadata {
+  format?: string;
+  width?: number;
+  height?: number;
+  orientation?: number;
+  pages?: number;
+}
+interface SharpPipeline {
+  metadata(): Promise<SharpMetadata>;
+  rotate(): SharpPipeline;
+  resize(options: {
+    width: number;
+    withoutEnlargement: boolean;
+  }): SharpPipeline;
+  webp(options: {
+    quality: number;
+  }): SharpPipeline;
+  toBuffer(): Promise<Uint8Array>;
+}
+type SharpFactory = (input: Uint8Array) => SharpPipeline;
+/** `/path/to/hero.jpg?pracht` → true; `?pracht` may combine with other params. */
+declare function isPrachtImageId(id: string): boolean;
+/** Strip the entire query, leaving the file path. */
+declare function stripImageQuery(id: string): string;
+/**
+ * Read intrinsic dimensions (respecting EXIF orientation) and generate the
+ * blur placeholder for one image buffer. Exported for tests.
+ */
+declare function analyzeImage(sharp: SharpFactory, source: Uint8Array, options: {
+  blurWidth: number;
+  blurQuality: number;
+}): Promise<Omit<PrachtImageMetadata, "src">>;
+/**
+ * Generate the virtual module for a `?pracht` import. The `?url` import
+ * delegates the actual file to Vite's asset pipeline, so hashing, `base`,
+ * and dev serving all behave exactly like a plain asset import. `no-inline`
+ * opts out of `assetsInlineLimit`: without it, images under the limit
+ * (default 4 KB) turn `src` into a `data:` URI, which breaks
+ * optimization-endpoint loaders (`/api/_pracht/image?url=data%3A…` is not a
+ * fetchable same-origin path) and double-ships the bytes next to
+ * `blurDataURL`. The metadata contract promises a real asset URL (hashed for
+ * source files, stable for publicDir files). Exported for tests.
+ */
+declare function createImageModuleCode(assetId: string, analyzed: Omit<PrachtImageMetadata, "src">): string;
+declare function prachtImage(options?: PrachtImageOptions): Plugin;
+//#endregion
+export { PrachtImageOptions, analyzeImage, createImageModuleCode, isPrachtImageId, prachtImage, stripImageQuery };

package/dist/vite.mjs

@@ -0,0 +1,184 @@
+import { readFile, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+//#region src/vite.ts
+const PRACHT_IMAGE_QUERY = "pracht";
+const DEFAULT_BLUR_WIDTH = 8;
+const DEFAULT_BLUR_QUALITY = 70;
+const SHARP_INSTALL_HINT = "[pracht/image] \"?pracht\" image imports require the optional \"sharp\" dependency at build time. Install it in your app with \"pnpm add -D sharp\" (or npm install -D sharp / yarn add -D sharp).";
+function createSharpImporter(load) {
+	let cached;
+	return () => {
+		cached ??= load().then((mod) => mod.default ?? mod, () => {
+			cached = void 0;
+			throw new Error(SHARP_INSTALL_HINT);
+		});
+		return cached;
+	};
+}
+/** `/path/to/hero.jpg?pracht` → true; `?pracht` may combine with other params. */
+function isPrachtImageId(id) {
+	const queryStart = id.indexOf("?");
+	if (queryStart === -1) return false;
+	return id.slice(queryStart + 1).split("&").some((part) => part === PRACHT_IMAGE_QUERY);
+}
+/** Strip the entire query, leaving the file path. */
+function stripImageQuery(id) {
+	const queryStart = id.indexOf("?");
+	return queryStart === -1 ? id : id.slice(0, queryStart);
+}
+/**
+* Read intrinsic dimensions (respecting EXIF orientation) and generate the
+* blur placeholder for one image buffer. Exported for tests.
+*/
+async function analyzeImage(sharp, source, options) {
+	const metadata = await sharp(source).metadata();
+	let width = metadata.width;
+	let height = metadata.height;
+	const orientation = metadata.orientation ?? 1;
+	if (orientation >= 5 && orientation <= 8) {
+		width = metadata.height;
+		height = metadata.width;
+	}
+	if (width == null || height == null || width <= 0 || height <= 0) throw new Error(`could not determine intrinsic dimensions (format: ${metadata.format ?? "unknown"}). For SVG sources, add width/height or a viewBox attribute.`);
+	if (metadata.format === "svg") return {
+		width,
+		height
+	};
+	const blur = await sharp(source).rotate().resize({
+		width: options.blurWidth,
+		withoutEnlargement: true
+	}).webp({ quality: options.blurQuality }).toBuffer();
+	return {
+		width,
+		height,
+		blurDataURL: `data:image/webp;base64,${Buffer.from(blur).toString("base64")}`
+	};
+}
+/**
+* Generate the virtual module for a `?pracht` import. The `?url` import
+* delegates the actual file to Vite's asset pipeline, so hashing, `base`,
+* and dev serving all behave exactly like a plain asset import. `no-inline`
+* opts out of `assetsInlineLimit`: without it, images under the limit
+* (default 4 KB) turn `src` into a `data:` URI, which breaks
+* optimization-endpoint loaders (`/api/_pracht/image?url=data%3A…` is not a
+* fetchable same-origin path) and double-ships the bytes next to
+* `blurDataURL`. The metadata contract promises a real asset URL (hashed for
+* source files, stable for publicDir files). Exported for tests.
+*/
+function createImageModuleCode(assetId, analyzed) {
+	const assetImport = `${assetId.replace(/\\/g, "/")}?url&no-inline`;
+	return [
+		`import src from ${JSON.stringify(assetImport)};`,
+		`export const width = ${JSON.stringify(analyzed.width)};`,
+		`export const height = ${JSON.stringify(analyzed.height)};`,
+		`export const blurDataURL = ${JSON.stringify(analyzed.blurDataURL)};`,
+		"export { src };",
+		"export default { src, width, height, blurDataURL };"
+	].join("\n");
+}
+async function resolvePublicFile(publicDir, source) {
+	if (!publicDir || !source.startsWith("/")) return void 0;
+	const candidate = resolve(publicDir, `.${source}`);
+	const relativePath = relative(publicDir, candidate);
+	if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) return;
+	return (await stat(candidate).catch(() => void 0))?.isFile() ? candidate : void 0;
+}
+/**
+* Vite plugin enabling build-time image imports:
+*
+* ```ts
+* // vite.config.ts — add it next to pracht(); it is not included by default.
+* import { prachtImage } from "@pracht/image/vite";
+* export default { plugins: [pracht({ … }), prachtImage()] };
+* ```
+*
+* ```tsx
+* import hero from "./hero.jpg?pracht";
+* <Image src={hero} alt="…" placeholder="blur" />;
+* ```
+*
+* The import yields `{ src, width, height, blurDataURL }`: `src` goes through
+* Vite's normal asset pipeline (hashed source assets, stable publicDir URLs,
+* `base`, dev server), dimensions come from sharp metadata with EXIF
+* orientation applied, and `blurDataURL` is a tiny inline WebP generated at
+* build time. Add
+* `/// <reference types="@pracht/image/client" />` (or `"types":
+* ["@pracht/image/client"]` in tsconfig) so TypeScript understands the query.
+*/
+function prachtImage(options = {}) {
+	const blurWidth = options.blurWidth ?? DEFAULT_BLUR_WIDTH;
+	const blurQuality = options.blurQuality ?? DEFAULT_BLUR_QUALITY;
+	if (!Number.isInteger(blurWidth) || blurWidth < 1 || blurWidth > 64) throw new Error("prachtImage({ blurWidth }) expects an integer between 1 and 64.");
+	if (!Number.isInteger(blurQuality) || blurQuality < 1 || blurQuality > 100) throw new Error("prachtImage({ blurQuality }) expects an integer between 1 and 100.");
+	const importSharp = createSharpImporter(options.loadSharp ?? (() => import("sharp")));
+	const cache = /* @__PURE__ */ new Map();
+	const resolvedImages = /* @__PURE__ */ new Map();
+	let publicDir = "";
+	async function transform(filePath, assetId) {
+		const stats = await stat(filePath).catch(() => {
+			throw new Error(`[pracht/image] Could not read "${filePath}" for a "?pracht" import.`);
+		});
+		const cacheKey = `${filePath}\0${assetId}`;
+		const cached = cache.get(cacheKey);
+		if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) return cached.code;
+		const code = (async () => {
+			const [sharp, source] = await Promise.all([importSharp(), readFile(filePath)]);
+			let analyzed;
+			try {
+				analyzed = await analyzeImage(sharp, source, {
+					blurWidth,
+					blurQuality
+				});
+			} catch (error) {
+				throw new Error(`[pracht/image] Failed to process "?pracht" import of "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return createImageModuleCode(assetId, analyzed);
+		})();
+		code.catch(() => cache.delete(cacheKey));
+		cache.set(cacheKey, {
+			mtimeMs: stats.mtimeMs,
+			size: stats.size,
+			code
+		});
+		return code;
+	}
+	return {
+		name: "pracht:image-imports",
+		enforce: "pre",
+		configResolved(config) {
+			publicDir = config.publicDir;
+		},
+		async resolveId(source, importer) {
+			if (!isPrachtImageId(source)) return null;
+			const sourcePath = stripImageQuery(source);
+			const resolved = await this.resolve(sourcePath, importer, { skipSelf: true });
+			if (!resolved) return null;
+			const publicFile = resolved.id === sourcePath ? await resolvePublicFile(publicDir, sourcePath) : void 0;
+			const moduleId = `${resolved.id}${resolved.id.includes("?") ? "&" : "?"}${PRACHT_IMAGE_QUERY}`;
+			resolvedImages.set(moduleId, {
+				filePath: publicFile ?? resolved.id,
+				assetId: publicFile ? sourcePath : resolved.id
+			});
+			return moduleId;
+		},
+		async load(id) {
+			if (!isPrachtImageId(id)) return null;
+			const resolved = resolvedImages.get(id) ?? {
+				filePath: stripImageQuery(id),
+				assetId: stripImageQuery(id)
+			};
+			this.addWatchFile(resolved.filePath);
+			return transform(resolved.filePath, resolved.assetId);
+		},
+		watchChange(filePath) {
+			if (this.environment.mode !== "dev") return;
+			for (const [moduleId, resolved] of resolvedImages) {
+				if (resolved.filePath.replace(/\\/g, "/") !== filePath.replace(/\\/g, "/")) continue;
+				const module = this.environment.moduleGraph.getModuleById(moduleId);
+				if (module) this.environment.moduleGraph.invalidateModule(module);
+			}
+		}
+	};
+}
+//#endregion
+export { analyzeImage, createImageModuleCode, isPrachtImageId, prachtImage, stripImageQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/image",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Responsive, CLS-safe <Image> component for Pracht with pluggable optimization loaders and a Node image endpoint.",
   "keywords": [
     "pracht",
@@ -23,7 +23,8 @@
     "directory": "packages/image"
   },
   "files": [
-    "dist"
+    "dist",
+    "client.d.ts"
   ],
   "type": "module",
   "exports": {
@@ -34,22 +35,34 @@
     "./node": {
       "types": "./dist/node.d.mts",
       "default": "./dist/node.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "default": "./dist/vite.mjs"
+    },
+    "./client": {
+      "types": "./client.d.ts"
     }
   },
   "publishConfig": {
     "provenance": true
   },
   "peerDependencies": {
-    "preact": "^10.0.0",
-    "sharp": "^0.33.0 || ^0.34.0"
+    "preact": "^10.0.0 || ^11.0.0-0",
+    "sharp": "^0.33.0 || ^0.34.0",
+    "vite": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
       "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "sharp": "^0.34.0"
+    "sharp": "^0.34.0",
+    "vite": "^8.0.0"
   },
   "scripts": {
     "build": "tsdown"