# RenderLoop

Version: 0.4.0 — last updated: 2026-10-20

> RenderLoop is a render feedback loop for PHP applications: capture the rendered HTML of a page before a change, then compare it afterwards, so you only see the real change — noise (DebugBar, scripts, CSRF tokens, timestamps) is masked out.

RenderLoop is an open-source PHP library (MIT license) that answers a single question after a code change: "did my edit produce exactly the intended effect, and nothing else?". It compares the **rendered** state of a page before and after, not the diff of the sources. So it also reveals the indirect effects a `git diff` does not show: a modified shared include, a common function, a query that empties a table, a concurrent edit on the same page.

It is a semantic HTML diff, not an image diff: no screenshots and no headless browser are needed for server-side rendered pages. Runtime cost stays low, locally and in CI.

The tool is usable by a human as well as by an AI coding agent. The actions `recheck`, `compare`, `list`, `calibrate`, `mask-add`, `capabilities` and `advise` accept `-f json`; only `recheck` and `compare` produce the compact summary (`lines_added`, `lines_removed`, `hunks`, `tags_touched`, `changes`) designed for a reader on a limited token budget. `capture`, `store`, `golden-record` and `golden-verify` always write text. The `capabilities` action describes the machine contract of the CLI.

## Site pages

- [Home](https://renderloop.jnk.ovh/en/): what RenderLoop is, the problem it solves, the capture / edit / recheck loop, and what the tool detects beyond a `git diff`.
- [Live demo](https://renderloop.jnk.ovh/en/demo/): compare two HTML snippets in the real RenderLoop engine, no install required.
- [Documentation](https://renderloop.jnk.ovh/en/docs/): installation, requirements, quick start and the complete CLI reference (actions, options, JSON format, exit codes).
- [AI agent integration](https://renderloop.jnk.ovh/en/agents/): the feedback loop to give an agent, the `--expect-selector` scope assertion, and the pitfalls to avoid.

## Repository and sources

- [GitHub repository](https://github.com/linquant/render-loop): source code, tests, demo (`examples/demo-shop`), changelog and security policy.
- [AGENTS.md](https://github.com/linquant/render-loop/blob/main/AGENTS.md): operating procedure for AI agents that read the repository before running anything.
- [llms-full.txt](https://renderloop.jnk.ovh/en/llms-full.txt): full standalone text version of this documentation, enough to answer without reading the site's HTML.

## Installation

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

Requirements: PHP 8.2 or higher, with the `ext-dom`, `ext-libxml`, `ext-json` and `ext-curl` extensions. Composer requires `ext-curl` at install time; at runtime, only capturing over an HTTP request uses it — the strategy that pushes already rendered HTML does not call curl.

## The loop in three steps

1. Capture the rendered state **before** any change (`-a capture -u <url> -t before`).
2. Change the code, by hand or through an agent.
3. Run `-a recheck -u <url>` again: the diff must contain only the intended change; everything else is a regression.

## What the tool adds

- Noise masking by CSS selectors, never by regular expression on the content: a price that drops to `0.00` stays visible.
- Automatic noise calibration (`-a calibrate`) and manual selector declaration (`-a mask-add`).
- Golden master for legacy pages without tests (`-a golden-record`, `-a golden-verify`).
- Per-edit scope assertion (`--expect-selector`) with a binary verdict and a non-zero exit code when the change leaks.
- Replay of internal AJAX endpoints without a browser (`--ajax`, `--method`, `--data`, `--header`).
- Authenticated pages through the `RENDERLOOP_COOKIE` environment variable.

## Accepted limitations

- Only rendering is covered: a database write, an export, a PDF or an API response remain invisible.
- The golden master only covers the declared entries and assumes deterministic rendering (frozen data and mask).
- The `changes` table is best-effort on badly structured HTML; the unified diff remains the reliable reference.

## License

MIT. Copyright (c) 2026 Johann Nowacki.