docs(browser): add an interaction example that captures the visible result

[akram1089]

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.

[N0zoM1z0]

Added follow-up commit 0ef7f787 to clarify capture timing and wait for a page-specific current-results marker. The example now uses the existing wait_for; click timeouts and capture completeness are explicitly distinguished from asynchronous application readiness.

Verified the documented JSON through the named input contract (focused test passed), then ran it through real REA CLI/Chromium against a local delayed-render page: click-only returned complete captures showing Loading; adding the documented wait captured One note. Both reported terminated-owned-process and left no temporary profiles. Markdown formatting and git diff --check passed. No runtime/default/schema changes.

[morluto]

Thanks, @akram1089, for your work on “docs(browser): add an interaction example that captures the visible result.” I appreciate your contribution to REA.