The Visual check's framework is written in browser words; separate it from its web layer #432

Closed
opened 2026-11-08 12:45:10 -05:00 by cmoriarty · 1 comment
Owner

What happens. The Visual check is web-only by construction. It runs only when the run changed a file a browser renders and there is a page to open (deliverable-judge, "A judge looks when there is a page to look at"); its brief drives the app through window.__app, freezes motion with page scripts and the page clock, looks through browser or Playwright's tools, and measures with probes that read the DOM. A phone app or a thick client (#304) would get no Visual check at all, not a different one. Meanwhile the parts that are not about the web are written in browser words too, in the specs, the briefs and the issues.

Fix. Name the two layers and keep them apart. The framework is platform-neutral: criteria from scenarios, the look and carry lists between rounds, the report written as it goes, the verdict, the time limit, the filmstrip from frames, the rule that only what needs a person's eyes is left to it. The web layer is how to open the deliverable, how to drive it, how to freeze and measure it, and the gate "a file a browser renders". Reword the specs and briefs so neutral rules use neutral words ("what a person sees", "the deliverable", "a person's eyes"), and mark the web layer as one of several, so #304 adds a simulator layer beside it instead of forking the step.

Done when. The deliverable-judge spec and the judge's brief name the framework and the web layer; a search of the spec's neutral requirements finds no browser words; the gate's requirement says "a file a person sees" with the browser rule as its web case. No behaviour changes on a web run.

Groundwork for #304. From the review of run 182's findings (braid#425).

**What happens.** The Visual check is web-only by construction. It runs only when the run changed a file a browser renders and there is a page to open (deliverable-judge, "A judge looks when there is a page to look at"); its brief drives the app through `window.__app`, freezes motion with page scripts and the page clock, looks through `browser` or Playwright's tools, and measures with probes that read the DOM. A phone app or a thick client (#304) would get no Visual check at all, not a different one. Meanwhile the parts that are not about the web are written in browser words too, in the specs, the briefs and the issues. **Fix.** Name the two layers and keep them apart. The framework is platform-neutral: criteria from scenarios, the look and carry lists between rounds, the report written as it goes, the verdict, the time limit, the filmstrip from frames, the rule that only what needs a person's eyes is left to it. The web layer is how to open the deliverable, how to drive it, how to freeze and measure it, and the gate "a file a browser renders". Reword the specs and briefs so neutral rules use neutral words ("what a person sees", "the deliverable", "a person's eyes"), and mark the web layer as one of several, so #304 adds a simulator layer beside it instead of forking the step. **Done when.** The deliverable-judge spec and the judge's brief name the framework and the web layer; a search of the spec's neutral requirements finds no browser words; the gate's requirement says "a file a person sees" with the browser rule as its web case. No behaviour changes on a web run. Groundwork for #304. From the review of run 182's findings (braid#425).
Author
Owner

Shipped in PR #437 (merged 6a8ee372), archived in PR #438 (visual-check-framework-and-web-layer). The deliverable-judge spec's purpose names the two layers and lists the web layer's eleven requirements; the gate requirement's body is stated for "a file a person sees" with the browser rule as its web case; seven framework requirements and two sentences of the judge's brief drop their browser words; the guide says a simulator (#304) is a layer beside the web one. No behaviour changes on a web run.

Evidence: tests/engine/test_visual_check_layers.py reads the spec, takes the web list from the purpose, and asserts no framework requirement body says browser, page, Playwright, window.__app or DOM. ./tools/test.sh green; ./tools/sim.sh judge-requirement-by-name passes.

**Shipped in PR #437 (merged 6a8ee372), archived in PR #438 (`visual-check-framework-and-web-layer`).** The `deliverable-judge` spec's purpose names the two layers and lists the web layer's eleven requirements; the gate requirement's body is stated for "a file a person sees" with the browser rule as its web case; seven framework requirements and two sentences of the judge's brief drop their browser words; the guide says a simulator (#304) is a layer beside the web one. No behaviour changes on a web run. Evidence: `tests/engine/test_visual_check_layers.py` reads the spec, takes the web list from the purpose, and asserts no framework requirement body says browser, page, Playwright, `window.__app` or DOM. `./tools/test.sh` green; `./tools/sim.sh judge-requirement-by-name` passes.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#432
No description provided.