[PR #750] [MERGED] docs(browser): add an interaction example that captures the visible result #2212

New issue

Closed

opened 2026-10-16 21:15:44 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:15:44 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/750
Author: @akram1089
Created: 10/6/2026
Status: ✅ Merged
Merged: 10/6/2026
Merged by: @N0zoM1z0

Base: main ← Head: docs/728-browser-interaction-example

📝 Commits (2)

d4a3e3c docs(browser): add an interaction example that captures the visible result
0ef7f78 docs(browser): wait for asynchronous search results before capture

📊 Changes

3 files changed (+96 additions, -9 deletions)

View changed files

📝 README.md (+6 -2)
📝 docs/browser-scenario-contract.md (+81 -0)
📝 tests/boundary/cli/productCatalog.test.ts (+9 -7)

📄 Description

Summary

Fixes #728.

The browser scenario contract only shows a minimal scenario whose default capture is the final sanitized URL. When an interaction changes the page without navigating (for example, a Search button that renders results in place), that default result reports a successful click and an unchanged URL, and cannot answer what the page displayed. This PR adds a worked interaction example that explicitly selects the artifacts that answer the question, and explains how to choose captures and how to read not_requested versus complete.

Problem and expected behavior

Prior behavior (docs): the only example uses the default capture (at_end: ["url"]). Readers following it for a click interaction get a complete capture that contains only an unchanged URL.
Expected: a current-contract example showing a click on a local page with capture.at_end: ["dom", "accessibility", "url"], the equivalent CLI scenario-file flow, guidance on when to request DOM/accessibility, screenshots, history/storage, or event families, and a clear explanation that not_requested means "not observed" and that completeness: complete covers only requested sections.
The conservative default and analyst choice are preserved: nothing new is captured implicitly, and storage and event families are still opt-in.

Change and scope

docs/browser-scenario-contract.md: new "Interaction example: capture the visible result" section after the minimal example. It contains the scenario JSON from the issue, the rea capture-browser-scenario ./browser-search.json --json flow, an MCP note, capture-selection guidance, and the not_requested / complete explanation.
README.md: one sentence in "Controlled browser scenarios" noting that the default retains only the final URL, and pointing to the new example.
tests/boundary/cli/productCatalog.test.ts: the existing guard parsed only the first json block of the contract doc through the capture_browser_scenario input schema. It now parses every json block, so the new example is checked against the real contract and cannot drift. The fence regex also accepts CRLF, so the test no longer fails on Windows checkouts with core.autocrlf=true. It previously failed there with "Missing browser scenario example".

Not included: no schema, default, or behavior changes, and no new action or origin-permission mechanism (as the issue requests).

Contract and boundary impact

Semantic owner and earliest changed stage: documentation only (browser scenario contract guide)
CLI and MCP/tool-catalog contract: none
Provider, bridge, target-format, or platform compatibility: none
Evidence, artifact, provenance, or reconstruction contract: none (documents existing capture states)
Process execution, authorization, cleanup, or containment impact: none
Generated metadata (docs/product-catalog.json), package, or installation impact: none

Evidence and regression coverage

Tests added or updated: admits every documented browser scenario through the named contract now validates all JSON examples in docs/browser-scenario-contract.md against capture_browser_scenario's inputSchema. It also asserts that at least two examples exist.
Base reproduction or other evidence: field names were verified against src/domain/browserScenarioValues.ts: the click action with a css locator, timeout_ms, the capture.at_end snapshot kinds, and the event family names. Capture state names were verified against src/domain/browserScenarioCaptureValues.ts: not_requested, and completeness.status values complete, incomplete, and truncated.
User-visible CLI/MCP output: not applicable
Remaining proof gaps: the example was not executed against a real browser in this PR. The issue's supporting evidence records an equivalent real run.

Validation performed

npx vitest run tests/boundary/cli/productCatalog.test.ts -t "browser scenario": passed (1 passed)
npx oxfmt on the three changed files: formatted, no remaining issues
The other tests in productCatalog.test.ts need a built dist/ and fail identically on unmodified main in this environment. They are unrelated to this change.

Compatibility, safety, and release

Breaking changes or migration steps: none
Real Hopper/Ghidra, browser, or OS coverage: not applicable (docs and test only)
Package or release metadata impact: none
Security, privacy, process, or containment review: the example uses loopback HTTP and a placeholder executable path, and contains no secrets

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/750 **Author:** [@akram1089](https://github.com/akram1089) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `docs/728-browser-interaction-example` --- ### 📝 Commits (2) - [`d4a3e3c`](https://github.com/morluto/rea/commit/d4a3e3c3544d43ed496520ec49c865b7dffa1389) docs(browser): add an interaction example that captures the visible result - [`0ef7f78`](https://github.com/morluto/rea/commit/0ef7f787f2f2070f1bf7fc3d754f81b3c92229dd) docs(browser): wait for asynchronous search results before capture ### 📊 Changes **3 files changed** (+96 additions, -9 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+6 -2) 📝 `docs/browser-scenario-contract.md` (+81 -0) 📝 `tests/boundary/cli/productCatalog.test.ts` (+9 -7) </details> ### 📄 Description ## Summary Fixes #728. The browser scenario contract only shows a minimal scenario whose default capture is the final sanitized URL. When an interaction changes the page without navigating (for example, a Search button that renders results in place), that default result reports a successful click and an unchanged URL, and cannot answer what the page displayed. This PR adds a worked interaction example that explicitly selects the artifacts that answer the question, and explains how to choose captures and how to read `not_requested` versus `complete`. ## Problem and expected behavior - Prior behavior (docs): the only example uses the default `capture` (`at_end: ["url"]`). Readers following it for a click interaction get a `complete` capture that contains only an unchanged URL. - Expected: a current-contract example showing a click on a local page with `capture.at_end: ["dom", "accessibility", "url"]`, the equivalent CLI scenario-file flow, guidance on when to request DOM/accessibility, screenshots, history/storage, or event families, and a clear explanation that `not_requested` means "not observed" and that `completeness: complete` covers only requested sections. - The conservative default and analyst choice are preserved: nothing new is captured implicitly, and storage and event families are still opt-in. ## Change and scope - `docs/browser-scenario-contract.md`: new "Interaction example: capture the visible result" section after the minimal example. It contains the scenario JSON from the issue, the `rea capture-browser-scenario ./browser-search.json --json` flow, an MCP note, capture-selection guidance, and the `not_requested` / `complete` explanation. - `README.md`: one sentence in "Controlled browser scenarios" noting that the default retains only the final URL, and pointing to the new example. - `tests/boundary/cli/productCatalog.test.ts`: the existing guard parsed only the **first** `json` block of the contract doc through the `capture_browser_scenario` input schema. It now parses **every** `json` block, so the new example is checked against the real contract and cannot drift. The fence regex also accepts CRLF, so the test no longer fails on Windows checkouts with `core.autocrlf=true`. It previously failed there with "Missing browser scenario example". Not included: no schema, default, or behavior changes, and no new action or origin-permission mechanism (as the issue requests). ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation only (browser scenario contract guide) - CLI and MCP/tool-catalog contract: none - Provider, bridge, target-format, or platform compatibility: none - Evidence, artifact, provenance, or reconstruction contract: none (documents existing capture states) - Process execution, authorization, cleanup, or containment impact: none - Generated metadata (`docs/product-catalog.json`), package, or installation impact: none ## Evidence and regression coverage - Tests added or updated: `admits every documented browser scenario through the named contract` now validates all JSON examples in `docs/browser-scenario-contract.md` against `capture_browser_scenario`'s `inputSchema`. It also asserts that at least two examples exist. - Base reproduction or other evidence: field names were verified against `src/domain/browserScenarioValues.ts`: the `click` action with a `css` locator, `timeout_ms`, the `capture.at_end` snapshot kinds, and the event family names. Capture state names were verified against `src/domain/browserScenarioCaptureValues.ts`: `not_requested`, and `completeness.status` values `complete`, `incomplete`, and `truncated`. - User-visible CLI/MCP output: not applicable - Remaining proof gaps: the example was not executed against a real browser in this PR. The issue's supporting evidence records an equivalent real run. ## Validation performed - `npx vitest run tests/boundary/cli/productCatalog.test.ts -t "browser scenario"`: passed (1 passed) - `npx oxfmt` on the three changed files: formatted, no remaining issues - The other tests in `productCatalog.test.ts` need a built `dist/` and fail identically on unmodified `main` in this environment. They are unrelated to this change. ## Compatibility, safety, and release - Breaking changes or migration steps: none - Real Hopper/Ghidra, browser, or OS coverage: not applicable (docs and test only) - Package or release metadata impact: none - Security, privacy, process, or containment review: the example uses loopback HTTP and a placeholder executable path, and contains no secrets ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:15:44 +00:00