RenderLoop — complete documentation (llms-full.txt)
====================================================

Source: https://renderloop.jnk.ovh/en/ — pages: https://renderloop.jnk.ovh/en/docs/, https://renderloop.jnk.ovh/en/agents/ and https://renderloop.jnk.ovh/en/demo/
French full text: https://renderloop.jnk.ovh/llms-full.txt
Repository: https://github.com/linquant/render-loop
Version: 0.4.0 — last updated: 2026-10-20
License: MIT. Author: Johann Nowacki. Composer package: linquant/render-loop.
This document is standalone: it contains enough to answer usage questions without reading the site's HTML.

1. In one sentence
------------------

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, site chrome) being masked automatically.

2. The problem
--------------

After a code change, the useful question is not "what did I write?" but "what did the rendered page change?". A `git diff` shows the source edit; it shows neither the indirect effects (a shared include, a common function, a query that empties a table), nor a change made in parallel on the same page. On a large legacy codebase where a page has no tests, those effects go unnoticed.

RenderLoop compares the rendered state before and after. Anything that changes outside the intended edit is a regression.

    git diff                        RenderLoop
    shows YOUR edit            ->   shows the RENDERED change
      - $price = 1295;              p.price : "1295.00" -> "995.00"
      + $price =  995;          +   a shared include emptied the cart

3. The loop
-----------

1. Capture the rendered state before touching the code: `-a capture -u <url> -t before`.
2. Change the code (by hand or through an agent), and make sure the server actually serves the new file (opcache, build steps).
3. Run `-a recheck -u <url>` again. The diff must contain only the intended change. Everything else is a regression.

Without a "before" capture there is nothing to compare: that is pitfall number one.

4. Installation and requirements
--------------------------------

    composer require linquant/render-loop

The binary is then called `vendor/bin/render-loop` (in a repository checkout: `bin/render-loop`).

Requirements: PHP 8.2 or higher, with `ext-dom`, `ext-libxml`, `ext-json` and `ext-curl`. 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. Composer installs symfony/console (6.4, 7.x or 8.x), symfony/css-selector and sebastian/diff. For development: PHPUnit 11 or 12 and PHPStan 2 (level 10 / max on `src` and `tests`).

In the examples, `render-loop` refers to `vendor/bin/render-loop` when `vendor/bin` is in the `PATH`.

5. Quick start
--------------

    # 1. capture the state BEFORE the change
    vendor/bin/render-loop -a capture -u "http://localhost:8000/my_page.php" -t before

    # 2. change the page (by hand or through an agent)

    # 3. recheck: the diff must contain ONLY the intended change
    vendor/bin/render-loop -a recheck -u "http://localhost:8000/my_page.php"

6. CLI reference
----------------

General form:

    render-loop -a <action> [options]

The default action is `recheck`. Two output formats: `table` (default, human-readable) and `json` (`-f json`, meant for machines and agents) for the actions that support it — see the list in §8.

6.1 capture
-----------

Fetches a page over HTTP (curl) and saves its rendered HTML as a snapshot.

    render-loop -a capture -u "http://localhost:8000/page.php" -t before

Options: `-u/--url` (required), `-t/--tag` (label, e.g. `before`), `-d/--dir`, `-c/--config`, `--allow-host`, `--cookie-name`, `--method`, `--header`, `--data`, `--ajax`.

Text output: `Snapshot saved: <id>`, where the identifier has the form `<directory>_<timestamp>` (for example `page.php_1792491901.2345`). Exit code 0 on success, non-zero on error (URL rejected by the guard, HTTP status greater than or equal to 400, curl failure).

Capturing an internal AJAX endpoint (fragment) without a browser:

    render-loop -a capture -u "http://localhost/ajax/price.php?id=42" --ajax -t before

`--ajax` adds the `X-Requested-With: XMLHttpRequest` header (no duplicate if it is already provided through `--header`). For a POST endpoint:

    render-loop -a capture -u "http://localhost/search" --method POST --data "q=bag&page=2" --ajax -t before

`--data` implies POST if `--method` is not provided. `--header` is repeatable, in the `"Name: value"` format.

6.2 store
---------

Saves already rendered HTML, read from standard input. Used for JS/SPA pages whose HTML is produced by a headless browser or another tool.

    cat rendered.html | render-loop -a store -u "http://localhost/app" -t before

Options: `-u/--url` (required), `-t/--tag` (default `store`), `-d/--dir`, `-c/--config`. An empty STDIN causes an error and a non-zero exit code.

6.3 recheck
-----------

Recaptures the page and compares it to its latest reference: the most recent capture that is not itself a recheck (or the explicitly designated baseline). This is the default action: several successive rechecks therefore do not make the comparison base drift.

    render-loop -a recheck -u "http://localhost/page.php"
    render-loop -a recheck -u "http://localhost/page.php" -f json

Options: `-u/--url` (required), `-d/--dir`, `-c/--config`, `-f/--format`, `--max-hunks`, `--exit-code`, `--expect-selector`, `--allow-host`, `--cookie-name`, `--method`, `--header`, `--data`, `--ajax`.

Exit code: 0 even if the diff is not empty, except with `--exit-code` (behaviour of `git diff --exit-code`). With `--expect-selector`, the confinement verdict drives the exit code.

6.4 compare
-----------

Compares two specific snapshots, designated by their identifier. An identifier has the form `<directory>_<Unix timestamp with 4 decimals>`, for example `page.php_1792491901.2345`.

    render-loop -a list -f json
    render-loop -a compare --from=page.php_1792491901.2345 --to=page.php_1792491902.6789

Options: `--from` and `--to` (required), `-d/--dir`, `-c/--config`, `-f/--format`, `--max-hunks`, `--exit-code`, `--expect-selector`.

Same output shape and same exit codes as `recheck`.

6.5 list
--------

Lists the saved snapshots, optionally filtered by URL.

    render-loop -a list
    render-loop -a list -u "http://localhost/page.php" -f json

Options: `-u/--url`, `-d/--dir`, `-f/--format`.

JSON output: array of objects `{"id": string, "url": string, "tag": string|null, "datetime": string}`. Exit code 0.

    [{"id": "page.php_1792491901.2345", "url": "http://localhost/page.php",
      "tag": "before", "datetime": "2026-10-20 10:15:00"}]

6.6 calibrate
-------------

Captures the same page several times without any change: anything that differs between identical captures is noise (timestamps, counters, tokens). The action suggests the selectors to mask, or writes them to the configuration with `--apply`.

    render-loop -a calibrate -u "http://localhost/page.php"
    render-loop -a calibrate -u "http://localhost/page.php" --samples=4 --apply -c normalizer.json

Options: `-u/--url` (required), `--samples` (number of captures, minimum 2, default 2), `--apply`, `-c/--config`, `-d/--dir`, `-f/--format`, `--allow-host`, `--cookie-name`, `--method`, `--header`, `--data`, `--ajax`.

Two captures are about 1.1 seconds apart to cross a second boundary and make timestamps vary. More samples catch slower noise. JSON output: `{"candidates": [string], "applied": [string]}`. Exit code 0, including when no noise is detected.

6.7 mask-add
------------

Adds noise selectors to the configuration without going through calibration. Useful when you already know that a chat widget or a cookie banner is noise.

    render-loop -a mask-add --selector='.chat-widget' --selector='.cookie-banner' -c normalizer.json

Options: `--selector` (required, repeatable), `-c/--config`, `-f/--format`. The operation is idempotent: no duplicate is added. JSON output: `{"applied": [string]}` with only the selectors actually added. Non-zero exit code if no `--selector` is provided.

6.8 capabilities
----------------

Returns the machine contract of every action: name, summary, required and optional options, shape of the JSON output, semantics of the exit codes.

    render-loop -a capabilities -f json

Options: `-f/--format`. Without `-f json`, it prints a readable summary that points to the JSON version. Exit code 0. This is the recommended entry point for an agent that does not want to parse the help text.

6.9 advise
----------

Returns the operating procedure meant for an AI agent: the loop to follow, how to read the output, and the pitfalls. Where `capabilities` describes the "what", `advise` conveys the "how".

    render-loop -a advise
    render-loop -a advise -f json

Options: `-f/--format`. JSON output: `{"audience": string, "one_liner": string, "workflow": [string], "reading_the_output": [string], "pitfalls": [string]}`. Exit code 0. The content is authoritative at runtime; the repository's AGENTS.md file mirrors it for agents that read the repository first, but in case of divergence, the CLI wins.

6.10 golden-record
------------------

Pins the current rendered output of a suite of representative cases, before a refactor (approval testing / characterization testing).

    render-loop -a golden-record --suite=product

Options: `--suite` (required), `--golden-dir` (default `golden`), `-c/--config`, `-d/--dir`, `--allow-host`, `--cookie-name`, `--method`, `--header`, `--data`, `--ajax`.

The `golden/<suite>.json` manifest declares the cases and the mask:

    {
        "name": "shop",
        "cases": [
            { "id": "catalog",       "url": "http://localhost:8123/index.php" },
            { "id": "product-aeron", "url": "http://localhost:8123/product.php?sku=aeron" }
        ],
        "mask": [".phpdebugbar", ".server-time", "input[name=csrf_token]"]
    }

The normalized output is written to `golden/<suite>/<case>.html`. This file must be committed: the diff is then reviewed in git like an `.approved` file. Text output: number of pinned cases and size of the mask. The manifest's mask is enriched automatically on record, then written back to the file.

6.11 golden-verify
------------------

Recaptures each case of a suite and compares it to its golden. Fails on any rendering drift.

    render-loop -a golden-verify --suite=product

Options: `--suite` (required), `--golden-dir`, `-c/--config`, `-d/--dir`, `--allow-host`, `--cookie-name`, `--method`, `--header`, `--data`, `--ajax`. Output is always text: `-f json` is not supported by this action.

Output per case: `OK`, `CHANGED` (with summary and unified diff) or missing golden. Non-zero exit code if at least one case changed or is missing; 0 if everything matches.

Important point: capture against frozen data, so that the diff reflects the code and not the data.

7. Cross-cutting options
------------------------

- `-a/--action`: capture, store, recheck, compare, list, calibrate, mask-add, golden-record, golden-verify, capabilities, advise. Default: recheck.
- `-u/--url`: URL of the page.
- `-t/--tag`: snapshot label (e.g. `before`).
- `--from`, `--to`: snapshot identifiers for `compare`.
- `--suite`: name of the golden suite (manifest `<golden-dir>/<suite>.json`).
- `--golden-dir`: directory of the golden suites. Default: `golden`.
- `-d/--dir`: snapshot storage directory. Default: `.render-loop/snapshots`.
- `-c/--config`: normalizer configuration file (noise selectors). Default: the `config/normalizer.json` shipped with the package.
- `-f/--format`: `table` or `json`. Default: `table`.
- `--max-hunks`: maximum number of hunks displayed. Default: 40, minimum 1.
- `--allow-host`: host allowed in addition to `localhost` and `127.0.0.1`. Repeatable.
- `--cookie-name`: name of the session cookie. Default: `PHPSESSID`.
- `--samples`: number of calibration captures (minimum 2). Default: 2.
- `--apply`: `calibrate` writes the selectors it found to the configuration.
- `--selector`: noise selector for `mask-add`. Repeatable.
- `--expect-selector`: for `recheck` and `compare`, allowed scope of the change. Repeatable.
- `--exit-code`: non-zero exit code when the diff is not empty (`recheck`, `compare`), like `git diff --exit-code`.
- `--method`: HTTP method of the capture (`POST`, etc.). Default: GET, or POST if `--data` is provided. `--header` adds a `"Name: value"` header (repeatable), `--data` provides the body, `--ajax` adds `X-Requested-With: XMLHttpRequest`.

8. JSON format
--------------

The actions `recheck`, `compare`, `list`, `calibrate`, `mask-add`, `capabilities` and `advise` accept `-f json`. Only `recheck` and `compare` return the diff summary; the others have their own shape, described below. `capture`, `store`, `golden-record` and `golden-verify` always write text: the flag is ignored there. JSON outputs are readable (indentation, Unicode and slashes not escaped).

8.1 Diff (`recheck`, `compare`)

    {
      "summary": {
        "lines_added": 1,
        "lines_removed": 1,
        "hunks": 1,
        "truncated": false,
        "tags_touched": ["p"],
        "changes": [
          { "kind": "text", "selector": "article.product-detail > p.price",
            "context": "Aeron Chair", "before": "$1295.00", "after": "$995.00" }
        ]
      },
      "diff": "--- ...\n+++ ...\n@@ ..."
    }

- `lines_added`, `lines_removed`, `hunks`: counters of the unified diff.
- `truncated`: true if the displayed diff was capped by `--max-hunks`.
- `tags_touched`: names of the tags present in the modified lines.
- `changes`: semantic layer, one entry per localized change.
  - `kind`: `text` (modified content), `added` (node appeared) or `removed` (node disappeared); `before` and `after` carry the values depending on the type.
  - `selector`: best-effort CSS path, degrading from `#id` to `tag.class` then to `tag:nth-of-type(n)`.
  - `context`: text of the nearest heading or label, a readable anchor on legacy HTML without id or class (the `<h1>`, a `<th>`, the previous `<td>` of a key/value row). `null` if nothing close fits.
- `diff`: unified diff of the normalized HTML, always present. It is the reliable foundation; `changes` only enriches it.

For a reader on a token budget: read `summary` first, only unroll `diff` if the summary is not empty, and decide from the JSON summary rather than from the exit code (`recheck` and `compare` return 0 even with a diff, except with `--exit-code`).

With `--expect-selector`, the response gains an `assertion` block:

    "assertion": {
      "expected_selectors": [".price"],
      "satisfied": false,
      "inside_scope_changed": true,
      "reason": "1 change(s) outside the expected scope",
      "out_of_scope": { "lines_added": 1, "lines_removed": 1, "hunks": 1, "diff": "..." }
    }

`out_of_scope` is a diff summary (same fields as `summary`, plus `diff`).

8.2 Other JSON outputs

- `list`: `[{"id": string, "url": string, "tag": string|null, "datetime": string}]`.
- `calibrate`: `{"candidates": [string], "applied": [string]}`.
- `mask-add`: `{"applied": [string]}`.
- `capabilities`: manifest `{"tool": "render-loop", "formats": ["table", "json"], "exit_codes": string, "actions": [...]}`; each action carries `name`, `summary`, `required`, `optional`, `output`, `exit_code`.
- `advise`: `{"audience", "one_liner", "workflow", "reading_the_output", "pitfalls"}`.

9. Noise masking and calibration
--------------------------------

Before comparison, the HTML is normalized: `<script>`, `<style>` blocks and comments are removed by a pre-pass, then the configuration's CSS selectors remove the noise nodes (DebugBar, CSRF tokens, site chrome). Serialization is then stabilized (one node per line) to make the diff readable.

Masking is always done by selector, never by regular expression on the content: a price that drops to `0.00` must stay visible in the diff, not be erased as noise. That is a design rule, not an oversight.

The pre-pass on scripts, styles and comments is an accepted exception: on real malformed HTML, the DOM parser produces a lopsided tree and lets some `<script>` elements through. It only removes non-visible blocks, never a business value.

Configuration shipped by default (`config/normalizer.json`):

    {
        "root_selector": null,
        "noise_selectors": [
            ".phpdebugbar",
            "#phpdebugbar",
            ".phpdebugbar-openhandler-overlay",
            "input[name=csrf_token]",
            "input[name=_token]",
            "input[name=__RequestVerificationToken]",
            "meta[name=csrf-token]"
        ]
    }

`root_selector` restricts the comparison to a subtree; `null` compares the whole document.

Once the library is installed, that file lives under `vendor/` and is read-only: point `-c/--config` to a file of your own project, versioned and editable.

`calibrate` finds the selectors for you (repeated captures without changes; whatever differs is noise). `--samples=N` captures more than twice to catch slower noise. `--apply` writes the results straight into the configuration. `mask-add` lets you declare a known noise yourself without calibration. Both writes are idempotent.

10. Scope assertion (`--expect-selector`)
-----------------------------------------

Rather than scrutinizing the diff, you declare the single selector the edit is allowed to touch, and you get a binary verdict.

    render-loop -a recheck -u "http://localhost/page.php" --expect-selector='.price' -f json

- Exit code 0 if every visible change is confined to the scope; non-zero if a change falls outside it.
- On a leak, the `assertion` block isolates the out-of-scope diff (expected changes are masked) to show the problem without drowning it.
- `satisfied: true` only means that no visible change leaked outside the selector: neither that the edit is correct, nor that the non-rendered effects are fine. A wrong or missing selector produces `satisfied: false` with the reason "matched no element" — never a false pass.
- Mechanics: the expected selectors are temporarily masked, then a new diff is computed; the tool therefore relies on the reliable unified diff, and masking stays selector-based.
- It is a per-edit guard rail, not a frozen regression net: for that, see the golden master.

11. Golden master (legacy pages without tests)
----------------------------------------------

`golden-record --suite=<name>` pins the current rendered output of the manifest's cases; you refactor; `golden-verify --suite=<name>` recaptures and compares, with a non-zero exit code on drift. The `golden/<suite>/<case>.html` file is the reference to commit. The `golden/<suite>.json` manifest declares the cases (`id`, `url`) and the mask. Capture against frozen data, otherwise the diff reflects the data and not the code.

12. Authenticated pages
-----------------------

The session cookie is read from the `RENDERLOOP_COOKIE` environment variable (cookie value), never passed as a command-line argument, where it would be visible in `ps`:

    RENDERLOOP_COOKIE=<value> render-loop -a capture -u "http://localhost:8000/account.php"

The cookie name is adjustable with `--cookie-name` (default `PHPSESSID`). For an authenticated page, combine with `--allow-host` if the host is not local.

13. Security
------------

The capture attaches the user's session cookie: a free-form URL would allow exfiltrating what the user sees to a third-party host. `UrlGuard` therefore restricts the capture to the http(s) scheme and to an allowlist of hosts (local origin: `localhost` and `127.0.0.1`, plus the provided `--allow-host`). Redirects are not followed, because a cross-origin redirect would bypass that guard. Keep the host list narrow. See SECURITY.md in the repository.

14. Programmatic use
--------------------

The engine is independent of any framework:

    use RenderLoop\Model\SnapshotRepository;
    use RenderLoop\Service\{HtmlCompareService, HtmlNormalizer, HtmlDiffer,
        NormalizerConfig, CurlCaptureStrategy, PushedHtmlStrategy, UrlGuard};

    $service = new HtmlCompareService(
        new SnapshotRepository('/var/snapshots'),
        new HtmlNormalizer(NormalizerConfig::default()),
        new HtmlDiffer(),
    );

    $fetch = new CurlCaptureStrategy(new UrlGuard(['localhost']));
    $service->capture('http://localhost/page.php', $fetch, 'before');

    $result = $service->recheck('http://localhost/page.php', $fetch);
    if (!$result->diff->isIdentical()) {
        echo $result->diff->unifiedDiff;
        print_r($result->diff->summary());
    }

    $service->capture('http://localhost/app', new PushedHtmlStrategy($renderedHtml), 'before');

`CaptureStrategy` is the extension point: `CurlCaptureStrategy` fetches a server-side rendered page, bounded by `UrlGuard`, with an optional session cookie and no redirect following; `PushedHtmlStrategy` accepts HTML already rendered elsewhere (headless browser for Vue or React); any other source is obtained by implementing the interface.

15. Bundled examples
--------------------

- The examples are not part of the Composer package (they are excluded from the distribution).
- `examples/demo-shop`: a small PHP shop with deliberate noise and a script that runs and verifies every scenario (masking, real edit, indirect effect, calibration, golden master, scope assertion), through `bash examples/demo-shop/run-demo.sh`.

16. Accepted limitations
------------------------

Catches: a text or structure change in the rendered HTML, an indirect effect (shared include, common function), a concurrent edit on the same page, a leak outside the declared scope, a drift from a committed golden.

Does not catch: a database write, an export, a PDF, an API response, an HTTP header or status code, a purely visual regression (CSS, font, pixels). It is a semantic HTML diff, not an image diff, and a page without a "before" snapshot or a golden has no reference at all.

- Covers rendering only. For critical computation, extract the function and unit-test it: the loop complements tests, it does not replace them.
- 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: without id or class, the selector is a positional path; a structural insertion that shifts those paths makes it collapse to empty. The unified diff remains the always-reliable signal.
- The scope assertion is a per-edit guard rail, not a permanent regression net.
- HTTP redirects are not followed.

17. Exit codes, in summary
--------------------------

- 0: success.
- `recheck` and `compare`: 0 even with a diff, except with `--exit-code` (non-zero if the diff is not empty) or `--expect-selector` (non-zero if a change falls outside the scope).
- `golden-verify`: non-zero if a case changed or a golden is missing.
- Any action: non-zero on error (rejected URL, HTTP error status, empty STDIN, missing required option, unknown action).

18. Contributing and license
----------------------------

See CONTRIBUTING.md. Before a pull request, `composer test` and `composer phpstan` (level 10) must pass. When an action changes, keep the `match` in `src/Command/HtmlCompareCommand.php`, the `capabilities` manifest of the same file and the help text in sync; the content of `advise` lives in `adviceManifest()`. Masking stays selector-based, and the tests are written in French. Security vulnerabilities follow SECURITY.md.

MIT license — see LICENSE. Copyright (c) 2026 Johann Nowacki <johann.nowacki@ponera.fr>.