@pyreon/zero 0.12.2 → 0.12.3

package/lib/env.js

@@ -0,0 +1,217 @@
+//#region src/env.ts
+/**
+* String validator — accepts any non-empty string.
+*/
+function str(options) {
+	return {
+		__type: "env-validator",
+		required: options?.default === void 0 && options?.required !== false,
+		defaultValue: options?.default,
+		parse(raw, key) {
+			if (raw === void 0 || raw === "") {
+				if (options?.default !== void 0) return options.default;
+				throw new EnvError(key, "is required but not set", options?.description);
+			}
+			return raw;
+		}
+	};
+}
+/**
+* Number validator — parses to a number, rejects NaN.
+*/
+function num(options) {
+	return {
+		__type: "env-validator",
+		required: options?.default === void 0 && options?.required !== false,
+		defaultValue: options?.default,
+		parse(raw, key) {
+			if (raw === void 0 || raw === "") {
+				if (options?.default !== void 0) return options.default;
+				throw new EnvError(key, "is required but not set", options?.description);
+			}
+			const n = Number(raw);
+			if (Number.isNaN(n)) throw new EnvError(key, `must be a number, got "${raw}"`, options?.description);
+			return n;
+		}
+	};
+}
+/**
+* Boolean validator — accepts "true"/"1" as true, "false"/"0" as false.
+*/
+function bool(options) {
+	return {
+		__type: "env-validator",
+		required: options?.default === void 0 && options?.required !== false,
+		defaultValue: options?.default,
+		parse(raw, key) {
+			if (raw === void 0 || raw === "") {
+				if (options?.default !== void 0) return options.default;
+				throw new EnvError(key, "is required but not set", options?.description);
+			}
+			const lower = raw.toLowerCase();
+			if (lower === "true" || lower === "1") return true;
+			if (lower === "false" || lower === "0") return false;
+			throw new EnvError(key, `must be "true" or "false", got "${raw}"`, options?.description);
+		}
+	};
+}
+/**
+* URL validator — validates that the value is a valid URL.
+*/
+function url(options) {
+	return {
+		__type: "env-validator",
+		required: options?.default === void 0 && options?.required !== false,
+		defaultValue: options?.default,
+		parse(raw, key) {
+			if (raw === void 0 || raw === "") {
+				if (options?.default !== void 0) return options.default;
+				throw new EnvError(key, "is required but not set", options?.description);
+			}
+			try {
+				new URL(raw);
+				return raw;
+			} catch {
+				throw new EnvError(key, `must be a valid URL, got "${raw}"`, options?.description);
+			}
+		}
+	};
+}
+/**
+* Enum validator — value must be one of the allowed values.
+*/
+function oneOf(values, options) {
+	return {
+		__type: "env-validator",
+		required: options?.default === void 0 && options?.required !== false,
+		defaultValue: options?.default,
+		parse(raw, key) {
+			if (raw === void 0 || raw === "") {
+				if (options?.default !== void 0) return options.default;
+				throw new EnvError(key, "is required but not set", options?.description);
+			}
+			if (!values.includes(raw)) throw new EnvError(key, `must be one of [${values.join(", ")}], got "${raw}"`, options?.description);
+			return raw;
+		}
+	};
+}
+var EnvError = class extends Error {
+	constructor(key, message, description) {
+		const desc = description ? ` (${description})` : "";
+		super(`[zero:env] ${key}${desc}: ${message}`);
+		this.name = "EnvError";
+	}
+};
+function isEnvValidator(v) {
+	return typeof v === "object" && v !== null && v.__type === "env-validator";
+}
+/**
+* Convert a plain schema value to an EnvValidator.
+*
+* - `3000` → num({ default: 3000 })
+* - `false` → bool({ default: false })
+* - `"localhost"` → str({ default: "localhost" })
+* - `String` → str() (required)
+* - `Number` → num() (required)
+* - `Boolean` → bool() (required)
+* - EnvValidator → pass through
+*/
+function toValidator(value) {
+	if (isEnvValidator(value)) return value;
+	if (value === String) return str();
+	if (value === Number) return num();
+	if (value === Boolean) return bool();
+	if (typeof value === "number") return num({ default: value });
+	if (typeof value === "boolean") return bool({ default: value });
+	if (typeof value === "string") return str({ default: value });
+	throw new Error(`[zero:env] Invalid schema value: ${String(value)}. Use a default value, String/Number/Boolean, or a validator like url().`);
+}
+/**
+* Validate environment variables.
+*
+* Schema values can be:
+* - **Default values**: `3000`, `false`, `"localhost"` → type inferred, used as default
+* - **Constructors**: `String`, `Number`, `Boolean` → required, no default
+* - **Validators**: `url()`, `oneOf([...])`, `str()`, `num()`, `bool()` → explicit validation
+* - **Custom**: `schema(raw => z.coerce.number().parse(raw))` — bridge to any schema library
+*
+* @example
+* ```ts
+* import { validateEnv, url, oneOf } from "@pyreon/zero/env"
+*
+* const env = validateEnv({
+*   PORT: 3000,                                // optional, default 3000
+*   DATABASE_URL: url(),                       // required, validated URL
+*   NODE_ENV: oneOf(["dev", "prod", "test"]),  // required, must be one of
+*   API_KEY: String,                           // required string
+*   DEBUG: false,                              // optional, default false
+* })
+* ```
+*/
+function validateEnv(schema, source) {
+	const env = source ?? (typeof process !== "undefined" ? process.env : {});
+	const result = {};
+	const errors = [];
+	for (const [key, entry] of Object.entries(schema)) {
+		const validator = toValidator(entry);
+		try {
+			result[key] = validator.parse(env[key], key);
+		} catch (e) {
+			errors.push(e.message);
+		}
+	}
+	if (errors.length > 0) {
+		const header = `\n[zero:env] Environment validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):\n`;
+		const body = errors.map((e) => `  ✗ ${e.replace("[zero:env] ", "")}`).join("\n");
+		throw new Error(header + body + "\n");
+	}
+	return result;
+}
+function publicEnv(schema) {
+	const prefix = "ZERO_PUBLIC_";
+	const env = typeof process !== "undefined" ? process.env : {};
+	if (!schema) {
+		const result = {};
+		for (const [key, value] of Object.entries(env)) if (key.startsWith(prefix) && value !== void 0) result[key.slice(12)] = value;
+		return result;
+	}
+	const prefixedSource = {};
+	for (const key of Object.keys(schema)) prefixedSource[key] = env[`${prefix}${key}`];
+	return validateEnv(schema, prefixedSource);
+}
+/**
+* Create an env validator from a custom parse function.
+* Use this to integrate any schema library (Zod, Valibot, ArkType, etc.).
+*
+* @example
+* ```ts
+* import { z } from "zod"
+* import { validateEnv, schema } from "@pyreon/zero/env"
+*
+* const env = validateEnv({
+*   PORT: schema(raw => z.coerce.number().parse(raw)),
+*   DATABASE_URL: schema(raw => z.string().url().parse(raw)),
+*   HOST: "localhost",  // plain defaults still work alongside
+* })
+* ```
+*/
+function schema(parse) {
+	return {
+		__type: "env-validator",
+		required: true,
+		defaultValue: void 0,
+		parse(raw, key) {
+			if (raw === void 0 || raw === "") throw new Error(`[zero:env] ${key}: is required but not set`);
+			try {
+				return parse(raw);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				throw new Error(`[zero:env] ${key}: ${msg}`);
+			}
+		}
+	};
+}
+
+//#endregion
+export { bool, num, oneOf, publicEnv, schema, str, url, validateEnv };
+//# sourceMappingURL=env.js.map

package/lib/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","names":[],"sources":["../src/env.ts"],"sourcesContent":["/**\n * Environment variable validation.\n *\n * Infers types from default values — no verbose validator imports needed.\n * Explicit validators (`url()`, `oneOf()`) available for special cases.\n *\n * @example\n * ```ts\n * import { validateEnv, url, oneOf } from \"@pyreon/zero/env\"\n *\n * const env = validateEnv({\n *   PORT: 3000,                                // number, default 3000\n *   DEBUG: false,                              // boolean, default false\n *   HOST: \"localhost\",                         // string, default \"localhost\"\n *   DATABASE_URL: url(),                       // validated URL, required\n *   NODE_ENV: oneOf([\"development\", \"production\", \"test\"]),\n *   API_KEY: String,                           // required string, no default\n *   MAX_RETRIES: Number,                       // required number, no default\n * })\n * ```\n */\n\nexport interface EnvValidatorOptions<T = string> {\n  /** Whether this variable is required. Default: true */\n  required?: boolean\n  /** Default value when not set. Makes the variable optional. */\n  default?: T\n  /** Human-readable description for error messages. */\n  description?: string\n}\n\nexport interface EnvValidator<T> {\n  __type: 'env-validator'\n  parse: (raw: string | undefined, key: string) => T\n  required: boolean\n  defaultValue?: T | undefined\n}\n\n// ─── Explicit validators (for special cases) ────────────────────────────────\n\n/**\n * String validator — accepts any non-empty string.\n */\nexport function str(options?: EnvValidatorOptions<string>): EnvValidator<string> {\n  const required = options?.default === undefined && options?.required !== false\n  return {\n    __type: 'env-validator',\n    required,\n    defaultValue: options?.default,\n    parse(raw, key) {\n      if (raw === undefined || raw === '') {\n        if (options?.default !== undefined) return options.default\n        throw new EnvError(key, 'is required but not set', options?.description)\n      }\n      return raw\n    },\n  }\n}\n\n/**\n * Number validator — parses to a number, rejects NaN.\n */\nexport function num(options?: EnvValidatorOptions<number>): EnvValidator<number> {\n  const required = options?.default === undefined && options?.required !== false\n  return {\n    __type: 'env-validator',\n    required,\n    defaultValue: options?.default,\n    parse(raw, key) {\n      if (raw === undefined || raw === '') {\n        if (options?.default !== undefined) return options.default\n        throw new EnvError(key, 'is required but not set', options?.description)\n      }\n      const n = Number(raw)\n      if (Number.isNaN(n)) {\n        throw new EnvError(key, `must be a number, got \"${raw}\"`, options?.description)\n      }\n      return n\n    },\n  }\n}\n\n/**\n * Boolean validator — accepts \"true\"/\"1\" as true, \"false\"/\"0\" as false.\n */\nexport function bool(options?: EnvValidatorOptions<boolean>): EnvValidator<boolean> {\n  const required = options?.default === undefined && options?.required !== false\n  return {\n    __type: 'env-validator',\n    required,\n    defaultValue: options?.default,\n    parse(raw, key) {\n      if (raw === undefined || raw === '') {\n        if (options?.default !== undefined) return options.default\n        throw new EnvError(key, 'is required but not set', options?.description)\n      }\n      const lower = raw.toLowerCase()\n      if (lower === 'true' || lower === '1') return true\n      if (lower === 'false' || lower === '0') return false\n      throw new EnvError(key, `must be \"true\" or \"false\", got \"${raw}\"`, options?.description)\n    },\n  }\n}\n\n/**\n * URL validator — validates that the value is a valid URL.\n */\nexport function url(options?: EnvValidatorOptions<string>): EnvValidator<string> {\n  const required = options?.default === undefined && options?.required !== false\n  return {\n    __type: 'env-validator',\n    required,\n    defaultValue: options?.default,\n    parse(raw, key) {\n      if (raw === undefined || raw === '') {\n        if (options?.default !== undefined) return options.default\n        throw new EnvError(key, 'is required but not set', options?.description)\n      }\n      try {\n        new URL(raw)\n        return raw\n      } catch {\n        throw new EnvError(key, `must be a valid URL, got \"${raw}\"`, options?.description)\n      }\n    },\n  }\n}\n\n/**\n * Enum validator — value must be one of the allowed values.\n */\nexport function oneOf<T extends string>(\n  values: readonly T[],\n  options?: EnvValidatorOptions<T>,\n): EnvValidator<T> {\n  const required = options?.default === undefined && options?.required !== false\n  return {\n    __type: 'env-validator',\n    required,\n    defaultValue: options?.default,\n    parse(raw, key) {\n      if (raw === undefined || raw === '') {\n        if (options?.default !== undefined) return options.default\n        throw new EnvError(key, 'is required but not set', options?.description)\n      }\n      if (!values.includes(raw as T)) {\n        throw new EnvError(\n          key,\n          `must be one of [${values.join(', ')}], got \"${raw}\"`,\n          options?.description,\n        )\n      }\n      return raw as T\n    },\n  }\n}\n\n// ─── Internal helpers ───────────────────────────────────────────────────────\n\nclass EnvError extends Error {\n  constructor(key: string, message: string, description?: string) {\n    const desc = description ? ` (${description})` : ''\n    super(`[zero:env] ${key}${desc}: ${message}`)\n    this.name = 'EnvError'\n  }\n}\n\nfunction isEnvValidator(v: unknown): v is EnvValidator<unknown> {\n  return typeof v === 'object' && v !== null && (v as any).__type === 'env-validator'\n}\n\n/**\n * Convert a plain schema value to an EnvValidator.\n *\n * - `3000` → num({ default: 3000 })\n * - `false` → bool({ default: false })\n * - `\"localhost\"` → str({ default: \"localhost\" })\n * - `String` → str() (required)\n * - `Number` → num() (required)\n * - `Boolean` → bool() (required)\n * - EnvValidator → pass through\n */\nfunction toValidator(value: unknown): EnvValidator<unknown> {\n  if (isEnvValidator(value)) return value\n\n  // Constructor markers → required, no default\n  if (value === String) return str()\n  if (value === Number) return num()\n  if (value === Boolean) return bool()\n\n  // Plain values → infer type + use as default\n  if (typeof value === 'number') return num({ default: value })\n  if (typeof value === 'boolean') return bool({ default: value })\n  if (typeof value === 'string') return str({ default: value })\n\n  throw new Error(`[zero:env] Invalid schema value: ${String(value)}. Use a default value, String/Number/Boolean, or a validator like url().`)\n}\n\n// ─── Type inference ─────────────────────────────────────────────────────────\n\n/** Schema entry: plain value, constructor, or explicit validator. */\ntype SchemaEntry =\n  | string | number | boolean\n  | StringConstructor | NumberConstructor | BooleanConstructor\n  | EnvValidator<any>\n\n/** Infer the output type from a schema entry. */\ntype InferEntry<T> =\n  T extends EnvValidator<infer V> ? V :\n  T extends StringConstructor ? string :\n  T extends NumberConstructor ? number :\n  T extends BooleanConstructor ? boolean :\n  T extends string ? string :\n  T extends number ? number :\n  T extends boolean ? boolean :\n  never\n\ntype InferEnvSchema<T> = {\n  [K in keyof T]: InferEntry<T[K]>\n}\n\n// ─── Main API ───────────────────────────────────────────────────────────────\n\n/**\n * Validate environment variables.\n *\n * Schema values can be:\n * - **Default values**: `3000`, `false`, `\"localhost\"` → type inferred, used as default\n * - **Constructors**: `String`, `Number`, `Boolean` → required, no default\n * - **Validators**: `url()`, `oneOf([...])`, `str()`, `num()`, `bool()` → explicit validation\n * - **Custom**: `schema(raw => z.coerce.number().parse(raw))` — bridge to any schema library\n *\n * @example\n * ```ts\n * import { validateEnv, url, oneOf } from \"@pyreon/zero/env\"\n *\n * const env = validateEnv({\n *   PORT: 3000,                                // optional, default 3000\n *   DATABASE_URL: url(),                       // required, validated URL\n *   NODE_ENV: oneOf([\"dev\", \"prod\", \"test\"]),  // required, must be one of\n *   API_KEY: String,                           // required string\n *   DEBUG: false,                              // optional, default false\n * })\n * ```\n */\nexport function validateEnv<T extends Record<string, SchemaEntry>>(\n  schema: T,\n  source?: Record<string, string | undefined>,\n): InferEnvSchema<T> {\n  const env = source ?? (typeof process !== 'undefined' ? process.env : {})\n  const result: Record<string, unknown> = {}\n  const errors: string[] = []\n\n  for (const [key, entry] of Object.entries(schema)) {\n    const validator = toValidator(entry)\n    try {\n      result[key] = validator.parse(env[key], key)\n    } catch (e) {\n      errors.push((e as Error).message)\n    }\n  }\n\n  if (errors.length > 0) {\n    const header = `\\n[zero:env] Environment validation failed (${errors.length} error${errors.length > 1 ? 's' : ''}):\\n`\n    const body = errors.map((e) => `  ✗ ${e.replace('[zero:env] ', '')}`).join('\\n')\n    throw new Error(header + body + '\\n')\n  }\n\n  return result as InferEnvSchema<T>\n}\n\n// ─── Public env (client-safe) ────────────────────────────────────────────────\n\n/**\n * Extract public environment variables (prefixed with `ZERO_PUBLIC_`).\n *\n * @example\n * ```ts\n * const pub = publicEnv()\n * // → { API_URL: \"https://...\", APP_NAME: \"MyApp\" }\n *\n * const pub = publicEnv({ API_URL: url(), APP_NAME: \"Default\" })\n * // → validated against ZERO_PUBLIC_API_URL, ZERO_PUBLIC_APP_NAME\n * ```\n */\nexport function publicEnv(): Record<string, string>\nexport function publicEnv<T extends Record<string, SchemaEntry>>(schema: T): InferEnvSchema<T>\nexport function publicEnv(schema?: Record<string, SchemaEntry>): Record<string, unknown> {\n  const prefix = 'ZERO_PUBLIC_'\n  const env = typeof process !== 'undefined' ? process.env : {}\n\n  if (!schema) {\n    const result: Record<string, string> = {}\n    for (const [key, value] of Object.entries(env)) {\n      if (key.startsWith(prefix) && value !== undefined) {\n        result[key.slice(prefix.length)] = value\n      }\n    }\n    return result\n  }\n\n  const prefixedSource: Record<string, string | undefined> = {}\n  for (const key of Object.keys(schema)) {\n    prefixedSource[key] = env[`${prefix}${key}`]\n  }\n  return validateEnv(schema, prefixedSource)\n}\n\n// ─── Custom validator escape hatch ──────────────────────────────────────────\n\n/**\n * Create an env validator from a custom parse function.\n * Use this to integrate any schema library (Zod, Valibot, ArkType, etc.).\n *\n * @example\n * ```ts\n * import { z } from \"zod\"\n * import { validateEnv, schema } from \"@pyreon/zero/env\"\n *\n * const env = validateEnv({\n *   PORT: schema(raw => z.coerce.number().parse(raw)),\n *   DATABASE_URL: schema(raw => z.string().url().parse(raw)),\n *   HOST: \"localhost\",  // plain defaults still work alongside\n * })\n * ```\n */\nexport function schema<T>(parse: (raw: string) => T): EnvValidator<T> {\n  return {\n    __type: 'env-validator',\n    required: true,\n    defaultValue: undefined,\n    parse(raw: string | undefined, key: string) {\n      if (raw === undefined || raw === '') {\n        throw new Error(`[zero:env] ${key}: is required but not set`)\n      }\n      try {\n        return parse(raw)\n      } catch (e) {\n        const msg = e instanceof Error ? e.message : String(e)\n        throw new Error(`[zero:env] ${key}: ${msg}`)\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/lib/favicon.js

@@ -0,0 +1,424 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+//#region src/favicon.ts
+let sharpWarned = false;
+function warnSharpMissing() {
+	if (sharpWarned) return;
+	sharpWarned = true;
+	console.warn("\n[zero:favicon] sharp not installed — favicons will not be generated. Install for full support: bun add -D sharp\n");
+}
+const SIZES = [
+	{
+		size: 16,
+		name: "favicon-16x16.png"
+	},
+	{
+		size: 32,
+		name: "favicon-32x32.png"
+	},
+	{
+		size: 180,
+		name: "apple-touch-icon.png"
+	},
+	{
+		size: 192,
+		name: "icon-192.png"
+	},
+	{
+		size: 512,
+		name: "icon-512.png"
+	}
+];
+/**
+* Favicon generation Vite plugin.
+*
+* Generates all required favicon formats at build time from a single source.
+* In dev mode, serves the source directly.
+*
+* @example
+* ```ts
+* // vite.config.ts
+* import { faviconPlugin } from "@pyreon/zero"
+*
+* export default {
+*   plugins: [faviconPlugin({ source: "./src/assets/icon.svg" })],
+* }
+* ```
+*/
+function faviconPlugin(config) {
+	const themeColor = config.themeColor ?? "#ffffff";
+	const backgroundColor = config.backgroundColor ?? "#ffffff";
+	const generateManifest = config.manifest !== false;
+	let root = "";
+	let isBuild = false;
+	return {
+		name: "pyreon-zero-favicon",
+		enforce: "pre",
+		configResolved(resolvedConfig) {
+			root = resolvedConfig.root;
+			isBuild = resolvedConfig.command === "build";
+		},
+		configureServer(server) {
+			const sourcePath = join(root, config.source);
+			const devCache = /* @__PURE__ */ new Map();
+			server.middlewares.use(async (req, res, next) => {
+				const url = req.url ?? "";
+				const localeSource = resolveLocaleSource(url, config, root);
+				const svgUrl = localeSource ? localeSource.url : url;
+				const svgPath = localeSource ? localeSource.sourcePath : sourcePath;
+				const isSvgSource = localeSource ? localeSource.source.endsWith(".svg") : config.source.endsWith(".svg");
+				if (svgUrl.endsWith("/favicon.svg") && isSvgSource) try {
+					const content = await readFile(svgPath, "utf-8");
+					res.setHeader("Content-Type", "image/svg+xml");
+					res.end(content);
+					return;
+				} catch {}
+				const baseName = svgUrl.split("/").pop() ?? "";
+				const sizeMatch = SIZES.find((s) => s.name === baseName);
+				if (sizeMatch) {
+					const cacheKey = `${svgPath}:${sizeMatch.size}`;
+					let png = devCache.get(cacheKey);
+					if (!png) {
+						const result = await resizeToPng(svgPath, sizeMatch.size);
+						if (result) {
+							png = result;
+							devCache.set(cacheKey, result);
+						}
+					}
+					if (png) {
+						res.setHeader("Content-Type", "image/png");
+						res.setHeader("Cache-Control", "no-cache");
+						res.end(Buffer.from(png));
+						return;
+					}
+				}
+				if (baseName === "favicon.ico") {
+					const cacheKey = `ico:${svgPath}`;
+					let ico = devCache.get(cacheKey);
+					if (!ico) {
+						const result = await generateIco(svgPath);
+						if (result) {
+							ico = result;
+							devCache.set(cacheKey, result);
+						}
+					}
+					if (ico) {
+						res.setHeader("Content-Type", "image/x-icon");
+						res.setHeader("Cache-Control", "no-cache");
+						res.end(Buffer.from(ico));
+						return;
+					}
+				}
+				if (baseName === "site.webmanifest" && generateManifest) {
+					const prefix = localeSource ? `/${localeSource.locale}` : "";
+					const manifest = {
+						name: config.name ?? "App",
+						short_name: config.name ?? "App",
+						icons: [{
+							src: `${prefix}/icon-192.png`,
+							sizes: "192x192",
+							type: "image/png"
+						}, {
+							src: `${prefix}/icon-512.png`,
+							sizes: "512x512",
+							type: "image/png"
+						}],
+						theme_color: themeColor,
+						background_color: backgroundColor,
+						display: "standalone"
+					};
+					res.setHeader("Content-Type", "application/manifest+json");
+					res.end(JSON.stringify(manifest, null, 2));
+					return;
+				}
+				next();
+			});
+		},
+		transformIndexHtml() {
+			const isSvg = config.source.endsWith(".svg");
+			const tags = [];
+			if (isSvg) tags.push({
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/svg+xml",
+					href: "/favicon.svg"
+				},
+				injectTo: "head"
+			});
+			tags.push({
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/png",
+					sizes: "32x32",
+					href: "/favicon-32x32.png"
+				},
+				injectTo: "head"
+			}, {
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					type: "image/png",
+					sizes: "16x16",
+					href: "/favicon-16x16.png"
+				},
+				injectTo: "head"
+			}, {
+				tag: "link",
+				attrs: {
+					rel: "apple-touch-icon",
+					sizes: "180x180",
+					href: "/apple-touch-icon.png"
+				},
+				injectTo: "head"
+			});
+			if (generateManifest) tags.push({
+				tag: "link",
+				attrs: {
+					rel: "manifest",
+					href: "/site.webmanifest"
+				},
+				injectTo: "head"
+			});
+			tags.push({
+				tag: "meta",
+				attrs: {
+					name: "theme-color",
+					content: themeColor
+				},
+				injectTo: "head"
+			});
+			return tags;
+		},
+		async generateBundle() {
+			if (!isBuild) return;
+			await generateFaviconSet.call(this, root, config.source, config.darkSource, "", config, themeColor, backgroundColor, generateManifest);
+			if (config.locales) for (const [locale, localeConfig] of Object.entries(config.locales)) await generateFaviconSet.call(this, root, localeConfig.source, localeConfig.darkSource, `${locale}/`, config, themeColor, backgroundColor, generateManifest);
+		}
+	};
+}
+/**
+* Wrap two SVGs into a single SVG that switches based on prefers-color-scheme.
+*/
+function wrapSvgWithDarkMode(lightSvg, darkSvg) {
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${lightSvg.match(/viewBox="([^"]*)"/)?.[1] ?? "0 0 32 32"}">
+  <style>
+    :root { color-scheme: light dark; }
+    @media (prefers-color-scheme: dark) { .light { display: none; } }
+    @media (prefers-color-scheme: light), (prefers-color-scheme: no-preference) { .dark { display: none; } }
+  </style>
+  <g class="light">${stripSvgWrapper(lightSvg)}</g>
+  <g class="dark">${stripSvgWrapper(darkSvg)}</g>
+</svg>`;
+}
+function stripSvgWrapper(svg) {
+	return svg.replace(/<svg[^>]*>/, "").replace(/<\/svg>\s*$/, "").trim();
+}
+/**
+* Resolve the source path for a locale-prefixed favicon URL.
+* Returns null if the URL is not locale-prefixed or locale has no override.
+*/
+function resolveLocaleSource(url, config, rootDir) {
+	if (!config.locales) return null;
+	for (const [locale, localeConfig] of Object.entries(config.locales)) {
+		const prefix = `/${locale}/`;
+		if (url.startsWith(prefix)) return {
+			locale,
+			url,
+			source: localeConfig.source,
+			sourcePath: join(rootDir, localeConfig.source)
+		};
+	}
+	return null;
+}
+/**
+* Generate a complete favicon set (SVG, PNGs, ICO, manifest) with a file prefix.
+* Called once for base (prefix = '') and once per locale (prefix = '{locale}/').
+*/
+async function generateFaviconSet(rootDir, source, darkSource, prefix, config, themeColor, backgroundColor, generateManifest) {
+	const sourcePath = join(rootDir, source);
+	if (!existsSync(sourcePath)) {
+		console.warn(`[zero:favicon] Source not found: ${sourcePath}`);
+		return;
+	}
+	if (source.endsWith(".svg")) {
+		const svgContent = await readFile(sourcePath, "utf-8");
+		let finalSvg = svgContent;
+		if (darkSource) {
+			const darkPath = join(rootDir, darkSource);
+			if (existsSync(darkPath)) finalSvg = wrapSvgWithDarkMode(svgContent, await readFile(darkPath, "utf-8"));
+		}
+		this.emitFile({
+			type: "asset",
+			fileName: `${prefix}favicon.svg`,
+			source: finalSvg
+		});
+	}
+	for (const { size, name } of SIZES) {
+		const pngBuffer = await resizeToPng(sourcePath, size);
+		if (pngBuffer) this.emitFile({
+			type: "asset",
+			fileName: `${prefix}${name}`,
+			source: pngBuffer
+		});
+	}
+	const ico = await generateIco(sourcePath);
+	if (ico) this.emitFile({
+		type: "asset",
+		fileName: `${prefix}favicon.ico`,
+		source: ico
+	});
+	if (generateManifest) {
+		const manifestPrefix = prefix ? `/${prefix.slice(0, -1)}` : "";
+		const manifest = {
+			name: config.name ?? "App",
+			short_name: config.name ?? "App",
+			icons: [{
+				src: `${manifestPrefix}/icon-192.png`,
+				sizes: "192x192",
+				type: "image/png"
+			}, {
+				src: `${manifestPrefix}/icon-512.png`,
+				sizes: "512x512",
+				type: "image/png"
+			}],
+			theme_color: themeColor,
+			background_color: backgroundColor,
+			display: "standalone"
+		};
+		this.emitFile({
+			type: "asset",
+			fileName: `${prefix}site.webmanifest`,
+			source: JSON.stringify(manifest, null, 2)
+		});
+	}
+}
+/**
+* Get favicon link tags for a specific locale.
+* Returns link objects suitable for `useHead()` or direct HTML injection.
+*
+* @example
+* ```ts
+* const links = faviconLinks("de", { source: "./icon.svg", locales: { de: { source: "./icon-de.svg" } } })
+* // → [{ rel: "icon", type: "image/svg+xml", href: "/de/favicon.svg" }, ...]
+* ```
+*/
+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 links = [];
+	if (isSvg) links.push({
+		rel: "icon",
+		type: "image/svg+xml",
+		href: `${prefix}/favicon.svg`
+	});
+	links.push({
+		rel: "icon",
+		type: "image/png",
+		sizes: "32x32",
+		href: `${prefix}/favicon-32x32.png`
+	}, {
+		rel: "icon",
+		type: "image/png",
+		sizes: "16x16",
+		href: `${prefix}/favicon-16x16.png`
+	}, {
+		rel: "apple-touch-icon",
+		sizes: "180x180",
+		href: `${prefix}/apple-touch-icon.png`
+	});
+	if (config.manifest !== false) links.push({
+		rel: "manifest",
+		href: `${prefix}/site.webmanifest`
+	});
+	return links;
+}
+async function resizeToPng(input, size) {
+	try {
+		return await (await import("sharp").then((m) => m.default ?? m))(input).resize(size, size, {
+			fit: "contain",
+			background: {
+				r: 0,
+				g: 0,
+				b: 0,
+				alpha: 0
+			}
+		}).png().toBuffer();
+	} catch {
+		warnSharpMissing();
+		return null;
+	}
+}
+async function generateIco(input) {
+	try {
+		const sharp = await import("sharp").then((m) => m.default ?? m);
+		const png16 = await sharp(input).resize(16, 16, {
+			fit: "contain",
+			background: {
+				r: 0,
+				g: 0,
+				b: 0,
+				alpha: 0
+			}
+		}).png().toBuffer();
+		const png32 = await sharp(input).resize(32, 32, {
+			fit: "contain",
+			background: {
+				r: 0,
+				g: 0,
+				b: 0,
+				alpha: 0
+			}
+		}).png().toBuffer();
+		return createIcoFromPngs([{
+			buffer: png16,
+			size: 16
+		}, {
+			buffer: png32,
+			size: 32
+		}]);
+	} catch {
+		warnSharpMissing();
+		return null;
+	}
+}
+/** @internal Exported for testing */
+function createIcoFromPngs(entries) {
+	const headerSize = 6;
+	const dirEntrySize = 16;
+	const dirSize = dirEntrySize * entries.length;
+	let dataOffset = headerSize + dirSize;
+	const header = Buffer.alloc(headerSize);
+	header.writeUInt16LE(0, 0);
+	header.writeUInt16LE(1, 2);
+	header.writeUInt16LE(entries.length, 4);
+	const dirEntries = Buffer.alloc(dirSize);
+	const dataBuffers = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		const offset = i * dirEntrySize;
+		dirEntries.writeUInt8(entry.size === 256 ? 0 : entry.size, offset);
+		dirEntries.writeUInt8(entry.size === 256 ? 0 : entry.size, offset + 1);
+		dirEntries.writeUInt8(0, offset + 2);
+		dirEntries.writeUInt8(0, offset + 3);
+		dirEntries.writeUInt16LE(1, offset + 4);
+		dirEntries.writeUInt16LE(32, offset + 6);
+		dirEntries.writeUInt32LE(entry.buffer.length, offset + 8);
+		dirEntries.writeUInt32LE(dataOffset, offset + 12);
+		dataOffset += entry.buffer.length;
+		dataBuffers.push(entry.buffer);
+	}
+	return Buffer.concat([
+		header,
+		dirEntries,
+		...dataBuffers
+	]);
+}
+
+//#endregion
+export { createIcoFromPngs, faviconLinks, faviconPlugin };
+//# sourceMappingURL=favicon.js.map