@surea11y/webdriverio 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Rumoroso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# surea11y-webdriverio
+
+A WebdriverIO binding for [`surea11y`](../surea11y) — scans a real, already-rendered page for accessibility issues using surea11y's DOM-rules engine.
+
+This is a **separate project/package** from `surea11y` itself and from its siblings [`surea11y-playwright`](../surea11y-playwright) and [`surea11y-puppeteer`](../surea11y-puppeteer), kept as its own sibling directory rather than a monorepo subfolder — see `ROADMAP.md` §1 for the reasoning (the same reasoning the two sibling bindings already used).
+
+## Install (local development)
+
+`surea11y` isn't published to npm yet, so this package depends on it via a relative `file:` path (see `package.json`):
+
+```json
+"dependencies": { "surea11y": "file:../core" }
+```
+
+That means this project must stay a sibling of `surea11y` (or you update the path) for `npm install` to resolve it.
+
+```bash
+npm install
+npm test
+```
+
+`webdriverio` is a `devDependency` here. WebdriverIO v9 auto-manages a local `chromedriver` for you the first time it launches Chrome (no separate Selenium server, and no `npx playwright install`-style step needed for `npm test` to work) — so a fresh clone's `npm install && npm test` launches a real headless Chrome on its own.
+
+## Usage
+
+```js
+const { remote } = require('webdriverio');
+const { A11yCoreBuilder } = require('surea11y-webdriverio');
+
+const browser = await remote({
+  capabilities: {
+    browserName: 'chrome',
+    'wdio:enforceWebDriverClassic': true,               // recommended -- see below
+    'goog:chromeOptions': { args: ['--headless=new'] }
+  }
+});
+await browser.url('https://example.com/');
+
+const results = await new A11yCoreBuilder({ browser })
+  .include('#main')            // optional -- call multiple times for multi-region scans
+  .exclude('.cookie-banner')    // optional
+  .withTags(['wcag2a', 'wcag2aa'])
+  .disableRules(['meta-refresh-no-exceptions'])
+  .options({ contrast: { mode: 'auditorAssist' } })
+  .analyze();
+
+console.log(results.checksResults.filter(r => r.outcome === 'fail'));
+await browser.deleteSession();
+```
+
+The builder takes `{ browser }` — the object WebdriverIO's `remote()` returns (standalone mode), or the global `browser` the WDIO testrunner injects (see the E2E section). It must already be navigated to and settled at the URL to scan; the class does not navigate for you.
+
+`results` is surea11y's own native result shape — see [`../surea11y/docs/OUTPUT_SCHEMA.md`](../surea11y/docs/OUTPUT_SCHEMA.md) — not the `violations`/`passes`/`incomplete`/`inapplicable` shape used by other popular accessibility testing tools. The builder's *method names* are modeled on common conventions in this space for migration familiarity; the richer result schema is kept as-is.
+
+Also see `examples/basic-scan.js` for a runnable script (`npm run example -- <url>`).
+
+### A note on the protocol: prefer classic WebDriver for this workload
+
+WebdriverIO v9 defaults to the WebDriver **BiDi** protocol. A long-lived session that issues many `browser.execute()` calls — exactly what an accessibility scan does — degraded badly over BiDi in testing here: per-scan latency climbed from ~2s into the *minutes* and eventually the session started dropping commands (`Couldn't resolve command with id N`). Forcing the **classic** WebDriver protocol with `'wdio:enforceWebDriverClassic': true` in the capabilities gave a steady ~150ms per scan with no degradation, and every operation this binding needs (`execute`, `$`, `$$`, `switchFrame`) is fully supported on it. This project's own tests and examples all set that flag, and it's recommended for yours. The binding itself works under either protocol (it never depends on a BiDi-only feature) — see `ROADMAP.md` §2c/§4 for the full write-up.
+
+### Composing the rule filters
+
+`withTags()`/`disableRules()` above have counterparts: `.withRules([...])` (only run these specific rule IDs) and `.disableTags([...])` (never run rules carrying any of these tags). All four compose the same way similar allow/deny-list options do in other accessibility testing tools, with one non-obvious rule worth knowing: a "disable" always wins over a "with" on the same ID/tag (e.g. `.withRules(['a']).disableRules(['a'])` drops `'a'` entirely), and combining `.withRules()` **and** `.withTags()` together requires a rule to satisfy *both* (surea11y's default `includeMode: 'and'` — see `../surea11y/docs/ENGINE_OPTIONS.md`), not either one.
+
+**Create one builder per scan.** `A11yCoreBuilder` is a mutable object with no reset between `.analyze()` calls — `include()`/`exclude()`/`withRules()`/`disableRules()`/`withTags()`/`disableTags()`/`options()`/`withCustomRules()` all push onto or merge into internal state that persists for the instance's lifetime. Calling one of them again before a second `.analyze()` call *accumulates* on top of the first scan's scope rather than replacing it (this is exactly what makes "call `.include()` several times for one scan," above, work — the same accumulation just also applies across separate scans if you reuse an instance). `.reportOnly()`/`.frames()`/`.elementRef()` are the exception: each call replaces the previous value instead of merging with it.
+
+This binding works against any browser WebdriverIO can drive; the tests and examples use headless Chrome via `chromedriver`, which WebdriverIO manages automatically.
+
+### Using it as an E2E accessibility gate
+
+The pattern above works unchanged inside a real WebdriverIO testrunner spec, which is the pattern that actually matters for a CI/E2E suite (not just an ad hoc script). Inside the testrunner, `browser` is a global you don't construct yourself:
+
+```js
+const assert = require('node:assert');
+const { A11yCoreBuilder, formatFailures } = require('surea11y-webdriverio');
+
+describe('accessibility gate', () => {
+  it('has no accessibility violations', async () => {
+    await browser.url('https://example.com/');
+
+    const results = await new A11yCoreBuilder({ browser }).reportOnly(['fail']).analyze();
+
+    assert.strictEqual(results.checksResults.length, 0, formatFailures(results.checksResults));
+  });
+});
+```
+
+See `examples/e2e-test-example.test.js` for a fuller, runnable version (`npm run example:e2e`), driven by `examples/wdio.conf.js` — one test proving real violations get caught (unlabeled button, missing `alt`), one proving a well-formed page passes cleanly. It uses the **WebdriverIO testrunner** (`@wdio/cli` + mocha), which is how real WebdriverIO suites are written — unlike the sibling Puppeteer project, which used `node:test` because Puppeteer ships no first-party runner (`ROADMAP.md` §6 has the full reasoning). This project's own *unit* suite (`tests/*.test.js`) still uses `node:test` + `remote()`, the right tool for exercising the builder API in isolation.
+
+Note the gate above uses `node:assert`, not WebdriverIO's bundled `expect`: WebdriverIO's `expect` takes **at most one argument** — there's no `expect(value, message)` custom-failure-message overload the way Playwright's `expect` has — so `node:assert`'s message parameter is what carries `formatFailures()`' readable block onto a failed assertion.
+
+### Readable console/CI output on failure
+
+A bare length/equality assertion alone gets you a *working* gate, but the failure message is a raw, deeply-nested object diff — hundreds of lines for a handful of violations. `formatFailures(checksResults)` turns that into a short, scannable block (one entry per occurrence, numbered, with rule ID/severity/selector/hint) that you hand to your assertion library's own failure-message parameter, as above. A real failure then prints:
+
+```
+1) button-name-present (serious): This button has no accessible name.
+   at html > body > button
+   Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.
+2) img-alt-present (serious): Missing alt attribute on <img>.
+   at html > body > img
+   Add an alt attribute (use alt="" only for decorative images).
+```
+
+Deliberately a plain function, not a custom matcher — no dependency on any particular assertion library, so it works the same with `node:assert`, WebdriverIO's `expect`, Jest, Vitest, or a hand-rolled `if`/`throw`. Defaults to `fail`/`cantTell` outcomes (the only two that ever carry occurrences); pass `{ outcomes: [...] }` to narrow further. A thrown rule (`occurrences: []`, `error` set — see `../surea11y/docs/OUTPUT_SCHEMA.md`) is still surfaced using its `error` message rather than silently dropped.
+
+### Scanning every frame, including cross-origin and nested iframes
+
+```js
+const results = await new A11yCoreBuilder({ browser }).frames(true).analyze();
+
+console.log(results.topFrame.checksResults.filter(r => r.outcome === 'fail'));   // the top-level page
+for (const frame of results.frames) {
+  console.log(frame.checksResults.filter(r => r.outcome === 'fail'));            // each sub-frame, same result shape
+}
+```
+
+`results.frames` is a **flat array**, one entry per sub-frame at any depth (nested iframes-within-iframes included), matching the shape the Puppeteer/Playwright bindings return.
+
+The mechanics here are genuinely different from those bindings, though, because WebdriverIO's frame model is different. Puppeteer/Playwright expose `page.frames()` — an array of independent `Frame` objects, each with its own `.evaluate()`/`.$()` — so a binding can iterate them freely. WebdriverIO instead has a single **stateful current context**: `browser.switchFrame(iframeElement)` changes which document `browser.execute()`/`browser.$()` run against, and `browser.switchFrame(null)` returns to the top-level frame. There is no array of frame objects. So `.frames(true)` enumerates each context's direct-child `<iframe>` elements with `browser.$$('iframe')`, switches into each, scans the now-current document, and recurses into that frame's own children (re-navigating from the top each time, since element references and BiDi context ids don't reliably survive a context switch). Cross-origin iframes are reached with no extra work — WebdriverIO's automation layer switches into them the same as same-origin ones, exactly like Puppeteer/Playwright's CDP does.
+
+Verified against a real cross-origin page (`https://example.org/` embedded in an unrelated origin) and against a real nested-iframe page (top → child → grandchild) — see `ROADMAP.md` §2c and `tests/builder.test.js`. Default off, so plain `.analyze()` is unaffected unless you opt in. Unlike script-injection-based accessibility tools (which need a `postMessage`-based protocol to reach cross-origin iframes, since they're injected as a plain `<script>` subject to the same-origin policy), this needs no `surea11y` engine support at all.
+
+### Trimming the result to just violations
+
+By default `analyze()` returns every rule's outcome, including `pass`/`notApplicable` — surea11y's own deliberate "not a violations-only list" design (see `../surea11y/docs/OUTPUT_SCHEMA.md`). Use `.reportOnly()` to post-filter down to only the outcomes you care about:
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .reportOnly(['fail', 'cantTell'])
+  .analyze();
+
+console.log(results.checksResults); // only fail/cantTell entries, pass/notApplicable dropped
+```
+
+Valid outcome values are `'pass'`, `'fail'`, `'cantTell'`, `'notApplicable'`. This is pure binding-layer filtering — surea11y itself still computes every rule; nothing about the scan itself changes. Combines with `.frames(true)`: the filter is applied to `results.topFrame` and each entry of `results.frames` independently.
+
+### Getting a live element, not just a selector string
+
+By default each occurrence carries a CSS selector + HTML snippet, not a live reference to the element. Opt in to a real `WebdriverIO.Element` with `.elementRef(true)`:
+
+```js
+const results = await new A11yCoreBuilder({ browser }).elementRef(true).analyze();
+
+const [failing] = results.checksResults.filter(r => r.outcome === 'fail');
+await failing.occurrences[0].element.saveScreenshot('./flagged.png');
+await failing.occurrences[0].element.click();
+```
+
+This resolves `occurrence.selector` to a `WebdriverIO.Element` (via `browser.$()`) and attaches it as **`occurrence.element`** — instead of leaving you to re-resolve a possibly-stale selector string yourself. Default off — resolving an element per occurrence is a real page query per occurrence, so it costs more than a plain `.analyze()`.
+
+Two WebdriverIO-specific differences from the sibling bindings' `.elementRef(true)`, both real and worth knowing:
+
+- **The field is `occurrence.element`, not `occurrence.elementHandle`.** WebdriverIO has no "handle" concept — `browser.$()` returns a `WebdriverIO.Element`. Its API differs too: read a property with `.getProperty('id')` (not Puppeteer's `.evaluate(el => el.id)`), screenshot with `.saveScreenshot(path)` (not `.screenshot({ path })`). See the [WebdriverIO element API](https://webdriver.io/docs/api/element).
+- **A sub-frame element is only usable while switched into its frame.** WebdriverIO element references are bound to whichever frame was the current context when they were resolved. When you combine `.frames(true).elementRef(true)`, a *sub-frame* occurrence's `element` is resolved against that frame's own document (correct), but after `analyze()` returns the browser is back at the top-level frame — so to act on a sub-frame element you must `browser.switchFrame()` back into its frame first (`browser.switchFrame((await browser.$$('iframe'))[i])`). Top-frame occurrences have no such caveat. This is a direct consequence of WebdriverIO's stateful context model and has no analogue in Puppeteer/Playwright, whose handles are bound to an execution context, not a mutable "current frame." See `ROADMAP.md` §2d.
+
+Not every occurrence has one target element — a page-wide finding (some `manual`/`cantTell` rules) can carry `selector: ""`, in which case `occurrence.element` is `null` rather than an element. (WebdriverIO's `browser.$('')` actually *throws* `invalid selector: No selector specified`, unlike Puppeteer/Playwright's `.$('')` which resolves to `null` — so the empty-selector guard that produces this `null` matters even more here; verified with a real run.)
+
+### Registering a custom rule at runtime
+
+`surea11y` supports registering additional rules per-scan via `engineOptions.customRules`. Use `.withCustomRules()` to register one:
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .withCustomRules({
+    id: 'my-org-custom-rule',
+    meta: { title: 'My custom rule', tags: ['custom'], defaultSeverity: 'serious' },
+    // A real, live function is fine here -- .withCustomRules() converts it
+    // to a function-source string for you (see below for why that matters).
+    runInPage(ctx) {
+      const el = ctx.document.querySelector('.my-widget');
+      return el ? { outcome: 'fail', occurrences: [{ __node: el }] } : { outcome: 'notApplicable', occurrences: [] };
+    }
+  })
+  .analyze();
+```
+
+A custom rule descriptor is the same shape as one of surea11y's own internal rule modules (`{ id, meta, runInPage, applicability?, data? }`) — see `../surea11y/docs/ENGINE_OPTIONS.md` for the full contract. Results appear in `checksResults` exactly like a built-in rule's, including automatic `selector`/`html`/`structuralPath` fill-in. Registered per-scan only (nothing persists between calls or shows up in any catalog listing), and a custom rule whose `id` collides with a built-in one overrides it for that scan.
+
+Pass an array to register several at once, or call `.withCustomRules()` again to add more — like `.withRules()`/`.withTags()`, it accumulates rather than replacing what was already registered:
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .withCustomRules([firstRule, secondRule])
+  .withCustomRules(thirdRule) // adds a third, doesn't replace the first two
+  .analyze();
+```
+
+**Why `.withCustomRules()` instead of the raw `.options({ customRules })` passthrough** (still supported, and composes with this method if you use both): `runInPage`/`applicability` must reach the page as a function-source *string*, not a live `Function` — a WebdriverIO `browser.execute()` argument crosses a serialization boundary that can't carry a live function reference, only a string surea11y can reconstruct with `new Function` on the page side. Passing a raw live function via `.options()` directly would silently fail to serialize; `.withCustomRules()` calls `.toString()` on a live function for you (patching the ES6 method-shorthand `.toString()` quirk automatically — see `ROADMAP.md` §2a), so you can write a normal function and not have to remember that constraint yourself. A string is still accepted as-is if you already have one.
+
+Invalid input (a missing/empty `id`, or a `runInPage`/`applicability` that's neither a function nor a non-empty string) throws immediately from `.withCustomRules()` itself, rather than surfacing later as a silently-skipped rule deep inside the page — easier to catch during development. (Note: a *raw* `.options({ customRules })` call bypasses this check entirely and defers to surea11y's own engine-side behavior, which silently skips an invalid descriptor rather than throwing — see `../surea11y/docs/ENGINE_OPTIONS.md`.)
+
+### Element addressing beyond a CSS selector
+
+Every occurrence already carries `selector` and (with `.elementRef(true)`, above) a live `element`. It also carries `structuralPath` — a sibling-index path from the document root down to the flagged element (e.g. `[1, 0, 2]`) — a more robust identity than a selector string alone, since it survives some DOM changes a selector wouldn't (an id/class rename, for instance). No opt-in needed; it's already on every `fail`/`cantTell` occurrence today. See `../surea11y/docs/OUTPUT_SCHEMA.md` for the full field description.
+
+## TypeScript
+
+`src/A11yCoreBuilder.d.ts` (re-exported from `src/index.d.ts`, wired up via `package.json`'s `types` field) ships hand-written types for the whole builder API plus surea11y's native result shapes (`A11yCoreResult`, `CheckResult`, `Occurrence`, `CompositeResult`, etc.), mirrored from `../surea11y/docs/OUTPUT_SCHEMA.md`. `analyze()` is typed `Promise<A11yCoreResult | A11yCoreMultiFrameResult>` — narrow on `'topFrame' in results` (or cast, if you already know which mode you called) to get the specific shape back, since a fluent builder can't statically track that `.frames(true)` was called earlier in the chain. `occurrence.element` is typed `WebdriverIO.Element | null`. `webdriverio` is a `peerDependencies` entry (not just `devDependencies`) since the class's `browser` argument and `Occurrence#element` both come from its global `WebdriverIO` type namespace — consumers need their own `webdriverio` install for the types to resolve, same as they already do to construct a `browser` in the first place. Verified with a real `tsc --strict` compile against a throwaway consumer script exercising every builder method and both `analyze()` return shapes (see `ROADMAP.md` §4).
+
+## Relationship to `surea11y-playwright` and `surea11y-puppeteer`
+
+This binding's builder API is deliberately the same shape as [`surea11y-playwright`](../surea11y-playwright)'s and [`surea11y-puppeteer`](../surea11y-puppeteer)'s — same method names, same mutability contract, same result shapes — so the accessibility-gate logic reads almost identically across all three. The state-accumulation half of the builder (`include`/`exclude`/`withTags`/`disableTags`/`withRules`/`disableRules`/`options`/`withCustomRules`/`reportOnly`) used to be copied near-verbatim across every binding; as of `ROADMAP.md` §8 it's no longer copied at all — `A11yCoreBuilder` here extends `A11yCoreBuilderBase` from [`../surea11y-binding-base`](../surea11y-binding-base), the single shared implementation every sibling binding now depends on.
+
+Where it genuinely diverges is WebdriverIO's driver model, and those differences are real, not cosmetic:
+
+- **`analyze()`'s injection call** is variadic like Puppeteer's (`browser.execute(runa11yCoreInPage, url, ctx, opts, runOnly)`) — no single-arg wrapper/`eval()` trick the Playwright binding needs.
+- **`.frames(true)`** can't iterate a `page.frames()` array (there isn't one) — it drives WebdriverIO's stateful `switchFrame()` context model instead, recursing to reach nested frames. See above and `ROADMAP.md` §2c.
+- **`.elementRef(true)`** attaches `occurrence.element` (a `WebdriverIO.Element`), not `occurrence.elementHandle`, with the sub-frame-context caveat described above.
+- **Protocol:** classic WebDriver is strongly preferred over WebdriverIO v9's default BiDi for this execute()-heavy workload (see above and `ROADMAP.md` §4).
+
+Also see [`../surea11y/docs/BINDING_AUTHORS_GUIDE.md`](../surea11y/docs/BINDING_AUTHORS_GUIDE.md) — `surea11y`'s own reference for building a binding like this one (it names WebdriverIO explicitly as a candidate next binding), distinguishing what's already engine-level (a generic `.options()`/`runOnly` passthrough, WCAG-version tag filtering, `structuralPath`) from what every binding has to build itself (element refs, `reportOnly`-style verbosity filtering, the serialization-boundary caveat `.withCustomRules()` exists to paper over).
+
+## Status and what's next
+
+See `ROADMAP.md` — it documents what's built, what's verified with a real passing run, and what's still open.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@surea11y/webdriverio",
+  "version": "0.1.1",
+  "description": "WebdriverIO binding for surea11y -- scan real, live-rendered pages for accessibility issues.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "author": "Jorge Rumoroso",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rumoroso/surea11y-core-webdriverio.git"
+  },
+  "homepage": "https://github.com/rumoroso/surea11y-core-webdriverio#readme",
+  "bugs": {
+    "url": "https://github.com/rumoroso/surea11y-core-webdriverio/issues"
+  },
+  "engines": {
+    "node": ">=18.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@surea11y/core": "^1.1.0",
+    "@surea11y/binding-base": "^0.1.0"
+  },
+  "peerDependencies": {
+    "webdriverio": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@wdio/cli": "^9.30.0",
+    "@wdio/local-runner": "^9.30.0",
+    "@wdio/mocha-framework": "^9.30.0",
+    "@wdio/spec-reporter": "^9.29.1",
+    "webdriverio": "^9.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.js\"",
+    "example": "node examples/basic-scan.js",
+    "example:e2e": "wdio run examples/wdio.conf.js"
+  }
+}

package/src/A11yCoreBuilder.d.ts

@@ -0,0 +1,214 @@
+// Pull in WebdriverIO's global type augmentation (WebdriverIO.Browser /
+// WebdriverIO.Element live on a `declare global { namespace WebdriverIO }`,
+// not as named module exports) -- see webdriverio's own build/types.d.ts.
+import type {} from 'webdriverio';
+
+// See surea11y's docs/OUTPUT_SCHEMA.md -- this file mirrors that document's
+// shapes exactly (plus the `element` field this binding adds on top when
+// .elementRef(true) is used). Keep in sync with that doc, not the other way
+// around -- it's the source of truth for what the engine actually returns.
+
+export type Outcome = 'pass' | 'fail' | 'cantTell' | 'notApplicable';
+export type OutcomeNormalized = 'pass' | 'fail' | 'cantTell' | 'inapplicable';
+export type Severity = 'minor' | 'moderate' | 'serious' | 'critical';
+export type Confidence = 'high' | 'medium' | 'low';
+export type RuleType = 'automatic' | 'manual';
+export type Category = 'perceivable' | 'operable' | 'understandable' | 'robust' | null;
+
+export interface EngineInfo {
+  tag: string;
+  schemaVersion: string;
+}
+
+export interface NormativeMapping {
+  standard: string;
+  version: string;
+  requirement: string;
+  title: string;
+  conformanceLevel: string;
+}
+
+export interface CheckResultMeta {
+  ruleId: string;
+  ruleInterfaceVersion: string;
+  ruleVersion: string;
+  normative: boolean;
+  atomic: boolean;
+  category: Category;
+  normativeMappings: NormativeMapping[];
+  standard: string | null;
+  applicability: string;
+  expectation: string;
+  references: string[];
+  requirements: Record<string, unknown> | null;
+  mappings: Record<string, unknown> | null;
+}
+
+export interface VisibilityFilter {
+  targetSet: string;
+  accEligible: boolean | null;
+  reasons: string[];
+}
+
+export interface Occurrence {
+  selector: string;
+  html: string;
+  structuralPath: number[] | null;
+  summary: string;
+  hint: string;
+  i18n: { summaryKey: string; hintKey: string; params: Record<string, unknown> } | null;
+  data: {
+    visibilityFilter?: VisibilityFilter;
+    details?: Record<string, unknown>;
+  };
+  /**
+   * Only present when `.elementRef(true)` was used. `null` when this
+   * occurrence has no single resolvable target element (e.g. `selector` was
+   * `""`) -- see A11yCoreBuilder#elementRef. Named `element` (a
+   * `WebdriverIO.Element`), not `elementHandle` as in the Puppeteer/Playwright
+   * bindings -- WebdriverIO has no "handle" concept. A sub-frame occurrence's
+   * element is only usable while the browser is switched into that frame; see
+   * A11yCoreBuilder#elementRef and ../ROADMAP.md §2d.
+   */
+  element?: WebdriverIO.Element | null;
+}
+
+export interface CheckResult {
+  ruleId: string;
+  outcome: Outcome;
+  outcomeNormalized: OutcomeNormalized;
+  severity: Severity;
+  confidence: Confidence;
+  type: RuleType;
+  occurrences: Occurrence[];
+  title: string;
+  description: string;
+  i18n: { titleKey: string; descriptionKey: string } | null;
+  meta: CheckResultMeta;
+  engineOptions: Record<string, unknown>;
+  schemaVersion: string;
+  /** Present only if the rule threw, or the manual-fail-to-cantTell coercion fired. */
+  error?: string;
+}
+
+export interface CompositeResultDetails {
+  reasonCode: string;
+  checksIds: string[];
+  contributors: Array<{ testId: string; outcome: string; severity: string | null }>;
+  metrics: {
+    failCount: number;
+    cantTellCount: number;
+    notApplicableCount: number;
+    passCount: number;
+    missingCount: number;
+  };
+}
+
+export interface CompositeResult {
+  ruleId: string;
+  outcome: Outcome;
+  severity: Severity;
+  confidence: Confidence;
+  type: RuleType;
+  title: string;
+  description: string;
+  meta: CheckResultMeta;
+  engineOptions: Record<string, unknown>;
+  schemaVersion: string;
+  /** Always empty -- composites are rollups, not element-level findings. */
+  occurrences: [];
+  data: { details: CompositeResultDetails };
+}
+
+/** surea11y's native top-level result shape -- see docs/OUTPUT_SCHEMA.md. */
+export interface A11yCoreResult {
+  engine: EngineInfo;
+  url: string | null;
+  title: string | null;
+  timestamp: string | null;
+  perfStats: Record<string, unknown> | null;
+  contextSelector: string | string[] | null;
+  checksResults: CheckResult[];
+  rulesResults: CompositeResult[];
+}
+
+/** A sub-frame that couldn't be scanned (detached, navigated away, or sandboxed). */
+export interface A11yCoreFrameError {
+  url: string | null;
+  error: string;
+}
+
+/** Returned by analyze() when .frames(true) is enabled, instead of a single A11yCoreResult. */
+export interface A11yCoreMultiFrameResult {
+  topFrame: A11yCoreResult;
+  frames: Array<A11yCoreResult | A11yCoreFrameError>;
+}
+
+/**
+ * A runtime-registered rule descriptor for `.withCustomRules()` -- the same
+ * shape as an internal surea11y rule module's own export (see surea11y's
+ * docs/ENGINE_OPTIONS.md). `runInPage`/`applicability` may be passed as
+ * either a real function or a function-source string -- `.withCustomRules()`
+ * converts a live function to its source string for you, since it must
+ * cross a browser.execute() serialization boundary that cannot carry a live
+ * Function reference.
+ */
+export interface CustomRuleDescriptor {
+  id: string;
+  meta?: {
+    title?: string;
+    description?: string;
+    tags?: string[];
+    defaultSeverity?: Severity;
+    defaultConfidence?: Confidence;
+    [key: string]: unknown;
+  };
+  runInPage: ((ctx: unknown) => unknown) | string;
+  applicability?: ((ctx: unknown) => boolean) | string;
+  data?: Record<string, unknown>;
+}
+
+export class A11yCoreBuilder {
+  /**
+   * @param opts.browser A WebdriverIO Browser (from `remote()` or the WDIO
+   *   testrunner's global `browser`), already navigated to and settled at the
+   *   URL to scan -- this class does not navigate for you.
+   */
+  constructor(opts: { browser: WebdriverIO.Browser; url?: string });
+
+  /** Scope the scan to one region. Call multiple times for a multi-region union. */
+  include(selector: string): this;
+  /** Skip elements matching this selector anywhere in the scanned scope. */
+  exclude(selector: string): this;
+  /** Only run rules carrying at least one of these tags. */
+  withTags(tags: string | string[]): this;
+  /** Never run rules carrying any of these tags (applied after withTags). */
+  disableTags(tags: string | string[]): this;
+  /** Only run these specific rule IDs (accepts with or without the  prefix). */
+  withRules(ruleIds: string | string[]): this;
+  /** Never run these specific rule IDs (applied after withRules). */
+  disableRules(ruleIds: string | string[]): this;
+  /** Merge arbitrary engineOptions (locale, contrast.mode, policyContract, ...). */
+  options(partialEngineOptions: Record<string, unknown>): this;
+  /** Register one or more custom rules for just this scan. Call multiple times to accumulate. */
+  withCustomRules(rules: CustomRuleDescriptor | CustomRuleDescriptor[]): this;
+  /** Post-filter checksResults down to only the given outcomes. */
+  reportOnly(outcomes: Outcome | Outcome[]): this;
+  /** Opt in to also scanning every sub-frame on the page (including cross-origin and nested iframes). */
+  frames(enabled?: boolean): this;
+  /** Opt in to resolving each fail/cantTell occurrence's selector to a live WebdriverIO.Element. */
+  elementRef(enabled?: boolean): this;
+
+  /** Runs the scan. Returns { topFrame, frames } instead of a single result when .frames(true) was used. */
+  analyze(): Promise<A11yCoreResult | A11yCoreMultiFrameResult>;
+}
+
+/**
+ * Formats a checksResults array into a short, human-readable block -- one
+ * entry per occurrence, not per rule. Meant for an assertion library's
+ * failure-message parameter, e.g.
+ * `assert.strictEqual(results.checksResults.length, 0, formatFailures(results.checksResults))`.
+ * Deliberately framework-agnostic -- no dependency on any particular
+ * `expect` implementation.
+ */
+export function formatFailures(checksResults: CheckResult[], opts?: { outcomes?: Outcome[] }): string;

package/src/A11yCoreBuilder.js

@@ -0,0 +1,291 @@
+'use strict';
+
+const { runa11yCoreInPage } = require('@surea11y/core');
+const { A11yCoreBuilderBase } = require('@surea11y/binding-base');
+
+/**
+ * WebdriverIO binding for surea11y -- scans a real, already-rendered page.
+ *
+ * const results = await new A11yCoreBuilder({ browser })
+ *   .include('#main')
+ *   .exclude('.cookie-banner')
+ *   .withTags(['wcag2a', 'wcag2aa'])
+ *   .disableRules(['meta-refresh-no-exceptions'])
+ *   .options({ contrast: { mode: 'auditorAssist' } })
+ *   .analyze();
+ *
+ * `results` is surea11y's own native result shape (checksResults /
+ * rulesResults -- see surea11y's docs/OUTPUT_SCHEMA.md), not the
+ * violations/passes/incomplete/inapplicable shape used by other tools in
+ * this space. Method names are modeled on common conventions in this space
+ * for migration ease, but the richer native schema (severity, confidence,
+ * occurrences, policy contract, WCAG SC mappings) is kept as-is rather than
+ * reshaped to match.
+ *
+ * `browser` is the object returned by WebdriverIO's `remote()` (standalone
+ * mode) or the global `browser` inside the WDIO testrunner -- it must already
+ * be navigated to and settled at the URL to scan; this class does not
+ * navigate for you.
+ *
+ * Extends `A11yCoreBuilderBase` (from `surea11y-binding-base`), which owns
+ * every method with no driver-specific work at all -- `include()`/
+ * `exclude()`/`withTags()`/`disableTags()`/`withRules()`/`disableRules()`/
+ * `options()`/`reportOnly()`/`elementRef()`/`frames()`/`withCustomRules()`'s
+ * validation (including the default customRules stringification, correct
+ * here since WebdriverIO's `browser.execute()` crosses a real serialization
+ * boundary), and `_buildEngineArgs()`. This class adds exactly the parts
+ * that are genuinely WebdriverIO-specific: `analyze()`'s injection
+ * mechanics, the stateful index-path frame-traversal design below, and
+ * `_attachElementRefs()`. See `../surea11y-binding-base/README.md` for
+ * what's shared and why.
+ *
+ * Opt in to scanning every frame on the page (including cross-origin
+ * iframes -- and nested iframes-within-iframes, recursively) via
+ * .frames(true):
+ *
+ * const results = await new A11yCoreBuilder({ browser }).frames(true).analyze();
+ * // results.topFrame        -- same shape as the single-frame case above
+ * // results.frames          -- flat array of the same native result shape, one per sub-frame
+ *
+ * WebdriverIO's frame model is fundamentally different from Puppeteer's and
+ * Playwright's. Those expose `page.frames()` -- an array of independent Frame
+ * objects, each with its own `.evaluate()`/`.$()` -- so a binding can iterate
+ * them freely. WebdriverIO instead has a single *stateful current context*:
+ * `browser.switchFrame(iframeElement)` changes which document
+ * `browser.execute()`/`browser.$()` run against, and `browser.switchFrame(null)`
+ * returns to the top-level frame. There is no array of frame objects. So
+ * `.frames(true)` here works by enumerating each context's direct-child
+ * `<iframe>` elements with `browser.$$('iframe')`, switching into each with
+ * `browser.switchFrame(el)`, scanning the now-current document, then
+ * recursing into that frame's own children before returning to the parent
+ * context (re-entered by the context id `switchFrame()` handed back on the
+ * way in). Cross-origin iframes are reached with no extra work -- the
+ * WebDriver/BiDi automation layer switches into them the same as same-origin
+ * ones, exactly like Puppeteer/Playwright's CDP does; verified against a
+ * real cross-origin frame (`https://example.org/`). See ../ROADMAP.md §2c.
+ * Default off, so plain .analyze() keeps returning the single native result
+ * object it always has.
+ *
+ * By default `analyze()` returns every rule's outcome, including
+ * `pass`/`notApplicable` -- surea11y's own deliberate "not a
+ * violations-only list" design (see surea11y's docs/OUTPUT_SCHEMA.md).
+ * Opt in to a lighter payload with `.reportOnly(['fail', 'cantTell'])`,
+ * which post-filters `checksResults` by `outcome` (applied per-frame when
+ * combined with `.frames(true)`, since `checksResults` lives at
+ * `results.topFrame` / each `results.frames[i]` in that shape, not at the
+ * top level):
+ *
+ * const results = await new A11yCoreBuilder({ browser })
+ *   .reportOnly(['fail', 'cantTell'])
+ *   .analyze();
+ *
+ * Opt in to a live `WebdriverIO.Element` per occurrence (instead of just a
+ * CSS selector string) with `.elementRef(true)`, attached as
+ * `occurrence.element`, so you can act on the flagged element directly
+ * (`.click()`, `.saveScreenshot()`, `.getProperty()`, ...) rather than
+ * re-resolving its selector yourself:
+ *
+ * const results = await new A11yCoreBuilder({ browser }).elementRef(true).analyze();
+ * const [firstFail] = results.checksResults.filter(r => r.outcome === 'fail');
+ * await firstFail.occurrences[0].element.saveScreenshot('./flagged.png');
+ *
+ * NOTE the field is `occurrence.element` (a `WebdriverIO.Element`), not
+ * Puppeteer/Playwright's `occurrence.elementHandle` -- WebdriverIO has no
+ * "handle" concept, and its element API differs (`.getProperty('id')` rather
+ * than `.evaluate(el => el.id)`, `.saveScreenshot(path)` rather than
+ * `.screenshot({ path })`). See ../ROADMAP.md §2d and the README.
+ *
+ * Register your own rule(s) for just this scan with
+ * `.withCustomRules([...])` (surea11y's `engineOptions.customRules`
+ * escape hatch -- see surea11y's docs/ENGINE_OPTIONS.md). Pass a real,
+ * live `runInPage`/
+ * `applicability` function -- unlike the raw `.options({ customRules })`
+ * passthrough, this method converts them to the function-source string
+ * surea11y needs on this side of the browser.execute() serialization
+ * boundary for you, so you don't have to remember to call .toString()
+ * yourself:
+ *
+ * const results = await new A11yCoreBuilder({ browser })
+ *   .withCustomRules({
+ *     id: 'my-org-custom-rule',
+ *     meta: { title: 'My custom rule', tags: ['custom'] },
+ *     runInPage(ctx) {
+ *       const el = ctx.document.querySelector('.my-widget');
+ *       return el ? { outcome: 'fail', occurrences: [{ __node: el }] } : { outcome: 'notApplicable', occurrences: [] };
+ *     }
+ *   })
+ *   .analyze();
+ *
+ * Create one builder per scan. This is a mutable object with no reset
+ * between analyze() calls: include()/exclude()/withRules()/disableRules()/
+ * withTags()/disableTags()/options()/withCustomRules() all push onto or
+ * merge into internal state that persists for the instance's lifetime, so
+ * calling one of them again before a second analyze() call accumulates on
+ * top of the first scan's scope rather than replacing it (intentional for
+ * "call include() several times for one scan" -- see above -- but a footgun
+ * if you hold one instance across multiple assertions).
+ * reportOnly()/frames()/elementRef() are the exception: each call replaces
+ * the previous value rather than merging with it.
+ */
+class A11yCoreBuilder extends A11yCoreBuilderBase {
+  /**
+   * @param {{ browser: import('webdriverio').Browser, url?: string }} opts
+   *   `browser` must already be navigated to and settled at the URL to scan --
+   *   this class does not navigate for you.
+   */
+  constructor({ browser, url } = {}) {
+    super({ url });
+    if (!browser || typeof browser.execute !== 'function') {
+      throw new Error('A11yCoreBuilder requires { browser } (a WebdriverIO Browser, with an .execute() method).');
+    }
+    this._browser = browser;
+  }
+
+  /**
+   * Runs the scan and returns surea11y's native result object.
+   * @returns {Promise<object>} see surea11y's docs/OUTPUT_SCHEMA.md
+   */
+  async analyze() {
+    const { contextSelector, engineOptions, runOnly } = this._buildEngineArgs();
+
+    // Unlike Playwright's page.evaluate(fn, arg), which only accepts a
+    // SINGLE argument (forcing a hand-built single-arg wrapper there),
+    // WebdriverIO's browser.execute() is genuinely variadic:
+    // execute<ReturnValue, InnerArguments extends unknown[]>(script, ...args)
+    // (confirmed against a real webdriverio 9.x install's own
+    // build/commands/browser/execute.d.ts). Like Puppeteer, that means
+    // runa11yCoreInPage's own 4 positional args can be passed straight
+    // through with no wrapper/eval() trick -- WebdriverIO serializes the
+    // function itself. Verified empirically against a real headless Chrome
+    // session before trusting it (this project's whole ethos, inherited
+    // from surea11y and its sibling bindings, is "verified against a real
+    // run," not "reasoned about").
+    //
+    // Runs against whatever frame the browser is CURRENTLY switched into --
+    // WebdriverIO's execute()/$ target the current context, a stateful model
+    // unlike Puppeteer/Playwright's per-frame-object one. `.frames(true)`
+    // orchestrates the switching (see _scanChildFrames).
+    const scanCurrent = async () => {
+      const frameUrl = this._url || (await this._browser.execute(() => document.location.href));
+      const result = await this._browser.execute(runa11yCoreInPage, frameUrl, contextSelector, engineOptions, runOnly);
+      return this._elementRef ? this._attachElementRefs(result) : result;
+    };
+
+    if (!this._scanFrames) {
+      return this._applyReportOnly(await scanCurrent());
+    }
+
+    // Make sure we start from the top-level frame, whatever context the
+    // caller happened to leave the browser in.
+    await this._browser.switchFrame(null);
+    const topFrame = this._applyReportOnly(await scanCurrent());
+
+    const frames = [];
+    await this._scanChildFrames([], scanCurrent, frames);
+
+    // Leave the browser back at the top-level frame regardless of how the
+    // traversal ended, so a caller's next command isn't silently running in
+    // some leftover sub-frame context.
+    await this._browser.switchFrame(null).catch(() => {});
+
+    return { topFrame, frames };
+  }
+
+  /**
+   * Depth-first traversal of the frame tree rooted at the context addressed
+   * by `path` -- an array of child <iframe> indices from the top frame (so
+   * `[]` is the top frame, `[0]` its first child, `[0, 2]` that child's third
+   * child, and so on). Each direct child is navigated into, scanned, and
+   * recursed through; every scanned frame at any depth is pushed onto the same
+   * flat `out` array, matching the flat `frames` list Puppeteer/Playwright's
+   * page.frames()-based bindings return.
+   *
+   * The traversal deliberately re-navigates from the top frame down for each
+   * child (via _switchToPath) rather than caching a "handle" to return to.
+   * That's what makes it protocol-agnostic: WebdriverIO's switchFrame()
+   * returns a reusable BiDi context id under the default BiDi protocol but
+   * `null` under the classic WebDriver protocol (`wdio:enforceWebDriverClassic`,
+   * which this project's own tests/examples use -- see ../ROADMAP.md §2c/§4),
+   * and `$$('iframe')` element references don't survive a context switch away
+   * and back either. The one thing that reliably re-addresses a nested context
+   * on both protocols is replaying `switchFrame(null)` then the chain of
+   * `switchFrame(childElement)` down the index path, re-querying the iframes
+   * fresh at each hop.
+   */
+  async _scanChildFrames(path, scanCurrent, out) {
+    let childCount;
+    try {
+      const iframes = await this._browser.$$('iframe');
+      childCount = iframes.length;
+    } catch (e) {
+      return; // can't enumerate this context's children -- nothing to recurse into
+    }
+
+    for (let i = 0; i < childCount; i++) {
+      let frameUrl = null;
+      try {
+        // Re-establish this context from the top, then step into child i with
+        // a freshly re-queried element reference.
+        await this._switchToPath(path);
+        const iframes = await this._browser.$$('iframe');
+        await this._browser.switchFrame(iframes[i]);
+        frameUrl = await this._browser.execute(() => document.location.href);
+      } catch (e) {
+        // A frame can detach/navigate away mid-scan, or be a sandboxed frame
+        // the browser blocks switching into -- record it and move on rather
+        // than aborting the whole multi-frame scan.
+        out.push({ url: frameUrl, error: (e && e.message) || String(e) });
+        continue;
+      }
+
+      try {
+        out.push(this._applyReportOnly(await scanCurrent()));
+      } catch (e) {
+        out.push({ url: frameUrl, error: (e && e.message) || String(e) });
+      }
+
+      // We're currently switched into child i -- recurse into ITS children.
+      await this._scanChildFrames(path.concat(i), scanCurrent, out);
+    }
+  }
+
+  /**
+   * Switches the browser into the context addressed by `path` (array of child
+   * <iframe> indices from the top frame) by replaying switchFrame(null) then
+   * one switchFrame(childElement) per hop, re-querying $$('iframe') fresh at
+   * each level. Protocol-agnostic -- see _scanChildFrames.
+   */
+  async _switchToPath(path) {
+    await this._browser.switchFrame(null);
+    for (const index of path) {
+      const iframes = await this._browser.$$('iframe');
+      await this._browser.switchFrame(iframes[index]);
+    }
+  }
+
+  /**
+   * Resolves occurrence.selector to a live WebdriverIO.Element for every
+   * fail/cantTell occurrence, scoped to whatever frame the browser is
+   * currently switched into (browser.$ is stateful on the current context).
+   * Mutates and returns the same result object -- it's a fresh object from
+   * this scan, not shared external state.
+   */
+  async _attachElementRefs(result) {
+    if (!Array.isArray(result.checksResults)) return result;
+    for (const check of result.checksResults) {
+      if (!Array.isArray(check.occurrences) || !check.occurrences.length) continue;
+      for (const occurrence of check.occurrences) {
+        // Most occurrences carry a concrete element selector, but a page-wide
+        // finding with no single target element (e.g. some `manual`/cantTell
+        // rules) can carry "" -- leave `element` null rather than passing ""
+        // to browser.$(), which throws ("invalid selector: No selector
+        // specified") on WebdriverIO, unlike Puppeteer/Playwright's .$("")
+        // which resolves to null. Verified against a real run.
+        occurrence.element = occurrence.selector ? await this._browser.$(occurrence.selector) : null;
+      }
+    }
+    return result;
+  }
+}
+
+module.exports = { A11yCoreBuilder };

package/src/formatFailures.js

@@ -0,0 +1,12 @@
+'use strict';
+
+// Re-exported from surea11y-binding-base, which now holds the single
+// canonical copy shared across every surea11y binding -- see
+// ../ROADMAP.md's note on the shared-package extraction, and
+// ../surea11y-binding-base/README.md for the full rationale. Kept as a
+// real file here (not just re-exporting straight from src/index.js) so
+// `require('surea11y-webdriverio/src/formatFailures')` keeps working for
+// anyone importing the submodule path directly.
+const { formatFailures } = require('@surea11y/binding-base');
+
+module.exports = { formatFailures };

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './A11yCoreBuilder';

package/src/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { A11yCoreBuilder } = require('./A11yCoreBuilder');
+const { formatFailures } = require('./formatFailures');
+
+module.exports = { A11yCoreBuilder, formatFailures };