@pyreon/zero 0.20.0 → 0.21.0

package/README.md

@@ -18,7 +18,7 @@ bun add @pyreon/zero
 - **Components** — `<Image>` (lazy load, srcset, blur-up), `<Link>` (prefetch, active state), `<Script>` (loading strategies)
 - **Theme** — Dark/light/system with `theme` signal, `<ThemeToggle>`, and anti-flash inline script
 - **Fonts** — Google Fonts self-hosting at build time, local fonts, size-adjusted fallbacks
-- **Image optimization** — Build-time processing via `?optimize` imports (WebP/AVIF, blur placeholders)
+- **Image optimization** — Build-time processing via `?optimize` imports (WebP/AVIF, blur placeholders). Type the custom queries with one line — `/// <reference types="@pyreon/zero/image-types" />` — which ships ambient `declare module "*?optimize"` / `"*?component"` / `"*?raw"` reusing the plugin's own `ProcessedImage`.
 - **SEO** — Sitemap, robots.txt, JSON-LD helpers (Vite plugin + dev middleware)
 - **Middleware** — `cacheMiddleware()`, `securityHeaders()`, `corsMiddleware()`, `rateLimitMiddleware()`, `compressionMiddleware()`
 - **Adapters** — Node.js, Bun, static, Vercel, Cloudflare Pages, Netlify Functions

package/lib/favicon.js

@@ -121,6 +121,20 @@ function faviconPlugin(config) {
 				const svgUrl = localeSource ? localeSource.url : url;
 				const svgPath = localeSource ? localeSource.sourcePath : sourcePath;
 				const isSvgSource = localeSource ? localeSource.source.endsWith(".svg") : config.source.endsWith(".svg");
+				if (isSvgSource && (svgUrl.endsWith("/favicon-light.svg") || svgUrl.endsWith("/favicon-dark.svg"))) {
+					const isDarkVariant = svgUrl.endsWith("/favicon-dark.svg");
+					const variantPath = isDarkVariant ? darkPath ?? svgPath : svgPath;
+					try {
+						let content = await readFile(variantPath, "utf-8");
+						if (!isDarkVariant) {
+							if (autoDevBadge) content = addDevBadgeToSvg(content);
+							else if (devSourcePath && existsSync(devSourcePath)) content = await readFile(devSourcePath, "utf-8");
+						}
+						res.setHeader("Content-Type", "image/svg+xml");
+						res.end(content);
+						return;
+					} catch {}
+				}
 				if (svgUrl.endsWith("/favicon.svg") && isSvgSource) try {
 					let content = await readFile(svgPath, "utf-8");
 					if (autoDevBadge) content = addDevBadgeToSvg(content);
@@ -197,7 +211,27 @@ function faviconPlugin(config) {
 			const isSvg = config.source.endsWith(".svg");
 			const hasDark = !!config.darkSource;
 			const tags = [];
-			if (isSvg) tags.push({
+			if (isSvg && hasDark) tags.push({
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon-light.svg",
+					"data-favicon-theme": "light"
+				},
+				injectTo: "head"
+			}, {
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon-dark.svg",
+					"data-favicon-theme": "dark",
+					media: "not all"
+				},
+				injectTo: "head"
+			});
+			else if (isSvg) tags.push({
 				tag: "link",
 				attrs: {
 					rel: "icon",
@@ -389,7 +423,20 @@ async function generateFaviconSet(rootDir, source, darkSource, prefix, config, t
 		let finalSvg = svgContent;
 		if (darkSource) {
 			const darkPath = join(rootDir, darkSource);
-			if (existsSync(darkPath)) finalSvg = wrapSvgWithDarkMode(svgContent, await readFile(darkPath, "utf-8"));
+			if (existsSync(darkPath)) {
+				const darkSvg = await readFile(darkPath, "utf-8");
+				finalSvg = wrapSvgWithDarkMode(svgContent, darkSvg);
+				this.emitFile({
+					type: "asset",
+					fileName: `${prefix}favicon-light.svg`,
+					source: svgContent
+				});
+				this.emitFile({
+					type: "asset",
+					fileName: `${prefix}favicon-dark.svg`,
+					source: darkSvg
+				});
+			}
 		}
 		this.emitFile({
 			type: "asset",
@@ -479,8 +526,21 @@ function faviconLinks(locale, config) {
 	const hasLocaleOverride = locale && config.locales?.[locale];
 	const prefix = hasLocaleOverride ? `/${locale}` : "";
 	const isSvg = (hasLocaleOverride ? config.locales[locale].source : config.source).endsWith(".svg");
+	const hasDark = !!config.darkSource;
 	const links = [];
-	if (isSvg) links.push({
+	if (isSvg && hasDark) links.push({
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon-light.svg`,
+		"data-favicon-theme": "light"
+	}, {
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon-dark.svg`,
+		"data-favicon-theme": "dark",
+		media: "not all"
+	});
+	else if (isSvg) links.push({
 		rel: "icon",
 		type: "image/svg+xml",
 		href: `${prefix}/favicon.svg`

package/lib/image-plugin.js

@@ -170,7 +170,7 @@ export default function SvgComponent(props) {
 }
 async function loadDevImage(absPath, rawPath, strategy, placeholderSize) {
 	const metadata = await getImageMetadata(absPath);
-	const publicPath = rawPath.startsWith("/") ? rawPath : `/@fs/${absPath}`;
+	const publicPath = rawPath.startsWith("/") && !existsSync(rawPath) ? rawPath : `/@fs/${absPath}`;
 	return {
 		src: publicPath,
 		srcset: "",

package/lib/server.js

@@ -2866,6 +2866,20 @@ function faviconPlugin(config) {
 				const svgUrl = localeSource ? localeSource.url : url;
 				const svgPath = localeSource ? localeSource.sourcePath : sourcePath;
 				const isSvgSource = localeSource ? localeSource.source.endsWith(".svg") : config.source.endsWith(".svg");
+				if (isSvgSource && (svgUrl.endsWith("/favicon-light.svg") || svgUrl.endsWith("/favicon-dark.svg"))) {
+					const isDarkVariant = svgUrl.endsWith("/favicon-dark.svg");
+					const variantPath = isDarkVariant ? darkPath ?? svgPath : svgPath;
+					try {
+						let content = await readFile(variantPath, "utf-8");
+						if (!isDarkVariant) {
+							if (autoDevBadge) content = addDevBadgeToSvg(content);
+							else if (devSourcePath && existsSync(devSourcePath)) content = await readFile(devSourcePath, "utf-8");
+						}
+						res.setHeader("Content-Type", "image/svg+xml");
+						res.end(content);
+						return;
+					} catch {}
+				}
 				if (svgUrl.endsWith("/favicon.svg") && isSvgSource) try {
 					let content = await readFile(svgPath, "utf-8");
 					if (autoDevBadge) content = addDevBadgeToSvg(content);
@@ -2942,7 +2956,27 @@ function faviconPlugin(config) {
 			const isSvg = config.source.endsWith(".svg");
 			const hasDark = !!config.darkSource;
 			const tags = [];
-			if (isSvg) tags.push({
+			if (isSvg && hasDark) tags.push({
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon-light.svg",
+					"data-favicon-theme": "light"
+				},
+				injectTo: "head"
+			}, {
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon-dark.svg",
+					"data-favicon-theme": "dark",
+					media: "not all"
+				},
+				injectTo: "head"
+			});
+			else if (isSvg) tags.push({
 				tag: "link",
 				attrs: {
 					rel: "icon",
@@ -3134,7 +3168,20 @@ async function generateFaviconSet(rootDir, source, darkSource, prefix, config, t
 		let finalSvg = svgContent;
 		if (darkSource) {
 			const darkPath = join(rootDir, darkSource);
-			if (existsSync(darkPath)) finalSvg = wrapSvgWithDarkMode(svgContent, await readFile(darkPath, "utf-8"));
+			if (existsSync(darkPath)) {
+				const darkSvg = await readFile(darkPath, "utf-8");
+				finalSvg = wrapSvgWithDarkMode(svgContent, darkSvg);
+				this.emitFile({
+					type: "asset",
+					fileName: `${prefix}favicon-light.svg`,
+					source: svgContent
+				});
+				this.emitFile({
+					type: "asset",
+					fileName: `${prefix}favicon-dark.svg`,
+					source: darkSvg
+				});
+			}
 		}
 		this.emitFile({
 			type: "asset",
@@ -3224,8 +3271,21 @@ function faviconLinks(locale, config) {
 	const hasLocaleOverride = locale && config.locales?.[locale];
 	const prefix = hasLocaleOverride ? `/${locale}` : "";
 	const isSvg = (hasLocaleOverride ? config.locales[locale].source : config.source).endsWith(".svg");
+	const hasDark = !!config.darkSource;
 	const links = [];
-	if (isSvg) links.push({
+	if (isSvg && hasDark) links.push({
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon-light.svg`,
+		"data-favicon-theme": "light"
+	}, {
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon-dark.svg`,
+		"data-favicon-theme": "dark",
+		media: "not all"
+	});
+	else if (isSvg) links.push({
 		rel: "icon",
 		type: "image/svg+xml",
 		href: `${prefix}/favicon.svg`

package/lib/types/favicon.d.ts

@@ -35,9 +35,21 @@ interface FaviconPluginConfig {
   /** Generate web manifest. Default: true */
   manifest?: boolean;
   /**
-   * Dark mode favicon (SVG only).
-   * When provided, the SVG favicon uses prefers-color-scheme media query
-   * to switch between light and dark variants.
+   * Dark-mode favicon source.
+   *
+   * When provided, the plugin emits theme-aware `light`/`dark` variants
+   * (`favicon-light.svg` / `favicon-dark.svg` for SVG sources, plus the
+   * `*-light-*` / `*-dark-*` PNG/apple-touch set) tagged with
+   * `data-favicon-theme`. The injected blocking theme-swap script and
+   * `initTheme()` toggle their `media` attribute so the displayed
+   * favicon follows the app's resolved theme — including a manual
+   * in-app theme toggle, not just the OS `prefers-color-scheme`.
+   *
+   * For SVG sources a `favicon.svg` is also emitted that wraps both
+   * variants behind an OS `prefers-color-scheme` query — kept as the
+   * no-JS / direct-`/favicon.svg`-reference fallback only (it cannot
+   * follow a manual toggle, which is why the `data-favicon-theme`
+   * variants above are what the reactive mechanism actually uses).
    */
   darkSource?: string;
   /**
@@ -110,6 +122,8 @@ declare function faviconLinks(locale: string | undefined, config: FaviconPluginC
   type?: string;
   sizes?: string;
   href: string;
+  'data-favicon-theme'?: string;
+  media?: string;
 }>;
 interface IcoEntry {
   buffer: Buffer;

package/lib/types/image-types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Ambient type declarations for the custom image-import queries that
+ * `@pyreon/zero`'s `imagePlugin` introduces (`?optimize` / `?component`
+ * / `?raw`). Shipped + exported so the documented usage type-checks out
+ * of the box — no consumer hand-authoring required.
+ *
+ * Add ONE line to any tsconfig-covered `.d.ts` (e.g. `src/env.d.ts`):
+ *   /// <reference types="@pyreon/zero/image-types" />
+ *
+ * Or via tsconfig.json:
+ *   "types": ["@pyreon/zero/image-types"]
+ *
+ * This is an ambient-only **script** (no top-level import/export) so
+ * every `declare module` below is a global module augmentation. The
+ * `ProcessedImage` shape is referenced via the package self-ref
+ * `import('@pyreon/zero/image-plugin')` (resolution-stable in the
+ * published layout, and re-uses the plugin's own type so it can never
+ * drift out of sync).
+ */
+//#region src/image-types.d.ts
+declare module '*.jpg?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage;
+  export default image;
+}
+declare module '*.jpeg?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage;
+  export default image;
+}
+declare module '*.png?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage;
+  export default image;
+}
+declare module '*.webp?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage;
+  export default image;
+}
+declare module '*.avif?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage;
+  export default image;
+}
+declare module '*.svg?component' {
+  const component: import('@pyreon/core').ComponentFn<{
+    width?: number;
+    height?: number;
+    class?: string;
+    style?: string;
+    [key: string]: unknown;
+  }>;
+  export default component;
+}
+declare module '*.svg?raw' {
+  const svg: string;
+  export default svg;
+}
+//# sourceMappingURL=image-types2.d.ts.map

package/lib/types/server.d.ts

@@ -1036,9 +1036,21 @@ interface FaviconPluginConfig {
   /** Generate web manifest. Default: true */
   manifest?: boolean;
   /**
-   * Dark mode favicon (SVG only).
-   * When provided, the SVG favicon uses prefers-color-scheme media query
-   * to switch between light and dark variants.
+   * Dark-mode favicon source.
+   *
+   * When provided, the plugin emits theme-aware `light`/`dark` variants
+   * (`favicon-light.svg` / `favicon-dark.svg` for SVG sources, plus the
+   * `*-light-*` / `*-dark-*` PNG/apple-touch set) tagged with
+   * `data-favicon-theme`. The injected blocking theme-swap script and
+   * `initTheme()` toggle their `media` attribute so the displayed
+   * favicon follows the app's resolved theme — including a manual
+   * in-app theme toggle, not just the OS `prefers-color-scheme`.
+   *
+   * For SVG sources a `favicon.svg` is also emitted that wraps both
+   * variants behind an OS `prefers-color-scheme` query — kept as the
+   * no-JS / direct-`/favicon.svg`-reference fallback only (it cannot
+   * follow a manual toggle, which is why the `data-favicon-theme`
+   * variants above are what the reactive mechanism actually uses).
    */
   darkSource?: string;
   /**
@@ -1111,6 +1123,8 @@ declare function faviconLinks(locale: string | undefined, config: FaviconPluginC
   type?: string;
   sizes?: string;
   href: string;
+  'data-favicon-theme'?: string;
+  media?: string;
 }>;
 //#endregion
 //#region src/icon.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/zero",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Pyreon Zero — zero-config full-stack framework powered by Pyreon and Vite",
   "license": "MIT",
   "author": "Vit Bokisch",
@@ -84,6 +84,11 @@
       "import": "./lib/image-plugin.js",
       "types": "./lib/types/image-plugin.d.ts"
     },
+    "./image-types": {
+      "bun": "./src/image-types.ts",
+      "import": "./lib/image-types.js",
+      "types": "./lib/types/image-types.d.ts"
+    },
     "./actions": {
       "bun": "./src/actions.ts",
       "import": "./lib/actions.js",
@@ -168,15 +173,15 @@
     "lint": "oxlint ."
   },
   "dependencies": {
-    "@pyreon/core": "^0.20.0",
-    "@pyreon/head": "^0.20.0",
-    "@pyreon/meta": "^0.20.0",
-    "@pyreon/reactivity": "^0.20.0",
-    "@pyreon/router": "^0.20.0",
-    "@pyreon/runtime-dom": "^0.20.0",
-    "@pyreon/runtime-server": "^0.20.0",
-    "@pyreon/server": "^0.20.0",
-    "@pyreon/vite-plugin": "^0.20.0",
+    "@pyreon/core": "^0.21.0",
+    "@pyreon/head": "^0.21.0",
+    "@pyreon/meta": "^0.21.0",
+    "@pyreon/reactivity": "^0.21.0",
+    "@pyreon/router": "^0.21.0",
+    "@pyreon/runtime-dom": "^0.21.0",
+    "@pyreon/runtime-server": "^0.21.0",
+    "@pyreon/server": "^0.21.0",
+    "@pyreon/vite-plugin": "^0.21.0",
     "vite": "^8.0.0"
   },
   "devDependencies": {

package/src/favicon.ts

@@ -81,9 +81,21 @@ export interface FaviconPluginConfig {
   /** Generate web manifest. Default: true */
   manifest?: boolean
   /**
-   * Dark mode favicon (SVG only).
-   * When provided, the SVG favicon uses prefers-color-scheme media query
-   * to switch between light and dark variants.
+   * Dark-mode favicon source.
+   *
+   * When provided, the plugin emits theme-aware `light`/`dark` variants
+   * (`favicon-light.svg` / `favicon-dark.svg` for SVG sources, plus the
+   * `*-light-*` / `*-dark-*` PNG/apple-touch set) tagged with
+   * `data-favicon-theme`. The injected blocking theme-swap script and
+   * `initTheme()` toggle their `media` attribute so the displayed
+   * favicon follows the app's resolved theme — including a manual
+   * in-app theme toggle, not just the OS `prefers-color-scheme`.
+   *
+   * For SVG sources a `favicon.svg` is also emitted that wraps both
+   * variants behind an OS `prefers-color-scheme` query — kept as the
+   * no-JS / direct-`/favicon.svg`-reference fallback only (it cannot
+   * follow a manual toggle, which is why the `data-favicon-theme`
+   * variants above are what the reactive mechanism actually uses).
    */
   darkSource?: string
   /**
@@ -214,6 +226,34 @@ export function faviconPlugin(config: FaviconPluginConfig): Plugin {
         const svgPath = localeSource ? localeSource.sourcePath : sourcePath
         const isSvgSource = localeSource ? localeSource.source.endsWith('.svg') : config.source.endsWith('.svg')
 
+        // Serve the per-theme SVG variants (the app-toggle path):
+        // /favicon-light.svg → source, /favicon-dark.svg → darkSource.
+        // Dev-badge / devSource override applies to the light variant
+        // only (it is the active default the swap toggles to), matching
+        // the /favicon.svg handler's intent.
+        if (
+          isSvgSource &&
+          (svgUrl.endsWith('/favicon-light.svg') ||
+            svgUrl.endsWith('/favicon-dark.svg'))
+        ) {
+          const isDarkVariant = svgUrl.endsWith('/favicon-dark.svg')
+          const variantPath = isDarkVariant ? (darkPath ?? svgPath) : svgPath
+          try {
+            let content = await readFile(variantPath, 'utf-8')
+            if (!isDarkVariant) {
+              if (autoDevBadge) content = addDevBadgeToSvg(content)
+              else if (devSourcePath && existsSync(devSourcePath)) {
+                content = await readFile(devSourcePath, 'utf-8')
+              }
+            }
+            res.setHeader('Content-Type', 'image/svg+xml')
+            res.end(content)
+            return
+          } catch {
+            /* fall through */
+          }
+        }
+
         // Serve favicon.svg — in dev, add dev badge overlay if configured
         if (svgUrl.endsWith('/favicon.svg') && isSvgSource) {
           try {
@@ -307,8 +347,22 @@ export function faviconPlugin(config: FaviconPluginConfig): Plugin {
         injectTo: 'head'
       }> = []
 
-      // SVG favicon (with prefers-color-scheme media query when dark variant exists)
-      if (isSvg) {
+      // SVG favicon. Browsers prefer an SVG favicon over PNG when both
+      // are present, so the SVG link MUST carry the same
+      // `data-favicon-theme` contract the PNG dual-variant uses —
+      // otherwise the theme-swap script / initTheme() (which only touch
+      // `[data-favicon-theme]`) can never change the displayed icon and
+      // the whole reactive-favicon feature is silently dead in every
+      // SVG-capable browser. When a dark variant exists, emit TWO
+      // theme-aware SVG links (mirroring the PNG pattern); the static
+      // `/favicon.svg` (an OS `prefers-color-scheme` wrapped dual) stays
+      // emitted as the no-JS / direct-reference fallback only.
+      if (isSvg && hasDark) {
+        tags.push(
+          { tag: 'link', attrs: { rel: 'icon', type: 'image/svg+xml', href: '/favicon-light.svg', 'data-favicon-theme': 'light' }, injectTo: 'head' },
+          { tag: 'link', attrs: { rel: 'icon', type: 'image/svg+xml', href: '/favicon-dark.svg', 'data-favicon-theme': 'dark', media: 'not all' }, injectTo: 'head' },
+        )
+      } else if (isSvg) {
         tags.push({
           tag: 'link',
           attrs: { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' },
@@ -502,6 +556,22 @@ async function generateFaviconSet(
       if (existsSync(darkPath)) {
         const darkSvg = await readFile(darkPath, 'utf-8')
         finalSvg = wrapSvgWithDarkMode(svgContent, darkSvg)
+        // Per-theme SVG variants for the app-toggle path:
+        // transformIndexHtml / faviconLinks emit
+        // `/favicon-light.svg` + `/favicon-dark.svg` with
+        // `data-favicon-theme` so the theme-swap actually changes the
+        // SVG (the wrapped `favicon.svg` is OS-`prefers-color-scheme`
+        // only — kept above as the no-JS / direct-ref fallback).
+        this.emitFile({
+          type: 'asset',
+          fileName: `${prefix}favicon-light.svg`,
+          source: svgContent,
+        })
+        this.emitFile({
+          type: 'asset',
+          fileName: `${prefix}favicon-dark.svg`,
+          source: darkSvg,
+        })
       }
     }
 
@@ -599,14 +669,39 @@ async function generateFaviconSet(
 export function faviconLinks(
   locale: string | undefined,
   config: FaviconPluginConfig,
-): Array<{ rel: string; type?: string; sizes?: string; href: string }> {
+): Array<{
+  rel: string
+  type?: string
+  sizes?: string
+  href: string
+  'data-favicon-theme'?: string
+  media?: string
+}> {
   const hasLocaleOverride = locale && config.locales?.[locale]
   const prefix = hasLocaleOverride ? `/${locale}` : ''
   const isSvg = (hasLocaleOverride ? config.locales![locale]!.source : config.source).endsWith('.svg')
-
-  const links: Array<{ rel: string; type?: string; sizes?: string; href: string }> = []
-
-  if (isSvg) {
+  const hasDark = !!config.darkSource
+
+  const links: Array<{
+    rel: string
+    type?: string
+    sizes?: string
+    href: string
+    'data-favicon-theme'?: string
+    media?: string
+  }> = []
+
+  // Mirror transformIndexHtml: a single static SVG link would always
+  // win over the theme-toggled PNGs (browsers prefer SVG), silently
+  // killing reactive switching for SSR'd pages too. Emit the two
+  // theme-aware SVG variants so initTheme()'s `[data-favicon-theme]`
+  // swap reaches the SVG. `/favicon.svg` stays the no-JS fallback.
+  if (isSvg && hasDark) {
+    links.push(
+      { rel: 'icon', type: 'image/svg+xml', href: `${prefix}/favicon-light.svg`, 'data-favicon-theme': 'light' },
+      { rel: 'icon', type: 'image/svg+xml', href: `${prefix}/favicon-dark.svg`, 'data-favicon-theme': 'dark', media: 'not all' },
+    )
+  } else if (isSvg) {
     links.push({ rel: 'icon', type: 'image/svg+xml', href: `${prefix}/favicon.svg` })
   }
 

package/src/image-plugin.ts

@@ -23,7 +23,13 @@ function warnSharpMissing() {
 //
 // Usage in code:
 //   import heroImg from "./hero.jpg?optimize"
-//   // → { src, srcset, width, height, placeholder }
+//   // → ProcessedImage { src, srcset, width, height, placeholder }
+//
+// Type the `?optimize` / `?component` / `?raw` imports out of the box —
+// add ONE line to a tsconfig-covered `.d.ts` (e.g. `src/env.d.ts`):
+//   /// <reference types="@pyreon/zero/image-types" />
+// (ships the ambient `declare module "*?optimize"` etc. — reuses this
+//  module's own `ProcessedImage`, so it never drifts.)
 //
 // Or use the component helper:
 //   import { Image } from "@pyreon/zero/image"
@@ -389,7 +395,15 @@ async function loadDevImage(
   placeholderSize: number,
 ): Promise<ProcessedImage> {
   const metadata = await getImageMetadata(absPath)
-  const publicPath = rawPath.startsWith('/') ? rawPath : `/@fs/${absPath}`
+  // `rawPath` is a public-dir web path (e.g. `/logo.png`, served from
+  // `public/` at the web root) ONLY when it does NOT resolve to a real
+  // file on disk — the same discriminator the `absPath` derivation uses
+  // above. `resolveId` now hands absolute fs paths for relative/aliased
+  // imports (`/Users/…/img.png`); those ARE real files and must be
+  // served through Vite's `/@fs/` prefix, not as a literal `/Users/…`
+  // URL (which 404s in dev — build mode was unaffected).
+  const isPublicWebPath = rawPath.startsWith('/') && !existsSync(rawPath)
+  const publicPath = isPublicWebPath ? rawPath : `/@fs/${absPath}`
 
   return {
     src: publicPath,

package/src/image-types.ts

@@ -0,0 +1,60 @@
+/**
+ * Ambient type declarations for the custom image-import queries that
+ * `@pyreon/zero`'s `imagePlugin` introduces (`?optimize` / `?component`
+ * / `?raw`). Shipped + exported so the documented usage type-checks out
+ * of the box — no consumer hand-authoring required.
+ *
+ * Add ONE line to any tsconfig-covered `.d.ts` (e.g. `src/env.d.ts`):
+ *   /// <reference types="@pyreon/zero/image-types" />
+ *
+ * Or via tsconfig.json:
+ *   "types": ["@pyreon/zero/image-types"]
+ *
+ * This is an ambient-only **script** (no top-level import/export) so
+ * every `declare module` below is a global module augmentation. The
+ * `ProcessedImage` shape is referenced via the package self-ref
+ * `import('@pyreon/zero/image-plugin')` (resolution-stable in the
+ * published layout, and re-uses the plugin's own type so it can never
+ * drift out of sync).
+ */
+
+declare module '*.jpg?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage
+  export default image
+}
+
+declare module '*.jpeg?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage
+  export default image
+}
+
+declare module '*.png?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage
+  export default image
+}
+
+declare module '*.webp?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage
+  export default image
+}
+
+declare module '*.avif?optimize' {
+  const image: import('@pyreon/zero/image-plugin').ProcessedImage
+  export default image
+}
+
+declare module '*.svg?component' {
+  const component: import('@pyreon/core').ComponentFn<{
+    width?: number
+    height?: number
+    class?: string
+    style?: string
+    [key: string]: unknown
+  }>
+  export default component
+}
+
+declare module '*.svg?raw' {
+  const svg: string
+  export default svg
+}

package/src/image-types.d.ts

@@ -1,51 +0,0 @@
-/**
- * Type declarations for image imports processed by @pyreon/zero's imagePlugin.
- *
- * Add to your tsconfig.json:
- *   "types": ["@pyreon/zero/image-types"]
- *
- * Or reference directly:
- *   /// <reference types="@pyreon/zero/image-types" />
- */
-
-declare module '*.jpg?optimize' {
-  const image: import('./image-plugin').ProcessedImage
-  export default image
-}
-
-declare module '*.jpeg?optimize' {
-  const image: import('./image-plugin').ProcessedImage
-  export default image
-}
-
-declare module '*.png?optimize' {
-  const image: import('./image-plugin').ProcessedImage
-  export default image
-}
-
-declare module '*.webp?optimize' {
-  const image: import('./image-plugin').ProcessedImage
-  export default image
-}
-
-declare module '*.avif?optimize' {
-  const image: import('./image-plugin').ProcessedImage
-  export default image
-}
-
-declare module '*.svg?component' {
-  import type { ComponentFn } from '@pyreon/core'
-  const component: ComponentFn<{
-    width?: number
-    height?: number
-    class?: string
-    style?: string
-    [key: string]: unknown
-  }>
-  export default component
-}
-
-declare module '*.svg?raw' {
-  const svg: string
-  export default svg
-}