@lovrozagar/flare 0.1.0

package/src/plugins/dev-prerender.ts

@@ -0,0 +1,168 @@
+import { watch } from "node:fs";
+import { join } from "node:path";
+import type { RouteDefinition } from "../generators/index.ts";
+import { scanSourceFiles } from "../generators/index.ts";
+import type { PrerenderRoute } from "../prerender/index.ts";
+import { prerender } from "../prerender/index.ts";
+import type { ServerHandler } from "../server-handler/index.ts";
+import type { FlareStore } from "../store/index.ts";
+import { createFileSystemStore } from "../store/filesystem.ts";
+import type { FlarePluginConfig, VitePlugin } from "./index.ts";
+import type { ResolvedEntries } from "./types.ts";
+
+/**
+ * Convert virtual path to URL pathname.
+ * `_root_/about` → `/about`, `_root_/blog/[slug]` → `/blog/[slug]`
+ */
+function virtualPathToPathname(virtualPath: string): string {
+	const parts = virtualPath.split("/");
+	const rootIdx = parts.findIndex((p) => p.startsWith("_") && p.endsWith("_") && p.length >= 3);
+	const urlParts: string[] = [];
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i] ?? "";
+		if (rootIdx >= 0 && i <= rootIdx) continue;
+		if (part.startsWith("(") && part.endsWith(")")) continue;
+		if (part === "") continue;
+		urlParts.push(part);
+	}
+
+	return `/${urlParts.join("/")}`;
+}
+
+/**
+ * Filter route definitions to only static (SSG) non-dynamic routes
+ * suitable for dev-mode prerendering. Dynamic routes and ISR routes
+ * are excluded — dynamic requires params, ISR has its own serving path.
+ */
+export function filterDevPrerenderRoutes(defs: RouteDefinition[]): PrerenderRoute[] {
+	const routes: PrerenderRoute[] = [];
+
+	for (const def of defs) {
+		if (def.type !== "page") continue;
+		if (def.responseRoute) continue;
+		if (!def.cache.ssg) continue;
+
+		const pathname = virtualPathToPathname(def.virtualPath);
+
+		/* skip dynamic routes — they need params we don't have at dev time */
+		if (pathname.includes("[")) continue;
+
+		routes.push({ mode: "static", pathname });
+	}
+
+	return routes;
+}
+
+interface SsrEnvironment {
+	runner?: { import: (id: string) => Promise<Record<string, unknown>> };
+}
+
+interface DevPrerenderServer {
+	config?: { root?: string };
+	environments?: Record<string, SsrEnvironment>;
+	httpServer?: { on?: (event: string, fn: () => void) => void } | null;
+}
+
+/**
+ * Vite plugin that pre-renders SSG routes on dev server start,
+ * writes entries to FileSystemStore, and invalidates on HMR.
+ */
+export function createDevPrerenderPlugin(config: FlarePluginConfig, entries: ResolvedEntries): VitePlugin {
+	const ignorePrefix = config.ignorePrefix ?? "_";
+	let store: FlareStore;
+	let root: string;
+	let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+
+	function getRoutes(): PrerenderRoute[] {
+		const defs = scanSourceFiles({ ignorePrefix, rootDir: root });
+		return filterDevPrerenderRoutes(defs);
+	}
+
+	async function prerenderRoutes(routes: PrerenderRoute[], ssrRunner: SsrEnvironment["runner"]): Promise<void> {
+		if (routes.length === 0 || !ssrRunner) return;
+
+		try {
+			const mod = await ssrRunner.import(`./${entries.server}`);
+			const defaultExport = mod["default"] as Record<string, unknown> | undefined;
+			const handler = (mod["handler"] ?? defaultExport?.["handler"]) as ServerHandler | undefined;
+			if (!handler) return;
+
+			const result = await prerender({
+				handler,
+				origin: "http://localhost",
+				routes,
+			});
+
+			/* Write entries to store */
+			for (const entry of result.entries) {
+				await store.set(`static:${entry.pathname}`, {
+					data: {
+						headers: entry.headers,
+						html: entry.html,
+						ndjson: entry.ndjson,
+					},
+					storedAt: Date.now(),
+				});
+			}
+
+			if (result.entries.length > 0) {
+				process.stderr.write(`[flare:dev-prerender] Pre-rendered ${result.entries.length} SSG route(s)\n`);
+			}
+
+			for (const err of result.errors) {
+				process.stderr.write(`[flare:dev-prerender] Error ${err.pathname}: ${err.message}\n`);
+			}
+		} catch (e: unknown) {
+			const msg = e instanceof Error ? e.message : String(e);
+			process.stderr.write(`[flare:dev-prerender] Failed: ${msg}\n`);
+		}
+	}
+
+	return {
+		configureServer(server: unknown) {
+			const vite = server as DevPrerenderServer;
+			root = vite.config?.root ?? process.cwd();
+			store = createFileSystemStore({ cacheDir: join(root, ".flare/cache") });
+
+			const ssrEnv = vite.environments?.ssr;
+			if (!ssrEnv?.runner) return undefined;
+
+			/* Pre-render on server start */
+			vite.httpServer?.on?.("listening", () => {
+				const routes = getRoutes();
+				prerenderRoutes(routes, ssrEnv.runner).catch(() => {
+					/* swallow — logged internally */
+				});
+			});
+
+			/* HMR invalidation — watch route files for changes */
+			const srcRoutes = join(root, "src/routes");
+			const routeWatcher = watch(srcRoutes, { recursive: true }, (_event, filename) => {
+				if (!filename) return;
+				const name = String(filename);
+				if (!name.endsWith(".tsx") && !name.endsWith(".ts")) return;
+
+				clearTimeout(debounceTimer);
+				debounceTimer = setTimeout(() => {
+					const routes = getRoutes();
+
+					/* Delete stale entries then re-prerender */
+					const deleteKeys = routes.map((r) => `static:${r.pathname}`);
+					if (store.deleteByKeys && deleteKeys.length > 0) {
+						store.deleteByKeys(deleteKeys).catch(() => {});
+					}
+					prerenderRoutes(routes, ssrEnv.runner).catch(() => {});
+				}, 200);
+			});
+
+			vite.httpServer?.on?.("close", () => {
+				clearTimeout(debounceTimer);
+				routeWatcher.close();
+			});
+
+			return undefined;
+		},
+		name: "flare:dev-prerender",
+	};
+}

package/src/plugins/dev-server.ts

@@ -0,0 +1,327 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ResolvedEntries, VitePlugin } from "./types.ts";
+
+interface NodeReq {
+	headers: Record<string, string | string[] | undefined>;
+	method?: string;
+	on: (event: string, fn: (chunk?: unknown) => void) => void;
+	socket?: { encrypted?: boolean };
+	url?: string;
+}
+
+interface NodeRes {
+	end: (data?: unknown) => void;
+	on: (event: string, fn: () => void) => void;
+	writableEnded?: boolean;
+	write: (chunk: unknown) => void;
+	writeHead: (status: number, headers: Record<string, string | string[]>) => void;
+}
+
+interface SsrEnvironment {
+	runner?: { import: (id: string) => Promise<Record<string, unknown>> };
+}
+
+interface ViteDevServer {
+	config?: { root?: string; server?: { middlewareMode?: boolean } };
+	environments?: Record<string, SsrEnvironment>;
+	middlewares: {
+		use: (fn: (req: NodeReq, res: NodeRes, next: (err?: unknown) => void) => void) => void;
+	};
+	ssrFixStacktrace: (e: Error) => void;
+	transformIndexHtml: (url: string, html: string) => Promise<string>;
+}
+
+function nodeToWebRequest(req: NodeReq, url: URL): Request {
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(req.headers)) {
+		/* skip HTTP/2 pseudo-headers (e.g. :method, :path, :scheme) */
+		if (key.startsWith(":")) continue;
+		if (value) {
+			const values = Array.isArray(value) ? value : [value];
+			for (const v of values) {
+				headers.append(key, v);
+			}
+		}
+	}
+
+	const hasBody = req.method !== "GET" && req.method !== "HEAD";
+	const body = hasBody
+		? new ReadableStream({
+				start(controller) {
+					req.on("data", (chunk: unknown) => {
+						controller.enqueue(chunk);
+					});
+					req.on("end", () => {
+						controller.close();
+					});
+					req.on("error", (err: unknown) => {
+						controller.error(err);
+					});
+				},
+			})
+		: undefined;
+
+	return new Request(url.href, {
+		body: body ?? null,
+		duplex: hasBody ? "half" : undefined,
+		headers,
+		method: req.method ?? "GET",
+	} as RequestInit);
+}
+
+async function streamResponse(response: Response, res: NodeRes): Promise<void> {
+	const responseHeaders: Record<string, string | string[]> = {};
+	/* Set-Cookie must be sent as separate headers — Node.js writeHead
+	 * accepts string[] for multi-value headers like Set-Cookie */
+	const setCookies =
+		"getSetCookie" in response.headers
+			? (response.headers as Headers & { getSetCookie(): string[] }).getSetCookie()
+			: [];
+	response.headers.forEach((value, key) => {
+		if (key === "set-cookie") return;
+		responseHeaders[key] = value;
+	});
+	if (setCookies.length > 0) {
+		responseHeaders["set-cookie"] = setCookies;
+	}
+	res.writeHead(response.status, responseHeaders);
+
+	if (response.body) {
+		const reader = response.body.getReader();
+		const pump = async (): Promise<void> => {
+			const { done, value } = await reader.read();
+			if (done) {
+				res.end();
+				return;
+			}
+			res.write(value);
+			return pump();
+		};
+		try {
+			await pump();
+		} finally {
+			reader.cancel().catch(() => {});
+			if (!res.writableEnded) res.end();
+		}
+	} else {
+		res.end();
+	}
+}
+
+const INLINE_PLACEHOLDER = (i: number) => `<!--flare-inline-${i}-->`;
+const INLINE_PLACEHOLDER_RE = /<!--flare-inline-(\d+)-->/g;
+
+/**
+ * Vite's transformIndexHtml virtualises every inline <script>/<style> as
+ * `?html-proxy` modules. Theme IIFEs must stay blocking, and the body
+ * `import(entry)` must stay a real inline module — a NUL-prefixed virtual
+ * id 500s and hydrate never starts. Peel, transform, restore in place.
+ */
+export function peelInlineTags(html: string): { html: string; tags: string[] } {
+	const tags: string[] = [];
+	const next = html.replace(/<(script|style)(\s[^>]*)?>([\s\S]*?)<\/\1>/gi, (full, tag: string, attrs = "") => {
+		if (tag.toLowerCase() === "script" && /\ssrc\s*=/i.test(attrs)) return full;
+		const i = tags.length;
+		tags.push(full);
+		return INLINE_PLACEHOLDER(i);
+	});
+	return { html: next, tags };
+}
+
+export function restoreInlineTags(html: string, tags: string[]): string {
+	if (tags.length === 0) return html;
+	return html.replace(INLINE_PLACEHOLDER_RE, (_, n) => tags[Number(n)] ?? "");
+}
+
+export function createDevServerPlugin(entries: ResolvedEntries, _assetsBase: string = "/assets"): VitePlugin {
+	return {
+		configureServer(server: unknown) {
+			const vite = server as ViteDevServer;
+
+			/* post-phase callback — runs AFTER Vite's built-in middleware */
+			return () => {
+				const ssrEnv = vite.environments?.ssr;
+
+				/* Auto-skip: middlewareMode means external HTTP server owns routing */
+				if (vite.config?.server?.middlewareMode) return;
+
+				/* Auto-skip: no SSR environment available */
+				if (!ssrEnv) return;
+
+				/*
+				 * Auto-skip: platform plugin (CF, Nitro) provides its own SSR handler.
+				 * Duck-type check — do not use isFetchableDevEnvironment() since Nitro
+				 * implements the interface duck-style, not via class inheritance.
+				 */
+				if ("dispatchFetch" in ssrEnv) return;
+
+				/* Auto-skip: @cloudflare/vite-plugin owns request dispatch via its own middleware
+				   (which delegates to miniflare with full env binding). It does not advertise
+				   `dispatchFetch` on the ssrEnv, so the duck-type check above misses it. Detect
+				   the plugin by name and yield to it. Without this, Flare's dev-server intercepts
+				   first (lower middleware priority depending on plugin order) and calls
+				   `handler.fetch(request)` without `env`, breaking service bindings. */
+				const plugins = (vite.config as { plugins?: { name?: string }[] }).plugins;
+				const cfPluginPresent =
+					Array.isArray(plugins) &&
+					plugins.some((p) => typeof p?.name === "string" && p.name.startsWith("vite-plugin-cloudflare"));
+				if (cfPluginPresent) return;
+
+				vite.middlewares.use(async (req, res, next) => {
+					if (!req.url) return next();
+
+					try {
+						const mod = ssrEnv.runner ? await ssrEnv.runner.import(`./${entries.server}`) : undefined;
+
+						if (!mod) return next();
+
+						const handler = (mod.server ?? mod.handler ?? mod.default) as {
+							fetch: (request: Request) => Promise<Response>;
+						};
+
+						/* HTTP/2 uses :authority instead of host header */
+						const url = new URL(
+							req.url,
+							`${req.socket?.encrypted ? "https" : "http"}://${req.headers.host ?? req.headers[":authority"] ?? "localhost"}`,
+						);
+						const webReq = nodeToWebRequest(req, url);
+						const response = await handler.fetch(webReq);
+
+						const contentType = response.headers.get("content-type") ?? "";
+						if (contentType.includes("text/html")) {
+							let html = await response.text();
+							/*
+							 * Sanitize pathname for transformIndexHtml: Vite creates virtual
+							 * module IDs for inline <script> tags based on the URL pathname.
+							 * If the path has a file extension (e.g. /foo.json), Vite's
+							 * built-in plugins (vite:json, vite:css) match the extension
+							 * and try to parse the JS as JSON/CSS, causing a 500.
+							 */
+							const lastSlash = url.pathname.lastIndexOf("/");
+							const hasFileExt = url.pathname.indexOf(".", lastSlash) !== -1;
+							const { html: peeledHtml, tags } = peelInlineTags(html);
+							html = restoreInlineTags(
+								await vite.transformIndexHtml(hasFileExt ? "/" : url.pathname, peeledHtml),
+								tags,
+							);
+
+							const htmlHeaders: Record<string, string | string[]> = {
+								"content-type": "text/html; charset=utf-8",
+							};
+							const htmlSetCookies =
+								"getSetCookie" in response.headers
+									? (response.headers as Headers & { getSetCookie(): string[] }).getSetCookie()
+									: [];
+							response.headers.forEach((value, key) => {
+								if (key === "content-type" || key === "content-length" || key === "set-cookie") return;
+								htmlHeaders[key] = value;
+							});
+							if (htmlSetCookies.length > 0) {
+								htmlHeaders["set-cookie"] = htmlSetCookies;
+							}
+							res.writeHead(response.status, htmlHeaders);
+							res.end(html);
+							return;
+						}
+
+						await streamResponse(response, res);
+					} catch (e: unknown) {
+						if (e instanceof Error) {
+							vite.ssrFixStacktrace(e);
+						}
+						next(e);
+					}
+				});
+			};
+		},
+		name: "flare:dev-server",
+	};
+}
+
+/* ── Preview Server ──────────────────────────────────────────────────── */
+
+interface PreviewServer {
+	config?: { root?: string };
+	middlewares: {
+		use: (fn: (req: NodeReq, res: NodeRes, next: (err?: unknown) => void) => void) => void;
+	};
+}
+
+export function createPreviewServerPlugin(assetsBase: string = "/assets"): VitePlugin {
+	return {
+		configurePreviewServer(server: unknown) {
+			const preview = server as PreviewServer;
+			const root = preview.config?.root ?? process.cwd();
+			const serverPath = join(root, "dist/server/server.js");
+			const clientDir = join(root, "dist/client");
+
+			let handlerPromise: Promise<{ fetch: (request: Request) => Promise<Response> }> | undefined;
+
+			function getHandler() {
+				if (!handlerPromise) {
+					handlerPromise = import(`${serverPath}?t=${Date.now()}`).then(
+						(mod) =>
+							(mod.server ?? mod.handler) as {
+								fetch: (request: Request) => Promise<Response>;
+							},
+					);
+					/* Clear on failure so next request retries instead of caching the rejection */
+					handlerPromise.catch((e: unknown) => {
+						const msg = e instanceof Error ? e.message : String(e);
+						process.stderr.write(`[flare:preview] handler import failed, will retry: ${msg}\n`);
+						handlerPromise = undefined;
+					});
+				}
+				return handlerPromise;
+			}
+
+			return () => {
+				preview.middlewares.use(async (req, res, next) => {
+					if (!req.url) return next();
+
+					/* Serve static client assets */
+					const urlPath = req.url.split("?")[0];
+					if (urlPath?.startsWith(`${assetsBase}/`)) {
+						const filePath = resolve(join(clientDir, urlPath));
+						const clientDirSlash = clientDir.endsWith("/") ? clientDir : `${clientDir}/`;
+						if (!filePath.startsWith(clientDirSlash)) return next();
+						try {
+							const content = readFileSync(filePath);
+							const ext = filePath.split(".").pop() ?? "";
+							const mimeTypes: Record<string, string> = {
+								css: "text/css",
+								js: "application/javascript",
+								json: "application/json",
+								svg: "image/svg+xml",
+							};
+							res.writeHead(200, {
+								"cache-control": "public, max-age=31536000, immutable",
+								"content-type": mimeTypes[ext] ?? "application/octet-stream",
+							});
+							res.end(content);
+							return;
+						} catch {
+							/* fall through to SSR */
+						}
+					}
+
+					try {
+						const handler = await getHandler();
+						/* HTTP/2 uses :authority instead of host header */
+						const url = new URL(
+							req.url,
+							`${req.socket?.encrypted ? "https" : "http"}://${req.headers.host ?? req.headers[":authority"] ?? "localhost"}`,
+						);
+						const webReq = nodeToWebRequest(req, url);
+						const response = await handler.fetch(webReq);
+						await streamResponse(response, res);
+					} catch (e: unknown) {
+						next(e);
+					}
+				});
+			};
+		},
+		name: "flare:preview-server",
+	};
+}

package/src/plugins/generate-watch.ts

@@ -0,0 +1,32 @@
+import { runGenerate, type RunGenerateOptions } from "../generators/index.ts";
+
+const GEN_IGNORE_RE = /(_gen[/\\]|\.gen\.tsx?$)/;
+
+export const FS_CODEGEN_SUFFIX_RE = /\.(page|layout|root-layout|path-segment)\.(tsx?|jsx?)$/;
+
+/**
+ * Whether a filesystem watch event should re-run codegen.
+ * `fsVirtualPaths: true` only reacts to suffix route files, or add/delete (`rename`).
+ * `false` reacts to any non-generated source change.
+ */
+export function shouldTriggerGenerate(
+	filename: string | null | undefined,
+	event: string,
+	fsVirtualPaths: boolean,
+): boolean {
+	if (!filename) return false;
+	const name = String(filename);
+	if (GEN_IGNORE_RE.test(name)) return false;
+	if (fsVirtualPaths && event !== "rename" && !FS_CODEGEN_SUFFIX_RE.test(name)) return false;
+	return true;
+}
+
+/** Watch-path generate: log layout errors instead of taking down the dev server. */
+export function safeRunGenerate(options: RunGenerateOptions): void {
+	try {
+		runGenerate(options);
+	} catch (e: unknown) {
+		const msg = e instanceof Error ? e.message : String(e);
+		console.error(`[flare:generate] ${msg}`);
+	}
+}

package/src/plugins/image-plugin.ts

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { basename, dirname, extname, resolve } from "node:path";
+import type { VitePlugin } from "./types.ts";
+
+const IMAGE_EXTS = new Set([".avif", ".gif", ".jpeg", ".jpg", ".png", ".tiff", ".webp"]);
+const ANIMATED_EXTS = new Set([".gif"]);
+const IMAGE_DEFAULT_WIDTHS = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const IMAGE_DEFAULT_QUALITY = 75;
+
+interface SharpInstance {
+	metadata: () => Promise<{ height?: number; width?: number }>;
+	resize: (width: number) => SharpInstance;
+	toBuffer: () => Promise<Buffer>;
+	webp: (opts?: { quality?: number }) => SharpInstance;
+}
+
+type SharpFactory = (input: string) => SharpInstance;
+
+async function importSharp(): Promise<SharpFactory> {
+	try {
+		const mod = await import("sharp");
+		return (mod.default ?? mod) as unknown as SharpFactory;
+	} catch {
+		throw new Error("sharp is required for image optimization. Install it: bun add sharp -D");
+	}
+}
+
+interface ImagePluginContext {
+	emitFile?: (file: { fileName: string; source: Buffer; type: "asset" }) => void;
+	environment?: { config?: { mode?: string } };
+}
+
+interface NodeReq {
+	url?: string;
+}
+
+interface NodeRes {
+	end: (data?: unknown) => void;
+	writeHead: (status: number, headers: Record<string, string | string[]>) => void;
+}
+
+export function createImagePlugin(
+	config?: { image?: { exclude?: RegExp; quality?: number; widths?: number[] } },
+	assetsBase: string = "/assets",
+	assetsDir: string = "assets",
+): VitePlugin {
+	const quality = config?.image?.quality ?? IMAGE_DEFAULT_QUALITY;
+	const configWidths = config?.image?.widths ?? IMAGE_DEFAULT_WIDTHS;
+	const excludeRe = config?.image?.exclude;
+
+	return {
+		configureServer(server: unknown) {
+			const srv = server as {
+				middlewares?: {
+					use: (fn: (req: NodeReq, res: NodeRes, next: (err?: unknown) => void) => void) => void;
+				};
+			};
+
+			srv.middlewares?.use(async (req, res, next) => {
+				if (!req.url?.startsWith("/_flare/image?")) return next();
+
+				try {
+					const url = new URL(req.url, "http://localhost");
+					const src = url.searchParams.get("src");
+					const w = Number(url.searchParams.get("w"));
+					if (!src || !w) return next();
+
+					/* Guard against path traversal — resolve symlinks then check within cwd */
+					const resolvedSrc = resolve(src);
+					if (!resolvedSrc.startsWith(process.cwd())) return next();
+					let realSrc: string;
+					try {
+						realSrc = realpathSync(resolvedSrc);
+					} catch {
+						return next();
+					}
+					if (!realSrc.startsWith(process.cwd())) return next();
+
+					const sharp = await importSharp();
+					const sourceExt = extname(realSrc).toLowerCase();
+					const isWebPSource = sourceExt === ".webp";
+					const buf = isWebPSource
+						? await sharp(realSrc).resize(w).toBuffer()
+						: await sharp(realSrc).resize(w).webp({ quality }).toBuffer();
+
+					res.writeHead(200, {
+						"cache-control": "public, max-age=31536000, immutable",
+						"content-type": "image/webp",
+					});
+					res.end(buf);
+				} catch (e: unknown) {
+					next(e);
+				}
+			});
+			return undefined;
+		},
+		enforce: "pre",
+
+		async load(this: ImagePluginContext, id: string): Promise<{ code: string; moduleType: string } | null> {
+			if (!id.startsWith("\0flare-image:")) return null;
+			const imagePath = id.slice("\0flare-image:".length);
+
+			const sharp = await importSharp();
+			const img = sharp(imagePath);
+			const metadata = await img.metadata();
+			const width = metadata.width ?? 0;
+			const height = metadata.height ?? 0;
+
+			/* Blur placeholder: 8px wide WebP → base64 data URI */
+			const blurBuf = await sharp(imagePath).resize(8).webp({ quality: 20 }).toBuffer();
+			const blurDataURL = `data:image/webp;base64,${blurBuf.toString("base64")}`;
+
+			const isBuild = this.environment?.config?.mode !== "development";
+			const stem = basename(imagePath, extname(imagePath));
+
+			/* Compute variant widths — only ≤ original, always include original */
+			const widths = configWidths.filter((w) => w <= width);
+			if (!widths.includes(width)) widths.push(width);
+			widths.sort((a, b) => a - b);
+
+			if (isBuild) {
+				const variants: Record<number, string> = {};
+				for (const w of widths) {
+					const buf = await sharp(imagePath).resize(w).webp({ quality }).toBuffer();
+					const hash = createHash("sha256").update(buf).digest("hex").slice(0, 8);
+					const filename = `${stem}-${w}-${hash}.webp`;
+					const emitPath = assetsDir ? `${assetsDir}/${filename}` : filename;
+					this.emitFile?.({ fileName: emitPath, source: buf, type: "asset" });
+					variants[w] = `${assetsBase}/${filename}`;
+				}
+
+				const data = { blurDataURL, height, src: variants[width] ?? "", variants, width };
+				return { code: `export default ${JSON.stringify(data)}`, moduleType: "js" };
+			}
+
+			/* Dev mode: variants served on-demand via middleware */
+			const variants: Record<number, string> = {};
+			for (const w of widths) {
+				variants[w] = `/_flare/image?src=${encodeURIComponent(imagePath)}&w=${w}`;
+			}
+
+			const data = { blurDataURL, height, src: imagePath, variants, width };
+			return { code: `export default ${JSON.stringify(data)}`, moduleType: "js" };
+		},
+		name: "flare:image",
+
+		resolveId(id: string, importer?: unknown): string | null {
+			/* Explicit Vite passthrough */
+			if (id.includes("?url") || id.includes("?raw")) return null;
+
+			const ext = extname(id).toLowerCase();
+
+			/* SVG and animated formats: always pass through */
+			if (ext === ".svg" || ANIMATED_EXTS.has(ext)) return null;
+
+			if (!IMAGE_EXTS.has(ext)) return null;
+
+			/* Resolve relative paths using the importer directory */
+			let absolutePath = id;
+			if (id.startsWith(".") && typeof importer === "string") {
+				absolutePath = resolve(dirname(importer), id);
+			}
+
+			/* Check exclude regex against resolved path */
+			if (excludeRe?.test(absolutePath)) return null;
+
+			return `\0flare-image:${absolutePath}`;
+		},
+	};
+}