@kirigami/php-prepros 1.0.1 → 1.0.4

package/README.md

@@ -53,6 +53,7 @@ Part of the **Kirigami** project ecosystem. Other packages are coming soon.
 
 ---
 
+
 ## How it works
 
 `@kirigami/php-prepros` runs your PHP source files inside a **WebAssembly PHP 8.x runtime** ([`@kirigami/php-wasm`](https://github.com/kirigami/php-wasm)), entirely in Node.js — no PHP installation required on the host machine.
@@ -114,6 +115,9 @@ Source pages live in the directory pointed to by `kirigami.root`. The naming con
 
 ```
 src/
+├── _layout/
+├── _lib/
+├── about/
 ├── _index.php          →  src/index.html
 ├── about/
 │   └── _index.php      →  src/about/index.html

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",
@@ -44,14 +44,14 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@kirigami/php-wasm": "8.5.7-1",
-    "js-yaml": "^4.2.0"
+    "@kirigami/php-wasm": "8.5.9-1",
+    "@kirigami/struct-walker": "1.0.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/php-kirigami/kirigami"
+    "url": "git+https://github.com/php-kirigami/kirigami.git"
   },
-  "homepage": "https://github.com/php-kirigami/kirigami/#readme",
+  "homepage": "https://github.com/php-kirigami/kirigami/tree/main/packages/php-prepros#readme",
   "bugs": {
     "url": "https://github.com/php-kirigami/kirigami/issues"
   }

package/src/libraries/html.class.php

@@ -101,9 +101,13 @@ class HTML
             return "{$pad}<{$tag}{$attrs}></{$tag}>\n";
         }
 
-        // Si tous les enfants sont inline, on utilise innerHTML tel quel — pas de reconstruction
-        if (static::hasOnlyInlineChildren($node)) {
-            $inner = trim($node->innerHTML);
+        // 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 (static::hasOnlyInlineChildren($node) && static::looksLikeTextFlow($node)) {
+            $inner = trim(static::renderInline($node));
             return "{$pad}<{$tag}{$attrs}>{$inner}</{$tag}>\n";
         }
 
@@ -115,6 +119,53 @@ 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).
+    private static function renderInline(Dom\Node $node): string
+    {
+        $out = '';
+        foreach ($node->childNodes as $child) {
+            if ($child->nodeType === XML_TEXT_NODE) {
+                $text = preg_replace('/\s+/', ' ', $child->nodeValue);
+                $out .= htmlspecialchars($text, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+                continue;
+            }
+            if ($child->nodeType === XML_COMMENT_NODE) {
+                $out .= '<!--' . $child->nodeValue . '-->';
+                continue;
+            }
+            if ($child->nodeType !== XML_ELEMENT_NODE) {
+                continue;
+            }
+            $tag   = strtolower($child->nodeName);
+            $attrs = static::renderAttrs($child);
+            if (in_array($tag, self::VOID, true)) {
+                $out .= "<{$tag}{$attrs}>";
+            } else {
+                $out .= "<{$tag}{$attrs}>" . static::renderInline($child) . "</{$tag}>";
+            }
+        }
+        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.
+    private static function looksLikeTextFlow(Dom\Node $node): bool
+    {
+        $elementCount = 0;
+        foreach ($node->childNodes as $child) {
+            if ($child->nodeType === XML_TEXT_NODE && trim($child->nodeValue) !== '') {
+                return true;
+            }
+            if ($child->nodeType === XML_ELEMENT_NODE) {
+                $elementCount++;
+            }
+        }
+        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
     private static function hasOnlyInlineChildren(Dom\Node $node): bool
@@ -165,10 +216,11 @@ class HTML
             return $out;
         }
         foreach ($node->attributes as $attr) {
-            if (in_array($attr->name, self::BOOLEAN_ATTRS, true)) {
-                $out .= ' ' . $attr->name;
+            $name = strtolower(trim((string) $attr->name));
+            if (in_array($name, self::BOOLEAN_ATTRS, true)) {
+                $out .= ' ' . $name;
             } else {
-                $out .= ' ' . $attr->name . '="' . htmlspecialchars($attr->value, ENT_QUOTES | ENT_HTML5, 'UTF-8') . '"';
+                $out .= ' ' . $name . '="' . htmlspecialchars((string) $attr->value, ENT_QUOTES | ENT_HTML5, 'UTF-8') . '"';
             }
         }
         return $out;

package/src/libraries/md.class.php

@@ -64,6 +64,217 @@ class MD {
         return array_keys(self::$plugins);
     }
 
+    // ========================================================================
+    // Génère un id de type "slug" pour les ancres de titres (ATX et Setext).
+    // ========================================================================
+    private static function slugify(string $text): string {
+        $id = strtolower(preg_replace('/[^\w\- ]/u', '', $text));
+        return preg_replace('/\s+/', '-', trim($id));
+    }
+
+    // ========================================================================
+    // Convertit une largeur d'indentation (espaces/tabs) en nombre de colonnes,
+    // une tabulation comptant pour 4 espaces.
+    // ========================================================================
+    private static function indentWidth(string $whitespace): int {
+        return strlen(str_replace("\t", '    ', $whitespace));
+    }
+
+    /**
+     * Construit récursivement une liste (imbriquée) <ol>/<ul> à partir d'un
+     * tableau plat d'items { indent, type, text }. $i est avancé au fur et à
+     * mesure de la consommation des items.
+     *
+     * @param array<int, array{indent:int, type:string, text:string}> $items
+     */
+    private static function buildListTree(array $items, int &$i, int $count): string {
+        $type       = $items[$i]['type'];
+        $baseIndent = $items[$i]['indent'];
+        $out        = "<{$type}>\n";
+
+        while ($i < $count && $items[$i]['indent'] === $baseIndent && $items[$i]['type'] === $type) {
+            $text = $items[$i]['text'];
+            $i++;
+
+            $nested = '';
+            if ($i < $count && $items[$i]['indent'] > $baseIndent) {
+                $nested = "\n" . self::buildListTree($items, $i, $count);
+            }
+
+            $out .= "  <li>{$text}{$nested}</li>\n";
+        }
+
+        return $out . "</{$type}>";
+    }
+
+    // ========================================================================
+    // ÉMOJIS (syntaxe étendue) : :shortcode: → caractère unicode.
+    // Table non exhaustive mais couvrant les raccourcis les plus courants ;
+    // extensible via registerEmoji().
+    // ========================================================================
+    /** @var array<string, string> */
+    private static array $extraEmoji = [];
+
+    private static array $emojiMap = [
+        'smile' => '😄', 'smiley' => '😃', 'grin' => '😁', 'joy' => '😂', 'rofl' => '🤣',
+        'blush' => '😊', 'wink' => '😉', 'relaxed' => '☺️', 'slight_smile' => '🙂',
+        'upside_down_face' => '🙃', 'innocent' => '😇', 'heart_eyes' => '😍', 'kissing_heart' => '😘',
+        'thinking' => '🤔', 'neutral_face' => '😐', 'expressionless' => '😑', 'no_mouth' => '😶',
+        'roll_eyes' => '🙄', 'smirk' => '😏', 'unamused' => '😒', 'grimacing' => '😬',
+        'lying_face' => '🤥', 'relieved' => '😌', 'pensive' => '😔', 'sleepy' => '😪',
+        'drooling_face' => '🤤', 'sleeping' => '😴', 'mask' => '😷', 'sunglasses' => '😎',
+        'star_struck' => '🤩', 'partying_face' => '🥳', 'worried' => '😟', 'frowning' => '☹️',
+        'confused' => '😕', 'slightly_frowning_face' => '🙁', 'cry' => '😢', 'sob' => '😭',
+        'scream' => '😱', 'confounded' => '😖', 'persevere' => '😣', 'disappointed' => '😞',
+        'sweat' => '😓', 'weary' => '😩', 'tired_face' => '😫', 'yawning_face' => '🥱',
+        'triumph' => '😤', 'rage' => '😡', 'angry' => '😠', 'cursing_face' => '🤬',
+        'exploding_head' => '🤯', 'flushed' => '😳', 'hot_face' => '🥵', 'cold_face' => '🥶',
+        'scream_cat' => '🙀', 'nerd_face' => '🤓', 'monocle_face' => '🧐', 'zany_face' => '🤪',
+        'raised_eyebrow' => '🤨', 'shushing_face' => '🤫', 'zipper_mouth_face' => '🤐',
+        'heart' => '❤️', 'orange_heart' => '🧡', 'yellow_heart' => '💛', 'green_heart' => '💚',
+        'blue_heart' => '💙', 'purple_heart' => '💜', 'black_heart' => '🖤', 'white_heart' => '🤍',
+        'broken_heart' => '💔', 'two_hearts' => '💕', 'sparkling_heart' => '💖', 'heartbeat' => '💓',
+        'thumbsup' => '👍', '+1' => '👍', 'thumbsdown' => '👎', '-1' => '👎',
+        'clap' => '👏', 'raised_hands' => '🙌', 'pray' => '🙏', 'wave' => '👋',
+        'ok_hand' => '👌', 'v' => '✌️', 'crossed_fingers' => '🤞', 'muscle' => '💪',
+        'point_up' => '☝️', 'point_down' => '👇', 'point_left' => '👈', 'point_right' => '👉',
+        'handshake' => '🤝', 'writing_hand' => '✍️', 'fire' => '🔥', 'star' => '⭐',
+        'star2' => '🌟', 'sparkles' => '✨', 'zap' => '⚡', 'boom' => '💥', 'collision' => '💥',
+        'rocket' => '🚀', 'tada' => '🎉', 'confetti_ball' => '🎊', 'gift' => '🎁',
+        'balloon' => '🎈', 'trophy' => '🏆', 'medal' => '🏅', 'crown' => '👑',
+        'gem' => '💎', 'moneybag' => '💰', 'dollar' => '💵', '100' => '💯',
+        'warning' => '⚠️', 'no_entry' => '⛔', 'stop_sign' => '🛑', 'checkered_flag' => '🏁',
+        'white_check_mark' => '✅', 'heavy_check_mark' => '✔️', 'x' => '❌', 'negative_squared_cross_mark' => '❎',
+        'question' => '❓', 'grey_question' => '❔', 'exclamation' => '❗', 'bangbang' => '‼️',
+        'interrobang' => '⁉️', 'bulb' => '💡', 'bell' => '🔔', 'no_bell' => '🔕',
+        'lock' => '🔒', 'unlock' => '🔓', 'key' => '🔑', 'mag' => '🔍', 'link' => '🔗',
+        'pushpin' => '📌', 'paperclip' => '📎', 'calendar' => '📅', 'clock' => '🕐',
+        'hourglass' => '⌛', 'alarm_clock' => '⏰', 'memo' => '📝', 'pencil2' => '✏️',
+        'book' => '📖', 'books' => '📚', 'newspaper' => '📰', 'email' => '📧',
+        'envelope' => '✉️', 'inbox_tray' => '📥', 'outbox_tray' => '📤', 'package' => '📦',
+        'file_folder' => '📁', 'open_file_folder' => '📂', 'clipboard' => '📋',
+        'chart_with_upwards_trend' => '📈', 'chart_with_downwards_trend' => '📉', 'bar_chart' => '📊',
+        'computer' => '💻', 'desktop_computer' => '🖥️', 'keyboard' => '⌨️', 'printer' => '🖨️',
+        'phone' => '📱', 'iphone' => '📱', 'camera' => '📷', 'video_camera' => '📹',
+        'tv' => '📺', 'radio' => '📻', 'battery' => '🔋', 'electric_plug' => '🔌',
+        'bug' => '🐛', 'beetle' => '🪲', 'gear' => '⚙️', 'wrench' => '🔧', 'hammer' => '🔨',
+        'nut_and_bolt' => '🔩', 'toolbox' => '🧰', 'test_tube' => '🧪', 'microscope' => '🔬',
+        'satellite' => '🛰️', 'globe_with_meridians' => '🌐', 'earth_americas' => '🌎',
+        'sun' => '☀️', 'sunny' => '☀️', 'partly_sunny' => '⛅', 'cloud' => '☁️',
+        'rainbow' => '🌈', 'umbrella' => '☂️', 'snowflake' => '❄️', 'droplet' => '💧',
+        'ocean' => '🌊', 'tent' => '⛺', 'camping' => '🏕️', 'mountain' => '⛰️',
+        'evergreen_tree' => '🌲', 'deciduous_tree' => '🌳', 'palm_tree' => '🌴',
+        'cactus' => '🌵', 'seedling' => '🌱', 'four_leaf_clover' => '🍀', 'maple_leaf' => '🍁',
+        'dog' => '🐶', 'cat' => '🐱', 'mouse' => '🐭', 'rabbit' => '🐰', 'fox_face' => '🦊',
+        'bear' => '🐻', 'panda_face' => '🐼', 'koala' => '🐨', 'tiger' => '🐯', 'lion' => '🦁',
+        'cow' => '🐮', 'pig' => '🐷', 'frog' => '🐸', 'monkey_face' => '🐵', 'chicken' => '🐔',
+        'penguin' => '🐧', 'bird' => '🐦', 'baby_chick' => '🐤', 'owl' => '🦉',
+        'horse' => '🐴', 'unicorn' => '🦄', 'bee' => '🐝', 'butterfly' => '🦋', 'snail' => '🐌',
+        'octopus' => '🐙', 'fish' => '🐟', 'dolphin' => '🐬', 'whale' => '🐳',
+        'pizza' => '🍕', 'hamburger' => '🍔', 'fries' => '🍟', 'hotdog' => '🌭',
+        'taco' => '🌮', 'sushi' => '🍣', 'ramen' => '🍜', 'spaghetti' => '🍝',
+        'bread' => '🍞', 'cheese' => '🧀', 'egg' => '🥚', 'popcorn' => '🍿',
+        'cookie' => '🍪', 'doughnut' => '🍩', 'cake' => '🍰', 'birthday' => '🎂',
+        'candy' => '🍬', 'chocolate_bar' => '🍫', 'icecream' => '🍦', 'apple' => '🍎',
+        'banana' => '🍌', 'grapes' => '🍇', 'watermelon' => '🍉', 'strawberry' => '🍓',
+        'lemon' => '🍋', 'peach' => '🍑', 'coffee' => '☕', 'tea' => '🍵', 'beer' => '🍺',
+        'beers' => '🍻', 'wine_glass' => '🍷', 'cocktail' => '🍸', 'tropical_drink' => '🍹',
+        'champagne' => '🍾', 'soccer' => '⚽', 'basketball' => '🏀', 'football' => '🏈',
+        'baseball' => '⚾', 'tennis' => '🎾', 'volleyball' => '🏐', 'rugby_football' => '🏉',
+        '8ball' => '🎱', 'golf' => '⛳', 'dart' => '🎯', 'video_game' => '🎮',
+        'game_die' => '🎲', 'jigsaw' => '🧩', 'car' => '🚗', 'taxi' => '🚕', 'bus' => '🚌',
+        'ambulance' => '🚑', 'fire_engine' => '🚒', 'police_car' => '🚓', 'bike' => '🚲',
+        'airplane' => '✈️', 'helicopter' => '🚁', 'train' => '🚆', 'ship' => '🚢',
+        'house' => '🏠', 'office' => '🏢', 'hospital' => '🏥', 'school' => '🏫',
+        'church' => '⛪', 'castle' => '🏰', 'world_map' => '🗺️', 'flag_white' => '🏳️',
+        'flag_black' => '🏴', 'checkered_flag2' => '🏁', 'eyes' => '👀', 'eye' => '👁️',
+        'speech_balloon' => '💬', 'thought_balloon' => '💭', 'zzz' => '💤', 'boom2' => '💥',
+        'sos' => '🆘', 'new' => '🆕', 'ok' => '🆗', 'up' => '🆙', 'cool' => '🆒',
+        'free' => '🆓', 'id' => '🆔', 'ng' => '🆖',
+    ];
+
+    /**
+     * Enregistre (ou remplace) un raccourci emoji personnalisé.
+     */
+    public static function registerEmoji(string $shortcode, string $char): void {
+        self::$extraEmoji[strtolower(trim($shortcode, ':'))] = $char;
+    }
+
+    private static function emojiFor(string $shortcode): ?string {
+        $key = strtolower($shortcode);
+        return self::$extraEmoji[$key] ?? self::$emojiMap[$key] ?? null;
+    }
+
+    // ========================================================================
+    // LISTES DE DÉFINITION (syntaxe étendue)
+    //   Terme
+    //   : Définition
+    // Analyse procédurale ligne par ligne (plus sûre qu'une seule grosse
+    // regex pour regrouper plusieurs paires terme/définitions dans un même
+    // <dl>, séparées ou non par une ligne vide).
+    // ========================================================================
+    private static function isDefinitionColonLine(string $line): bool {
+        return (bool) preg_match('/^[ \t]*:[ \t]+.+$/', $line);
+    }
+
+    private static function looksLikeOtherBlock(string $line): bool {
+        $t = ltrim($line);
+        if ($t === '') return true;
+        if (str_starts_with($t, '<')) return true;
+        return (bool) preg_match('/^(?:#{1,6}[ \t]|>|```|\||[-*+][ \t]|\d+\.[ \t])/', $t);
+    }
+
+    private static function extractDefinitionLists(string $html): string {
+        $lines = explode("\n", $html);
+        $n     = count($lines);
+        $out   = [];
+        $i     = 0;
+
+        while ($i < $n) {
+            $isTermStart = $i + 1 < $n
+                && !self::looksLikeOtherBlock($lines[$i])
+                && !self::isDefinitionColonLine($lines[$i])
+                && self::isDefinitionColonLine($lines[$i + 1]);
+
+            if (!$isTermStart) {
+                $out[] = $lines[$i];
+                $i++;
+                continue;
+            }
+
+            $dl = "<dl>\n";
+            while (true) {
+                $term = trim($lines[$i]);
+                $dl  .= "  <dt>{$term}</dt>\n";
+                $i++;
+                while ($i < $n && preg_match('/^[ \t]*:[ \t]+(.*)$/', $lines[$i], $m)) {
+                    $dl .= "  <dd>{$m[1]}</dd>\n";
+                    $i++;
+                }
+
+                // Une seule ligne vide entre deux groupes reste dans le même <dl>
+                // si le groupe suivant est bien un nouveau terme.
+                if ($i < $n && trim($lines[$i]) === '') {
+                    $j = $i;
+                    while ($j < $n && trim($lines[$j]) === '') $j++;
+                    if ($j + 1 < $n
+                        && !self::looksLikeOtherBlock($lines[$j])
+                        && !self::isDefinitionColonLine($lines[$j])
+                        && self::isDefinitionColonLine($lines[$j + 1])
+                    ) {
+                        $i = $j;
+                        continue;
+                    }
+                }
+                break;
+            }
+            $dl   .= "</dl>";
+            $out[] = $dl;
+        }
+
+        return implode("\n", $out);
+    }
+
     // ========================================================================
 
     public static function toHtml(string $markdown): string {
@@ -137,6 +348,59 @@ class MD {
         );
 
 
+        // ====================================================================
+        // ÉTAPE 2a : DÉFINITIONS DE NOTES DE BAS DE PAGE (footnotes)
+        //   [^1]: Texte de la note.
+        //   [^bignote]: Première ligne.
+        //
+        //       Paragraphe suivant, indenté de 4 espaces ou 1 tabulation.
+        //
+        //       `{ du code }`
+        // Extraites (et retirées du texte) AVANT les définitions de liens par
+        // référence, car [^label]: matcherait aussi leur regex sinon.
+        // Le contenu de chaque note est rendu via un appel récursif à
+        // toHtml() pour supporter plusieurs paragraphes, du code, etc.
+        // ====================================================================
+        $footnoteDefs = [];
+        $html = preg_replace_callback(
+            '/^\[\^([^\]\s]+)\]:[ \t]?([^\n]*)((?:\n(?:[ \t]{4}[^\n]*|[ \t]*))*)/m',
+            function ($m) use (&$footnoteDefs): string {
+                $label = strtolower(trim($m[1]));
+                $first = $m[2];
+                $rest  = $m[3] ?? '';
+                $restLines = $rest !== '' ? explode("\n", $rest) : [];
+                $restLines = array_map(static function (string $l): string {
+                    return preg_replace('/^(?:[ ]{4}|\t)/', '', $l);
+                }, $restLines);
+                $content = trim($first . "\n" . implode("\n", $restLines));
+                $footnoteDefs[$label] = self::toHtml($content);
+                return '';
+            },
+            $html
+        );
+
+
+        // ====================================================================
+        // ÉTAPE 2b : DÉFINITIONS DE LIENS PAR RÉFÉRENCE
+        //   [label]: https://example.com "Titre optionnel"
+        //   [label]: <https://example.com> 'Titre optionnel'
+        //   [label]: https://example.com (Titre optionnel)
+        // Extraites (et retirées du texte) avant tout le reste ; utilisées
+        // plus loin par les liens [texte][label] / [texte][].
+        // ====================================================================
+        $refDefs = [];
+        $html = preg_replace_callback(
+            '/^[ \t]{0,3}\[([^\]]+)\]:[ \t]*<?([^\s>]+)>?(?:[ \t]+(?:"([^"]*)"|\'([^\']*)\'|\(([^)]*)\)))?[ \t]*$/m',
+            function ($m) use (&$refDefs): string {
+                $label = strtolower(trim($m[1]));
+                $title = $m[3] !== '' ? $m[3] : ($m[4] !== '' ? $m[4] : ($m[5] ?? ''));
+                $refDefs[$label] = ['url' => $m[2], 'title' => $title];
+                return '';
+            },
+            $html
+        );
+
+
         // ====================================================================
         // ÉTAPE 3 : BLOCS DE CODE (```lang ... ```)
         // ====================================================================
@@ -149,8 +413,44 @@ class MD {
             return $placeholder;
         }, $html);
 
-        // Code inline (`...`)
+        // ====================================================================
+        // ÉTAPE 3a : BLOCS DE CODE INDENTÉS (4 espaces ou 1 tabulation)
+        // Reconnu seulement quand précédé d'une ligne vide (ou du début du
+        // document) et suivi d'une ligne vide (ou de la fin du document), afin
+        // d'éviter les conflits avec l'indentation des listes imbriquées.
+        // ====================================================================
+        $html = preg_replace_callback(
+            '/(?<=\n\n|^)((?:[ ]{4}|\t)[^\n]*(?:\n(?:[ ]{4}|\t)[^\n]*)*)(?=\n\n|\n*$)/',
+            function ($matches) use (&$codeBlocks) {
+                $lines    = explode("\n", $matches[1]);
+                $stripped = array_map(static function (string $l): string {
+                    return preg_replace('/^(?:[ ]{4}|\t)/', '', $l);
+                }, $lines);
+                $code        = htmlspecialchars(implode("\n", $stripped), ENT_QUOTES, 'UTF-8');
+                $placeholder = "\x02CB" . count($codeBlocks) . "\x03";
+                $codeBlocks[$placeholder] = "<pre><code>{$code}</code></pre>";
+                return $placeholder;
+            },
+            $html
+        );
+
+        // Code inline avec double backticks (permet d'inclure un backtick littéral)
         $inlineCodes = [];
+        $html = preg_replace_callback('/``(.+?)``/s', function ($matches) use (&$inlineCodes) {
+            $content = $matches[1];
+            // Convention standard : si le contenu commence et finit par un
+            // espace (et n'est pas uniquement des espaces), on retire un
+            // espace de chaque côté — utile pour englober un ` en bordure.
+            if (preg_match('/^ (.*[^ ]) $/s', $content, $trim)) {
+                $content = $trim[1];
+            }
+            $code        = htmlspecialchars($content, ENT_QUOTES, 'UTF-8');
+            $placeholder = "\x02IC" . count($inlineCodes) . "\x03";
+            $inlineCodes[$placeholder] = "<code>{$code}</code>";
+            return $placeholder;
+        }, $html);
+
+        // Code inline (`...`)
         $html = preg_replace_callback('/`([^`\n]+)`/', function ($matches) use (&$inlineCodes) {
             $code        = htmlspecialchars($matches[1], ENT_QUOTES, 'UTF-8');
             $placeholder = "\x02IC" . count($inlineCodes) . "\x03";
@@ -160,7 +460,57 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 3b : ALERTES GFM ET BLOCKQUOTES
+        // ÉTAPE 3b : ÉCHAPPEMENT DES CARACTÈRES (\* \_ \# etc.)
+        // Traité après l'extraction du code (le code reste littéral) et avant
+        // tout le reste, pour que \* n'ouvre pas une emphase, \# ne crée pas
+        // un titre, \- ne crée pas de liste, etc.
+        // ====================================================================
+        $escapes = [];
+        $html = preg_replace_callback(
+            '/\\\\([\\\\`*_{}\[\]<>()#+\-.!|])/',
+            function ($m) use (&$escapes): string {
+                $placeholder = "\x02ESC" . count($escapes) . "\x03";
+                $escapes[$placeholder] = htmlspecialchars($m[1], ENT_QUOTES, 'UTF-8');
+                return $placeholder;
+            },
+            $html
+        );
+        // &#124; est la convention documentée (Markdown Extra / PHP Markdown)
+        // pour afficher un pipe littéral dans une cellule de tableau sans
+        // qu'il soit interprété comme séparateur de colonnes.
+        $html = preg_replace_callback(
+            '/&#124;/i',
+            function () use (&$escapes): string {
+                $placeholder = "\x02ESC" . count($escapes) . "\x03";
+                $escapes[$placeholder] = '|';
+                return $placeholder;
+            },
+            $html
+        );
+
+
+        // ====================================================================
+        // ÉTAPE 3d : LIENS AUTOMATIQUES <https://...> et <email@example.com>
+        // Traités avant l'encodage XSS car les caractères < > seraient encodés
+        // en &lt; &gt; et la regex ne matcherait plus.
+        // ====================================================================
+        $autolinks = [];
+        $html = preg_replace_callback('/<(https?:\/\/[^\s<>]+)>/', function ($m) use (&$autolinks): string {
+            $url         = htmlspecialchars($m[1], ENT_QUOTES, 'UTF-8');
+            $placeholder = "\x02AL" . count($autolinks) . "\x03";
+            $autolinks[$placeholder] = "<a href=\"{$url}\" target=\"_blank\" rel=\"noopener noreferrer\">{$url}</a>";
+            return $placeholder;
+        }, $html);
+        $html = preg_replace_callback('/<([^\s<>]+@[^\s<>]+\.[^\s<>]+)>/', function ($m) use (&$autolinks): string {
+            $email       = htmlspecialchars($m[1], ENT_QUOTES, 'UTF-8');
+            $placeholder = "\x02AL" . count($autolinks) . "\x03";
+            $autolinks[$placeholder] = "<a href=\"mailto:{$email}\">{$email}</a>";
+            return $placeholder;
+        }, $html);
+
+
+        // ====================================================================
+        // ÉTAPE 3e : ALERTES GFM ET BLOCKQUOTES
         // Traités avant l'encodage XSS car le caractère > serait encodé en &gt;
         // et les regex ne matcheraient plus.
         // ====================================================================
@@ -179,19 +529,26 @@ class MD {
                 $blockquotes[$placeholder] = "<div class=\"markdown-alert markdown-alert-{$type}\">"
                     . "<p class=\"markdown-alert-title\">{$label}</p>"
                     . "<p>{$content}</p></div>";
-                return $placeholder;
+                // Le \n final consommé par la regex est réinjecté après le
+                // placeholder pour ne pas fusionner la ligne vide suivante
+                // avec celle du placeholder (ce qui fausserait par exemple
+                // la détection d'un titre Setext juste après).
+                return $placeholder . (str_ends_with($matches[1], "\n") ? "\n" : '');
             },
             $html
         );
 
-        // Blockquotes standards
+        // Blockquotes standards (imbrication gérée par récursion sur toHtml,
+        // qui ré-applique cette même règle sur le contenu déjà dé-préfixé
+        // d'un niveau de ">")
         $html = preg_replace_callback('/^((?:>[ \t]?[^\n]*\n?)+)/m', function ($matches) use (&$blockquotes): string {
             $content = preg_replace('/^>[ \t]?/m', '', $matches[1]);
             // Les deux espaces trailing sont laissés tels quels : toHtml() les gère lui-même
             $inner   = self::toHtml(trim($content));
             $placeholder = "\x02BQ" . count($blockquotes) . "\x03";
             $blockquotes[$placeholder] = "<blockquote>{$inner}</blockquote>";
-            return $placeholder;
+            // Voir commentaire ci-dessus : on préserve le \n final consommé.
+            return $placeholder . (str_ends_with($matches[1], "\n") ? "\n" : '');
         }, $html);
 
 
@@ -251,7 +608,7 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 6 : (Alertes GFM et blockquotes traités à l'étape 3b)
+        // ÉTAPE 6 : (Alertes GFM et blockquotes traités à l'étape 3e)
         // ====================================================================
 
 
@@ -263,44 +620,79 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 8 : TITRES (ATX : # à ######)
+        // ÉTAPE 7b : TITRES SETEXT (syntaxe alternative == / --)
+        //   Titre
+        //   =====   → <h1>
+        //
+        //   Titre
+        //   -----   → <h2>
+        // Traité avant les titres ATX et avant les lignes séparatrices (une
+        // ligne de tirets juste après une ligne de texte est un titre, pas un <hr>).
         // ====================================================================
-        $html = preg_replace_callback('/^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?$/m', function ($matches) {
-            $level = strlen($matches[1]);
-            $text  = trim($matches[2]);
-            $id    = strtolower(preg_replace('/[^\w\- ]/u', '', $text));
-            $id    = preg_replace('/\s+/', '-', trim($id));
-            return "<h{$level} id=\"{$id}\">{$text}</h{$level}>";
-        }, $html);
+        $html = preg_replace_callback(
+            '/^(?![ \t]*(?:#{1,6}[ \t]|>|```|\||[-*+][ \t]|\d+\.[ \t]))[ \t]*(\S.*?)[ \t]*(?:\{#([a-zA-Z0-9_\-:.]+)\}[ \t]*)?\n[ \t]*=+[ \t]*$/m',
+            function ($matches) {
+                $text = trim($matches[1]);
+                $id   = !empty($matches[2]) ? $matches[2] : self::slugify($text);
+                return "<h1 id=\"{$id}\">{$text}</h1>";
+            },
+            $html
+        );
+        $html = preg_replace_callback(
+            '/^(?![ \t]*(?:#{1,6}[ \t]|>|```|\||[-*+][ \t]|\d+\.[ \t]))[ \t]*(\S.*?)[ \t]*(?:\{#([a-zA-Z0-9_\-:.]+)\}[ \t]*)?\n[ \t]*-+[ \t]*$/m',
+            function ($matches) {
+                $text = trim($matches[1]);
+                $id   = !empty($matches[2]) ? $matches[2] : self::slugify($text);
+                return "<h2 id=\"{$id}\">{$text}</h2>";
+            },
+            $html
+        );
 
 
         // ====================================================================
-        // ÉTAPE 9 : LISTES (puces et ordonnées)
+        // ÉTAPE 8 : TITRES (ATX : # à ######)
         // ====================================================================
         $html = preg_replace_callback(
-            '/^([ \t]*\d+\. .+(?:\n[ \t]*\d+\. .+)*)/m',
+            '/^(#{1,6})[ \t]+(.+?)[ \t]*(?:\{#([a-zA-Z0-9_\-:.]+)\}[ \t]*)?(?:[ \t]+#+)?$/m',
             function ($matches) {
-                $items = preg_split('/\n/', trim($matches[1]));
-                $out   = "<ol>\n";
-                foreach ($items as $item) {
-                    $text = preg_replace('/^[ \t]*\d+\. /', '', $item);
-                    $out .= "  <li>{$text}</li>\n";
-                }
-                return $out . "</ol>";
+                $level = strlen($matches[1]);
+                $text  = trim($matches[2]);
+                $id    = !empty($matches[3]) ? $matches[3] : self::slugify($text);
+                return "<h{$level} id=\"{$id}\">{$text}</h{$level}>";
             },
             $html
         );
 
+
+        // ====================================================================
+        // ÉTAPE 9 : LISTES (puces et ordonnées, avec imbrication)
+        // Une seule passe détecte un bloc contigu de lignes qui sont soit une
+        // puce (-,*,+) soit un item numéroté, quel que soit leur niveau
+        // d'indentation ; le bloc est ensuite reconstruit récursivement en
+        // <ol>/<ul> imbriqués selon la profondeur d'indentation relative.
+        // Les items de tâches (déjà convertis en <li class="task-item">) ne
+        // matchent plus ce motif et ne sont donc pas ré-englobés ici.
+        // ====================================================================
         $html = preg_replace_callback(
-            '/^([ \t]*[-*+] (?!\[[ xX]\] ).+(?:\n[ \t]*[-*+] (?!\[[ xX]\] ).+)*)/m',
+            '/^([ \t]*(?:\d+\.|[-*+])[ \t]+.+(?:\n[ \t]*(?:\d+\.|[-*+])[ \t]+.+)*)/m',
             function ($matches) {
-                $items = preg_split('/\n/', trim($matches[1]));
-                $out   = "<ul>\n";
-                foreach ($items as $item) {
-                    $text = preg_replace('/^[ \t]*[-*+] /', '', $item);
-                    $out .= "  <li>{$text}</li>\n";
+                $lines = explode("\n", $matches[1]);
+                $items = [];
+                foreach ($lines as $line) {
+                    if (preg_match('/^([ \t]*)(\d+)\.[ \t]+(.*)$/', $line, $m)) {
+                        $items[] = ['indent' => self::indentWidth($m[1]), 'type' => 'ol', 'text' => $m[3]];
+                    } elseif (preg_match('/^([ \t]*)[-*+][ \t]+(.*)$/', $line, $m)) {
+                        $items[] = ['indent' => self::indentWidth($m[1]), 'type' => 'ul', 'text' => $m[2]];
+                    }
                 }
-                return $out . "</ul>";
+                if (empty($items)) return $matches[1];
+                // Normalise le niveau d'indentation le plus bas à 0
+                $minIndent = min(array_column($items, 'indent'));
+                foreach ($items as &$it) $it['indent'] -= $minIndent;
+                unset($it);
+
+                $i = 0;
+                return self::buildListTree($items, $i, count($items));
             },
             $html
         );
@@ -315,7 +707,39 @@ class MD {
 
 
         // ====================================================================
-        // ÉTAPE 10 : TEXTE EN LIGNE (Gras, Italique, Barré)
+        // ÉTAPE 9b : LISTES DE DÉFINITION (syntaxe étendue)
+        //   Terme
+        //   : Définition
+        // ====================================================================
+        $html = self::extractDefinitionLists($html);
+
+
+        // ====================================================================
+        // ÉTAPE 9c : RÉFÉRENCES DE NOTES DE BAS DE PAGE [^label]
+        // Converties AVANT l'emphase pour ne pas entrer en collision avec le
+        // nouvel exposant ^texte^ (un [^1] suivi plus loin d'un [^2] sur la
+        // même ligne pourrait sinon être interprété comme ^1] ... [^2^).
+        // La numérotation est séquentielle, dans l'ordre de première
+        // apparition dans le texte (comme documenté).
+        // ====================================================================
+        $footnoteOrder = [];
+        $html = preg_replace_callback('/\[\^([^\]\s]+)\]/', function ($m) use (&$footnoteOrder, &$footnoteDefs): string {
+            $label = strtolower(trim($m[1]));
+            if (!isset($footnoteDefs[$label])) {
+                // Référence vers une note non définie : laissée telle quelle.
+                return $m[0];
+            }
+            if (!isset($footnoteOrder[$label])) {
+                $footnoteOrder[$label] = count($footnoteOrder) + 1;
+            }
+            $num = $footnoteOrder[$label];
+            return "<sup id=\"fnref:{$label}\"><a href=\"#fn:{$label}\">{$num}</a></sup>";
+        }, $html);
+
+
+        // ====================================================================
+        // ÉTAPE 10 : TEXTE EN LIGNE (Gras, Italique, Barré, Surlignage,
+        // Indice/Exposant, Emoji)
         // ====================================================================
         $html = preg_replace('/\*\*\*(.+?)\*\*\*/s', '<strong><em>$1</em></strong>', $html);
         $html = preg_replace('/___(.+?)___/s',        '<strong><em>$1</em></strong>', $html);
@@ -325,7 +749,25 @@ class MD {
         // Le _ italique ne doit matcher qu'aux frontières de mots pour ne pas
         // capturer les snake_case, noms de packages (@php-wasm/node), etc.
         $html = preg_replace('/(?<!\w)_([^_\n]+)_(?!\w)/',           '<em>$1</em>',                  $html);
+        // Surlignage ==texte== (syntaxe étendue)
+        $html = preg_replace('/==(.+?)==/s',           '<mark>$1</mark>',              $html);
+        // Barré ~~texte~~ — traité AVANT le sous-script (simple ~) pour que
+        // celui-ci ne matche pas la moitié d'une paire de tildes doubles.
         $html = preg_replace('/~~(.+?)~~/s',           '<del>$1</del>',                $html);
+        // Exposant ^texte^ (syntaxe étendue) — placé avant l'échappement des
+        // références de notes ([^label]) n'est pas un souci : celles-ci sont
+        // encadrées de crochets et ne forment donc pas de paire ^...^ isolée.
+        $html = preg_replace('/\^([^\^\n]+)\^/',       '<sup>$1</sup>',                $html);
+        // Sous-script ~texte~ (un seul tilde ; les ~~ ont déjà été consommés
+        // juste au-dessus par le barré).
+        $html = preg_replace('/~([^~\n]+)~/',          '<sub>$1</sub>',                $html);
+
+        // Émojis :shortcode: (syntaxe étendue) — les raccourcis inconnus sont
+        // laissés tels quels plutôt que silencieusement supprimés.
+        $html = preg_replace_callback('/:([a-zA-Z0-9_+\-]+):/', function ($m): string {
+            $emoji = self::emojiFor($m[1]);
+            return $emoji ?? $m[0];
+        }, $html);
 
 
         // ====================================================================
@@ -339,29 +781,39 @@ class MD {
             $html
         );
 
-        // Liens markdown [texte](url "titre optionnel")
+        $buildLink = static function (string $text, string $href, string $title): string {
+            $titleAttr = $title !== '' ? ' title="' . $title . '"' : '';
+            $extern    = preg_match('/^https?:\/\//i', $href)
+                ? ' target="_blank" rel="noopener noreferrer"'
+                : '';
+            return "<a href=\"{$href}\"{$titleAttr}{$extern}>{$text}</a>";
+        };
+
+        // Liens par référence [texte][label] et [texte][] (raccourci = label = texte)
         $html = preg_replace_callback(
-            '/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/',
-            function ($m): string {
-                $text   = $m[1];
-                $href   = $m[2];
-                $title  = isset($m[3]) && $m[3] !== '' ? ' title="' . $m[3] . '"' : '';
-                $extern = preg_match('/^https?:\/\//i', $href)
-                    ? ' target="_blank" rel="noopener noreferrer"'
-                    : '';
-                return "<a href=\"{$href}\"{$title}{$extern}>{$text}</a>";
+            '/\[([^\]]+)\]\[([^\]]*)\]/',
+            function ($m) use (&$refDefs, $buildLink): string {
+                $text  = $m[1];
+                $label = strtolower(trim($m[2] !== '' ? $m[2] : $m[1]));
+                if (!isset($refDefs[$label])) return $m[0];
+                $def = $refDefs[$label];
+                return $buildLink($text, $def['url'], $def['title']);
             },
             $html
         );
 
-        // Liens automatiques <https://...>
-        $html = preg_replace(
-            '/<(https?:\/\/[^>]+)>/',
-            '<a href="$1" target="_blank" rel="noopener noreferrer">$1</a>',
+        // Liens markdown [texte](url "titre optionnel")
+        $html = preg_replace_callback(
+            '/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/',
+            function ($m) use ($buildLink): string {
+                return $buildLink($m[1], $m[2], $m[3] ?? '');
+            },
             $html
         );
 
-        // URL nues https://...
+        // URL nues https://... (syntaxe étendue : auto-link sans crochets).
+        // Exclut celles déjà entre guillemets/attributs (href="...") ou déjà
+        // transformées en lien pour ne pas les doubler.
         $html = preg_replace(
             '/(?<!["\'=>])\b(https?:\/\/[^\s<>"\')\]]+)/',
             '<a href="$1" target="_blank" rel="noopener noreferrer">$1</a>',
@@ -384,12 +836,16 @@ class MD {
         // ====================================================================
         $blockStartTags = ['<h', '<pre', '<ul', '<ol', '<li', '<table', '<thead', '<tbody',
                            '<tr', '<td', '<th', '<blockquote', '<div', '<hr', '<img',
-                           '</ul>', '</ol>', '</table>', '</blockquote>', '</div>',
-                           "\x02CB", "\x02IC", "\x02PLG", "\x02BQ"];
+                           '<dl', '<dt', '<dd',
+                           "\x02CB", "\x02PLG", "\x02BQ"];
 
         $isBlockLine = static function (string $line) use ($blockStartTags): bool {
             $t = ltrim($line);
             if ($t === '') return false;
+            // Toute balise fermante (</...>) est toujours considérée comme une
+            // ligne "bloc" : ça évite qu'une fermeture de <table>, <thead>,
+            // <tr>, etc. finisse absorbée dans un <p> environnant.
+            if (str_starts_with($t, '</')) return true;
             foreach ($blockStartTags as $tag) {
                 if (str_starts_with($t, $tag)) return true;
             }
@@ -437,8 +893,27 @@ class MD {
         $html = strtr($html, $blockquotes);
         $html = strtr($html, $codeBlocks);
         $html = strtr($html, $inlineCodes);
+        $html = strtr($html, $autolinks);
+        // Les échappements sont réinjectés en tout dernier, une fois que plus
+        // aucune regex Markdown ne peut les interpréter.
+        $html = strtr($html, $escapes);
+
+
+        // ====================================================================
+        // ÉTAPE 15 : BLOC DES NOTES DE BAS DE PAGE
+        // Ajouté en fin de document, uniquement si au moins une note a été
+        // référencée (les notes définies mais jamais référencées sont
+        // silencieusement ignorées).
+        // ====================================================================
+        if (!empty($footnoteOrder)) {
+            $html .= "\n<div class=\"footnotes\">\n<ol>\n";
+            foreach ($footnoteOrder as $label => $num) {
+                $content = $footnoteDefs[$label];
+                $html   .= "  <li id=\"fn:{$label}\">{$content} <a href=\"#fnref:{$label}\" class=\"footnote-backref\">↩</a></li>\n";
+            }
+            $html .= "</ol>\n</div>";
+        }
 
         return $html;
     }
-}
-
+}

package/src/libraries/yaml.class.php

@@ -54,6 +54,137 @@ class YAML
         return self::parse(file_get_contents($path), $assoc);
     }
 
+    /**
+     * Charge un fichier YAML ou JSON, puis parcourt récursivement le résultat
+     * et remplace toute valeur string qui correspond à un chemin relatif vers
+     * un fichier YAML/JSON existant par le contenu désérialisé de ce fichier.
+     *
+     * Chaque fichier inclus est lui-même résolu relativement à son propre
+     * répertoire, et ainsi de suite (récursif).
+     *
+     * Si la chaîne ne se termine pas par .yml/.yaml/.json, ou si le fichier
+     * résolu n'existe pas, la valeur est conservée telle quelle.
+     *
+     * Les références circulaires (ex. A → B → A) lèvent une RuntimeException.
+     *
+     * Utilisation :
+     *   $data = YAML::loadFile('/chemin/vers/config.yaml');
+     *   $data = YAML::loadFile('/chemin/vers/config.yaml', true); // arrays assoc
+     *
+     * @param string   $path   Chemin vers le fichier racine (YAML ou JSON).
+     * @param bool     $assoc  true → mappings en array, false → stdClass.
+     * @return mixed
+     */
+    public static function loadFile(string $path, bool $assoc = false): mixed
+    {
+        $absolute = realpath($path);
+        if ($absolute === false || !is_readable($absolute)) {
+            throw new \RuntimeException("Impossible de lire le fichier : $path");
+        }
+
+        return self::loadFileRecursive($absolute, $assoc, []);
+    }
+
+    // -------------------------------------------------------------------------
+    // Méthodes privées pour loadFile
+    // -------------------------------------------------------------------------
+
+    /**
+     * Charge et résout un fichier, en propageant la liste des ancêtres pour
+     * détecter les cycles.
+     *
+     * @param string   $absolute Chemin absolu canonique du fichier à charger.
+     * @param bool     $assoc
+     * @param string[] $ancestors Chemins absolus des fichiers en cours de traitement.
+     * @return mixed
+     */
+    private static function loadFileRecursive(string $absolute, bool $assoc, array $ancestors): mixed
+    {
+        if (in_array($absolute, $ancestors, true)) {
+            throw new \RuntimeException(
+                "Référence circulaire détectée : " . implode(' → ', $ancestors) . " → $absolute"
+            );
+        }
+
+        $ext  = strtolower(pathinfo($absolute, PATHINFO_EXTENSION));
+        $raw  = file_get_contents($absolute);
+        $dir  = dirname($absolute);
+
+        if ($ext === 'json') {
+            $data = json_decode($raw, $assoc, 512, JSON_THROW_ON_ERROR);
+        } else {
+            // .yml, .yaml ou autre extension traitée comme YAML
+            $data = self::parse($raw, $assoc);
+        }
+
+        return self::resolveNode($data, $dir, $assoc, [...$ancestors, $absolute]);
+    }
+
+    /**
+     * Parcourt récursivement une valeur PHP (objet stdClass, array, string,
+     * scalaire) et résout les références vers des fichiers externes.
+     *
+     * @param mixed    $node
+     * @param string   $dir      Répertoire du fichier qui contient ce nœud.
+     * @param bool     $assoc
+     * @param string[] $ancestors
+     * @return mixed
+     */
+    private static function resolveNode(mixed $node, string $dir, bool $assoc, array $ancestors): mixed
+    {
+        if (is_string($node)) {
+            return self::resolveString($node, $dir, $assoc, $ancestors);
+        }
+
+        if (is_array($node)) {
+            foreach ($node as $key => $value) {
+                $node[$key] = self::resolveNode($value, $dir, $assoc, $ancestors);
+            }
+            return $node;
+        }
+
+        if ($node instanceof \stdClass) {
+            foreach ($node as $key => $value) {
+                $node->$key = self::resolveNode($value, $dir, $assoc, $ancestors);
+            }
+            return $node;
+        }
+
+        // int, float, bool, null → retourné tel quel
+        return $node;
+    }
+
+    /**
+     * Si la chaîne pointe vers un fichier YAML/JSON existant (chemin relatif
+     * au répertoire $dir), charge ce fichier récursivement. Sinon retourne la
+     * chaîne d'origine.
+     *
+     * @param string   $str
+     * @param string   $dir
+     * @param bool     $assoc
+     * @param string[] $ancestors
+     * @return mixed
+     */
+    private static function resolveString(string $str, string $dir, bool $assoc, array $ancestors): mixed
+    {
+        $trimmed = trim($str);
+
+        // Filtre rapide sur l'extension
+        if (!preg_match('/\.(ya?ml|json)$/i', $trimmed)) {
+            return $str;
+        }
+
+        // Résolution du chemin relatif au répertoire du fichier parent
+        $candidate = $dir . DIRECTORY_SEPARATOR . $trimmed;
+        $absolute  = realpath($candidate);
+
+        if ($absolute === false || !is_readable($absolute)) {
+            return $str; // Fichier introuvable → string ordinaire
+        }
+
+        return self::loadFileRecursive($absolute, $assoc, $ancestors);
+    }
+
     // -------------------------------------------------------------------------
     // Parsing récursif
     // -------------------------------------------------------------------------

package/src/prepros.js

@@ -1,16 +1,48 @@
 import fs from 'fs';
 import path, { dirname } from "path";
+import isBinary from './utils/isbinary.js';
+import joinWith from './utils/joinwith.js'
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
+import { walkFile } from '@kirigami/struct-walker';
 import { getPHPRuntime, getPHPRuntimeWithNetwork } from "@kirigami/php-wasm";
-import isBinary from './utils/isbinary.js';
-import joinWith from './utils/joinwith.js'
-import yaml from "js-yaml";
 
 
 const __project = process.cwd();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const __configpath = path.join(__project, 'kirigami.yaml');
+let   __root = null;
+let   __php  = null;
+
+
+if (!fs.existsSync(__configpath)) throw `Config file not found: ${__configpath}`;
+const config = await walkFile(__configpath);
+if(!config) throw `Invalid config file: ${__configpath}`;
+
+
+const getPHPInstance = async () => {
+    if(!__php) {
+        if(config?.kirigami?.root === undefined) throw `Missing prepros:root property in config file: ${__configpath}`;
+        __root = path.join(__project, config.kirigami.root);
+        if (!fs.existsSync(__root)) throw `Invalid prepros:root path: ${__root}`;
+
+        const preprosConfig = config.prepros;
+        preprosConfig.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        preprosConfig.root = joinWith('/project/', config?.kirigami?.root);
+        preprosConfig.data = config.kirigami || {};
+
+        __php = await (preprosConfig.network ? getPHPRuntimeWithNetwork() : getPHPRuntime());
+        __php.setSpawnHandler((command, args, options) => spawn(command, args, options));
+        __php.preprosConfig = preprosConfig;
+
+        const mountPaths = [];
+        const __cache = path.join(__project, '.cache.db');
+        mountPath(__php, __dirname, '/prepros');
+        mountPath(__php, joinWith(__project, config?.kirigami?.root), joinWith('/project', config?.kirigami?.root));
+        if (fs.existsSync(__cache)) mountPath(__php, __cache, '/project/.cache.db');
+    }
+    return __php;
+}
 
 
 const mountPath = (php, localPath, virtualDir) => {
@@ -32,14 +64,16 @@ const mountPath = (php, localPath, virtualDir) => {
 
 
 const run = async (args) => {
-    php.setSpawnHandler((command, args, options) => spawn(command, args, options));
+    const php = await getPHPInstance();
     const output = await php.runStream({
         scriptPath: '/prepros/prepros.php',
-        env: { PREPROS_ARGS: JSON.stringify(args), PREPROS_CONFIG: JSON.stringify(preprosConfig) }
+        env: {
+            PREPROS_ARGS:   JSON.stringify(args),
+            PREPROS_CONFIG: JSON.stringify(php.preprosConfig)
+        }
     });
     const stdout = await output.stdoutText;
     const stderr = await output.stderrText;
-    // console.log(stdout);
     let retobj;
     try {
         retobj = JSON.parse(stdout);
@@ -64,44 +98,29 @@ const run = async (args) => {
 
 
 const render = async (file = '.') => {
+    const php = await getPHPInstance();
     const target = path.resolve(__project, config?.kirigami?.root, file);
     const fsvm = path.join('/project', config?.kirigami?.root, file).replace(/\\/g, '/');
     mountPath(php, target, fsvm);
+    if(config?.prepros?.before) {
+        const include = path.resolve(__project, config?.kirigami?.root, config?.prepros?.before);
+        const dest = path.join('/project', config?.kirigami?.root, config?.prepros?.before).replace(/\\/g, '/');
+        mountPath(php, include, dest);
+    }
+    if(config?.prepros?.after) {
+        const include = path.resolve(__project, config?.kirigami?.root, config?.prepros?.after);
+        const dest = path.join('/project', config?.kirigami?.root, config?.prepros?.after).replace(/\\/g, '/');
+        mountPath(php, include, dest);
+    }
     return run([fsvm]);
 }
 
 
 const sitemap = async (dir) => {
+    const php = await getPHPInstance();
     mountPath(php, __root, '/project/' + config?.kirigami?.root);
     return run(['sitemap']);
 }
 
 
-if (!fs.existsSync(__configpath)) throw `Config file not found: ${__configpath}`;
-const configContents = fs.readFileSync(__configpath, 'utf8');
-const config = yaml.load(configContents);
-if(!config) throw `Invalid config file: ${__configpath}`;
-
-
-if(config?.kirigami?.root === undefined) throw `Missing prepros:root property in config file: ${__configpath}`;
-const __root = path.join(__project, config.kirigami.root);
-if (!fs.existsSync(__root)) throw `Invalid prepros:root path: ${__root}`;
-
-
-const preprosConfig = config.prepros;
-preprosConfig.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-preprosConfig.root = joinWith('/project/', config?.kirigami?.root);
-preprosConfig.data = config.kirigami || {};
-
-
-const php = await (preprosConfig.network ? getPHPRuntimeWithNetwork() : getPHPRuntime());
-
-
-const mountPaths = [];
-const __cache = path.join(__project, '.cache.db');
-mountPath(php, __dirname, '/prepros');
-mountPath(php, joinWith(__project, config?.kirigami?.root), joinWith('/project', config?.kirigami?.root));
-if (fs.existsSync(__cache)) mountPath(php, __cache, '/project/.cache.db');
-
-
 export { render, sitemap };

package/src/prepros.php

@@ -1,10 +1,10 @@
 <?php
 
-ini_set('display_errors', 1);
 ini_set('log_errors', 1);
-ini_set('error_log', 'php://stderr');
 ini_set('html_errors', 0);
+ini_set('display_errors', 1);
 ini_set('error_reporting', 32767);
+ini_set('error_log', 'php://stderr');
 error_reporting(E_ALL);