explorbot 0.2.3 → 0.2.4

package/docs/workflow/knowledge.md

@@ -0,0 +1,310 @@
+# Knowledge System
+
+Knowledge files tell explorbot facts about your app. Agents read them to make better decisions about authentication, special workflows, and app-specific behavior.
+
+## Adding Knowledge
+
+### Interactive Mode
+
+```bash
+npx explorbot learn
+```
+
+Opens a TUI form where you can:
+- Enter a URL pattern
+- See existing knowledge for that URL
+- Add new knowledge
+
+### CLI Mode
+
+```bash
+npx explorbot learn "<url-pattern>" "<description>"
+```
+
+Examples:
+
+```bash
+# Login credentials
+npx explorbot learn "/login" "Use credentials: admin@example.com / secret123"
+
+# General knowledge (applies to all pages)
+npx explorbot learn "*" "This is a React SPA. Wait for loading spinners to disappear."
+
+# Specific page behavior
+npx explorbot learn "/checkout" "Credit card field requires format: XXXX-XXXX-XXXX-XXXX"
+```
+
+### Inside TUI
+
+While exploring, use the `/learn` command.
+
+```
+/learn                              # Opens interactive form
+/learn Test user: test@example.com  # Adds to current page
+```
+
+### API Testing
+
+[API testing](../api-testing/basics.md) shares the same `knowledge/` directory. `npx explorbot api know <endpoint> "<description>"` adds endpoint-scoped notes, stored with an `endpoint:` frontmatter field instead of `url:`.
+
+## URL Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `/login` | Exact path `/login` |
+| `/admin/*` | Any path starting with `/admin/` |
+| `*` | All pages (general knowledge) |
+| `^/users/\d+` | Regex: `/users/` followed by digits |
+| `~dashboard~` | Regex: "dashboard" anywhere in URL (tilde on both sides) |
+
+## Knowledge File Format
+
+Knowledge lives in `./knowledge/` as markdown files with frontmatter:
+
+```markdown
+---
+url: /login
+title: Login Page
+---
+
+Test credentials:
+- email: admin@example.com
+- password: secret123
+
+Notes:
+- Submit button disabled until email validates
+- 3 failed attempts triggers captcha
+- "Remember me" checkbox persists session for 30 days
+```
+
+### Frontmatter Fields
+
+| Field | Purpose |
+|-------|---------|
+| `url` | URL pattern to match (optional, defaults to `*`) |
+| `title` | Human-readable title (optional) |
+| Custom fields | Any additional metadata for agents |
+
+## Variables
+
+Knowledge files support variable interpolation with `${namespace.key}` syntax. Explorbot resolves variables when it loads the knowledge.
+
+### Environment Variables
+
+Use `${env.VARNAME}` to reference environment variables. This keeps secrets out of knowledge files.
+
+```markdown
+---
+url: /login
+---
+
+Login credentials:
+- email: ${env.LOGIN}
+- password: ${env.PASSWORD}
+```
+
+Missing environment variables become an empty string.
+
+### Config Variables
+
+Use `${config.path}` to reference values from `explorbot.config.js` with dot notation.
+
+```markdown
+---
+url: *
+---
+
+Base URL: ${config.playwright.url}
+Browser: ${config.playwright.browser}
+```
+
+You can reference any scalar config value. Object values become an empty string.
+
+### Supported Namespaces
+
+| Namespace | Source | Example |
+|-----------|--------|---------|
+| `env` | `process.env` | `${env.API_KEY}` |
+| `config` | `explorbot.config.js` | `${config.playwright.url}` |
+
+Expressions with an unknown namespace (such as `${other.value}`) or no namespace (such as `${value}`) are left as-is.
+
+## Page Automation
+
+Knowledge files can run automation commands when explorbot navigates to a matching page. Use this for loading states, cookie banners, or page-specific setup.
+
+### Available Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `wait` | `number` | Wait for specified seconds after page load |
+| `waitForElement` | `string` | Wait for element to appear (CSS selector) |
+| `code` | `string` | Execute CodeceptJS code after navigation |
+| `statePush` | `boolean` | Use `history.pushState` instead of full navigation |
+
+### Wait for Page Load
+
+```markdown
+---
+url: /dashboard
+wait: 2
+waitForElement: '.dashboard-loaded'
+---
+
+Dashboard requires data to load before interaction.
+```
+
+### Execute Custom Code
+
+```markdown
+---
+url: /app/*
+code: |
+  I.waitForElement('.app-ready');
+  I.click('.cookie-accept');
+  I.wait(1);
+---
+
+App pages need cookie consent dismissed and loading complete.
+```
+
+### CodeceptJS Effects
+
+Knowledge code can use CodeceptJS effects for error handling and retries:
+
+| Effect | Purpose |
+|--------|---------|
+| `tryTo(fn)` | Execute without failing - returns `true`/`false` |
+| `retryTo(fn, maxTries, interval)` | Retry on failure with polling |
+| `within(context, fn)` | Execute within a specific element context |
+
+**Example with effects:**
+
+```markdown
+---
+url: /dashboard
+code: |
+  await tryTo(() => I.click('.cookie-dismiss'));
+  await retryTo(() => {
+    I.click('Reload Data');
+    I.waitForElement('.data-loaded');
+  }, 5, 500);
+---
+
+Dashboard may show cookie banner. Data loads asynchronously - retry reload if needed.
+```
+
+> [!NOTE]
+> Effects are async. Use `await` when you call them in knowledge code.
+
+### SPA Navigation
+
+For single-page apps where a full reload breaks state:
+
+```markdown
+---
+url: /settings/*
+statePush: true
+---
+
+Settings uses client-side routing. Use pushState to preserve app state.
+```
+
+> [!TIP]
+> Use knowledge automation for page-specific behavior. For agent-specific logic, such as code that runs only during testing, use [Agent Hooks](../web-testing/hooks.md) instead.
+
+### Execution Order
+
+When explorbot navigates to a page, automation runs in this order:
+
+1. Navigation (`I.amOnPage()` or `history.pushState`)
+2. `wait` (if specified)
+3. `waitForElement` (if specified)
+4. `code` (if specified)
+
+## What to Document
+
+### Authentication
+
+```markdown
+---
+url: /login
+---
+
+Credentials: test@example.com / testpass123
+OAuth: Use "Continue with Google" for SSO testing
+2FA: Code is always 123456 in test environment
+```
+
+### Form Behavior
+
+```markdown
+---
+url: /checkout
+---
+
+Required fields: name, email, card number, expiry, CVV
+Card format: XXXX-XXXX-XXXX-XXXX
+Test card: 4111-1111-1111-1111, any future expiry, any CVV
+Promo code "TEST10" gives 10% discount
+```
+
+### Navigation Quirks
+
+```markdown
+---
+url: *
+---
+
+- App uses React Router, wait for route transitions
+- Loading spinner class: .spinner-overlay
+- Modals block interaction until dismissed
+- Session expires after 15 minutes of inactivity
+```
+
+### Test Data
+
+```markdown
+---
+url: /users
+---
+
+Test users available:
+- admin@test.com (admin role)
+- user@test.com (standard user)
+- readonly@test.com (view-only permissions)
+```
+
+## How Agents Use Knowledge
+
+When an agent works on a page, it gets the knowledge whose URL pattern matches:
+
+1. **Navigator** — uses credentials and knows about special interactions
+2. **Researcher** — reads page structure and hidden elements
+3. **Planner** — adds edge cases and validation rules to test scenarios
+4. **Tester** — uses test data and expected behaviors
+
+## Best Practices
+
+1. **Start with auth** — add login credentials before exploring protected areas
+2. **Use `*` for globals** — document app-wide behavior such as loading states and timeouts
+3. **Be specific** — give exact selectors, formats, and values when you know them
+4. **Update as you learn** — add knowledge when agents struggle with an interaction
+
+## File Organization
+
+```
+./knowledge/
+├── login.md           # /login page
+├── checkout.md        # /checkout page
+├── general.md         # * (all pages)
+└── admin_users.md     # /admin/users/*
+```
+
+Files are named after the URL pattern. Multiple entries for the same URL append to the same file.
+
+## See Also
+
+- [Agent Hooks](../web-testing/hooks.md) — per-agent custom code execution
+- [Configuration](../reference/configuration.md) — full configuration reference
+- [Page Interaction](../web-testing/page-interaction.md) — how agents interact with pages

package/docs/workflow/planning-styles.md

@@ -0,0 +1,67 @@
+# Planning Styles
+
+A planning style is a markdown rule file that shapes what scenarios get planned. The whole file becomes the planning approach in the agent's prompt — written as instructions to a QA engineer on how to think about test scenarios.
+
+Two agents use styles through the same mechanism: the web [Planner](../web-testing/planner.md) and the API [Chief](../api-testing/basics.md).
+
+## Built-in Styles
+
+Bundled style files live in `rules/planner/styles/` (web) and `rules/chief/styles/` (API):
+
+| Style | Intent |
+|-------|--------|
+| `normal` | Complete user workflows: CRUD and full commit flows that end in a data or state change |
+| `curious` | Coverage gaps: mines previous test results and research to find paths earlier tests missed |
+| `psycho` | Stress tests: feeds empty, invalid, and extreme values to every reachable control, then commits |
+| `hacker` | API only: probes beyond the spec — hidden endpoints, undocumented fields, unprotected actions |
+
+## Cycling
+
+Each planning iteration uses the next style in the list, cycling by index.
+
+**Web Planner** — default order is `normal`, `curious`, `psycho`. The first `/plan` uses normal, the second curious, the third psycho, then the cycle repeats. Override the list and order with the `styles` option in [Planner configuration](../web-testing/planner.md#configuration); a name may appear more than once.
+
+**API Chief** — order is `normal`, `curious`, `psycho`, `hacker`. `api plan` cycles them the same way. `api explore` doesn't cycle: it runs every style once, generating and executing a plan per style.
+
+## Selecting a Style
+
+Force a style for a single run:
+
+```bash
+npx explorbot plan /users --style psycho        # web
+npx explorbot api plan /users --style hacker    # API
+```
+
+The web TUI accepts the same flag: `/plan --style psycho`. `api explore` has no `--style` flag — it always runs all styles.
+
+## Custom Styles
+
+Styles load from `rules/<agent>/styles/<name>.md` in your project first, falling back to the bundled file of the same name. To edit built-in styles, copy the bundled rules into your project:
+
+```bash
+npx explorbot extract-rules planner   # or: chief
+```
+
+This copies the agent's bundled rule files (including styles) to `./rules/<agent>/`, skipping files that already exist. Edit the copies — they take precedence over the bundled versions. Extract only what you want to change; anything you delete falls back to the bundled file.
+
+Style files are plain markdown with no frontmatter. Write the mindset, the patterns to test, what counts as a test, and what to skip.
+
+To add a new web style, create `rules/planner/styles/<name>.md` and add its name to the rotation:
+
+```javascript
+ai: {
+  agents: {
+    planner: {
+      styles: ['normal', 'curious', 'psycho', 'security'],
+    },
+  },
+}
+```
+
+The API Chief has no `styles` config option — customize it by overriding the built-in style files in `rules/chief/styles/`.
+
+## See Also
+
+- [Planner](../web-testing/planner.md) — how web test plans are generated
+- [API Testing](../api-testing/basics.md) — the Chief agent and API commands
+- [Test Plans](./test-plans.md) — the plan file format

package/docs/workflow/reporting.md

@@ -0,0 +1,133 @@
+# Test Reporting
+
+Explorbot generates test reports with [@testomatio/reporter](https://github.com/testomatio/reporter). Reports include test steps, screenshots, and result messages for every run. The [API tester](../api-testing/basics.md) reports through the same reporter, so the HTML and Testomat.io settings below apply to API runs too.
+
+The [Testomat.io cloud reporter](#testomatio-cloud-report) is the recommended way to review runs, especially on CI: pair it with the [Analyst](#session-analysis) and [screencasts](#screencasts) and each run opens with a written overview you can drill from down to a video of any single test. The [HTML](#html-report-local) and [markdown](#markdown-report-local) reports are the local alternatives. For the full CI setup, see [Continuous Integration](./ci.md#reporting-on-ci).
+
+## Session analysis
+
+After `/explore` and `/freesail` runs, the [Analyst agent](../web-testing/agents.md#analyst-agent) writes a summary that clusters findings by root cause.
+
+The same markdown is printed to the console, written to disk, and set as the run description on Testomat.io when the cloud reporter is enabled.
+
+**On disk:** `output/reports/<mode>-<sessionName>.md` — for example `explore-WiseFox42.md` or `freesail-CleverOwl91.md`. Each run gets a unique name, so nothing is overwritten.
+
+**On Testomat.io:** the markdown becomes the run description, so the analysis sits next to the test list in the cloud dashboard with no extra setup.
+
+See [Analyst Agent](../web-testing/agents.md#analyst-agent) for the report format and configuration options.
+
+## Screencasts
+
+Explorbot can record a video of every test instead of leaving you a trail of screenshots. Enable it on the Historian agent:
+
+```js
+export default {
+  ai: {
+    agents: {
+      historian: {
+        screencast: true,  // or { size: { width: 1280, height: 720 }, quality: 95 }
+      },
+    },
+  },
+};
+```
+
+Each test gets one video in `output/screencasts/`, with the executed actions overlaid in the corner and the current scenario step shown as a chapter title — the video narrates itself. The file is attached to the test as an artifact, so with [artifact storage configured](#artifacts-in-cloud-reports) it appears on the test in Testomat.io, ready to watch next to the failure message.
+
+## HTML report (local)
+
+With `html: true` under `reporter` in `explorbot.config.js`, Explorbot creates an HTML report after each run in `output/reports/<mode>-<sessionName>.html`, for example `explore-WiseFox42.html`. Each session gets its own file, so nothing is overwritten. Open it in a browser to review results. Configs generated by `explorbot init` enable it, so new projects get HTML reports out of the box.
+
+![HTML report](https://github.com/testomatio/explorbot/blob/main/docs/assets/html-report.png)
+
+For cloud reporting with history and team features, see [Testomat.io cloud report](#testomatio-cloud-report).
+
+## Markdown report (local)
+
+Explorbot can write a markdown report next to the HTML one. It's plain text, so you can paste it into a PR description, a chat thread, or a CI summary.
+
+Opt in via `explorbot.config.js`:
+
+```js
+export default {
+  reporter: {
+    enabled: true,
+    html: true,
+    markdown: true,
+  },
+};
+```
+
+Output: `output/reports/<mode>-<sessionName>-tests.md`, for example `explore-WiseFox42-tests.md`. Like the HTML report, the filename is session-scoped, so successive runs don't overwrite each other. The `-tests` suffix keeps it distinct from the [Analyst report](#session-analysis), which writes `<mode>-<sessionName>.md` in the same folder.
+
+The markdown report isn't generated unless `markdown: true` is set. Configs generated by `explorbot init` enable it as well.
+
+## Testomat.io cloud report
+
+[Testomat.io](https://testomat.io) provides a cloud dashboard with test history, analytics, and team collaboration. It's free with unlimited test runs.
+
+![Testomat.io cloud report](https://github.com/testomatio/explorbot/blob/main/docs/assets/cloud-report.png)
+
+### Setup
+
+1. Register at [app.testomat.io](https://app.testomat.io).
+2. Create an empty project.
+3. Copy the project API key.
+
+### Run with the key
+
+```bash
+TESTOMATIO=tstmt_your_key_here npx explorbot explore /
+```
+
+Set the key in your shell profile or CI environment so it's always active.
+
+### Options
+
+| Variable | Description |
+|----------|-------------|
+| `TESTOMATIO` | Project API key (required) |
+| `TESTOMATIO_TITLE` | Custom name for the test run |
+| `TESTOMATIO_ENV` | Environment label (e.g. `staging`, `production`) |
+| `TESTOMATIO_SHARED_RUN` | Merge parallel executions into one run |
+| `TESTOMATIO_RUNGROUP_TITLE` | Group successive runs under one heading (overrides `reporter.runGroup`) |
+
+See the [@testomatio/reporter docs](https://github.com/testomatio/reporter/blob/2.x/docs/pipes/testomatio.md) for the full list.
+
+### Run group
+
+Set `reporter.runGroup` to file successive runs under one heading on Testomat.io. There is no built-in default, but configs generated by `explorbot init` set it to today's date (`YYYY-MM-DD`), so all sessions from one day appear together in the dashboard.
+
+Change or remove it via `explorbot.config.js`:
+
+```js
+export default {
+  reporter: {
+    enabled: true,
+    runGroup: 'Smoke Suite',  // any string; remove to disable grouping
+  },
+};
+```
+
+If set, `TESTOMATIO_RUNGROUP_TITLE` from the environment takes precedence over the config.
+
+## Artifacts in cloud reports
+
+Explorbot attaches screenshots to test steps and, when [screencasts](#screencasts) are enabled, a video to every test. To see them in Testomat.io, configure an S3-compatible storage provider under Settings > Artifacts in Testomat.io. Without it, screenshots and screencasts won't appear in cloud reports.
+
+Set these environment variables:
+
+```bash
+S3_ACCESS_KEY_ID=your_access_key
+S3_SECRET_ACCESS_KEY=your_secret_key
+S3_BUCKET=your-bucket-name
+S3_REGION=us-east-1
+```
+
+For non-AWS providers (DigitalOcean Spaces, Cloudflare R2, Google Cloud Storage, Minio), also set:
+
+```bash
+S3_ENDPOINT=https://your-provider-endpoint.com
+```
+
+See the [@testomatio/reporter artifacts docs](https://github.com/testomatio/reporter/blob/2.x/docs/artifacts.md) for provider-specific examples.

package/docs/workflow/test-plans.md

@@ -0,0 +1,90 @@
+# Test Plans
+
+A test plan is a markdown file with a suite of scenarios for the Tester to run. The [Planner](../web-testing/planner.md) generates plans, but the format is plain markdown. You can write plans by hand, edit generated ones, or check them into version control.
+
+Explorbot saves plans to `output/plans/` by default. The same parser loads them whether they were generated or written by hand. [API testing](../api-testing/basics.md) saves and loads its plans in this same format.
+
+The format is a dialect of the [Testomat.io classical markdown format](https://docs.testomat.io/project/import-export/export-tests/classical-tests-markdown-format/). It adds a `### Prerequisite` block that tells Explorbot which page to open before each test.
+
+## Format
+
+```markdown
+<!-- suite -->
+# Plan Title
+
+### Prerequisite
+
+* URL: /relative-path
+
+<!-- test
+priority: critical
+-->
+# Scenario written as a user-facing sentence
+
+## Requirements
+/relative-path
+
+## Steps
+* First step in plain language
+* Second step
+
+## Expected
+* First expected outcome
+* Second expected outcome
+```
+
+One file can hold several suites. Each begins with its own `<!-- suite -->` marker and parses as an independent plan.
+
+## Elements
+
+### `<!-- suite -->`
+
+Marks the start of a plan. The `#` heading on the next line becomes the plan's title. This follows the Testomat.io convention of HTML-comment metadata blocks.
+
+### `### Prerequisite`
+
+Holds the suite-level URL as a single bullet:
+
+```
+* URL: /relative-path
+```
+
+The URL is required. Without it, the suite's tests do not run. Make it relative to the configured base URL (start with `/`), so the same plan runs against staging, production, or a local dev server without edits.
+
+Tests without their own `## Requirements` URL use this URL as their start page. Explorbot navigates to it before each scenario.
+
+### `<!-- test priority: … -->`
+
+Opens a test block. Valid priorities: `critical`, `important`, `high`, `normal`, `low`. Omit it and the priority defaults to `normal`. See [Test Priorities](../web-testing/planner.md#test-priorities) for what each level means.
+
+### `#` Scenario heading
+
+A single `#` heading inside a test block is the scenario description. Write it as a business outcome, not a click path.
+
+### `## Requirements`
+
+A per-test start URL, written as a plain line (no bullet) right under the heading. It overrides the suite Prerequisite URL for this test. The Planner writes it for every test; when authoring plans by hand, give each test its own Requirements URL.
+
+### `## Steps`
+
+A bulleted list (`* `) of planned actions in plain language. The Tester treats these as guidance, not a strict script, and may adapt them to what it sees on the page. To span a step across lines, indent continuation lines with 2 spaces.
+
+The Testomat.io classical format inlines `*Expected*:` inside each step. Explorbot splits actions and outcomes into separate `## Steps` and `## Expected` sections.
+
+### `## Expected`
+
+A bulleted list (`* `) of expected outcomes. Each outcome should describe a verifiable change: a data change, a state change, or a UI change with a side effect. See the Planner's [outcome-strength guidance](../web-testing/planner.md#built-in-styles) for what counts.
+
+The Tester passes a test only when it has verified every expected outcome.
+
+## Reusing saved plans
+
+Saved plans are reusable. Run `npx explorbot explore --configure="new:25%"` to load the matching plan, re-run a subset of its tests, and let the planner generate a few new ones to fill the budget. Filter old picks by priority or style, and order them by priority, file index, or random shuffle. See the [`--configure` reference in commands.md](../reference/commands.md#explore) for the full key list and examples.
+
+## See Also
+
+- [Automated Tests](../web-testing/automated-tests.md) — the runnable Playwright or CodeceptJS files Explorbot writes after executing a plan
+- [Planner](../web-testing/planner.md) — how plans are generated
+- [Planning Styles](./planning-styles.md) — how planning styles shape scenarios
+- [Commands](../reference/commands.md) — `/plan`, `/explore`, `npx explorbot plan`
+- [Rerun](../web-testing/rerun.md) — re-executing generated tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "src/**/*.ts",
     "src/**/*.tsx",
     "bin/**/*.ts",
@@ -119,7 +120,7 @@
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.60",
+    "playwright": "^1.62",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/rules/navigator/verification-actions.md

@@ -105,9 +105,29 @@ Checks that page source does NOT contain expected text.
   I.dontSeeInSource('error-class');
 </example>
 
+### Asserting the state of a control
+
+State means disabled, checked, readonly, required, selected, expanded. A presence assertion says
+nothing about it, so assert it with an attribute selector:
+
+<example>
+  I.seeElement('button[aria-label="Submit"][disabled]');
+  I.dontSeeElement('button[aria-label="Submit"][disabled]');
+  I.seeElement('input[name="accept"][checked]');
+  I.seeElement('button[aria-label="Details"][aria-expanded="true"]');
+</example>
+
+Use I.seeElement for the state you expect and I.dontSeeElement for the state you expect to be
+absent — that pair expresses both directions.
+
+I.seeAttributesOnElements(<locator>, { disabled: true }) also exists, but only takes a state that
+must be PRESENT and does not resolve reliably against a role/text locator. Prefer the selector form above.
+
 <verification_rules>
 Be strict in assertions to avoid false positives.
 Prefer I.seeElement() with ARIA locators - most reliable.
+For a claim about a control's state, assert it with an attribute selector — presence of the element is not evidence of its state.
+If no assertion above can express the claim, say so instead of proposing an assertion that checks something weaker.
 I.see() and I.dontSee() MUST include context parameter.
 For input field values, ALWAYS use I.seeInField() — never check value via CSS attribute selectors or I.seeInSource.
 Prefer text locators (label, name, placeholder) for form fields: I.seeInField('Search', 'value') over I.seeInField('input[name="search"]', 'value').

package/src/action-result.ts

@@ -30,6 +30,7 @@ interface ActionResultData extends WebPageState {
   iframeSnapshots?: Array<{ src: string; html: string; id?: string }>;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  focusedElement?: FocusedElement | null;
   iframeURL?: string;
   links?: Link[];
 }
@@ -74,6 +75,7 @@ export class ActionResult implements ActionResultData {
   private snapshotCache = new TTLCache<string>();
   readonly logFile: string | undefined = undefined;
   readonly ariaSnapshotFile: string | undefined = undefined;
+  readonly focusedElement: FocusedElement | null = null;
   private _ariaSnapshot: string | null | undefined = undefined;
   private _lastExtractedHtml: string | undefined = undefined;
   notes: string[] = [];
@@ -107,6 +109,9 @@ export class ActionResult implements ActionResultData {
     if (data.ariaSnapshotFile !== undefined) {
       this.ariaSnapshotFile = data.ariaSnapshotFile;
     }
+    if (data.focusedElement !== undefined) {
+      this.focusedElement = data.focusedElement;
+    }
 
     // Store HTML in a private property if provided
     if (data.html !== undefined) {
@@ -643,3 +648,9 @@ export class Diff {
     this._ariaChangeCount = ariaDiff.count;
   }
 }
+
+export interface FocusedElement {
+  role: string;
+  name: string;
+  value?: string;
+}