# RenderLoop

Version : 0.4.0 — dernière mise à jour : 2026-10-20

> RenderLoop est une boucle de retour visuelle pour applications PHP : capturer le HTML rendu d'une page avant modification, puis le comparer après, pour ne voir que le changement réel — le bruit (DebugBar, scripts, jetons CSRF, horodatages) étant masqué.

RenderLoop est une bibliothèque PHP open source (licence MIT) qui répond à une seule question après une modification de code : « mon édit a-t-il produit exactement l'effet voulu, et rien d'autre ? ». Elle compare l'état **rendu** d'une page avant et après, et non le diff des sources. Elle révèle donc aussi les effets indirects qu'un `git diff` ne montre pas : un include partagé modifié, une fonction commune, une requête qui vide une table, une édition concurrente sur la même page.

C'est un diff HTML sémantique, pas un diff d'images : aucune capture d'écran et aucun navigateur headless ne sont nécessaires pour les pages rendues côté serveur. Le coût d'exécution reste faible, en local comme en CI.

L'outil est utilisable par un humain comme par un agent de codage IA. Les actions `recheck`, `compare`, `list`, `calibrate`, `mask-add`, `capabilities` et `advise` acceptent `-f json` ; seuls `recheck` et `compare` produisent le résumé compact (`lines_added`, `lines_removed`, `hunks`, `tags_touched`, `changes`) conçu pour un lecteur à budget de tokens limité. `capture`, `store`, `golden-record` et `golden-verify` écrivent toujours du texte. L'action `capabilities` décrit le contrat machine de la CLI.

## Pages du site

- [Accueil](https://renderloop.jnk.ovh/): présentation de RenderLoop, le problème résolu, la boucle capture / modification / recheck, et ce que l'outil détecte de plus qu'un `git diff`.
- [Documentation](https://renderloop.jnk.ovh/docs/): installation, prérequis, démarrage rapide et référence complète de la CLI (actions, options, format JSON, codes de retour).
- [Intégration agents IA](https://renderloop.jnk.ovh/agents/): la boucle de rétroaction à faire suivre à un agent, l'assertion de portée `--expect-selector`, et les pièges à éviter.
- [Démo en ligne](https://renderloop.jnk.ovh/demo/): comparer deux extraits HTML dans le vrai moteur RenderLoop, sans installation.
- [English version](https://renderloop.jnk.ovh/en/): the same site in English, with [docs](https://renderloop.jnk.ovh/en/docs/), [AI agents](https://renderloop.jnk.ovh/en/agents/) and an [English full text](https://renderloop.jnk.ovh/en/llms-full.txt).

## Dépôt et sources

- [Dépôt GitHub](https://github.com/linquant/render-loop): code source, tests, démo (`examples/demo-shop`), journal des modifications et politique de sécurité.
- [AGENTS.md](https://github.com/linquant/render-loop/blob/main/AGENTS.md): mode opératoire destiné aux agents IA qui lisent le dépôt avant d'exécuter quoi que ce soit.
- [llms-full.txt](https://renderloop.jnk.ovh/llms-full.txt): version texte intégrale et autonome de cette documentation, suffisante pour répondre sans lire le HTML du site.

## Installation

```bash
composer require linquant/render-loop
```

Prérequis : PHP 8.2 ou plus, avec les extensions `ext-dom`, `ext-libxml`, `ext-json` et `ext-curl`. Composer exige `ext-curl` à l'installation ; à l'exécution, seule la capture par requête HTTP l'utilise, la stratégie d'envoi de HTML déjà rendu n'appelle pas curl.

## La boucle en trois étapes

1. Capturer l'état rendu **avant** toute modification (`-a capture -u <url> -t before`).
2. Modifier le code, à la main ou via un agent.
3. Relancer `-a recheck -u <url>` : le diff doit contenir uniquement le changement voulu ; tout le reste est une régression.

## Ce que l'outil ajoute

- Masquage du bruit par sélecteurs CSS, jamais par expression régulière sur le contenu : un prix qui tombe à `0.00` reste visible.
- Calibration automatique du bruit (`-a calibrate`) et déclaration manuelle de sélecteurs (`-a mask-add`).
- Golden master pour les pages legacy sans tests (`-a golden-record`, `-a golden-verify`).
- Assertion de portée par édition (`--expect-selector`) avec verdict binaire et code de retour non nul en cas de fuite.
- Rejeu d'endpoints AJAX internes sans navigateur (`--ajax`, `--method`, `--data`, `--header`).
- Pages authentifiées via la variable d'environnement `RENDERLOOP_COOKIE`.

## Limites assumées

- Seul le rendu est couvert : une écriture en base, un export, un PDF ou une réponse d'API restent invisibles.
- Le golden master ne couvre que les entrées déclarées et suppose un rendu déterministe (données figées et masque).
- Le tableau `changes` est au mieux sur du HTML mal structuré ; le diff unifié reste la référence fiable.

## Licence

MIT. Copyright (c) 2026 Johann Nowacki.