@pracht/image 0.2.0 → 0.4.0

package/README.md

@@ -20,6 +20,10 @@ next/image's loader pattern.
   URL (hashed source assets or stable `publicDir` URLs), intrinsic dimensions
   (EXIF-orientation aware), and a tiny inline `blurDataURL` for CSS-only
   `placeholder="blur"`.
+- Cached `?pracht&pracht-static` imports that emit responsive, content-hashed
+  WebP variants for static hosts and zero-hydration pages.
+- `getImageProps()` for HTML compilers that need exactly the same plain
+  `<img>` attributes as the Preact component.
 
 ```bash
 pnpm add @pracht/image
@@ -33,12 +37,24 @@ import { Image } from "@pracht/image";
 ```
 
 ```tsx
-// vite.config.ts: plugins: [pracht({ … }), prachtImage()] (from "@pracht/image/vite")
+// vite.config.ts: plugins: [prachtImage(), pracht({ … })]
 import hero from "./hero.jpg?pracht"; // { src, width, height, blurDataURL }
 
 <Image src={hero} alt="Hero" placeholder="blur" />;
 ```
 
+For prebuilt responsive files, import
+`./hero.jpg?pracht&pracht-static`. Configure the candidate widths and quality
+with `prachtImage({ staticWidths, staticQuality })`. Static metadata bypasses
+the global runtime loader unless the component supplies an explicit `loader`.
+Server-only route variants are published to `dist/client` by default; use
+`staticOutDir` for a different adapter-served directory. SVG and animated
+sources keep their original encoded bytes but are still published when only a
+server graph discovers them. Identical pass-through sources share one hashed
+URL while retaining a live source if another copy changes. Root-relative
+`publicDir` sources stay unprocessed at their stable public URLs and bypass the
+global runtime loader for static imports.
+
 ```ts
 // src/api/_pracht/image.ts — mounts the optimization endpoint
 import { createImageHandler } from "@pracht/image/node";

package/client.d.ts

@@ -17,3 +17,14 @@ declare module "*?pracht" {
   export const blurDataURL: string | undefined;
   export default metadata;
 }
+
+declare module "*?pracht&pracht-static" {
+  const metadata: import("@pracht/image").PrachtImageMetadata;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  /** Undefined for unprocessed root-relative publicDir sources. */
+  export const variants: readonly import("@pracht/image").PrachtImageVariant[] | undefined;
+  export default metadata;
+}

package/dist/{config-BavYkV_M.mjs → config-HOu7M27N.mjs}

@@ -1,5 +1,16 @@
 //#region src/loaders.ts
 const DEFAULT_QUALITY = 75;
+function normalizeDeployBase(raw) {
+	if (typeof raw !== "string" || raw === "" || raw === "." || raw === "./") return "/";
+	if (raw.includes("://") || raw.startsWith("//")) return "/";
+	const withLeadingSlash = raw.startsWith("/") ? raw : `/${raw}`;
+	return withLeadingSlash.endsWith("/") ? withLeadingSlash : `${withLeadingSlash}/`;
+}
+function withDeployBase(path) {
+	if (!path.startsWith("/") || path.startsWith("//")) return path;
+	const base = normalizeDeployBase(import.meta.env?.BASE_URL);
+	return base === "/" ? path : `${base}${path.slice(1)}`;
+}
 /**
 * The default optimization endpoint. It maps onto an API route file at
 * `src/api/_pracht/image.ts` that re-exports the handler from
@@ -11,7 +22,7 @@ const DEFAULT_IMAGE_ENDPOINT = "/api/_pracht/image";
 * 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}`;
+	return ({ src, width, quality }) => `${withDeployBase(endpoint)}?url=${encodeURIComponent(src)}&w=${width}&q=${quality ?? 75}`;
 }
 /**
 * Targets the pracht image endpoint served by `createImageHandler()` from

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { t as PrachtImageMetadata } from "./metadata-CA97TjOR.mjs";
+import { n as PrachtImageVariant, t as PrachtImageMetadata } from "./metadata-Dap0USIM.mjs";
 import { JSX, VNode } from "preact";
 
 //#region src/loaders.d.ts
@@ -103,6 +103,13 @@ interface ImageProps extends Omit<JSX.HTMLAttributes<HTMLImageElement>, "src" |
  * loader (see `configureImage()` and the `loader` prop).
  */
 declare function Image(props: ImageProps): VNode;
+/**
+ * Resolve the plain `<img>` attributes used by {@link Image}. This is useful
+ * for HTML compilers such as `@pracht/markdown`, which need the exact same
+ * sizing, loader, placeholder, and priority semantics without mounting a
+ * second Preact renderer.
+ */
+declare function getImageProps(props: ImageProps): JSX.IntrinsicElements["img"];
 //#endregion
 //#region src/config.d.ts
 /**
@@ -135,4 +142,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, type PrachtImageMetadata, 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, type PrachtImageVariant, cloudflareLoader, configureImage, createDefaultLoader, defaultLoader, getImageConfig, getImageProps, passthroughLoader, resetImageConfig, vercelLoader };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-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 { 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-HOu7M27N.mjs";
 import { h } from "preact";
 //#region src/image.ts
 const FILL_STYLE = {
@@ -97,6 +97,15 @@ function planSrcSet(deviceSizes, imageSizes, width, sizes) {
 * loader (see `configureImage()` and the `loader` prop).
 */
 function Image(props) {
+	return h("img", getImageProps(props));
+}
+/**
+* Resolve the plain `<img>` attributes used by {@link Image}. This is useful
+* for HTML compilers such as `@pracht/markdown`, which need the exact same
+* sizing, loader, placeholder, and priority semantics without mounting a
+* second Preact renderer.
+*/
+function getImageProps(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;
@@ -113,16 +122,19 @@ function Image(props) {
 		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 staticMetadata = loader == null && metadata != null && Object.hasOwn(metadata, "variants");
+	const staticVariants = staticMetadata ? metadata.variants : void 0;
+	const effectiveSizes = sizes ?? (fill ? "100vw" : staticVariants?.length && numericWidth != null ? `(max-width: ${numericWidth}px) 100vw, ${numericWidth}px` : void 0);
 	const plan = planSrcSet(config.deviceSizes, config.imageSizes, numericWidth, effectiveSizes);
-	const candidates = plan.widths.map((candidateWidth) => resolvedLoader({
+	const candidates = staticVariants?.length ? staticVariants.map((variant) => variant.src) : staticMetadata ? [srcString] : plan.widths.map((candidateWidth) => resolvedLoader({
 		src: srcString,
 		width: candidateWidth,
 		quality: resolvedQuality
 	}));
-	const largestSrc = candidates[candidates.length - 1];
+	const candidateWidths = staticVariants?.length ? staticVariants.map((variant) => variant.width) : plan.widths;
+	const largestSrc = candidates[candidates.length - 1] ?? srcString;
 	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 srcset = optimized ? candidates.map((url, index) => staticVariants?.length || plan.descriptor === "w" ? `${url} ${candidateWidths[index]}w` : `${url} ${index + 1}x`).join(", ") : void 0;
 	const blur = safeBlurDataURL != null ? blurBackground(safeBlurDataURL) : void 0;
 	let mergedStyle = style;
 	if (blur || fill) {
@@ -148,7 +160,7 @@ function Image(props) {
 	}
 	if (priority) imgProps.fetchpriority = "high";
 	if (mergedStyle != null) imgProps.style = mergedStyle;
-	return h("img", imgProps);
+	return imgProps;
 }
 //#endregion
-export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_ENDPOINT, DEFAULT_IMAGE_SIZES, DEFAULT_QUALITY, Image, cloudflareLoader, configureImage, createDefaultLoader, defaultLoader, getImageConfig, passthroughLoader, resetImageConfig, vercelLoader };
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_ENDPOINT, DEFAULT_IMAGE_SIZES, DEFAULT_QUALITY, Image, cloudflareLoader, configureImage, createDefaultLoader, defaultLoader, getImageConfig, getImageProps, passthroughLoader, resetImageConfig, vercelLoader };

package/dist/{metadata-CA97TjOR.d.mts → metadata-Dap0USIM.d.mts}

@@ -24,6 +24,20 @@ interface PrachtImageMetadata {
    * so a raster blur adds bytes without adding information.
    */
   blurDataURL?: string;
+  /**
+   * Build-generated responsive variants. Present for `?pracht&pracht-static`
+   * imports; ordinary `?pracht` imports continue to expose the hashed original
+   * and rely on the configured runtime/platform loader.
+   */
+  variants?: readonly PrachtImageVariant[];
+}
+interface PrachtImageVariant {
+  /** Final, base-aware URL of the generated asset. */
+  src: string;
+  /** Raster width represented by this candidate. */
+  width: number;
+  /** MIME type of the generated asset. */
+  type: `image/${string}`;
 }
 //#endregion
-export { PrachtImageMetadata as t };
+export { PrachtImageVariant as n, PrachtImageMetadata as t };

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { n as DEFAULT_IMAGE_SIZES, t as DEFAULT_DEVICE_SIZES } from "./config-BavYkV_M.mjs";
+import { n as DEFAULT_IMAGE_SIZES, t as DEFAULT_DEVICE_SIZES } from "./config-HOu7M27N.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";

package/dist/vite.d.mts

@@ -4,7 +4,7 @@
  * ```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()] };
+ * export default { plugins: [prachtImage(), pracht({ … })] };
  * ```
  *
  * ```tsx
@@ -19,7 +19,7 @@
  * 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 { t as PrachtImageMetadata } from "./metadata-Dap0USIM.mjs";
 import { Plugin } from "vite";
 
 //#region src/vite.d.ts
@@ -35,6 +35,16 @@ interface PrachtImageOptions {
   blurWidth?: number;
   /** WebP quality (1-100) of the blur placeholder. Defaults to 70. */
   blurQuality?: number;
+  /** Widths generated for `?pracht&pracht-static` imports. */
+  staticWidths?: readonly number[];
+  /** WebP quality for generated static variants. Defaults to 75. */
+  staticQuality?: number;
+  /**
+   * Client asset directory used when a static image is reachable only from
+   * the server graph. Relative paths resolve from Vite's root. Defaults to
+   * `dist/client`, matching `pracht build`.
+   */
+  staticOutDir?: string;
   /** Override how sharp is imported (useful for tests). */
   loadSharp?: () => Promise<unknown>;
 }
@@ -51,6 +61,8 @@ interface SharpPipeline {
   rotate(): SharpPipeline;
   resize(options: {
     width: number;
+    height?: number;
+    fit?: "inside";
     withoutEnlargement: boolean;
   }): SharpPipeline;
   webp(options: {
@@ -58,9 +70,14 @@ interface SharpPipeline {
   }): SharpPipeline;
   toBuffer(): Promise<Uint8Array>;
 }
-type SharpFactory = (input: Uint8Array) => SharpPipeline;
+type SharpFactory = ((input: Uint8Array) => SharpPipeline) & {
+  versions?: {
+    sharp?: string;
+  };
+};
 /** `/path/to/hero.jpg?pracht` → true; `?pracht` may combine with other params. */
 declare function isPrachtImageId(id: string): boolean;
+declare function isStaticPrachtImageId(id: string): boolean;
 /** Strip the entire query, leaving the file path. */
 declare function stripImageQuery(id: string): string;
 /**
@@ -82,7 +99,7 @@ declare function analyzeImage(sharp: SharpFactory, source: Uint8Array, options:
  * `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 createImageModuleCode(assetId: string, analyzed: Omit<PrachtImageMetadata, "src">, variants?: PrachtImageMetadata["variants"], staticQuery?: boolean): string;
 declare function prachtImage(options?: PrachtImageOptions): Plugin;
 //#endregion
-export { PrachtImageOptions, analyzeImage, createImageModuleCode, isPrachtImageId, prachtImage, stripImageQuery };
+export { PrachtImageOptions, analyzeImage, createImageModuleCode, isPrachtImageId, isStaticPrachtImageId, prachtImage, stripImageQuery };

package/dist/vite.mjs

@@ -1,9 +1,33 @@
-import { readFile, stat } from "node:fs/promises";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, stat, unlink, utimes, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, posix, 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 DEFAULT_STATIC_QUALITY = 75;
+const DEFAULT_STATIC_WIDTHS = [
+	320,
+	640,
+	960,
+	1280,
+	1920
+];
+const STATIC_IMAGE_QUERY = "pracht-static";
+const STATIC_CACHE_VERSION = "pracht-static-image-v2";
+/**
+* WebP stores each dimension in 14 bits, so no side of an encoded image may
+* exceed 16383px. Both the configured widths and the intrinsic-width variant
+* are capped to it: a panorama should ship one clamped variant, not fail the
+* build with a raw encoder error.
+*/
+const WEBP_MAX_DIMENSION = 16383;
+/**
+* Generated variants that have not been used for this long are dropped from
+* the disk cache. Entries are touched on every hit, so anything older belongs
+* to an image that has since been edited, renamed, or deleted.
+*/
+const STATIC_CACHE_MAX_AGE_MS = 720 * 60 * 60 * 1e3;
 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;
@@ -21,6 +45,11 @@ function isPrachtImageId(id) {
 	if (queryStart === -1) return false;
 	return id.slice(queryStart + 1).split("&").some((part) => part === PRACHT_IMAGE_QUERY);
 }
+function isStaticPrachtImageId(id) {
+	const queryStart = id.indexOf("?");
+	if (queryStart === -1) return false;
+	return id.slice(queryStart + 1).split("&").some((part) => part === STATIC_IMAGE_QUERY);
+}
 /** Strip the entire query, leaving the file path. */
 function stripImageQuery(id) {
 	const queryStart = id.indexOf("?");
@@ -46,6 +75,8 @@ async function analyzeImage(sharp, source, options) {
 	};
 	const blur = await sharp(source).rotate().resize({
 		width: options.blurWidth,
+		height: WEBP_MAX_DIMENSION,
+		fit: "inside",
 		withoutEnlargement: true
 	}).webp({ quality: options.blurQuality }).toBuffer();
 	return {
@@ -65,17 +96,30 @@ async function analyzeImage(sharp, source, options) {
 * `blurDataURL`. The metadata contract promises a real asset URL (hashed for
 * source files, stable for publicDir files). Exported for tests.
 */
-function createImageModuleCode(assetId, analyzed) {
+function createImageModuleCode(assetId, analyzed, variants = void 0, staticQuery = false) {
+	if (variants?.length) return [
+		`export const variants = ${JSON.stringify(variants)};`,
+		"export const src = variants[variants.length - 1].src;",
+		`export const width = ${JSON.stringify(analyzed.width)};`,
+		`export const height = ${JSON.stringify(analyzed.height)};`,
+		`export const blurDataURL = ${JSON.stringify(analyzed.blurDataURL)};`,
+		"export default { src, width, height, blurDataURL, variants };"
+	].join("\n");
 	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)};`,
+		...staticQuery ? ["export const variants = undefined;"] : [],
 		"export { src };",
-		"export default { src, width, height, blurDataURL };"
+		staticQuery ? "export default { src, width, height, blurDataURL, variants };" : "export default { src, width, height, blurDataURL };"
 	].join("\n");
 }
+/** Vite ids, watcher paths, and Windows drive paths must compare equal. */
+function toPosixPath(value) {
+	return value.replace(/\\/g, "/");
+}
 async function resolvePublicFile(publicDir, source) {
 	if (!publicDir || !source.startsWith("/")) return void 0;
 	const candidate = resolve(publicDir, `.${source}`);
@@ -83,13 +127,18 @@ async function resolvePublicFile(publicDir, source) {
 	if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) return;
 	return (await stat(candidate).catch(() => void 0))?.isFile() ? candidate : void 0;
 }
+function contentTypeForOriginal(format, extension) {
+	if (format === "svg" || extension === ".svg") return "image/svg+xml";
+	if (format) return `image/${format}`;
+	return `image/${extension.replace(/^\./, "") || "octet-stream"}`;
+}
 /**
 * 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()] };
+* export default { plugins: [prachtImage(), pracht({ … })] };
 * ```
 *
 * ```tsx
@@ -108,17 +157,139 @@ async function resolvePublicFile(publicDir, source) {
 function prachtImage(options = {}) {
 	const blurWidth = options.blurWidth ?? DEFAULT_BLUR_WIDTH;
 	const blurQuality = options.blurQuality ?? DEFAULT_BLUR_QUALITY;
+	const staticQuality = options.staticQuality ?? DEFAULT_STATIC_QUALITY;
+	const staticWidths = [...new Set(options.staticWidths ?? DEFAULT_STATIC_WIDTHS)].sort((left, right) => left - right);
 	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.");
+	if (!Number.isInteger(staticQuality) || staticQuality < 1 || staticQuality > 100) throw new Error("prachtImage({ staticQuality }) expects an integer between 1 and 100.");
+	if (staticWidths.length === 0 || staticWidths.some((width) => !Number.isInteger(width) || width < 1 || width > WEBP_MAX_DIMENSION)) throw new Error(`prachtImage({ staticWidths }) expects one or more integer widths between 1 and ${WEBP_MAX_DIMENSION}; WebP cannot encode a dimension above that.`);
 	const importSharp = createSharpImporter(options.loadSharp ?? (() => import("sharp")));
 	const cache = /* @__PURE__ */ new Map();
 	const resolvedImages = /* @__PURE__ */ new Map();
+	const staticAssets = /* @__PURE__ */ new Map();
 	let publicDir = "";
-	async function transform(filePath, assetId) {
+	let root = process.cwd();
+	let base = "/";
+	let assetsDir = "assets";
+	let cacheDir = "";
+	let staticOutDir = "";
+	let isSsrBuild = false;
+	function staticAssetUrl(fileName) {
+		if (base === "" || base === "./") return `${base}${fileName}`;
+		return `${base.endsWith("/") ? base : `${base}/`}${fileName}`;
+	}
+	function staticCacheDir() {
+		return join(cacheDir, "pracht-image");
+	}
+	/**
+	* Record a generated (or pass-through) asset by path. The same content hash
+	* can legitimately be produced by two sources, so ownership retains each
+	* source's backing path: an entry only disappears once every source that
+	* claimed it is gone.
+	*/
+	function registerStaticAsset(fileName, contentType, path, filePath) {
+		const existing = staticAssets.get(fileName);
+		if (existing) {
+			existing.sources.set(toPosixPath(filePath), path);
+			return;
+		}
+		staticAssets.set(fileName, {
+			contentType,
+			path,
+			sources: new Map([[toPosixPath(filePath), path]])
+		});
+	}
+	async function readStaticAsset(fileName, asset) {
+		try {
+			return await readFile(asset.path);
+		} catch (error) {
+			throw new Error(`[pracht/image] Could not read the bytes for static asset ${JSON.stringify(fileName)} from ${JSON.stringify(asset.path)} (generated from ${[...asset.sources.keys()].map((source) => JSON.stringify(source)).join(", ")}): ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	let cachePrune;
+	/**
+	* Age-based prune of the generated-variant cache, run once per plugin
+	* instance. Without it, every image edit leaves its previous encodes behind
+	* forever. Best effort by design: an unreadable or unwritable cache
+	* directory must never fail a build.
+	*/
+	function pruneStaticCache() {
+		cachePrune ??= (async () => {
+			const directory = staticCacheDir();
+			const entries = await readdir(directory).catch(() => []);
+			const cutoff = Date.now() - STATIC_CACHE_MAX_AGE_MS;
+			await Promise.all(entries.map(async (entry) => {
+				const entryPath = join(directory, entry);
+				const stats = await stat(entryPath).catch(() => void 0);
+				if (!stats?.isFile() || stats.mtimeMs >= cutoff) return;
+				await unlink(entryPath).catch(() => void 0);
+			}));
+		})().catch(() => void 0);
+		return cachePrune;
+	}
+	async function createStaticVariants(sharp, source, filePath, intrinsicWidth, intrinsicHeight) {
+		const metadata = await sharp(source).metadata();
+		if (metadata.format === "svg" || (metadata.pages ?? 1) > 1) {
+			const extension = extname(filePath).toLowerCase();
+			const stem = basename(filePath, extname(filePath)).replace(/[^a-zA-Z0-9_-]+/g, "-") || "image";
+			const hash = createHash("sha256").update(STATIC_CACHE_VERSION).update("original").update(source).digest("hex").slice(0, 12);
+			const fileName = posix.join(assetsDir, `${stem}.${hash}${extension}`);
+			const contentType = contentTypeForOriginal(metadata.format, extension);
+			registerStaticAsset(fileName, contentType, filePath, filePath);
+			return [{
+				src: staticAssetUrl(fileName),
+				width: intrinsicWidth,
+				type: contentType
+			}];
+		}
+		const maxWidth = Math.max(1, Math.min(intrinsicWidth, WEBP_MAX_DIMENSION, Math.floor(WEBP_MAX_DIMENSION * intrinsicWidth / intrinsicHeight)));
+		const widths = [...new Set([...staticWidths.filter((width) => width < maxWidth), maxWidth])];
+		const stem = basename(filePath, extname(filePath)).replace(/[^a-zA-Z0-9_-]+/g, "-") || "image";
+		const variants = [];
+		for (const width of widths) {
+			const hash = createHash("sha256").update(STATIC_CACHE_VERSION).update(source).update(JSON.stringify({
+				width,
+				quality: staticQuality,
+				format: "webp",
+				encoder: sharp.versions?.sharp ?? "unknown"
+			})).digest("hex").slice(0, 12);
+			const fileName = posix.join(assetsDir, `${stem}.${width}.${hash}.webp`);
+			const cachedPath = join(staticCacheDir(), `${hash}.webp`);
+			if ((await stat(cachedPath).catch(() => void 0))?.isFile()) {
+				const now = /* @__PURE__ */ new Date();
+				await utimes(cachedPath, now, now).catch(() => void 0);
+			} else {
+				const output = Buffer.from(await sharp(source).rotate().resize({
+					width,
+					height: WEBP_MAX_DIMENSION,
+					fit: "inside",
+					withoutEnlargement: true
+				}).webp({ quality: staticQuality }).toBuffer());
+				await mkdir(staticCacheDir(), { recursive: true });
+				const temporaryPath = `${cachedPath}.${process.pid}.${randomUUID()}.tmp`;
+				try {
+					await writeFile(temporaryPath, output);
+					await rename(temporaryPath, cachedPath);
+				} catch (error) {
+					if (!(await stat(cachedPath).catch(() => void 0))?.isFile()) throw error;
+				} finally {
+					await unlink(temporaryPath).catch(() => void 0);
+				}
+			}
+			registerStaticAsset(fileName, "image/webp", cachedPath, filePath);
+			variants.push({
+				src: staticAssetUrl(fileName),
+				width,
+				type: "image/webp"
+			});
+		}
+		return variants;
+	}
+	async function transform(filePath, assetId, staticImport, staticQuery) {
 		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 cacheKey = `${filePath}\0${assetId}\0${staticImport ? "static" : staticQuery ? "static-fallback" : "metadata"}`;
 		const cached = cache.get(cacheKey);
 		if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) return cached.code;
 		const code = (async () => {
@@ -132,7 +303,13 @@ function prachtImage(options = {}) {
 			} 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);
+			let variants;
+			if (staticImport) try {
+				variants = await createStaticVariants(sharp, source, filePath, analyzed.width, analyzed.height);
+			} catch (error) {
+				throw new Error(`[pracht/image] Failed to generate static variants for "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return createImageModuleCode(assetId, analyzed, variants, staticQuery);
 		})();
 		code.catch(() => cache.delete(cacheKey));
 		cache.set(cacheKey, {
@@ -146,18 +323,30 @@ function prachtImage(options = {}) {
 		name: "pracht:image-imports",
 		enforce: "pre",
 		configResolved(config) {
+			root = config.root;
 			publicDir = config.publicDir;
+			base = config.base;
+			assetsDir = config.build.assetsDir;
+			cacheDir = config.cacheDir;
+			staticOutDir = resolve(root, options.staticOutDir ?? "dist/client");
+			isSsrBuild = Boolean(config.build.ssr);
+		},
+		buildStart() {
+			return pruneStaticCache();
 		},
 		async resolveId(source, importer) {
 			if (!isPrachtImageId(source)) return null;
 			const sourcePath = stripImageQuery(source);
+			const staticImport = isStaticPrachtImageId(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}`;
+			const query = staticImport ? `${PRACHT_IMAGE_QUERY}&${STATIC_IMAGE_QUERY}` : PRACHT_IMAGE_QUERY;
+			const moduleId = `${resolved.id}${resolved.id.includes("?") ? "&" : "?"}${query}`;
 			resolvedImages.set(moduleId, {
 				filePath: publicFile ?? resolved.id,
-				assetId: publicFile ? sourcePath : resolved.id
+				assetId: publicFile ? sourcePath : resolved.id,
+				publicAsset: publicFile !== void 0
 			});
 			return moduleId;
 		},
@@ -168,12 +357,60 @@ function prachtImage(options = {}) {
 				assetId: stripImageQuery(id)
 			};
 			this.addWatchFile(resolved.filePath);
-			return transform(resolved.filePath, resolved.assetId);
+			const staticQuery = isStaticPrachtImageId(id);
+			const staticImport = staticQuery && !resolved.publicAsset;
+			if (staticImport && (base === "" || base === "./")) throw new Error("[pracht/image] \"?pracht&pracht-static\" imports require an absolute Vite base (for example \"/\" or \"/docs/\"); a relative base cannot produce route-safe image URLs.");
+			return transform(resolved.filePath, resolved.assetId, staticImport, staticQuery);
+		},
+		configureServer(server) {
+			server.middlewares.use((request, response, next) => {
+				const pathname = new URL(request.url ?? "/", "http://pracht.local").pathname;
+				const entry = [...staticAssets].find(([fileName]) => new URL(staticAssetUrl(fileName), "http://pracht.local").pathname === pathname);
+				if (!entry) return next();
+				const method = (request.method ?? "GET").toUpperCase();
+				if (method !== "GET" && method !== "HEAD") return next();
+				const respond = (source) => {
+					response.statusCode = 200;
+					response.setHeader("cache-control", "no-store");
+					response.setHeader("content-type", entry[1].contentType);
+					response.setHeader("x-content-type-options", "nosniff");
+					response.end(source);
+				};
+				if (method === "HEAD") return respond();
+				readStaticAsset(entry[0], entry[1]).then(respond, next);
+			});
+		},
+		async generateBundle() {
+			const consumer = this.environment?.config?.consumer;
+			if (consumer ? consumer === "server" : isSsrBuild) return;
+			for (const [fileName, asset] of staticAssets) this.emitFile({
+				type: "asset",
+				fileName,
+				source: await readStaticAsset(fileName, asset)
+			});
+		},
+		async writeBundle() {
+			const consumer = this.environment?.config?.consumer;
+			if (!(consumer ? consumer === "server" : isSsrBuild)) return;
+			for (const [fileName, asset] of staticAssets) {
+				const outputPath = resolve(staticOutDir, fileName);
+				const relativePath = relative(staticOutDir, outputPath);
+				if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) throw new Error(`[pracht/image] Refusing to write static variant outside ${JSON.stringify(staticOutDir)}: ${JSON.stringify(fileName)}.`);
+				await mkdir(dirname(outputPath), { recursive: true });
+				await writeFile(outputPath, await readStaticAsset(fileName, asset));
+			}
 		},
 		watchChange(filePath) {
+			const changed = toPosixPath(filePath);
+			for (const [fileName, asset] of staticAssets) {
+				if (!asset.sources.delete(changed)) continue;
+				const nextPath = asset.sources.values().next().value;
+				if (nextPath === void 0) staticAssets.delete(fileName);
+				else asset.path = nextPath;
+			}
 			if (this.environment.mode !== "dev") return;
 			for (const [moduleId, resolved] of resolvedImages) {
-				if (resolved.filePath.replace(/\\/g, "/") !== filePath.replace(/\\/g, "/")) continue;
+				if (toPosixPath(resolved.filePath) !== changed) continue;
 				const module = this.environment.moduleGraph.getModuleById(moduleId);
 				if (module) this.environment.moduleGraph.invalidateModule(module);
 			}
@@ -181,4 +418,4 @@ function prachtImage(options = {}) {
 	};
 }
 //#endregion
-export { analyzeImage, createImageModuleCode, isPrachtImageId, prachtImage, stripImageQuery };
+export { analyzeImage, createImageModuleCode, isPrachtImageId, isStaticPrachtImageId, prachtImage, stripImageQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/image",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Responsive, CLS-safe <Image> component for Pracht with pluggable optimization loaders and a Node image endpoint.",
   "keywords": [
     "pracht",