@kirigami/php-prepros 3.0.0 → 3.1.0

package/README.md

@@ -34,6 +34,7 @@ Part of the **Kirigami** project ecosystem.
 
 - [@kirigami/php-prepros](#kirigamiphp-prepros)
 - [Overview](#overview)
+- [What's new in 3.0.1](#whats-new-in-301)
 - [What's new in 3.0.0](#whats-new-in-300)
 - [What's new in 2.0.0](#whats-new-in-200)
 - [What's new in 1.9.3](#whats-new-in-193)
@@ -105,6 +106,12 @@ Part of the **Kirigami** project ecosystem.
 
 ---
 
+## What's new in 3.0.1
+
+A registered tag written inside Markdown code is no longer processed. `<markdown>`, `<img asset="...">` or a plugin tag shown in an inline code span (`` `<markdown prose>` ``) or a fenced block (` ``` ` / `~~~`) stays example text: before, a `<markdown>` in a code span paired with the real block's closing tag and broke the rest of the page, and an `<img asset>` in one became an empty image. Indented (four-space) code blocks are not recognized, since `<markdown>` bodies are indented; use a fence there.
+
+---
+
 ## What's new in 3.0.0
 
 This release switches `YAML::` to the native YAML extension, `MD::` to native mdhtml, `SCHEMA` to native jsonk, and `Normalizer` to native norm. It also includes page types and request lifecycle hooks.
@@ -1514,11 +1521,12 @@ $img->height  // int
 // Instance methods (resize/save are chainable)
 $img->resize(int $width, int $height = 0, bool $cover = false): self
 $img->save(string $dest, ?int $quality = null): self       // quality 0-100 for jpg/webp/avif; null = per-format default (82)
-$img->getRepresentativeColors(int $count = 5): string[]   // ['#rrggbb', …]
+$img->getRepresentativeColors(int $count = 5): string[]   // ['#rrggbb', …], median-cut + Lab merge
+$img->getAuraColors(int $count = 5): string[]             // ['#rrggbb', …], up to 6, via the Aura extension
 
 // Static helpers
 IMG::asset(string $path, int $width = 0, int $height = 0, bool $cover = false): string  // same feature as the <img asset> tag and the img-asset() Sass function
-IMG::palette(string $path, int $colors = 5): string[]
+IMG::palette(string $path, int $colors = 5): string[]      // Aura-backed: at most 6 colours
 ```
 
 `resize()` operates in *contain* mode by default (scales to fit within the target box while preserving aspect ratio). Pass `$cover = true` to crop and fill the exact target dimensions.
@@ -1536,7 +1544,10 @@ IMG::palette(string $path, int $colors = 5): string[]
 and `colors()` Sass functions: they resolve `$path` against `image.source` from
 `kirigami.yaml`, generate a resized/re-encoded file under `image.dest` (only
 when missing or stale), or return a `CACHE`-backed list of representative
-colours. Both are equally usable from your own PHP.
+colours. `IMG::palette()` extracts them with the Aura extension (vibrant and
+muted swatches, each in a dark and a light variant), so it returns at most six
+colours, most populated first; asking for more returns what Aura found. Both
+are equally usable from your own PHP.
 
 `IMG::asset()` is the single implementation behind the [`<img asset>` tag](#built-in-tags)
 too — the tag is just a thin wrapper. Generated files are named after the source
@@ -1602,7 +1613,7 @@ STR::normalize(string $str): string
 STR::slug(string $str, string $sep = ''): string
 ```
 
-`STR::replaceTags()` is the engine behind `PREPROS::registerTag()`. It finds all occurrences of `<tagname ...>...</tagname>` in an HTML string and replaces each with the return value of `$callback($fullMatch, $attrs, $body)`.
+`STR::replaceTags()` is the engine behind `PREPROS::registerTag()`. It finds all occurrences of `<tagname ...>...</tagname>` in an HTML string and replaces each with the return value of `$callback($fullMatch, $attrs, $body)`. Occurrences inside Markdown code (an inline code span or a fenced block) are left as written, so a tag shown as an example is not run.
 
 `STR::trimIndent()` strips the common leading whitespace from a multi-line string — handy when pulling content out of indented `<markdown>` blocks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",

package/src/libraries/img.class.php

@@ -332,6 +332,62 @@ class IMG
 	}
 
 
+	/**
+	 * Extracts a color palette with Aura (the static `aura` extension), which
+	 * picks up to six named swatches (vibrant, muted, each in a dark and a
+	 * light variant) instead of clustering N arbitrary colors.
+	 *
+	 * Swatches Aura had to fake (`was_ineligible`) are dropped, then colors
+	 * are ordered by descending population and deduplicated.
+	 *
+	 * @param int $numColors Number of colors to return (at most 6).
+	 * @return string[] Colors as "#rrggbb".
+	 */
+	public function getAuraColors(int $numColors = 5): array
+	{
+		if (!class_exists('Aura\Palette')) throw new Exception("The aura extension is not available.");
+
+		// Aura reads raw RGBA bytes. A small sample is plenty to find the
+		// dominant colors, and keeps the PHP pixel loop cheap.
+		$srcW = $this->width;
+		$srcH = $this->height;
+		$scale = min(1, 150 / max($srcW, $srcH));
+		$w = max(1, (int) round($srcW * $scale));
+		$h = max(1, (int) round($srcH * $scale));
+
+		$sample = imagecreatetruecolor($w, $h);
+		imagealphablending($sample, false);
+		imagesavealpha($sample, true);
+		imagefill($sample, 0, 0, imagecolorallocatealpha($sample, 0, 0, 0, 127));
+		imagecopyresampled($sample, $this->im, 0, 0, 0, 0, $w, $h, $srcW, $srcH);
+
+		$rgba = '';
+		for ($y = 0; $y < $h; $y++) {
+			for ($x = 0; $x < $w; $x++) {
+				$c = imagecolorat($sample, $x, $y);
+				$alpha = 255 - (($c >> 24) & 127) * 2; // GD alpha is 0 (opaque) to 127
+				$rgba .= chr(($c >> 16) & 255) . chr(($c >> 8) & 255) . chr($c & 255) . chr(min(255, $alpha));
+			}
+		}
+
+		$palette = \Aura\Palette::generate($rgba);
+
+		$swatches = [];
+		foreach (['vibrant', 'vibrant_dark', 'vibrant_light', 'muted', 'muted_dark', 'muted_light'] as $name) {
+			$swatch = $palette->$name;
+			if ($swatch && !$swatch->was_ineligible) $swatches[] = $swatch;
+		}
+		usort($swatches, fn($a, $b) => $b->population <=> $a->population);
+
+		$colors = [];
+		foreach ($swatches as $swatch) {
+			$colors[] = sprintf('#%02x%02x%02x', $swatch->color->r, $swatch->color->g, $swatch->color->b);
+		}
+
+		return array_slice(array_values(array_unique($colors)), 0, $numColors);
+	}
+
+
 	/**
 	 * The AVIF encoder (libavif/aom) used by imageavif() can fail with
 	 * "Encoding of color planes failed" in two common cases:
@@ -463,10 +519,10 @@ class IMG
 	{
 		$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}");
+		$key = 'aura_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}\".");
+		if(!$palette = (new self($localfile))->getAuraColors($colors)) throw new Exception("Can't extract palette from image \"{$path}\".");
 		CACHE::set($key, $palette);
 		return $palette;
 	}

package/src/libraries/str.class.php

@@ -18,7 +18,27 @@ class STR
 			. '|<' . $t . '([^>]*)/>'
 			. '|<' . $t . '([^>]*)>#msi';
 
-		return preg_replace_callback($pattern, function ($m) use ($clb) {
+		// A tag written inside Markdown code (a fenced block or an inline
+		// code span) is example text, not a tag: `<markdown>` shown in a
+		// code span must not close the real block around it, and
+		// `<img asset="...">` shown in one must not become an image. Mask
+		// that code before matching and put it back afterwards, both in the
+		// output and in what the callback receives.
+		$code = [];
+		if (!str_contains($contents, "\x1A")) $contents = preg_replace_callback(
+			'#^[ \t]*(`{3,}|~{3,})[^\n]*\n.*?^[ \t]*\1[ \t]*$'
+			. '|(?<!`)(`+)(?!`)[^\n]*?(?<!`)\2(?!`)#ms',
+			function ($m) use (&$code) {
+				$code[] = $m[0];
+				return "\x1A" . (count($code) - 1) . "\x1A";
+			},
+			$contents
+		);
+		$restore = fn(?string $s) => $s === null || !$code ? $s
+			: preg_replace_callback("#\x1A(\d+)\x1A#", fn($m) => $code[$m[1]], $s);
+
+		$result = preg_replace_callback($pattern, function ($m) use ($clb, $restore) {
+			$m = array_map($restore, $m);
 			if (isset($m[1]) || isset($m[2])) {
 				// paired form: <tag>content</tag>
 				$attrs = $m[1] ?? '';
@@ -34,6 +54,8 @@ class STR
 			}
 			return call_user_func($clb, $m[0], self::parseHtmlAttributes($attrs), $inner);
 		}, $contents, -1, $count, PREG_UNMATCHED_AS_NULL); // <-- the flag that fixes everything
+
+		return $restore($result);
 	}