Release 0.5.0

CHANGELOG.md

@@ -2,7 +2,32 @@
 
 All notable changes to this project are documented here.
 
-## 0.4.0 - Unreleased
+## 0.5.0 - Unreleased
+
+### Added
+
+- `journey` command with `replay` alias
+- declarative responsive and interaction scenarios
+- semantic locators by role, accessible name, label, placeholder, text, or test ID
+- allowlisted click, fill, keyboard, viewport, route, text, visibility, checkpoint, and audit actions
+- responsive viewport transitions and keyboard-state verification
+- bounded accessibility scoring at checkpoints and explicit audit steps
+- masked checkpoint screenshots and structured DOM evidence
+- `journey.json`, `accessibility.json`, `JOURNEY_REPORT.md`, and `JOURNEY_CORRECTIONS.md`
+- content-addressed journey manifests
+- journey unit tests and real Chromium passing/failing regression coverage
+
+### Security
+
+- arbitrary JavaScript, CSS selectors, XPath, uploads, and page-provided instructions are not supported by journey files
+- candidate location is revalidated after every completed action
+- cross-origin movement is rejected
+- form-submit controls and Enter inside forms are blocked by default
+- filled values are redacted in stored results
+- form fields are masked in checkpoint screenshots
+- browser request ceilings, Chromium sandboxing, TLS verification, CSP enforcement, popup blocking, dialog dismissal, download blocking, service-worker blocking, and WebSocket restrictions remain active
+
+## 0.4.0 - 2026-07-02
 
 ### Added
 

README.md

@@ -1,23 +1,26 @@
 # Reconstruct
 
-**Turn a web application into a build-ready specification, evaluate the implementation, and generate the corrections.**
+**Turn a web application into a build-ready specification, evaluate the implementation, replay its behavior, and generate the corrections.**
 
-Reconstruct captures observable product evidence, converts it into a provider-neutral AppSpec, exports focused implementation packages for coding agents, and scores a candidate application against the verified source evidence.
+Reconstruct captures observable product evidence, converts it into a provider-neutral AppSpec, exports focused implementation packages for coding agents, scores a candidate against verified source evidence, and replays declarative responsive journeys.
 
-> Observe → Map → Specify → Build → Compare → Correct
+> Observe → Map → Specify → Build → Compare → Replay → Correct
 
-## Reconstruct 0.4
+## Reconstruct 0.5
 
-The evaluation loop is now complete:
+The behavioral verification layer is now available:
 
-- render every recorded candidate route
-- compare candidate screenshots against verified reference PNGs
-- generate route-level visual heatmaps
-- score observable titles, headings, links, buttons, forms, landmarks, and design tokens
-- verify recorded navigation targets and trigger text
-- produce machine-readable and human-readable evaluation reports
-- generate a prioritized correction plan and coding-agent fix prompt
-- return exit code `3` when a completed evaluation fails its required score
+- replay click, fill, keyboard, route, text, visibility, and viewport steps
+- locate controls by semantic role, accessible name, label, text, placeholder, or test ID
+- verify mobile menus, responsive states, keyboard dismissal, and route transitions
+- capture masked checkpoint screenshots and structured DOM evidence
+- run bounded accessibility audits at checkpoints or explicit audit steps
+- redact filled values from stored results
+- block form submission and cross-origin movement by default
+- generate machine-readable results, human reports, and correction briefs
+- return exit code `3` when a completed journey misses its required score
+
+The 0.4 visual and structural evaluation loop remains fully supported.
 
 ## Quick start
 
@@ -62,7 +65,34 @@ npm run reconstruct -- evaluate ./example-app/appspec.json \
   --out ./example-app/evaluation
 ```
 
-`compare` is an alias for `evaluate`.
+Replay a responsive interaction journey:
+
+```bash
+npm run reconstruct -- journey ./journeys/mobile-navigation.json \
+  --candidate http://127.0.0.1:3000 \
+  --allow-private-network \
+  --out ./journey-results/mobile-navigation
+```
+
+`compare` aliases `evaluate`; `replay` aliases `journey`.
+
+## Journey output
+
+```text
+journey-output/
+├── journey.json
+├── accessibility.json
+├── JOURNEY_REPORT.md
+├── JOURNEY_CORRECTIONS.md
+├── JOURNEY_MANIFEST.json
+└── checkpoints/
+    ├── *.json
+    └── *.png
+```
+
+Journey scoring is 80% passed behavioral steps and 20% accessibility. The default overall requirement is 90; the default accessibility requirement is 80.
+
+See [docs/JOURNEYS.md](docs/JOURNEYS.md) for the JSON contract, semantic targets, actions, scoring, outputs, and security boundaries.
 
 ## Evaluation output
 
@@ -79,7 +109,7 @@ evaluation/
 └── diffs/
 ```
 
-The route score is weighted from visual similarity, observable interface structure, and recorded navigation behaviour. The default minimum passing score is 85.
+The route score combines visual similarity, observable interface structure, and recorded navigation behavior. The default minimum passing score is 85.
 
 See [docs/EVALUATION.md](docs/EVALUATION.md) for scoring, output, exit codes, and boundaries.
 
@@ -99,17 +129,19 @@ Every evidence artifact is content-addressed with a SHA-256 digest and byte coun
 
 ## Security-first design
 
-- public-network capture and evaluation by default
+- public-network capture, evaluation, and journeys by default
 - private, loopback, link-local, metadata, multicast, reserved, and special-use destinations denied unless explicitly enabled
-- every browser request revalidated and bounded
+- every browser request and completed journey action revalidated and bounded
+- semantic journey locators only; arbitrary scripts, CSS selectors, and XPath are rejected
+- filled values redacted and form fields masked in screenshots
+- form submission and Enter inside forms blocked by default
 - Chromium sandbox, TLS verification, and CSP enforcement remain enabled
 - downloads, service workers, popups, dialogs, WebSockets, and media resources restricted
 - output written through restrictive staging directories and atomic commits
 - captured page content treated as untrusted evidence, never trusted agent instructions
-- evaluation verifies source evidence before rendering a candidate
 - generated manifests avoid local absolute paths
 
-Application checks reduce risk but do not replace worker-level network isolation in a hosted deployment. Read [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md), and [docs/EVALUATION.md](docs/EVALUATION.md).
+Application checks reduce risk but do not replace worker-level network isolation in a hosted deployment. Read [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md), [docs/EVALUATION.md](docs/EVALUATION.md), and [docs/JOURNEYS.md](docs/JOURNEYS.md).
 
 ## Development
 
@@ -125,14 +157,14 @@ Repository layout:
 ```text
 packages/
 ├── appspec/    # schema, validation, serialization
-└── cli/        # capture, crawl, export, evaluation, correction
+└── cli/        # capture, crawl, export, evaluation, journeys, correction
 ```
 
 ## Scope
 
-Reconstruct documents and compares observable interfaces and behaviour. It does not recover private source code, hidden system prompts, proprietary backend logic, credentials, or authorization rules that are not visible in supplied evidence.
+Reconstruct documents and compares observable interfaces and behavior. It does not recover private source code, hidden system prompts, proprietary backend logic, credentials, or authorization rules that are not visible in supplied evidence.
 
-A high evaluation score does not prove backend correctness, accessibility compliance, data integrity, or production security.
+A high evaluation or journey score does not prove backend correctness, complete accessibility compliance, data integrity, or production security.
 
 Use Reconstruct only for public pages and applications you own or are authorized to evaluate. Respect applicable terms, privacy, intellectual property, and access controls.
 

docs/JOURNEYS.md

@@ -0,0 +1,133 @@
+# Declarative journeys
+
+Reconstruct 0.5 can replay responsive and interaction behavior against a running candidate application.
+
+Journeys are JSON documents. They use semantic locators and a small allowlist of actions instead of CSS selectors or arbitrary browser scripts.
+
+## Run a journey
+
+```bash
+npm run reconstruct -- journey ./journeys/mobile-navigation.json \
+  --candidate http://127.0.0.1:3000 \
+  --allow-private-network \
+  --out ./journey-results/mobile-navigation
+```
+
+`replay` is an alias for `journey`.
+
+The command exits with code `0` when the journey passes, `3` when execution completes but the required score is missed, `2` for invalid input, and `1` for an operational failure.
+
+## Example
+
+```json
+{
+  "version": 1,
+  "name": "Responsive navigation",
+  "startRoute": "/",
+  "viewport": { "width": 390, "height": 844 },
+  "minimumAccessibilityScore": 80,
+  "steps": [
+    {
+      "action": "expect-visible",
+      "target": { "role": "button", "name": "Menu" }
+    },
+    {
+      "action": "click",
+      "target": { "role": "button", "name": "Menu" }
+    },
+    {
+      "action": "expect-visible",
+      "target": { "role": "link", "name": "Pricing" }
+    },
+    { "action": "checkpoint", "name": "mobile-menu-open" },
+    { "action": "press", "key": "Escape" },
+    {
+      "action": "expect-hidden",
+      "target": { "role": "link", "name": "Pricing" }
+    },
+    { "action": "viewport", "width": 1280, "height": 800 },
+    {
+      "action": "click",
+      "target": { "role": "link", "name": "Pricing" }
+    },
+    { "action": "expect-url", "route": "/pricing" },
+    { "action": "audit", "minScore": 80 },
+    { "action": "checkpoint", "name": "pricing-desktop" }
+  ]
+}
+```
+
+## Supported actions
+
+- `goto`: navigate to a same-origin route
+- `click`: click one semantic target
+- `fill`: fill one semantically named field
+- `press`: press an allowlisted keyboard key
+- `viewport`: change the browser viewport
+- `expect-visible`: require one semantic target to be visible
+- `expect-hidden`: require matching semantic targets to be hidden or absent
+- `expect-text`: require visible text
+- `expect-url`: require the exact route and query
+- `checkpoint`: capture a screenshot, DOM evidence, viewport, route, and accessibility result
+- `audit`: require a minimum accessibility score at the current state
+
+## Semantic targets
+
+A target must use exactly one strategy:
+
+```json
+{ "role": "button", "name": "Menu" }
+{ "label": "Email" }
+{ "placeholder": "Search" }
+{ "text": "Pricing" }
+{ "testId": "account-menu" }
+```
+
+`exact` may be added when exact accessible-name or text matching is required. CSS selectors and XPath are not accepted.
+
+## Accessibility signal
+
+The built-in bounded audit checks observable issues including:
+
+- missing document title or language
+- missing or duplicate main landmarks
+- missing or duplicate level-one headings
+- skipped heading levels
+- images without `alt`
+- form controls and interactive elements without accessible names
+- positive `tabindex`
+- duplicate IDs
+- autofocus
+
+This is a fast deterministic signal, not a complete accessibility certification.
+
+## Output
+
+```text
+journey-output/
+├── journey.json
+├── accessibility.json
+├── JOURNEY_REPORT.md
+├── JOURNEY_CORRECTIONS.md
+├── JOURNEY_MANIFEST.json
+└── checkpoints/
+    ├── 004-mobile-menu-open.json
+    ├── 004-mobile-menu-open.png
+    └── ...
+```
+
+The overall score is 80% passed journey steps and 20% accessibility. By default the overall score must reach 90 and the journey accessibility score must reach 80.
+
+Filled values are replaced with `[REDACTED]` in results. Checkpoint screenshots mask inputs, textareas, and selects.
+
+## Security boundaries
+
+- candidate and browser requests use the existing network guard
+- private and loopback addresses require `--allow-private-network`
+- every completed action is checked for same-origin location
+- popups and dialogs are closed
+- WebSockets, downloads, and service workers remain restricted
+- form-submit controls and Enter inside forms are blocked by default
+- journey documents cannot execute arbitrary JavaScript, shell commands, CSS selectors, XPath, uploads, or page-provided instructions
+
+A hosted deployment should still isolate browser workers and enforce network egress outside the application process.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "reconstruct",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "Open-source application reconstruction engine for AI coding agents",
   "license": "Apache-2.0",