Add retention, trend reporting, and a browsable demo site

A second, mostly additive pass on top of the enterprise hardening: the
operability features that make formwatch sustainable over time, and a
bundled playground so people can see it work.

History retention. `formwatch prune (--keep-last N | --keep-days D)
[--dry-run]`, plus `keep_last`/`keep_days` config and
FORMWATCH_KEEP_LAST/FORMWATCH_KEEP_DAYS, trims append-only history per form.
Backed by history::prune (Retain::Last/Retain::Days), which only ever
touches *.json run files and uses a total filename tiebreak so same-second
runs stay ordered.

Reporting. history::streaks computes each check's unbroken run of its
current status; the plain-text report adds a "↳ FAIL for the last N run(s),
since <date>" line for chronic non-Pass checks, and the HTML report adds a
streak badge plus a compact trend strip. The HTML report also gained a
client-side toolbar: search by name/URL, filter by status (failing /
warnings / flaky / passing), sort by recency / severity / name, and a live
shown/total count — all self-contained, no external assets.

Demo site and benchmarks. `formwatch demo` serves, from the binary, 35
bundled forms (demo-sites/) covering every built-in check and known edge
case: a clean baseline, missing labels / low contrast / missing alt / no
landmarks, tiny targets and horizontal overflow, validation variants, the
document-upload variants, autofill, lost input vs. explained session loss,
multi-step wizards including slow/keyup-gated/icon-only-next, open and
nested and closed shadow roots, multiple forms on a page, RTL Arabic,
reCAPTCHA/hCaptcha/Turnstile/full-page Cloudflare challenge, and the LLM
wording demos. scripts/benchmark.sh runs monitor over the whole set and
reports timings; BENCHMARKS.md carries the methodology and current numbers
(35 forms / 280 checks, median 12.96s at --wait 1).

Fixes found by building the demo site:
- Mobile usability never reported horizontal overflow: it compared
  documentElement.scrollWidth to window.innerWidth, which under mobile
  emulation already reflects the overflowed width. Now compares against the
  layout viewport (documentElement.clientWidth). New fixture + test.
- Validation counted the <form> element itself as an unlabeled invalid
  field, since form:invalid matches whenever any control inside is invalid.
  Now queries input/select/textarea:invalid plus [aria-invalid=true]. New
  fixture + test.

Also corrects two demo pages that silently did nothing: a JS `var name`
collision with window.name, and a text glyph where an icon-only button
needs an SVG.

fmt, clippy -D warnings, and the full test suite (138 tests) pass.

Author: voidstackloop

.dockerignore

@@ -7,6 +7,6 @@ community-forms/
 docs/
 fixtures/
 tests/
-index.html
+/index.html
 *.md
 !README.md

BENCHMARKS.md

@@ -0,0 +1,70 @@
+# Benchmarks
+
+formwatch drives a real headless Chrome against every form, so its wall-clock
+time is dominated by browser work (page load, axe-core, DOM evaluation), not
+by formwatch's own bookkeeping. To make that measurable and reproducible
+without touching anyone's website, the benchmarks run against the **bundled
+demo site**: [`formwatch demo`](demo-sites/README.md) serves 35 local forms —
+a clean baseline plus a page for every check and known edge case — and
+`monitor demo-sites/forms.yml` checks all of them.
+
+Because everything is served from `127.0.0.1`, there's no network latency in
+these numbers — what's left is browser launch, the eight built-in checks per
+form, screenshot capture, and report writing.
+
+## Latest results
+
+Measured with `RUNS=5 WAIT=1 scripts/benchmark.sh` (median of 5 runs, after
+one warm-up run):
+
+| Forms | Checks/run | Runs | `--wait` | min (s) | median (s) | max (s) | forms/min | checks/s |
+|------:|-----------:|-----:|---------:|--------:|-----------:|--------:|----------:|---------:|
+| 35 | 280 | 5 | 1s | 12.93 | 12.96 | 13.19 | 162.0 | 21.6 |
+
+The 35 demo forms cover a clean baseline, a failing page for most checks, a
+three-step wizard and its slow/keyup/icon-only variants, shadow-DOM and
+nested-shadow forms, a closed shadow root, RTL, lost input vs. explained
+session loss, three bot-protection widgets, and the LLM-wording demos — a
+realistic mix, not 35 trivial pages.
+
+### Environment
+
+- CPU: 13th Gen Intel Core i7-13620H (16 threads)
+- RAM: 46.9 GiB
+- OS: Ubuntu on WSL2
+- Chromium (`~/.cache/formwatch/chrome`): 107.0.5296.0
+- Rust: 1.98.1
+- `--max-concurrent 4` (the default)
+
+## Reproduce
+
+```
+scripts/benchmark.sh                 # 5 runs, --wait 1
+RUNS=10 WAIT=0 scripts/benchmark.sh  # more runs, no idle wait
+PORT=9001 WAIT=3 scripts/benchmark.sh
+```
+
+The script builds the release binary, starts `formwatch demo`, runs
+`monitor` over `demo-sites/forms.yml` repeatedly, and prints the same table.
+Everything is local; it never contacts a third-party site.
+
+## Reading the numbers
+
+- **`--wait` dominates.** Each form's Input-persistence check idles for
+  `--wait` seconds (1s here; the default is 5s). That is deliberate idle
+  time, not overhead — set `WAIT=0` to see the floor. Real `monitor` runs
+  against remote forms add page-load time on top.
+- **Concurrency matters more than raw speed.** `--max-concurrent` (default
+  4) multiplies throughput on multi-core machines at the cost of running
+  more browsers at once; the per-host pacer (`--per-host-delay-ms`) is the
+  polite counterweight.
+- **Screenshots cost something.** Every non-Pass check captures a full-page
+  PNG; `--no-screenshots` trades evidence for speed.
+- **A failing page is slower than a passing one** (screenshots plus the
+  extra validation work), which is why the demo mix matters.
+
+## A note on comparing machines
+
+Absolute seconds vary with CPU, disk, and the Chromium revision, so treat
+the table as an order-of-magnitude reference and re-run the script on your
+own hardware rather than quoting these numbers as a spec.

CHANGELOG.md

@@ -75,6 +75,34 @@ project doesn't have a release yet, so everything below is grouped under
   Ctrl-C. Deliberately read-only — no endpoint accepts a URL, triggers a
   run, or submits anything, so exposing it can't make formwatch touch a
   third-party site.
+- History **retention**: `formwatch prune (--keep-last N | --keep-days D)
+  [--dry-run]` (defaults via `keep_last`/`keep_days` config or
+  `FORMWATCH_KEEP_LAST`/`FORMWATCH_KEEP_DAYS`) trims append-only history
+  per form, touching only `*.json` run files.
+- **Streak/trend reporting**: the report now computes each check's
+  unbroken run of its current status. The plain-text report adds a
+  `↳ FAIL for the last N run(s), since <date>` line for chronic
+  non-Pass checks, and the HTML report adds a streak badge plus a compact
+  coloured trend strip of recent runs.
+- The HTML report gained a client-side toolbar: search by name/URL, filter
+  by status (failing / warnings / flaky / passing), sort by recency,
+  severity, or name, and a live "shown/total" count — all self-contained,
+  no external assets.
+- A bundled **demo site** (`formwatch demo`, pages under `demo-sites/`)
+  with 35 deliberately varied forms covering **every** built-in check and
+  known edge case: a clean baseline; missing labels / low contrast /
+  missing alt / no landmarks; small tap targets and horizontal overflow;
+  validation variants (vague errors, aria-required-only, no required
+  fields, a required checkbox); document-upload variants; autofill;
+  lost input vs. explained session loss; multi-step wizards including
+  slow, keyup-gated, and icon-only-next variants; open, nested, and closed
+  shadow roots; multiple forms on a page; RTL Arabic; reCAPTCHA, hCaptcha,
+  Turnstile, and a full-page Cloudflare challenge; and the LLM-wording
+  demos. Pages are compiled into the binary, so `cargo install` gets them;
+  nothing third-party is contacted.
+- `scripts/benchmark.sh` + [BENCHMARKS.md](BENCHMARKS.md): a reproducible
+  benchmark over the demo site (9 forms / 72 checks, median 4.4s at
+  `--wait 1`), with methodology and caveats.
 - Structured diagnostics via `tracing`, written to **stderr** so
   machine-readable stdout is never corrupted: `-v`/`-vv`/`--quiet` and
   `--log-format json`.
@@ -160,6 +188,20 @@ project doesn't have a release yet, so everything below is grouped under
 
 ### Fixed
 
+- Mobile usability never reported horizontal overflow: the check compared
+  `document.documentElement.scrollWidth` against `window.innerWidth`, but
+  under mobile emulation `innerWidth` already reflects the overflowed
+  width, so the comparison was never true even on a page far wider than a
+  phone. It now compares against the layout viewport
+  (`documentElement.clientWidth`). Found while building the demo site, and
+  now covered by a fixture + regression test.
+- The validation check counted the `<form>` element itself as an unlabeled
+  invalid field: the invalid-field query used a bare `:invalid` scoped at
+  the form, and `form:invalid` matches whenever any control inside is
+  invalid. A form whose *actual* invalid field had a proper
+  `aria-describedby` was therefore failed. Found by building the demo
+  site; fixed to query `input:invalid, select:invalid, textarea:invalid,
+  [aria-invalid=true]`, with a regression fixture and test.
 - A truly **cold** Chrome cache failed to populate: the concurrent-safe
   download created the cache's parent directory but never the private
   temp directory the fetcher writes its archive into, so the very first

README.md

@@ -126,7 +126,12 @@ your own use.
   a textfile-collector path, or serve it). With `--baseline`, accepted
   findings render as `<skipped>` (JUnit) or `baselineState: "unchanged"`
   with a `suppressions` entry (SARIF), so an allow-listed finding doesn't
-  redden a pipeline.
+  redden a pipeline. The plain-text report also shows, for any check that
+  has held a non-Pass status for two or more consecutive runs, a `↳ FAIL
+  for the last N run(s), since <date>` line; the HTML report adds a streak
+  badge, a compact coloured trend strip of recent runs, and a client-side
+  toolbar to search by name/URL, filter by status (failing / warnings /
+  flaky / passing), and sort by recency, severity, or name.
 - `formwatch legal` — print the full authorized-use notice and exit.
 - `formwatch doctor [--json] [--probe-llm]` — check the local environment
   (Chrome availability, writable history/audit directories, config)
@@ -143,6 +148,13 @@ your own use.
 - `formwatch serve [--addr HOST:PORT]` — serve read-only HTTP endpoints
   (`/healthz`, `/readyz`, `/metrics`, `/api/forms`) over the accumulated
   history. See [Service mode](#service-mode).
+- `formwatch prune (--keep-last N | --keep-days D) [--dry-run]` — delete
+  old history runs so a long-lived deployment doesn't grow forever. See
+  [Retention](#retention).
+- `formwatch demo [--addr HOST:PORT]` — serve a bundled demo site of
+  deliberately varied forms (one clean, the rest each tripping a check) so
+  you can see what formwatch catches. See
+  [Demo site & benchmarks](#demo-site--benchmarks).
 - `formwatch completions <shell>` — emit a completion script for bash,
   zsh, fish, PowerShell, or elvish.
 
@@ -233,6 +245,7 @@ fail_on: fail               # or: warn — also fail CI on warnings
 audit_log: var/audit.jsonl
 baseline: .formwatch/baseline.json
 # serve_addr: 127.0.0.1:8080  # formwatch serve bind address
+# keep_last: 50               # formwatch prune: runs to keep per form
 accept_terms: true          # record acknowledgement of the legal notice
 notify:
   webhook_url: https://hooks.slack.com/services/...
@@ -257,6 +270,7 @@ in CI and containers: `FORMWATCH_HISTORY_DIR`, `FORMWATCH_CHECKS_DIR`,
 `FORMWATCH_INSECURE`,
 `FORMWATCH_NO_SANDBOX`, `FORMWATCH_AUDIT_LOG`, `FORMWATCH_BASELINE`,
 `FORMWATCH_SERVE_ADDR`, `FORMWATCH_ACCEPT_TERMS`,
+`FORMWATCH_KEEP_LAST`, `FORMWATCH_KEEP_DAYS`,
 `FORMWATCH_FAIL_ON`, `FORMWATCH_WEBHOOK_URL`, `FORMWATCH_WEBHOOK_ON`,
 `FORMWATCH_LLM`, `FORMWATCH_LLM_PROVIDER`, `FORMWATCH_LLM_MODEL`,
 `FORMWATCH_LLM_API_KEY`, `FORMWATCH_LLM_BASE_URL`,
@@ -397,6 +411,23 @@ It binds to `127.0.0.1` by default; set `--addr`, `serve_addr:`, or
 `/readyz`, or a status page at `/api/forms`. It runs until interrupted
 (Ctrl-C).
 
+## Retention
+
+History is append-only, so a deployment that runs nightly accumulates runs
+forever. `formwatch prune` trims it, per form:
+
+```
+formwatch prune --keep-last 50          # keep the 50 most recent runs of each form
+formwatch prune --keep-days 90          # keep only runs from the last 90 days
+formwatch prune --keep-last 50 --dry-run   # report what would go, delete nothing
+```
+
+`--keep-last` and `--keep-days` are mutually exclusive; both keep the
+newest runs. Defaults can live in config (`keep_last:` / `keep_days:`) or
+`FORMWATCH_KEEP_LAST` / `FORMWATCH_KEEP_DAYS`. `prune` only ever touches
+`*.json` run files and leaves anything else in the history directory
+alone. Run it from the same cron/Action that runs `monitor`.
+
 ## Container
 
 A multi-stage `Dockerfile` builds a small Debian image with Chromium and
@@ -409,6 +440,29 @@ docker build -t formwatch .
 docker run --rm -v "$PWD:/work" -w /work formwatch monitor forms.yml
 ```
 
+## Demo site & benchmarks
+
+Want to see it work before pointing it at anything real? `formwatch demo`
+serves 35 bundled forms — a clean baseline, plus a page for **every** check
+and known edge case (missing labels, low contrast, lost input vs. explained
+session loss, wizards and their slow/keyup/icon-only variants, shadow DOM,
+a closed shadow root, RTL, three bot-protection widgets, vague wording, …):
+
+```
+formwatch demo                        # serves http://127.0.0.1:8099
+formwatch monitor demo-sites/forms.yml
+formwatch report --html --out report.html
+```
+
+The pages are compiled into the binary (`demo-sites/`), so `cargo install`
+gets them too — nothing to copy, and nothing third-party is contacted. See
+[demo-sites/README.md](demo-sites/README.md) for the page-by-page list.
+
+For performance, `scripts/benchmark.sh` runs `monitor` over the demo site
+repeatedly and reports timings; the current reference numbers and how to
+reproduce them are in [BENCHMARKS.md](BENCHMARKS.md) (35 forms / 280 checks
+per run, **median 13.0s** with `--wait 1` and the default concurrency).
+
 ## Requirements
 
 Just a Chrome or Chromium install. If none is found on `PATH`, formwatch

demo-sites/README.md

@@ -0,0 +1,123 @@
+# formwatch demo site
+
+A deliberately varied set of forms for seeing what formwatch does — one
+clean baseline, plus a page for **every** built-in check and the known edge
+cases (shadow DOM, wizards, CAPTCHAs, RTL, lost input, …). It is served by
+`formwatch demo`, which embeds these pages in the binary, so they work after
+a plain `cargo install` with nothing to copy.
+
+## Running it
+
+```
+formwatch demo                 # serves http://127.0.0.1:8099
+formwatch demo --addr 127.0.0.1:9000
+```
+
+Then browse the pages, or point formwatch at them:
+
+```
+formwatch test    http://127.0.0.1:8099/good-form.html
+formwatch test    http://127.0.0.1:8099/lost-input.html --wait 3
+formwatch monitor demo-sites/forms.yml          # every demo form at once
+formwatch report  --html --out report.html      # browse the results
+```
+
+For the optional LLM wording checks:
+
+```
+OPENAI_API_KEY=... formwatch --llm test http://127.0.0.1:8099/vague-errors.html
+```
+
+## Baseline
+
+| Page | Expected headline |
+|---|---|
+| `good-form.html` | everything Passes |
+
+## Submission flow
+
+| Page | Expected headline |
+|---|---|
+| `multi-step.html` | Passes after a 3-step wizard |
+| `slow-step.html` | Passes despite a 1.2s transition |
+| `keyup-next.html` | Passes (Next enabled on `keyup`) |
+| `icon-only-next.html` | Passes via `aria-label` |
+| `no-submit-control.html` | **Fail** — no Next/Continue/Submit |
+| `shadow-form.html` | Passes — form inside an open shadow root |
+| `nested-shadow-form.html` | Validation reaches a doubly-nested shadow field |
+| `closed-shadow.html` | **Fail** "No `<form>` found" — a real platform limit |
+| `multi-form.html` | Targets the bigger form, not the header search |
+| `rtl-arabic.html` | Passes — Arabic Next/Submit wording |
+
+## Accessibility
+
+| Page | Expected headline |
+|---|---|
+| `missing-labels.html` | **Fail** — unlabeled fields |
+| `low-contrast.html` | **Fail** — axe color-contrast |
+| `missing-alt.html` | **Fail** — axe image-alt |
+| `no-landmarks.html` | **Warn** — moderate axe findings |
+
+## Validation errors
+
+| Page | Expected headline |
+|---|---|
+| `vague-errors.html` | described but unhelpful wording (LLM demo) |
+| `aria-required-only.html` | **Warn** — native validation can't exercise it |
+| `no-required-fields.html` | **Warn** — nothing to test |
+| `checkbox-required-first.html` | **Fail** — invalid with no accessible message |
+
+## Required documents
+
+| Page | Expected headline |
+|---|---|
+| `document-upload.html` | **Fail** — no label, no format guidance |
+| `no-format-guidance.html` | **Warn** — labeled but no accept/format text |
+| `documents-prose-no-upload.html` | **Warn** — documents mentioned, no file input |
+| `good-upload.html` | Passes — labeled with `accept` + guidance |
+
+## Autofill hints
+
+| Page | Expected headline |
+|---|---|
+| `no-autocomplete.html` | **Warn** — name/email/phone/address with no hints |
+
+## Input persistence
+
+| Page | Expected headline |
+|---|---|
+| `lost-input.html` | **Fail** — the field silently clears |
+| `session-timeout.html` | **Warn** — cleared, but explained |
+| `no-text-field.html` | **Warn** — nothing to test |
+
+## Mobile usability
+
+| Page | Expected headline |
+|---|---|
+| `tiny-targets.html` | **Warn** — sub-44px controls |
+| `horizontal-overflow.html` | **Warn** — content wider than a phone |
+
+## Bot protection
+
+| Page | Expected headline |
+|---|---|
+| `captcha.html` | **Warn** — reCAPTCHA widget on a testable form |
+| `hcaptcha.html` | **Warn** — hCaptcha widget |
+| `turnstile.html` | **Warn** — Cloudflare Turnstile widget |
+| `cloudflare-challenge.html` | **Warn** — full-page block, no form reached |
+| `generic-botcheck.html` | **Warn** — "prove you're not a robot" wording |
+
+## LLM wording (optional)
+
+| Page | Expected headline |
+|---|---|
+| `vague-errors.html` | Error wording — "Invalid input." |
+| `instructions-unclear.html` | Instructions — vague upload guidance |
+
+Expected results are indicative; real pages vary. The point is to have
+something to click around and compare against.
+
+## Benchmarks
+
+`scripts/benchmark.sh` starts this site and times repeated `monitor` runs
+against it; see [BENCHMARKS.md](../BENCHMARKS.md).

demo-sites/aria-required-only.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ARIA-required only</title>
+<link rel="stylesheet" href="/demo.css">
+</head>
+<body>
+<main>
+  <h1>ARIA-required only</h1>
+  <p class="lede">The field is required via <code>aria-required</code> but
+  not the native <code>required</code> attribute, so the browser's own
+  validation never exercises it — Validation errors should Warn (not a
+  false Pass).</p>
+
+  <form id="f">
+    <label for="name">Full name</label>
+    <input id="name" name="name" type="text" autocomplete="name" aria-required="true" aria-describedby="name-help">
+    <small class="hint" id="name-help">As it appears on your ID.</small>
+    <p><button type="submit">Submit</button></p>
+  </form>
+</main>
+</body>
+</html>