morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #7030] feat(browser): add passive CSS variables and design token extraction #7589

New issue

Open

opened 2026-11-03 13:38:55 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:38:55 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7030
Author: @Humaam-04-06
Created: 10/24/2026
Status: 🔄 Open

Base: main ← Head: feat/web-css-variables-inspection

📝 Commits (10+)

c6d831e feat(browser): add passive CSS variables and design token extraction
7614dcc fix(browser): preserve rejection reason and report discarded root CSS tokens
9fb12ce fix(browser): bound memory and preview string length for rejected CSS variables
5ae7646 fix(browser): sanitize CSS URL credentials, propagate completeness, and preserve token whitespace
ba2b7bd fix(browser): preserve unredacted CSS URL text and surrounding whitespace
7a951af fix(browser): bound URL regex scan time, admit Unicode tokens, and project CSS diffs
1f7bd9c fix(browser): sanitize quoted CSS URLs, scope bundle inputs, and separate capture diff metadata
d171280 fix(browser): preserve untrimmed CSS token identity and validate bundle storage options
1f5aefe fix(browser): compare retained CSS tokens under incomplete inventory, flag redacted values, and reject C1 controls
b42effa chore(browser): merge upstream/main into feat/web-css-variables-inspection

📊 Changes

22 files changed (+2164 additions, -35 deletions)

View changed files

📝 src/application/BrowserEvidence.ts (+3 -0)
📝 src/application/BrowserObservationService.ts (+6 -1)
📝 src/browser/CdpBrowserProvider.ts (+5 -1)
➕ src/browser/CdpCaptureCssVariables.test.ts (+906 -0)
➕ src/browser/CdpCaptureCssVariables.ts (+541 -0)
📝 src/browser/CdpPageCapture.ts (+24 -0)
📝 src/cli/browserCommands.ts (+1 -0)
📝 src/cliObservationOptions.ts (+4 -0)
📝 src/contracts/browserToolContracts.ts (+9 -1)
📝 src/contracts/toolOutputSchemaGroups.ts (+9 -9)
📝 src/cutter/CutterBridgeClient.ts (+6 -2)
📝 src/domain/browserCompleteness.ts (+1 -0)
📝 src/domain/browserObservation.test.ts (+228 -0)
📝 src/domain/browserObservation.ts (+26 -3)
📝 src/domain/browserObservationSchemas.ts (+40 -0)
📝 src/domain/webBundleAnalysis.ts (+4 -2)
📝 src/domain/webCaptureDiff.ts (+121 -8)
📝 src/evm/EvmoleInterfaceProvider.ts (+1 -1)
📝 src/ida/IdaProvider.ts (+1 -1)
📝 tests/boundary/browser/webCaptureDiff.test.ts (+146 -0)

...and 2 more files

📄 Description

Summary

Adds passive extraction of :root CSS custom properties (variables and design tokens) to web page inspection across domain schemas, the Chrome DevTools Protocol (CDP) provider, and the CLI/MCP tool boundaries under --include-css-variables.

Problem and expected behavior

When reverse-engineering and reconstructing web applications and user interfaces from captured browser sessions, agents and analysts need access to design system tokens (color schemes, spacing, typography scales, z-indexes, and design system variables). Previously, inspectWebPage only captured DOM snapshots, scripts, network requests, and storage, leaving CSS custom properties unobserved unless manually queried via console evaluations.

With this change:

inspectWebPage accepts an optional include_css_variables flag (defaults to false).
When enabled, it queries :root computed styles via CDP (CSS.enable, CSS.getComputedStyleForNode, and CSS.disable cleanup).
It extracts and strictly validates --[a-zA-Z0-9_-]+ variables, stripping non-printable/control characters, enforcing size limits (maximum 250 variables, 512 bytes per value, max 5 nested var() references, bounded 2,000 raw intake buffer).
Returns structured facts with deterministic sorting, origin_scope attribution, and diagnostic limitation reporting.

Change and scope

Added browserCssVariablesSummarySchema and input schema options in src/domain/browserObservationSchemas.ts and src/domain/browserObservation.ts.
Implemented captureCssVariables in src/browser/CdpCaptureCssVariables.ts and integrated into src/browser/CdpPageCapture.ts.
Exposed --include-css-variables flag in src/cliObservationOptions.ts, src/cli/browserCommands.ts, and tool schemas in src/contracts/browserToolContracts.ts.
Implemented unit tests for schema parsing/validation, CDP mock connection extraction & error handling, and CLI boundary execution.

Follow the contribution scope.
Ordinary enhancement within existing read-only browser inspection boundaries; maintainer scope decision is not applicable.

Contract and boundary impact

Semantic owner and earliest changed stage: src/domain/browserObservationSchemas.ts (domain contract), then src/browser/ (CDP provider extraction), then src/cli/ (CLI adapter).
Contribution scope fit and linked maintainer decision: Read-only passive observation of browser styling, not applicable.
CLI and MCP/tool-catalog contract: Added --include-css-variables boolean option to CLI rea browser inspect and MCP inspectWebPage.
Provider, bridge, target-format, or platform compatibility: Chrome DevTools Protocol (CDP) CSS and DOM domains. Handled protocol-level rejection gracefully with limitation reporting.
Evidence, artifact, provenance, or reconstruction contract: Returns css_variables object with status, origin_scope, total, retained_count, and sorted items.
Target selection, authority, upstream behavior, and cleanup details: Read-only query; guarantees CSS.disable cleanup in finally block.
Generated metadata, package, or installation impact: Verified via npm run mcp-catalog:check and npm run docs:check.

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated:
- src/domain/browserObservation.test.ts (domain validation, max items, BiDi/control character filtering, nesting depth bounds)
- src/browser/CdpCaptureCssVariables.test.ts (CDP protocol command sequence, error handling, truncation, detached DOM nodes)
- tests/boundary/cli/browserCssVariablesCli.test.ts (CLI argument parsing and tool dispatch)

User-visible CLI/MCP output:

"css_variables": {
  "status": "extracted",
  "origin_scope": "same_origin",
  "total": 2,
  "retained_count": 2,
  "items": [
    { "name": "--primary-color", "value": "#007acc" },
    { "name": "--spacing-unit", "value": "8px" }
  ]
}

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

node scripts/run-typescript.mjs --noEmit — 0 errors across all 5,275 files.
npx.cmd vitest run src/domain/browserObservation.test.ts src/browser/CdpCaptureCssVariables.test.ts tests/boundary/cli/browserCssVariablesCli.test.ts — 23/23 tests passed.
npm.cmd run check:fast — turbo typecheck + lint 2/2 tasks successful.
npm.cmd run format:check — 0 formatting issues across 5,766 files.
npm.cmd run docs:check — 6/6 tasks successful, 9/9 readme conformance tests passed.
npm.cmd run mcp-catalog:check — 4/4 tasks successful.
npm.cmd run build:cached — 3/3 tasks successful.

Compatibility, safety, and release

Breaking changes or migration steps: None. include_css_variables is optional and defaults to false.
Real Hopper/Ghidra, browser, or OS coverage: Validated against CDP protocol contract specifications on Windows.
Security, privacy, process, or containment review: Fully bounded: 250 items max, 512 bytes per value max, 5-level nested var() limit, non-printable & control characters stripped, 2000-variable intake cap to prevent memory exhaustion, detached DOM node resilience (-32000), guaranteed CSS.disable cleanup.

Author readiness

Human owner: @Humaam-04-06

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
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/7030 **Author:** [@Humaam-04-06](https://github.com/Humaam-04-06) **Created:** 10/24/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/web-css-variables-inspection` --- ### 📝 Commits (10+) - [`c6d831e`](https://github.com/morluto/rea/commit/c6d831ec475a55dcc16a873351ca57c13b522c80) feat(browser): add passive CSS variables and design token extraction - [`7614dcc`](https://github.com/morluto/rea/commit/7614dccb7e5473ac25a433a4a49e0636a7e37e93) fix(browser): preserve rejection reason and report discarded root CSS tokens - [`9fb12ce`](https://github.com/morluto/rea/commit/9fb12ce8351561e6337670ba8e9f8f6052198b0a) fix(browser): bound memory and preview string length for rejected CSS variables - [`5ae7646`](https://github.com/morluto/rea/commit/5ae76461cbad1c3c2a6d2444dd401263c2e24b3d) fix(browser): sanitize CSS URL credentials, propagate completeness, and preserve token whitespace - [`ba2b7bd`](https://github.com/morluto/rea/commit/ba2b7bd69ea91d11ef287c27f9f2b996d14c9050) fix(browser): preserve unredacted CSS URL text and surrounding whitespace - [`7a951af`](https://github.com/morluto/rea/commit/7a951afa40614bb1b2f31b7ca588c407a3fcca04) fix(browser): bound URL regex scan time, admit Unicode tokens, and project CSS diffs - [`1f7bd9c`](https://github.com/morluto/rea/commit/1f7bd9c2254aab16b676f7d3a36edee87f4280c3) fix(browser): sanitize quoted CSS URLs, scope bundle inputs, and separate capture diff metadata - [`d171280`](https://github.com/morluto/rea/commit/d17128085f6d6741fa55223f4db7e1132fd76740) fix(browser): preserve untrimmed CSS token identity and validate bundle storage options - [`1f5aefe`](https://github.com/morluto/rea/commit/1f5aefefbe7847008ac910412c21af3282ad3227) fix(browser): compare retained CSS tokens under incomplete inventory, flag redacted values, and reject C1 controls - [`b42effa`](https://github.com/morluto/rea/commit/b42effa4a1da5094bfa0e5319d31b1d5d8d9b8a0) chore(browser): merge upstream/main into feat/web-css-variables-inspection ### 📊 Changes **22 files changed** (+2164 additions, -35 deletions) <details> <summary>View changed files</summary> 📝 `src/application/BrowserEvidence.ts` (+3 -0) 📝 `src/application/BrowserObservationService.ts` (+6 -1) 📝 `src/browser/CdpBrowserProvider.ts` (+5 -1) ➕ `src/browser/CdpCaptureCssVariables.test.ts` (+906 -0) ➕ `src/browser/CdpCaptureCssVariables.ts` (+541 -0) 📝 `src/browser/CdpPageCapture.ts` (+24 -0) 📝 `src/cli/browserCommands.ts` (+1 -0) 📝 `src/cliObservationOptions.ts` (+4 -0) 📝 `src/contracts/browserToolContracts.ts` (+9 -1) 📝 `src/contracts/toolOutputSchemaGroups.ts` (+9 -9) 📝 `src/cutter/CutterBridgeClient.ts` (+6 -2) 📝 `src/domain/browserCompleteness.ts` (+1 -0) 📝 `src/domain/browserObservation.test.ts` (+228 -0) 📝 `src/domain/browserObservation.ts` (+26 -3) 📝 `src/domain/browserObservationSchemas.ts` (+40 -0) 📝 `src/domain/webBundleAnalysis.ts` (+4 -2) 📝 `src/domain/webCaptureDiff.ts` (+121 -8) 📝 `src/evm/EvmoleInterfaceProvider.ts` (+1 -1) 📝 `src/ida/IdaProvider.ts` (+1 -1) 📝 `tests/boundary/browser/webCaptureDiff.test.ts` (+146 -0) _...and 2 more files_ </details> ### 📄 Description ## Summary Adds passive extraction of `:root` CSS custom properties (variables and design tokens) to web page inspection across domain schemas, the Chrome DevTools Protocol (CDP) provider, and the CLI/MCP tool boundaries under `--include-css-variables`. ## Problem and expected behavior When reverse-engineering and reconstructing web applications and user interfaces from captured browser sessions, agents and analysts need access to design system tokens (color schemes, spacing, typography scales, z-indexes, and design system variables). Previously, `inspectWebPage` only captured DOM snapshots, scripts, network requests, and storage, leaving CSS custom properties unobserved unless manually queried via console evaluations. With this change: - `inspectWebPage` accepts an optional `include_css_variables` flag (defaults to `false`). - When enabled, it queries `:root` computed styles via CDP (`CSS.enable`, `CSS.getComputedStyleForNode`, and `CSS.disable` cleanup). - It extracts and strictly validates `--[a-zA-Z0-9_-]+` variables, stripping non-printable/control characters, enforcing size limits (maximum 250 variables, 512 bytes per value, max 5 nested `var()` references, bounded 2,000 raw intake buffer). - Returns structured facts with deterministic sorting, `origin_scope` attribution, and diagnostic limitation reporting. ## Change and scope - Added `browserCssVariablesSummarySchema` and input schema options in `src/domain/browserObservationSchemas.ts` and `src/domain/browserObservation.ts`. - Implemented `captureCssVariables` in `src/browser/CdpCaptureCssVariables.ts` and integrated into `src/browser/CdpPageCapture.ts`. - Exposed `--include-css-variables` flag in `src/cliObservationOptions.ts`, `src/cli/browserCommands.ts`, and tool schemas in `src/contracts/browserToolContracts.ts`. - Implemented unit tests for schema parsing/validation, CDP mock connection extraction & error handling, and CLI boundary execution. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Ordinary enhancement within existing read-only browser inspection boundaries; maintainer scope decision is not applicable. ## Contract and boundary impact - Semantic owner and earliest changed stage: `src/domain/browserObservationSchemas.ts` (domain contract), then `src/browser/` (CDP provider extraction), then `src/cli/` (CLI adapter). - Contribution scope fit and linked maintainer decision: Read-only passive observation of browser styling, not applicable. - CLI and MCP/tool-catalog contract: Added `--include-css-variables` boolean option to CLI `rea browser inspect` and MCP `inspectWebPage`. - Provider, bridge, target-format, or platform compatibility: Chrome DevTools Protocol (CDP) `CSS` and `DOM` domains. Handled protocol-level rejection gracefully with limitation reporting. - Evidence, artifact, provenance, or reconstruction contract: Returns `css_variables` object with `status`, `origin_scope`, `total`, `retained_count`, and sorted `items`. - Target selection, authority, upstream behavior, and cleanup details: Read-only query; guarantees `CSS.disable` cleanup in `finally` block. - Generated metadata, package, or installation impact: Verified via `npm run mcp-catalog:check` and `npm run docs:check`. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: - `src/domain/browserObservation.test.ts` (domain validation, max items, BiDi/control character filtering, nesting depth bounds) - `src/browser/CdpCaptureCssVariables.test.ts` (CDP protocol command sequence, error handling, truncation, detached DOM nodes) - `tests/boundary/cli/browserCssVariablesCli.test.ts` (CLI argument parsing and tool dispatch) - User-visible CLI/MCP output: ```json "css_variables": { "status": "extracted", "origin_scope": "same_origin", "total": 2, "retained_count": 2, "items": [ { "name": "--primary-color", "value": "#007acc" }, { "name": "--spacing-unit", "value": "8px" } ] } ``` For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `node scripts/run-typescript.mjs --noEmit` — 0 errors across all 5,275 files. - `npx.cmd vitest run src/domain/browserObservation.test.ts src/browser/CdpCaptureCssVariables.test.ts tests/boundary/cli/browserCssVariablesCli.test.ts` — 23/23 tests passed. - `npm.cmd run check:fast` — turbo typecheck + lint 2/2 tasks successful. - `npm.cmd run format:check` — 0 formatting issues across 5,766 files. - `npm.cmd run docs:check` — 6/6 tasks successful, 9/9 readme conformance tests passed. - `npm.cmd run mcp-catalog:check` — 4/4 tasks successful. - `npm.cmd run build:cached` — 3/3 tasks successful. ## Compatibility, safety, and release - Breaking changes or migration steps: None. `include_css_variables` is optional and defaults to `false`. - Real Hopper/Ghidra, browser, or OS coverage: Validated against CDP protocol contract specifications on Windows. - Security, privacy, process, or containment review: Fully bounded: 250 items max, 512 bytes per value max, 5-level nested `var()` limit, non-printable & control characters stripped, 2000-variable intake cap to prevent memory exhaustion, detached DOM node resilience (-32000), guaranteed `CSS.disable` cleanup. ## Author readiness Human owner: @Humaam-04-06 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] 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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-11-03 13:38:55 +00:00

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

morluto/rea#7589

No description provided.

Rows
Columns