@kirigami/php-prepros 1.2.0 → 1.6.1

package/src/libraries/curl.class.php

@@ -7,18 +7,30 @@ if(!boolval(PREPROS::$config->network ?? false)) STD::error("CURL Error: Network
 
 class CURL {
 
+	// Mimics a Google Chrome (stable) browser on Windows 11, desktop, requesting
+	// a top-level document. Windows 11 still reports "Windows NT 10.0" in the UA
+	// string; the real version is only exposed through the Sec-CH-UA-Platform-Version
+	// client hint ("15.0.0"). Accept advertises every image format modern Chrome
+	// supports, AVIF included.
 	const HEADERS = [
-		'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36',
-		'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9',
+		'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+		'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7',
 		'Accept-Language: fr-CA,fr;q=0.9,en-US;q=0.8,en;q=0.7',
-		'Sec-Ch-Ua: "Not_A Brand";v="99", "Google Chrome";v="109", "Chromium";v="109"',
+		// Accept-Encoding is intentionally left to CURLOPT_ENCODING so curl only
+		// advertises what it can actually transparently decode.
+		'Sec-Ch-Ua: "Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
 		'Sec-Ch-Ua-Mobile: ?0',
 		'Sec-Ch-Ua-Platform: "Windows"',
+		'Sec-Ch-Ua-Platform-Version: "15.0.0"',
+		'Sec-Ch-Ua-Arch: "x86"',
+		'Sec-Ch-Ua-Bitness: "64"',
+		'Sec-Ch-Ua-Full-Version-List: "Google Chrome";v="131.0.6778.86", "Chromium";v="131.0.6778.86", "Not_A Brand";v="24.0.0.0"',
 		'Sec-Fetch-Dest: document',
 		'Sec-Fetch-Mode: navigate',
 		'Sec-Fetch-Site: none',
 		'Sec-Fetch-User: ?1',
 		'Upgrade-Insecure-Requests: 1',
+		'Priority: u=0, i',
 	];
 
     

package/src/libraries/fs.class.php

@@ -48,6 +48,126 @@ class FS
 	}
 
 
+	/**
+	 * Lists the immediate child pages of the calling template.
+	 *
+	 * Scans the directories directly below the folder of the file that
+	 * called this function, keeps the ones that hold an `_index.php`, parses
+	 * that file's first PHPDOC block via {@see FS::phpFileInfo()} and returns
+	 * the pages ordered by `@position` ascending (a missing `@position`
+	 * counts as 999999), then by folder name.
+	 *
+	 * Only usable while a render is in progress (`PREPROS::$file` set).
+	 *
+	 * @param  string $anchor Path whose folder is scanned; defaults to the page
+	 *                         currently being rendered (`PREPROS::$file`), so it
+	 *                         works the same called straight from a template, from
+	 *                         a layout partial, or from a helper function.
+	 * @return object[]         One `stdClass` per child: the parsed PHPDOC
+	 *                          of its `_index.php`, plus a `->file` key
+	 *                          holding that file's absolute path.
+	 * @throws \Exception       When called outside of a render.
+	 */
+	public static function getChildren(string $anchor = ''): array
+	{
+		if (PREPROS::$file === '') throw new Exception('FS::getChildren() can only be called during a render.');
+		if (!$anchor) $anchor = PREPROS::$file;
+		if (!$anchor || !$dir = realpath(pathinfo($anchor, PATHINFO_DIRNAME))) return [];
+
+		$children = [];
+		foreach (glob($dir . '/*', GLOB_ONLYDIR) as $subdir) {
+			$index = $subdir . '/_index.php';
+			if (!is_file($index)) continue;
+			$info = FS::phpFileInfo($index) ?: new stdClass;
+			$info = clone $info;
+			$info->file = realpath($index);
+			$position = (isset($info->position) && is_numeric($info->position)) ? (int) $info->position : 999999;
+			$children[] = ['position' => $position, 'name' => pathinfo($subdir, PATHINFO_BASENAME), 'info' => $info];
+		}
+
+		usort($children, fn($a, $b) => ($a['position'] <=> $b['position']) ?: strnatcasecmp($a['name'], $b['name']));
+
+		return array_column($children, 'info');
+	}
+
+
+	/**
+	 * Builds the breadcrumb trail of the calling page.
+	 *
+	 * Only runs when the calling file opts in with `@breadcrumb true` (or
+	 * `@breadcrumb 1`) in its first PHPDOC block; otherwise returns `[]`.
+	 *
+	 * Starting from the folder *above* the caller's own folder (the current
+	 * page is never part of its own trail), it walks the parent directories
+	 * upward, collecting the `_index.php` of each one via
+	 * {@see FS::phpFileInfo()}. The walk stops at the source root, or at the
+	 * first ancestor `_index.php` that does not carry an active `@breadcrumb`
+	 * tag — that page is a pure separator and is left out of the result.
+	 * Directories with no `_index.php` are skipped without breaking the chain.
+	 *
+	 * Only usable while a render is in progress (`PREPROS::$file` set).
+	 *
+	 * @param  string $anchor Path the trail is walked from; defaults to the page
+	 *                         currently being rendered (`PREPROS::$file`), so it
+	 *                         works the same called straight from a template, from
+	 *                         a layout partial, or from a helper function.
+	 * @return object[]         One `stdClass` per ancestor page, ordered from
+	 *                          the top-most ancestor down to the nearest
+	 *                          parent: the parsed PHPDOC of its `_index.php`,
+	 *                          plus a `->file` key holding that file's
+	 *                          absolute path.
+	 * @throws \Exception       When called outside of a render.
+	 */
+	public static function getBreadcrumb(string $anchor = ''): array
+	{
+		if (PREPROS::$file === '') throw new Exception('FS::getBreadcrumb() can only be called during a render.');
+		if (!$anchor) $anchor = PREPROS::$file;
+		if (!$anchor || !$dir = realpath(pathinfo($anchor, PATHINFO_DIRNAME))) return [];
+
+		$self = FS::phpFileInfo($anchor) ?: new stdClass;
+		if (!self::truthy($self->breadcrumb ?? null)) return [];
+
+		if (!$root = realpath(PREPROS::$config->root)) return [];
+		$root = rtrim(str_replace('\\', '/', $root), '/');
+		$dir  = rtrim(str_replace('\\', '/', $dir), '/');
+
+		$trail = [];
+		while (true) {
+			$parent = str_replace('\\', '/', dirname($dir));
+			if ($parent === $dir) break;                                      // filesystem root
+			$dir = $parent;
+			if (strncmp($dir . '/', $root . '/', strlen($root) + 1) !== 0) break; // above the source root
+
+			$index = $dir . '/_index.php';
+			if (is_file($index)) {
+				$info = FS::phpFileInfo($index) ?: new stdClass;
+				if (!self::truthy($info->breadcrumb ?? null)) break;          // separator page: stop, exclude it
+				$info = clone $info;
+				$info->file = realpath($index);
+				$trail[] = $info;
+			}
+
+			if ($dir === $root) break;
+		}
+
+		return array_reverse($trail);
+	}
+
+
+	/**
+	 * Loose truthiness test for a PHPDOC tag value (`true` / `1` / `yes` /
+	 * `on`, case-insensitive). PHPDOC values always come through as strings,
+	 * but bool/int are handled too for callers that pass a raw value.
+	 */
+	private static function truthy(mixed $v): bool
+	{
+		if (is_bool($v)) return $v;
+		if (is_int($v))  return $v === 1;
+		if (!is_string($v)) return false;
+		return in_array(strtolower(trim($v)), ['1', 'true', 'yes', 'on'], true);
+	}
+
+
 	public static function phpFileInfo(string $file): object|bool
 	{
 		static $files = [];
@@ -62,17 +182,52 @@ class FS
 				}
 			}
 			if (empty($block)) return new stdClass;
-			if (!preg_match_all('#@([a-z0-9]+)[\s\t]+([^\n]+)#msi', $block, $m)) $files[$file] = new stdClass;
-			else {
-				$info = [];
-				foreach ($m[1] as $k => $v) $info[trim($v)] = trim($m[2][$k]);
-				$files[$file] = (object)$info;
-			}
+			$files[$file] = (object) self::parseDocBlock($block);
 		}
 		return $files[$file];
 	}
 
 
+	/**
+	 * Parses the `@tag value` lines of a PHPDOC block into a `tag => value` map.
+	 *
+	 * Only lines whose first non-whitespace character (past an optional `*`
+	 * gutter) is an `@` start a tag — so an `@word` dropped mid-sentence in the
+	 * block's prose is ignored and can't clobber a real tag. A tag's value may
+	 * wrap onto the following *indented* (hanging-indent) continuation lines,
+	 * up to the next `@tag`, a blank line, a flush-left prose line, or the end
+	 * of the block; continuation lines are joined with a single space.
+	 *
+	 * @param  string $block Raw `/** … *&#47;` doc-comment text.
+	 * @return array<string,string>
+	 */
+	private static function parseDocBlock(string $block): array
+	{
+		$info    = [];
+		$current = null;
+
+		foreach (preg_split('/\r\n|\r|\n/', $block) as $line) {
+			// Drop the opening `/**`, a ` * ` gutter, and the closing ` */`.
+			$line = preg_replace('#^\s*/\*\*+#', '', $line);
+			$line = preg_replace('#\s*\*/\s*$#', '', $line);
+			$line = preg_replace('#^[ \t]*\*[ \t]?#', '', $line, 1);
+
+			if (preg_match('/^[ \t]*@([A-Za-z0-9_]+)[ \t]*(.*)$/', $line, $m)) {
+				$current = trim($m[1]);
+				$info[$current] = trim($m[2]);
+			} elseif (trim($line) === '') {
+				$current = null;                                   // blank line ends a value
+			} elseif ($current !== null && preg_match('/^[ \t]/', $line)) {
+				$info[$current] = trim($info[$current] . ' ' . trim($line));   // hanging indent → continuation
+			} else {
+				$current = null;                                   // flush-left prose ends a value
+			}
+		}
+
+		return $info;
+	}
+
+
 	public static function rmdir(string $dir, bool $removeSelf = true): bool
 	{
 		if (!file_exists($dir)) return true;

package/src/libraries/html.class.php

@@ -28,21 +28,35 @@ class HTML
     ];
 
     private const RAW  = ['script', 'style'];
+    // Whitespace-significant elements: their text content is emitted byte for
+    // byte, never re-indented or collapsed (a code block must keep its line
+    // breaks and leading spaces; a <textarea> its exact value).
+    private const VERBATIM = ['pre', 'textarea'];
     private const VOID = [
         'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
         'link', 'meta', 'source', 'track', 'wbr',
     ];
 
+    /** Verbatim blocks stashed during a format() run, keyed by placeholder. */
+    private static array $verbatim = [];
+
     public static function format(string $html): string
     {
         $dom = Dom\HTMLDocument::createFromString($html, LIBXML_NOERROR);
 
+        self::$verbatim = [];
         $output = '';
         foreach ($dom->childNodes as $node) {
             $output .= static::renderNode($node, 0);
         }
 
+        // Collapse runs of blank lines — but not inside <pre>/<textarea>, whose
+        // content was swapped out for a placeholder above.
         $output = preg_replace('/\n{3,}/', "\n\n", $output);
+        if (self::$verbatim) {
+            $output = strtr($output, self::$verbatim);
+            self::$verbatim = [];
+        }
 
         return rtrim($output) . "\n";
     }
@@ -69,6 +83,44 @@ class HTML
             return "{$pad}<{$tag}{$attrs}>\n";
         }
 
+        // `<pre><code>` (a fenced code block): re-indent the code to this
+        // element's depth so the HTML source stays readable. The exact leading
+        // run added here is stripped again before display — at build time by
+        // @kirigami/plugin-highlight, otherwise by the small de-indent script
+        // Kirigami injects (prepros.head). Relative indentation is preserved.
+        if ($tag === 'pre') {
+            $code = self::soleCodeChild($node);
+            if ($code !== null) {
+                $childPad = str_repeat(' ', ($depth + 1) * self::INDENT);
+                $lines    = explode("\n", $code->innerHTML);
+
+                $min = PHP_INT_MAX;
+                foreach ($lines as $line) {
+                    if (trim($line) === '') continue;
+                    $min = min($min, strlen($line) - strlen(ltrim($line, ' ')));
+                }
+                $min = $min === PHP_INT_MAX ? 0 : $min;
+
+                $body = implode("\n", array_map(
+                    static fn(string $line) => trim($line) === '' ? '' : $childPad . substr($line, $min),
+                    $lines
+                ));
+                $token = "\x01VERB" . count(self::$verbatim) . "\x01";
+                self::$verbatim[$token] = "\n" . rtrim($body, "\n") . "\n{$pad}";
+                return "{$pad}<pre><code" . static::renderAttrs($code) . ">{$token}</code></pre>\n";
+            }
+        }
+
+        // Whitespace-significant: emit the inner HTML exactly as parsed, so a
+        // bare <pre>/<textarea> keeps its line breaks and indentation. Only the
+        // opening tag is padded to the current depth.
+        if (in_array($tag, self::VERBATIM, true)) {
+            /** @var DOMElement $node */
+            $token = "\x01VERB" . count(self::$verbatim) . "\x01";
+            self::$verbatim[$token] = $node->innerHTML;
+            return "{$pad}<{$tag}{$attrs}>" . $token . "</{$tag}>\n";
+        }
+
         if ($isRaw) {
             /** @var DOMElement $node */
             $inner = trim($node->innerHTML, "\n\r");
@@ -190,6 +242,23 @@ class HTML
         return true;
     }
 
+    // The lone <code> child of a <pre> (a fenced code block), or null when the
+    // <pre> holds anything else — raw text, several elements, markup to keep.
+    private static function soleCodeChild(Dom\Node $node): ?Dom\Node
+    {
+        $code = null;
+        foreach ($node->childNodes as $child) {
+            if ($child->nodeType === XML_TEXT_NODE) {
+                if (trim($child->nodeValue) !== '') return null;
+                continue;
+            }
+            if ($code !== null || $child->nodeType !== XML_ELEMENT_NODE) return null;
+            if (strtolower($child->nodeName) !== 'code') return null;
+            $code = $child;
+        }
+        return $code;
+    }
+
     private static function renderText(Dom\Node $node, int $depth): string
     {
         $text = trim($node->nodeValue);

package/src/libraries/img.class.php

@@ -147,6 +147,13 @@ class IMG
 
 	public function resize(int $width, int $height = 0, bool $cover = false)
 	{
+		// Never upscale. The AVIF encoder (and, less visibly, the others) can
+		// choke on an enlarged raster, and blowing pixels up gains nothing —
+		// so a target larger than the source is clamped down to it rather than
+		// throwing an opaque encode error. Ask for sizes <= the source.
+		if ($width  > $this->width)  $width  = $this->width;
+		if ($height > $this->height) $height = $this->height;
+
 		$srcRatio = $this->width / $this->height;
 
 		if (!$height) {
@@ -397,17 +404,25 @@ class IMG
 	}
 
 
-	public function save(string $dest): self
+	/**
+	 * Encodes the current image to $dest, the format taken from the file
+	 * extension (jpg/jpeg, png, gif, webp, avif).
+	 *
+	 * $quality (0-100) applies to the lossy formats (jpg, webp, avif); it is
+	 * ignored for png (whose second arg is a 0-9 compression level) and gif.
+	 * When null, each format keeps its own default (82 for jpg/webp/avif).
+	 */
+	public function save(string $dest, ?int $quality = null): 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.");
 		$ok = match ($ext) {
-			'jpg', 'jpeg' => imagejpeg($this->im, $dest, 82),
+			'jpg', 'jpeg' => imagejpeg($this->im, $dest, $quality ?? 82),
 			'png'         => imagepng($this->im, $dest, 6),
 			'gif'         => imagegif($this->im, $dest),
-			'webp'        => (function_exists('imagewebp') ? imagewebp($this->im, $dest, 82) : false),
-			'avif'        => (function_exists('imageavif') ? $this->encodeAvif($this->im, $dest, 82) : false),
+			'webp'        => (function_exists('imagewebp') ? imagewebp($this->im, $dest, $quality ?? 82) : false),
+			'avif'        => (function_exists('imageavif') ? $this->encodeAvif($this->im, $dest, $quality ?? 82) : false),
 			default       => throw new Exception("Invalid output file type.")
 		};
 		if (!$ok) throw new Exception("Failed to encode image as '{$ext}'.");