@kirigami/php-prepros 1.1.0 → 1.2.0

package/index.d.ts

@@ -9,7 +9,7 @@
  *
  * @example
  * ```js
- * import { render, sitemap } from '@kirigami/php-prepros';
+ * import { render, sitemap, runenv, mountPath } from '@kirigami/php-prepros';
  *
  * // Compile a single page
  * const result = await render('src/index.php');
@@ -19,6 +19,12 @@
  *
  * // Generate sitemap.xml
  * const sitemap = await sitemap();
+ *
+ * // Run an arbitrary PHP script in the same sandboxed environment
+ * const result = await runenv('scripts/purge-cache.php');
+ *
+ * // Mount a local file/directory into the sandbox before rendering
+ * await mountPath('assets/data/team.yaml');
  * ```
  */
 
@@ -106,4 +112,71 @@ export function render(file?: string): Promise<PreprosResult>;
  * @returns A {@link PreprosResult} with `files` containing the path to the
  *          generated `sitemap.xml`.
  */
-export function sitemap(dir?: string): Promise<PreprosResult>;
+export function sitemap(dir?: string): Promise<PreprosResult>;
+
+
+/**
+ * Run an arbitrary PHP script — not a page template — inside the same
+ * sandboxed WASM environment used by {@link render}, with the full
+ * `php-prepros` class library autoloaded and `kirigami.yaml`'s `kirigami`
+ * block available as `PREPROS::$config->data`.
+ *
+ * Useful for one-off maintenance scripts, data migrations, or CLI-style
+ * tooling that needs `CACHE`, `SCRAPER`, `IMG`, etc. without going through
+ * the page-rendering pipeline.
+ *
+ * ```js
+ * // Run a standalone PHP script
+ * const result = await runenv('scripts/purge-cache.php');
+ *
+ * // Also mount extra local paths/files into the sandbox before running
+ * const result = await runenv('scripts/build-og-images.php', ['assets/photos']);
+ *
+ * // Extra arguments are appended and available as $argv[2], $argv[3], … in the script
+ * const result = await runenv('scripts/import.php', [], '--force');
+ * ```
+ *
+ * @param script Path to a PHP file inside the project, executed with
+ *               `require_once`.
+ * @param paths  Extra local paths (files or directories) to mount into the
+ *               sandbox before the script runs.
+ * @param args   Extra string arguments appended to the script's `$argv`.
+ *
+ * @returns A {@link PreprosResult} describing what was written. Call
+ *          `PREPROS::exportFile()` inside the script for any file you want
+ *          listed in `result.files`.
+ *
+ * @throws When no `script` path is given.
+ * @throws When `script` resolves outside the project root, or doesn't exist.
+ */
+export function runenv(script: string, paths?: string[], ...args: string[]): Promise<PreprosResult>;
+
+
+/**
+ * The JavaScript-side counterpart to `PREPROS::mount()`. Mounts a local
+ * file or directory — recursively, preserving structure — into the WASM
+ * sandbox's virtual filesystem, ahead of (or between) calls to
+ * {@link render}, {@link sitemap}, or {@link runenv}.
+ *
+ * Mounting a directory only copies files whose extension is one of the
+ * defaults (`.php`, `.json`, `.yaml`, `.yml`, `.md`, `.db`, `.txt`) or
+ * listed in `prepros.mountext`, same as automatic root mounting. Mounting a
+ * single file directly copies it regardless of extension.
+ *
+ * ```js
+ * // Mount a single file at its natural virtual path (/project/<relative path>)
+ * await mountPath('assets/data/team.yaml');
+ *
+ * // Mount a whole directory, at a custom virtual path
+ * await mountPath('vendor/fonts', '/project/fonts');
+ * ```
+ *
+ * @param localPath  Path to a local file or directory. Relative paths are
+ *                    resolved against the project root.
+ * @param virtualDir  Destination path inside the WASM filesystem. Defaults
+ *                     to `/project/<localPath relative to the project root>`
+ *                     when omitted.
+ * @param php  WASM PHP instance to mount into. Defaults to the shared
+ *             singleton instance (creating it if needed).
+ */
+export function mountPath(localPath: string, virtualDir?: string, php?: unknown): Promise<void>;

package/index.js

@@ -1 +1 @@
-export { render, sitemap, runenv } from "./src/prepros.js";
+export { render, sitemap, runenv, mountPath } from "./src/prepros.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20.10.0",
+    "node": ">=24.0.0",
     "npm": ">=10.2.3"
   },
   "exports": {
@@ -44,8 +44,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@kirigami/php-wasm": "8.5.10-3",
-    "@kirigami/struct-walker": "1.0.3",
+    "@kirigami/php-wasm": "8.5.10-5",
+    "@kirigami/struct-walker": "1.0.4",
     "picomatch": "^4.0.7"
   },
   "repository": {

package/src/libraries/curl.class.php

@@ -1,5 +1,10 @@
 <?php
 
+
+
+if(!boolval(PREPROS::$config->network ?? false)) STD::error("CURL Error: Network option is not activated.");
+
+
 class CURL {
 
 	const HEADERS = [

package/src/libraries/html.class.php

@@ -1,16 +1,16 @@
 <?php
 
 /**
- * HtmlFormatter — formateur HTML pour Kirigami
- * Utilise Dom\HTMLDocument (PHP 8.4, moteur Lexbor) pour parser,
- * puis re-sérialise avec indentation.
- * Les blocs <script> et <style> sont indentés au bon niveau mais non reformatés.
+ * HtmlFormatter — HTML formatter for Kirigami
+ * Uses Dom\HTMLDocument (PHP 8.4, Lexbor engine) to parse, then re-serializes
+ * with indentation.
+ * <script> and <style> blocks are indented at the right level but not reformatted.
  */
 class HTML
 {
     private const INDENT = 4;
 
-    // Attributs booléens HTML5 — écrits sans valeur
+    // HTML5 boolean attributes — written without a value
     private const BOOLEAN_ATTRS = [
         'allowfullscreen', 'async', 'autofocus', 'autoplay', 'checked',
         'controls', 'default', 'defer', 'disabled', 'formnovalidate',
@@ -19,7 +19,7 @@ class HTML
         'readonly', 'required', 'reversed', 'selected', 'webkit-playsinline',
     ];
 
-    // Éléments inline — leur présence dans un parent n'empêche pas le rendu inline
+    // Inline elements — their presence in a parent doesn't prevent inline rendering
     private const INLINE = [
         'a', 'abbr', 'acronym', 'b', 'bdo', 'big', 'br', 'button', 'cite',
         'code', 'dfn', 'em', 'i', 'img', 'input', 'kbd', 'label', 'map',
@@ -78,7 +78,7 @@ class HTML
             $childPad = str_repeat(' ', ($depth + 1) * self::INDENT);
             $lines    = explode("\n", $inner);
 
-            // Calcule le niveau d'indentation minimal existant (ignore les lignes vides)
+            // Compute the existing minimum indentation level (ignoring blank lines)
             $minIndent = PHP_INT_MAX;
             foreach ($lines as $line) {
                 if (trim($line) === '') continue;
@@ -86,7 +86,7 @@ class HTML
             }
             $minIndent = $minIndent === PHP_INT_MAX ? 0 : $minIndent;
 
-            // Dédente puis ré-indente au bon niveau
+            // Dedent then re-indent at the right level
             $indented = implode("\n", array_map(
                 static fn(string $line) => trim($line) !== ''
                     ? $childPad . substr($line, $minIndent)
@@ -102,11 +102,11 @@ class HTML
             return "{$pad}<{$tag}{$attrs}></{$tag}>\n";
         }
 
-        // Si tous les enfants sont inline ET que ça ressemble à un flux de texte
-        // (du vrai texte, ou un seul élément enfant), on re-sérialise en une seule ligne.
-        // Sans looksLikeTextFlow, un <section> qui contient plusieurs gros <a> côte à côte
-        // (ex: une grille de logos) se retrouverait aussi collé sur une seule ligne,
-        // puisque <a> est dans INLINE — ce n'est pas ce qu'on veut.
+        // If all children are inline AND it looks like a text flow (real text,
+        // or a single child element), re-serialize on a single line.
+        // Without looksLikeTextFlow, a <section> holding several large <a> side
+        // by side (e.g. a logo grid) would also end up crammed onto one line,
+        // since <a> is in INLINE — which is not what we want.
         if (static::hasOnlyInlineChildren($node) && static::looksLikeTextFlow($node)) {
             $inner = trim(static::renderInline($node));
             return "{$pad}<{$tag}{$attrs}>{$inner}</{$tag}>\n";
@@ -120,9 +120,9 @@ class HTML
         return "{$pad}<{$tag}{$attrs}>\n{$inner}{$pad}</{$tag}>\n";
     }
 
-    // Sérialise le contenu inline d'un nœud sur une seule ligne, en réduisant
-    // tout groupe d'espaces/tabs/retours à la ligne du texte source à une seule espace
-    // (équivalent au comportement de collapse des espaces en HTML).
+    // Serializes a node's inline content on a single line, collapsing any run
+    // of spaces/tabs/newlines in the source text to a single space (equivalent
+    // to HTML's whitespace-collapsing behavior).
     private static function renderInline(Dom\Node $node): string
     {
         $out = '';
@@ -150,9 +150,10 @@ class HTML
         return $out;
     }
 
-    // Distingue "du texte qui contient un peu d'inline" (Cliquez <a>ici</a>.) d'un
-    // conteneur qui aligne simplement plusieurs blocs inline côte à côte (grille de <a><img></a>).
-    // Vrai si : il y a du texte significatif parmi les enfants, OU un seul enfant élément.
+    // Tells "text that contains a bit of inline" (Click <a>here</a>.) apart from
+    // a container that just lines up several inline blocks side by side (a grid
+    // of <a><img></a>).
+    // True if: there is meaningful text among the children, OR a single child element.
     private static function looksLikeTextFlow(Dom\Node $node): bool
     {
         $elementCount = 0;
@@ -167,8 +168,8 @@ class HTML
         return $elementCount <= 1;
     }
 
-    // Vérifie que tous les descendants directs sont inline (texte, void inline, éléments inline)
-    // Les éléments inline eux-mêmes ne doivent pas contenir d'éléments block
+    // Checks that every direct descendant is inline (text, inline void, inline elements)
+    // The inline elements themselves must not contain block elements
     private static function hasOnlyInlineChildren(Dom\Node $node): bool
     {
         foreach ($node->childNodes as $child) {
@@ -181,7 +182,7 @@ class HTML
             if (!in_array(strtolower($child->nodeName), self::INLINE, true)) {
                 return false;
             }
-            // Récursif : l'élément inline ne doit pas contenir d'éléments block
+            // Recursive: the inline element must not contain block elements
             if (!static::hasOnlyInlineChildren($child)) {
                 return false;
             }

package/src/libraries/img.class.php

@@ -1,9 +1,26 @@
 <?php
 
+if (!defined('IMAGETYPE_AVIF')) define('IMAGETYPE_AVIF', 19);
 
 class IMG
 {
 
+	/**
+	 * Default raster size (in pixels) used for the longest side when
+	 * rasterizing vector formats (SVG, EPS, AI, PDF) via Imagick. Vector
+	 * files are resolution-independent, and GD only ever deals in pixels,
+	 * so a fallback size is needed for files that don't declare their own
+	 * explicit pixel dimensions -- otherwise the underlying delegate
+	 * library (librsvg, ghostscript...) may rasterize at a tiny default
+	 * (often 100x100). The other side is scaled to preserve the aspect
+	 * ratio reported by the file (explicit width/height, or a viewBox);
+	 * a file that does declare explicit dimensions is honored as-is.
+	 */
+	private const VECTOR_DEFAULT_SIZE = 2000;
+
+	/** File extensions treated as vector formats for VECTOR_DEFAULT_SIZE purposes. */
+	private const VECTOR_EXTENSIONS = ['svg', 'eps', 'ai', 'pdf'];
+
 	private GdImage|null $im = null;
 	private array|null $info = null;
 
@@ -13,18 +30,99 @@ class IMG
 		if (!is_file($file) || !is_readable($file)) throw new Exception("Source file unreadable.");
 
 		$this->info = @getimagesize($file);
-		if (!$this->info) throw new Exception("Invalid image file.");
 
-		[$srcW, $srcH, $type] = $this->info;
-		if ($srcW <= 0 || $srcH <= 0) throw new Exception("Invalid image file.");
+		if ($this->info) {
+			[$srcW, $srcH, $type] = $this->info;
+			if ($srcW <= 0 || $srcH <= 0) throw new Exception("Invalid image file.");
 
-		$this->im = match ($type) {
-			IMAGETYPE_JPEG => @imagecreatefromjpeg($file),
-			IMAGETYPE_PNG  => @imagecreatefrompng($file),
-			IMAGETYPE_GIF  => @imagecreatefromgif($file),
-			IMAGETYPE_WEBP => (function_exists('imagecreatefromwebp') ? @imagecreatefromwebp($file) : null),
-			default => throw new Exception("Image format not supported."),
-		};
+			$this->im = match ($type) {
+				IMAGETYPE_JPEG => @imagecreatefromjpeg($file),
+				IMAGETYPE_PNG  => @imagecreatefrompng($file),
+				IMAGETYPE_GIF  => @imagecreatefromgif($file),
+				IMAGETYPE_WEBP => (function_exists('imagecreatefromwebp') ? @imagecreatefromwebp($file) : null),
+				IMAGETYPE_AVIF => (function_exists('imagecreatefromavif') ? @imagecreatefromavif($file) : null),
+				default => null,
+			};
+		}
+
+		// Fall back to Imagick for anything GD can't handle: a type GD
+		// doesn't recognize at all, a format GD was compiled without
+		// support for, or a format getimagesize() itself can't parse
+		// (e.g. HEIC, TIFF, BMP).
+		if (!$this->im) {
+			$this->im = $this->loadFromImagick($file);
+		}
+
+		if (!$this->im) throw new Exception("Image format not supported or GD extension missing support for this format.");
+
+		// getimagesize() failed but Imagick managed to decode the file:
+		// rebuild a minimal $info from the resulting GD image so the rest
+		// of the class (which reads $this->info[2]) keeps working.
+		if (!$this->info) {
+			$this->info = [imagesx($this->im), imagesy($this->im), IMAGETYPE_PNG];
+		}
+	}
+
+
+	/**
+	 * Loads an image via Imagick and bridges it back to a GD resource.
+	 * Used as a fallback for formats GD itself cannot decode (HEIC, TIFF,
+	 * BMP, or any format missing from the compiled GD build). Imagick
+	 * converts the image to a PNG blob in memory (preserving alpha), and
+	 * GD then decodes that blob normally; nothing is written to disk.
+	 */
+	private function loadFromImagick(string $file): ?GdImage
+	{
+		if (!class_exists('Imagick')) return null;
+
+		try {
+			$imagick = new Imagick();
+
+			$ext = strtolower(pathinfo($file, PATHINFO_EXTENSION));
+			if (in_array($ext, self::VECTOR_EXTENSIONS, true)) {
+				// Vector formats have no intrinsic pixel size. Ping first
+				// to read whatever aspect ratio the file/delegate reports
+				// (an explicit width/height, or an SVG viewBox), then
+				// rasterize at VECTOR_DEFAULT_SIZE on the longest side
+				// while keeping that ratio, instead of forcing a square
+				// that could distort the image.
+				$probe = new Imagick();
+				$probe->pingImage($file);
+				$pw = $probe->getImageWidth();
+				$ph = $probe->getImageHeight();
+				$probe->clear();
+
+				if ($pw > 0 && $ph > 0) {
+					$scale = self::VECTOR_DEFAULT_SIZE / max($pw, $ph);
+					$targetW = max(1, (int) round($pw * $scale));
+					$targetH = max(1, (int) round($ph * $scale));
+				} else {
+					// Nothing usable to infer a ratio from: fall back to
+					// a square canvas.
+					$targetW = $targetH = self::VECTOR_DEFAULT_SIZE;
+				}
+
+				$imagick->setBackgroundColor(new ImagickPixel('transparent'));
+				$imagick->setSize($targetW, $targetH);
+			}
+
+			$imagick->readImage($file);
+
+			// If the source has multiple frames/pages (e.g. an animated
+			// HEIC sequence, or a multi-page PDF), keep only the first
+			// one, matching how GD would have loaded a static image.
+			if ($imagick->getNumberImages() > 1) {
+				$imagick->setIteratorIndex(0);
+			}
+			$imagick->setImageFormat('png32'); // 32-bit PNG, keeps alpha channel
+			$blob = $imagick->getImageBlob();
+			$imagick->clear();
+		} catch (\Throwable $e) {
+			return null;
+		}
+
+		$im = @imagecreatefromstring($blob);
+		return $im ?: null;
 	}
 
 
@@ -90,7 +188,7 @@ class IMG
 	private function prepare(int $x, int $y): GdImage
 	{
 		$img = imagecreatetruecolor($x, $y);
-		$hasAlpha = in_array($this->info[2], [IMAGETYPE_PNG, IMAGETYPE_WEBP, IMAGETYPE_GIF], true);
+		$hasAlpha = in_array($this->info[2], [IMAGETYPE_PNG, IMAGETYPE_WEBP, IMAGETYPE_GIF, IMAGETYPE_AVIF], true);
 		if ($hasAlpha) {
 			imagealphablending($img, false);
 			imagesavealpha($img, true);
@@ -104,19 +202,261 @@ class IMG
 	}
 
 
+	/**
+	 * Converts an sRGB color (0-255) to Lab (D65), a perceptually uniform
+	 * color space: a Euclidean distance in Lab roughly matches a color
+	 * difference as perceived by the eye, unlike RGB where two colors at
+	 * the same numeric "distance" can look very different or identical
+	 * depending on the hue.
+	 */
+	private static function rgbToLab(int $r, int $g, int $b): array
+	{
+		$toLinear = fn(float $c) => ($c /= 255) <= 0.04045 ? $c / 12.92 : (($c + 0.055) / 1.055) ** 2.4;
+		[$rl, $gl, $bl] = [$toLinear($r), $toLinear($g), $toLinear($b)];
+
+		// Linear RGB -> XYZ (D65), then normalization against the white point.
+		$x = ($rl * 0.4124564 + $gl * 0.3575761 + $bl * 0.1804375) / 0.95047;
+		$y =  $rl * 0.2126729 + $gl * 0.7151522 + $bl * 0.0721750;
+		$z = ($rl * 0.0193339 + $gl * 0.1191920 + $bl * 0.9503041) / 1.08883;
+
+		$f = fn(float $t) => $t > 0.008856 ? $t ** (1 / 3) : (7.787 * $t) + (16 / 116);
+		[$fx, $fy, $fz] = [$f($x), $f($y), $f($z)];
+
+		return [(116 * $fy) - 16, 500 * ($fx - $fy), 200 * ($fy - $fz)]; // [L, a, b]
+	}
+
+
+	/**
+	 * Extracts the most representative colors from the image.
+	 *
+	 * Algorithm: median-cut quantization (imagetruecolortopalette, the
+	 * same family of technique as Imagick::quantizeImage), heavily
+	 * over-sampling the number of requested colors, followed by
+	 * perceptual post-processing in Lab space:
+	 *  - merging colors that are too close (CIE76 distance in Lab): the
+	 *    quantization often produces several hues that look virtually
+	 *    identical to the eye, which we don't want as separate entries;
+	 *  - excluding near-pure white/black via the L lightness component
+	 *    (reliable regardless of hue, unlike a threshold on raw r/g/b).
+	 *
+	 * @param int   $numColors                Number of colors to return.
+	 * @param float $mergeTolerance           Lab distance below which two colors are merged (0-100, ~6-10 = "near identical").
+	 * @param bool  $excludeNearWhiteAndBlack Excludes near-white/near-black colors.
+	 * @param float $lightnessThreshold       Lab lightness threshold (0-100) above/below which a color is considered near-white/near-black.
+	 * @return string[] Colors as "#rrggbb", sorted by descending frequency.
+	 */
+	public function getRepresentativeColors(
+		int $numColors = 5,
+		float $mergeTolerance = 8.0,
+		bool $excludeNearWhiteAndBlack = true,
+		float $lightnessThreshold = 8.0
+	): array {
+		$srcW = $this->width;
+		$srcH = $this->height;
+
+		// Analyzing at full resolution brings nothing for this kind of
+		// extraction and is expensive in compute time.
+		$maxDim = 150;
+		$scale = min(1, $maxDim / max($srcW, $srcH));
+		$w = max(1, (int) round($srcW * $scale));
+		$h = max(1, (int) round($srcH * $scale));
+
+		// Flatten onto a white background (as for JPEG export): otherwise
+		// the transparent areas of PNG/WEBP images would default to being
+		// counted as black on a truecolor canvas.
+		$sample = imagecreatetruecolor($w, $h);
+		imagealphablending($sample, true);
+		$white = imagecolorallocate($sample, 255, 255, 255);
+		imagefilledrectangle($sample, 0, 0, $w, $h, $white);
+		imagecopyresampled($sample, $this->im, 0, 0, 0, 0, $w, $h, $srcW, $srcH);
+
+		// We heavily over-sample the number of requested colors: this
+		// leaves enough room for the perceptual merge and the white/black
+		// exclusion below without running short of colors.
+		$buckets = max($numColors * 6, 24);
+		imagetruecolortopalette($sample, false, $buckets);
+
+		// Count occurrences of each color in the generated palette.
+		$counts = array_fill(0, imagecolorstotal($sample), 0);
+		for ($y = 0; $y < $h; $y++) {
+			for ($x = 0; $x < $w; $x++) {
+				$counts[imagecolorat($sample, $x, $y)]++;
+			}
+		}
+
+		$entries = [];
+		foreach ($counts as $index => $count) {
+			if ($count === 0) continue;
+			$rgb = imagecolorsforindex($sample, $index);
+			$lab = self::rgbToLab($rgb['red'], $rgb['green'], $rgb['blue']);
+
+			if ($excludeNearWhiteAndBlack && ($lab[0] > 100 - $lightnessThreshold || $lab[0] < $lightnessThreshold)) {
+				continue;
+			}
+
+			$entries[] = ['r' => $rgb['red'], 'g' => $rgb['green'], 'b' => $rgb['blue'], 'lab' => $lab, 'count' => $count];
+		}
+
+		usort($entries, fn($a, $b) => $b['count'] - $a['count']);
+
+		// Merge perceptually close colors by grouping their occurrences,
+		// always starting from the most frequent one.
+		$merged = [];
+		foreach ($entries as $entry) {
+			foreach ($merged as &$cluster) {
+				$dl = $cluster['lab'][0] - $entry['lab'][0];
+				$da = $cluster['lab'][1] - $entry['lab'][1];
+				$db = $cluster['lab'][2] - $entry['lab'][2];
+				if (sqrt($dl * $dl + $da * $da + $db * $db) <= $mergeTolerance) {
+					$cluster['count'] += $entry['count'];
+					continue 2;
+				}
+			}
+			unset($cluster);
+			$merged[] = $entry;
+		}
+
+		usort($merged, fn($a, $b) => $b['count'] - $a['count']);
+
+		return array_map(
+			fn($c) => sprintf('#%02x%02x%02x', $c['r'], $c['g'], $c['b']),
+			array_slice($merged, 0, $numColors)
+		);
+	}
+
+
+	/**
+	 * The AVIF encoder (libavif/aom) used by imageavif() can fail with
+	 * "Encoding of color planes failed" in two common cases:
+	 *  - odd width/height (4:2:0 chroma subsampling constraint)
+	 *  - image too large, causing the encoder to run out of memory for
+	 *    its internal buffers ("aom_codec_encode: Failed to allocate lag buffers")
+	 * We fix both before encoding, on a temporary copy, without modifying
+	 * $this->im.
+	 */
+	private function prepareForAvif(GdImage $im, int $maxDimension = 4000): GdImage
+	{
+		$w = imagesx($im);
+		$h = imagesy($im);
+
+		// Cap the resolution if needed (encoder memory protection).
+		if ($w > $maxDimension || $h > $maxDimension) {
+			$scale = min($maxDimension / $w, $maxDimension / $h);
+			$newW = max(1, (int) round($w * $scale));
+			$newH = max(1, (int) round($h * $scale));
+			$resized = imagecreatetruecolor($newW, $newH);
+			imagealphablending($resized, false);
+			imagesavealpha($resized, true);
+			$transparent = imagecolorallocatealpha($resized, 0, 0, 0, 127);
+			imagefilledrectangle($resized, 0, 0, $newW, $newH, $transparent);
+			imagecopyresampled($resized, $im, 0, 0, 0, 0, $newW, $newH, $w, $h);
+			$im = $resized;
+			$w = $newW;
+			$h = $newH;
+		}
+
+		// Force even dimensions.
+		$w2 = $w % 2 ? $w + 1 : $w;
+		$h2 = $h % 2 ? $h + 1 : $h;
+		if ($w2 !== $w || $h2 !== $h) {
+			$padded = imagecreatetruecolor($w2, $h2);
+			imagealphablending($padded, false);
+			imagesavealpha($padded, true);
+			$transparent = imagecolorallocatealpha($padded, 0, 0, 0, 127);
+			imagefilledrectangle($padded, 0, 0, $w2, $h2, $transparent);
+			imagecopy($padded, $im, 0, 0, 0, 0, $w, $h);
+			$im = $padded;
+		}
+
+		return $im;
+	}
+
+
+	/**
+	 * Encodes to AVIF with automatic fallback: if encoding fails (memory
+	 * error or another internal aom issue), retry with a higher speed
+	 * (less memory-hungry), then with a reduced resolution. Throws an
+	 * explicit exception if everything fails, instead of letting a silent
+	 * PHP warning through and leaving a corrupted/missing file behind.
+	 */
+	private function encodeAvif(GdImage $im, string $dest, int $quality = 82): bool
+	{
+		$attempts = [
+			['maxDimension' => 4000, 'speed' => 4],
+			['maxDimension' => 4000, 'speed' => 8],
+			['maxDimension' => 2000, 'speed' => 8],
+		];
+
+		foreach ($attempts as $attempt) {
+			$prepared = $this->prepareForAvif($im, $attempt['maxDimension']);
+			$ok = @imageavif($prepared, $dest, $quality, $attempt['speed']);
+			if ($ok && is_file($dest) && filesize($dest) > 0) return true;
+		}
+
+		return false;
+	}
+
+
 	public function save(string $dest): self
 	{
 		$ext = strtolower(pathinfo($dest, PATHINFO_EXTENSION));
 		$dir = pathinfo($dest, PATHINFO_DIRNAME);
 		if (!is_dir($dir) && !@mkdir($dir, 0777, true)) throw new Exception("Invalid destination.");
-		match ($ext) {
-			'jpg', 'jpeg' => imagejpeg($this->im, $dest, 85),
+		$ok = match ($ext) {
+			'jpg', 'jpeg' => imagejpeg($this->im, $dest, 82),
 			'png'         => imagepng($this->im, $dest, 6),
 			'gif'         => imagegif($this->im, $dest),
-			'webp'        => (function_exists('imagewebp') ? imagewebp($this->im, $dest, 85) : false),
+			'webp'        => (function_exists('imagewebp') ? imagewebp($this->im, $dest, 82) : false),
+			'avif'        => (function_exists('imageavif') ? $this->encodeAvif($this->im, $dest, 82) : false),
 			default       => throw new Exception("Invalid output file type.")
 		};
-		// PREPROS::exportFile(realpath($dest));
+		if (!$ok) throw new Exception("Failed to encode image as '{$ext}'.");
+		PREPROS::exportFile(realpath($dest));
 		return $this;
 	}
-}
+
+
+	public static function asset(string $path, $width = 0, $height = 0, $cover = false, $backtrace = '')
+	{
+		$srcfile = FS::pathJoin(PREPROS::$config->image->source, $path);
+		if(!$srcinfo = PREPROS::fstat($srcfile)) throw new Exception("Invalid image file.");
+
+		$suffix = '';
+		if ($width && $height) $suffix = $cover ? '-' . $width . 'x' . $height . '-cover' : '-' . $width . 'x' . $height;
+		elseif ($width) $suffix = '-' . $width . 'w';
+		elseif ($height) $suffix = '-' . $height . 'h';
+		$destname = preg_replace('/\.[a-z]{2,4}+$/i', '', $path) . $suffix . '.' . PREPROS::$config->image->format;
+		$destfile = FS::pathJoin(PREPROS::$config->data->root, PREPROS::$config->image->dest, $destname);
+		$destinfo = PREPROS::fstat($destfile);
+
+		if(!$destinfo || ((strtotime($srcinfo->modifiedAt) - strtotime($destinfo->modifiedAt)) > 10)) {
+			if(!$localfile = current(PREPROS::mount($srcfile))) throw new Exception("Can't mount image.");
+			if(!is_file($localfile)) throw new Exception("Can't mount image.");
+			$img = new self($localfile);
+			if ($width && $height) $img->resize($width, $height, $cover);
+			elseif ($width) $img->resize($width);
+			elseif ($height) $img->resize((int) round($img->width * $height / $img->height), $height);
+			$img->save(FS::pathJoin('/project', $destfile));
+		}
+
+		if(!$backtrace) $backtrace = PREPROS::backtraceFile();
+		return FS::getRelativePath($backtrace, FS::pathJoin('/project', $destfile));
+	}
+
+
+	public static function palette(string $path, $colors = 5)
+	{
+		$srcfile = FS::pathJoin(PREPROS::$config->image->source, $path);
+		if(!$srcinfo = PREPROS::fstat($srcfile)) throw new Exception("Invalid image file.");
+		$key = 'palette_' . STR::shorthash("{$srcfile}:{$srcinfo->modifiedAt}:{$colors}");
+		if($palette = CACHE::get($key)) return $palette;
+		if(!$localfile = current(PREPROS::mount($srcfile))) throw new Exception("Can't mount image.");
+		if(!$palette = (new self($localfile))->getRepresentativeColors($colors)) throw new Exception("Can't extract palette from image \"{$path}\".");
+		CACHE::set($key, $palette);
+		return $palette;
+	}
+
+
+
+
+}