@surea11y/webdriverio 1.1.0 → 1.3.0

package/README.md

@@ -28,12 +28,13 @@ 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'])
+  .withWcag('2.2', 'AA')         // the rules for WCAG 2.2's A and AA criteria
   .disableRules(['meta-refresh-no-exceptions'])
   .options({ contrast: { mode: 'auditorAssist' } })
   .analyze();
 
 console.log(results.checksResults.filter(r => r.outcome === 'fail'));
+console.log(results.engine.version); // the @surea11y/core release that scanned, e.g. "1.11.1"
 await browser.deleteSession();
 ```
 
@@ -49,11 +50,17 @@ WebdriverIO v9 defaults to the WebDriver **BiDi** protocol. A long-lived session
 
 ### 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/core`'s default `includeMode: 'and'`), not either one.
+`.withWcag(version, level)` selects by conformance target: `.withWcag('2.2', 'AA')` runs the rules for WCAG 2.2's Level A and AA criteria, by the level each criterion has in that version (4.1.1 Parsing, which 2.2 removed, is part of a `'2.1'` target and not of a `'2.2'` one). `.withBestPractices()` adds the rules that name no WCAG criterion, such as `region` and `heading-order`; on its own it runs only those. `.withRules()` and `.withTags()` add to a target's rules, and the disable methods apply after. A version other than `'2.0'`, `'2.1'` or `'2.2'`, or a level other than `'A'`, `'AA'` or `'AAA'`, throws a `TypeError` with `code: 'INVALID_RUN_ONLY'` at the call. Both need `@surea11y/core` 1.11 or later.
+
+`withTags()`/`disableRules()` 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/core`'s default `includeMode: 'and'`), not either one.
+
+A rule or tag list that names nothing `@surea11y/core` knows makes `analyze()` reject with `code: 'INVALID_RUN_ONLY'` (see [When a scan can't run as asked](#when-a-scan-cant-run-as-asked)), so a typo such as `.withTags(['wcag2.2aa'])` can't run no rule at all and pass. An unknown name beside known ones is ignored, with a warning in the page's console. The four methods also throw a `TypeError` with the same `code` straight away for anything but a string or an array of strings, such as `undefined` from a missing config value.
+
+Rule IDs change rarely, but core 1.10.0 changed two: `label-title-only` is deprecated (it reports `notApplicable`; every field it flagged, `form-control-programmatic-label-quality` flags too) and keeps resolving until 2.0.0, so a `.disableRules(['label-title-only'])` still works but no longer does anything; and `landmark-role-name-present` is new, a `best-practice` rule that asks about an element with `role="region"` or `role="form"` and no accessible name.
 
 `.exclude(selector)` above excludes globally. Pass a second argument to scope it to specific rule IDs instead: `.exclude('.mat-select', { rules: ['aria-required-children'] })` skips `.mat-select` for that rule only — every other rule still sees it. Global and rule-scoped `.exclude()` calls compose freely.
 
-**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.
+**Create one builder per scan.** `A11yCoreBuilder` is a mutable object with no reset between `.analyze()` calls — `include()`/`exclude()`/`withRules()`/`disableRules()`/`withTags()`/`disableTags()`/`options()`/`withCustomRules()`/`withPacks()` 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()`/`.withWcag()`/`.withBestPractices()` 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.
 
@@ -63,7 +70,7 @@ The pattern above works unchanged inside a real WebdriverIO testrunner spec, whi
 
 ```js
 const assert = require('node:assert');
-const { A11yCoreBuilder, formatFailures } = require('@surea11y/webdriverio');
+const { A11yCoreBuilder, formatFailures, getScanGaps } = require('@surea11y/webdriverio');
 
 describe('accessibility gate', () => {
   it('has no accessibility violations', async () => {
@@ -71,29 +78,36 @@ describe('accessibility gate', () => {
 
     const results = await new A11yCoreBuilder({ browser }).reportOnly(['fail']).analyze();
 
-    assert.strictEqual(results.checksResults.length, 0, formatFailures(results.checksResults));
+    assert.strictEqual(results.checksResults.length, 0, formatFailures(results));
+    // An include() scope that matched nothing, or a custom rule or a pack
+    // that did not run, leaves no failure behind: check for them too.
+    assert.deepStrictEqual(getScanGaps(results), [], formatFailures(results));
   });
 });
 ```
 
-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. This project's own *unit* suite (`tests/*.test.js`) uses `node:test` + `remote()`, the right tool for exercising the builder API in isolation.
+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, and one gating a page on a pack's checklist (see [Scanning with packs](#scanning-with-packs-standards-checklists-and-your-own-rules)). It uses the **WebdriverIO testrunner** (`@wdio/cli` + mocha), which is how real WebdriverIO suites are written. This project's own *unit* suite (`tests/*.test.js`) 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:
+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(results)` turns that into a short, scannable block (one entry per occurrence, numbered, with rule ID/severity/location/hint) that you hand to your assertion library's own failure-message parameter, as above. Given the whole result, it also says what the scan left out and which `@surea11y/core` release ran it. 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).
+   Give the button visible text, or name it with aria-label, so screen reader users know what it does.
+2) img-alt-present (serious): This <img> has no alt attribute.
+   at #host >>> p > img
+   Add an alt attribute that says what the image shows, or alt="" if the image is purely decorative.
+
+Scanned with @surea11y/core 1.11.1.
 ```
 
-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) is still surfaced using its `error` message rather than silently dropped.
+An element inside a shadow tree is located as `host >>> selector` (the second entry above); `formatOccurrenceLocation(occurrence)` gives the same text if you print occurrences yourself. `formatFailures(results.checksResults)` still works and prints only the entries. A `.frames(true)` result is not one result, so `formatFailures()` throws a `TypeError` for it: format `results.topFrame` and each entry of `results.frames` on its own.
+
+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 whose occurrences are findings: a `notApplicable` rule may carry one occurrence saying why it had nothing to judge); pass `{ outcomes: [...] }` to narrow further. A thrown rule (`occurrences: []`, `error` set) is still surfaced using its `error` message rather than silently dropped.
 
 ### Scanning every frame, including cross-origin and nested iframes
 
@@ -110,6 +124,18 @@ for (const frame of results.frames) {
 
 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.
 
+**`.include()` scopes the top frame only.** Each sub-frame is scanned whole, as `@surea11y/core`'s own `runa11yCoreAcrossFrames` does: the selectors belong to the top document, and since core 1.10.0 a selector that matches nothing scans nothing, so passing them down would leave every frame without them unscanned. `.exclude()` and the rule filters apply in every frame. An `EngineError` (see [When a scan can't run as asked](#when-a-scan-cant-run-as-asked)) rejects `analyze()` from the top frame, before any sub-frame is scanned; a sub-frame that fails for another reason is listed in `results.frames` as `{ url, error }`.
+
+`@surea11y/core`'s reporters take this result as it is (core 1.11.1 and later): `renderSarifReport(results)`, `renderJunitReport(results)`, `renderHtmlReport(results)` and the baseline functions report every frame's findings, and a frame that couldn't be scanned as not scanned, so it never reads as a pass.
+
+```js
+const fs = require('node:fs');
+const { renderSarifReport } = require('@surea11y/core/sarif');
+
+const results = await new A11yCoreBuilder({ browser }).frames(true).analyze();
+fs.writeFileSync('a11y.sarif', renderSarifReport(results));
+```
+
 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 `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 extra `@surea11y/core` engine support at all.
 
 ### Trimming the result to just violations
@@ -126,6 +152,8 @@ console.log(results.checksResults); // only fail/cantTell entries, pass/notAppli
 
 Valid outcome values are `'pass'`, `'fail'`, `'cantTell'`, `'notApplicable'`. This is pure binding-layer filtering — the engine 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.
 
+A result trimmed this way is no longer the whole scan to `@surea11y/core`'s reporters: JUnit counts one test per rule it finds, and EARL makes one assertion per rule. To keep a result small and still hand it to them, ask the engine for a compact one instead, with `.options({ output: { detail: 'findings' } })`: a rule that passed or did not apply keeps only its outcome, and every reporter reads it as the full result. An empty page's result goes from about 238 KB to 82 KB.
+
 ### 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)`:
@@ -138,14 +166,14 @@ 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()`.
+This finds each occurrence's element in the page and attaches it as **`occurrence.element`** — instead of leaving you to re-resolve a possibly-stale selector string yourself. An element inside a shadow tree is found through its `shadowHostSelectors` (see below), where `browser.$(occurrence.selector)` would find another element or none. `element` is `null` when nothing matches any more. 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."
 
-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.)
+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.
 
 ### Registering a custom rule at runtime
 
@@ -179,23 +207,92 @@ const results = await new A11yCoreBuilder({ browser })
 
 **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/core` 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), 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/core`'s own engine-side behavior, which silently skips an invalid descriptor rather than throwing.)
+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 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/core`'s own engine-side behavior, which skips an invalid descriptor rather than throwing. The result lists each skipped rule in `skippedCustomRules`, and `analyze()` warns about it — see below.)
+
+### When a scan can't run as asked
+
+`analyze()` rejects with an `EngineError` (exported, along with `ENGINE_ERROR_CODES`) when `@surea11y/core` can't use what it was given. Its `code` says why:
+
+- `INVALID_RUN_ONLY`: none of the rule IDs, or none of the tags, given to `.withRules()`/`.withTags()` is one the engine knows.
+- `INVALID_CONTEXT_SELECTOR`: an `.include()` selector is not valid CSS; `error.selector` names it.
+- `INVALID_ENGINE_OPTIONS`: with `.options({ strictOptions: true })`, an option the engine doesn't read or a value it can't use. The message names each, with the closest known option (`lcoale`: did you mean `locale`?). Without `strictOptions`, a likely typo is only warned about in the page's console.
+- `PAGE_BUILTINS_BROKEN`: the page's own scripts broke a JavaScript built-in the engine relies on (`Array.prototype.filter`, `Map`, `JSON.stringify`, ...), so no result it gave could be trusted. The message names each one.
+
+```js
+const { A11yCoreBuilder, EngineError } = require('@surea11y/webdriverio');
+
+try {
+  await new A11yCoreBuilder({ browser }).withTags(['wcag2.2aa']).analyze();
+} catch (e) {
+  if (e instanceof EngineError && e.code === 'INVALID_RUN_ONLY') {
+    // a typo in the tag list, not a broken page
+  }
+  throw e;
+}
+```
+
+Two other cases don't throw but leave part of the page unchecked, so a result that reports nothing failing is not a clean page:
+
+- **An `.include()` selector that matches nothing.** Since core 1.10.0 nothing is then scanned (it used to fall back to the whole page): every rule reports `notApplicable`, and `results.contextMatch` is `{ elementCount: 0, unmatchedSelectors: [...] }`. With several selectors, one that matches nothing is named there while the others are scanned.
+- **A custom rule that did not run**, listed with its reason in `results.skippedCustomRules`.
+- **A pack that did not run**, listed with its reason in `results.skippedPacks` (see [Scanning with packs](#scanning-with-packs-standards-checklists-and-your-own-rules)).
+
+`analyze()` prints each of these with `console.warn`, and `getScanGaps(results)` returns them as `[{ kind, message, ... }]` (`kind` is `context-not-found`, `context-partly-not-found`, `custom-rule-skipped` or `pack-skipped`), so a gate can fail on them, as the E2E example above does. `formatFailures(results)` lists them too.
+
+### Scanning with packs: standards, checklists and your own rules
+
+A pack brings rules, variants of core's rules, a standard or a checklist, and their profiles and messages, from a package of its own: a national standard such as RGAA, or your organisation's accessibility policy. `@surea11y/core` runs a pack as it runs its own rules and standards, so its results, rollups and report entries look like core's. Packs need `@surea11y/core` 1.11.1 or later.
+
+`.withPacks()` registers packs in the page with `browser.execute()`, and in every frame with `.frames(true)`, before the scan; a pack's profile is chosen with `.options({ profile })`:
+
+```js
+const acmePolicy = require('@acme/a11y-policy'); // a pack
+
+const results = await new A11yCoreBuilder({ browser })
+  .withPacks(acmePolicy)
+  .options({ profile: 'acme-web-2026' })
+  .analyze();
+
+results.engine.packs;   // ['@acme/a11y-policy@1.0.0']
+results.engine.profile; // 'acme-web-2026'
+
+// A checklist's items, each one result, beside core's WCAG rollups:
+results.rulesResults.filter((r) => r.meta && r.meta.standard === 'Acme web policy');
+```
+
+A pack's own rules appear in `checksResults` like core's, with ids that start with its namespace (`acme-no-autoplay`). Without its profile, a pack's rules run only when selected, with `.withRules()` or by a tag. `@surea11y/core`'s HTML, SARIF and JUnit reports show a standard's or a checklist's items in a section of their own. Pass an array, or call `.withPacks()` again, to scan with several packs.
+
+**Writing a pack.** A pack is an object made with `definePack` from `@surea11y/core/pack`. [`examples/acme-policy-pack.js`](./examples/acme-policy-pack.js) is a small one: a house rule, a checklist profile (WCAG 2.2 A and AA, `region`, and the house rule) and two checklist items. `npm run example:pack` scans a page with it, and [`examples/e2e-test-example.test.js`](./examples/e2e-test-example.test.js) uses it as a test gate. For a pack of your own, `npx surea11y-pack new <folder>` (from `@surea11y/core`) writes a package that works as generated, with its tests, docs and lint; core's [`PACKS.md`](https://github.com/SureA11y/core/blob/main/docs/PACKS.md) is the guide.
+
+**When a pack doesn't run.** `.withPacks()` builds the page's script with the `@surea11y/core` this binding loads, and checks each pack as it does: `.analyze()` throws before scanning for a pack that core can't run, such as one whose `core` range leaves out the installed core, or whose profile names a rule that doesn't exist. A pack the page then doesn't run (one named with a raw `.options({ packs })` and never registered, or a page running another core version, when two copies of core are installed) is listed in `results.skippedPacks` with the reason. `getScanGaps()` reports that as `'pack-skipped'`, and `.analyze()` warns about it, so a test gate that asserts on `getScanGaps(results)` fails rather than passing with the pack's checks never run. Install the pack beside the binding, so npm resolves one core for both.
 
 ### 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 [`OUTPUT_SCHEMA.md`](https://github.com/SureA11y/core/blob/main/docs/OUTPUT_SCHEMA.md) for the full field description.
+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.
+
+An element inside a shadow tree is different: its `selector` holds only inside its shadow root, its `shadowHostSelectors` lists the shadow hosts that lead to it (outermost first), and its `structuralPath` is `null`. `formatOccurrenceLocation(occurrence)` joins them as `host >>> selector` for display. See [`OUTPUT_SCHEMA.md`](https://github.com/SureA11y/core/blob/main/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/core`'s native result shapes (`A11yCoreResult`, `CheckResult`, `Occurrence`, `CompositeResult`, etc.). `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.
+`src/A11yCoreBuilder.d.ts` (re-exported from `src/index.d.ts`, wired up via `package.json`'s `types` field) ships types for the whole builder API plus `@surea11y/core`'s native result shapes (`A11yCoreResult`, `CheckResult`, `Occurrence`, `CompositeResult`, etc.). The result shapes are built on the types `@surea11y/core` ships itself, so fields such as `engine.version`, `engine.environment`, `contextMatch`, `skippedCustomRules`, `margin` and `shadowHostSelectors` follow the engine; this package adds `occurrence.element` and the `.frames(true)` shape. `EngineError`, `EngineErrorCode` and `ScanGap` come from `@surea11y/binding-base`, and so do the types of `withWcag()` (`WcagVersion`, `WcagLevel`) and `withPacks()`, which takes a pack made with `definePack` (`PackLike`). Code that handles every `ScanGap` kind it knows and treats the rest in an `else` branch needs a branch for `'pack-skipped'`, which carries `pack` rather than `selectors`. `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.
+
+## What changes with `@surea11y/core` 1.11
+
+The binding passes rule IDs, tags and options through to the engine, so these show in results without a change here (see core's [`CHANGELOG.md`](https://github.com/SureA11y/core/blob/main/CHANGELOG.md) for the full list):
+
+- **Messages are reworded** in all five languages to say plainly what is wrong and what to do (`This <img> has no alt attribute.`). Message keys, rule IDs, reason codes and baselines are unchanged; a test that matches message text needs the new wording.
+- **Contrast and target size measure what is on screen.** In a browser, the contrast rules check only text a reader can see, measure it against what is painted under it, and measure form field values and placeholders. `target-size-minimum` measures the area a pointer can hit, and exempts only links in a sentence. Expect new findings, and some old ones gone.
+- **`aria-hidden-focus` maps to 4.1.2 only**, no longer to 2.4.7 Focus Visible, so `.withTags('wcag2aa')` alone no longer selects it.
+- **A custom rule counts toward its WCAG criterion.** A `.withCustomRules()` rule with `meta.wcagSc` (or a WCAG `normativeMappings` entry) fails that criterion's rollup when it fails, and custom rules run after core's.
+- **On/off options read as meant**: `.options({ perfStats: 'false' })` is off, where it was on. `.options({ strictOptions: true })` rejects any option the engine doesn't read (see [When a scan can't run as asked](#when-a-scan-cant-run-as-asked)).
 
 ## Relationship to `@surea11y/playwright` and `@surea11y/puppeteer`
 
-This binding's builder API is deliberately the same shape as [`@surea11y/playwright`](https://github.com/SureA11y/playwright)'s and `@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`) is not copied across bindings — `A11yCoreBuilder` here extends `A11yCoreBuilderBase` from [`@surea11y/binding-base`](https://github.com/SureA11y/binding-base), the single shared implementation every sibling binding depends on.
+This binding's builder API is deliberately the same shape as [`@surea11y/playwright`](https://github.com/SureA11y/playwright)'s and `@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`/`withWcag`/`withBestPractices`/`options`/`withCustomRules`/`withPacks`/`reportOnly`) is not copied across bindings — `A11yCoreBuilder` here extends `A11yCoreBuilderBase` from [`@surea11y/binding-base`](https://github.com/SureA11y/binding-base), the single shared implementation every sibling binding 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.
+- **`analyze()`'s injection call** is variadic like Puppeteer's (`browser.execute(inPageScan, url, ctx, opts, runOnly)`, where `inPageScan` is `@surea11y/core`'s `runa11yCoreInPage` wrapped by `@surea11y/binding-base` so an engine error keeps its `code`) — no single-arg wrapper 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.
 - **`.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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/webdriverio",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "WebdriverIO binding for surea11y -- scan real, live-rendered pages for accessibility issues.",
   "keywords": [
     "accessibility",
@@ -40,22 +40,24 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@surea11y/binding-base": "^1.1.0",
-    "@surea11y/core": "^1.5.0"
+    "@surea11y/binding-base": "^1.3.1",
+    "@surea11y/core": "^1.11.1"
   },
   "peerDependencies": {
     "webdriverio": ">=8.0.0"
   },
   "devDependencies": {
-    "@wdio/cli": "^9.30.0",
-    "@wdio/local-runner": "^9.30.0",
-    "@wdio/mocha-framework": "^7.7.3",
-    "@wdio/spec-reporter": "^9.29.1",
-    "webdriverio": "^9.0.0"
+    "@wdio/cli": "^9.32.0",
+    "@wdio/local-runner": "^9.32.0",
+    "@wdio/mocha-framework": "^9.32.0",
+    "@wdio/spec-reporter": "^9.32.0",
+    "typescript": "^7.0.2",
+    "webdriverio": "^9.32.0"
   },
   "scripts": {
     "test": "node --test --test-concurrency=1 tests/*.test.js",
     "example": "node examples/basic-scan.js",
-    "example:e2e": "wdio run examples/wdio.conf.js"
+    "example:e2e": "wdio run examples/wdio.conf.js",
+    "example:pack": "node examples/scan-with-pack.js"
   }
 }

package/src/A11yCoreBuilder.d.ts

@@ -3,150 +3,70 @@
 // 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.
+// The result shapes come from @surea11y/core's own types (shipped since
+// 1.9.0 and checked there against real scan results), so they follow the
+// engine instead of a copy here. This file adds what the binding puts on
+// top: the `element` field .elementRef(true) attaches, and the
+// { topFrame, frames } shape of .frames(true). The names below are the ones
+// this file has always exported.
+import type * as Core from '@surea11y/core';
+import type { PackLike, WcagVersion, WcagLevel } from '@surea11y/binding-base';
+export type { PackLike, WcagVersion, WcagLevel } from '@surea11y/binding-base';
+
+export type Outcome = Core.Outcome;
+export type OutcomeNormalized = Core.OutcomeNormalized;
+export type Severity = Core.Severity;
+export type Confidence = Core.Confidence;
+export type RuleType = Core.RuleType;
+export type Category = Core.RuleMeta['category'];
+/** An open set: core can add a value in a minor release. */
+export type LocaleResolutionReason = Core.LocaleResolution['reason'];
+export type LocaleResolution = Core.LocaleResolution;
+/** `engine.version` is the @surea11y/core release that produced the result (1.10.0 and later). */
+export type EngineInfo = Core.EngineInfo;
+export type RenderingEnvironment = Core.RenderingEnvironment;
+export type NormativeMapping = Core.NormativeMapping;
+export type CheckResultMeta = Core.RuleMeta;
+export type VisibilityFilter = Core.VisibilityFilter;
+/** How close a rule's closest passing measurement came to its threshold (`CheckResult.margin`). */
+export type Margin = Core.Margin;
+/** How the include() scope resolved; `elementCount: 0` means nothing was scanned. */
+export type ContextMatch = Core.ContextMatch;
+export type CompositeResult = Core.CompositeResult;
+export type CompositeResultDetails = Core.CompositeResult['data']['details'];
+export type EngineOptions = Core.EngineOptions;
 
-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;
-
-// The reason set is open: core can add a value in a minor release, so the
-// union stays assignable from any string rather than going stale.
-export type LocaleResolutionReason =
-  | 'ok'
-  | 'primary-subtag'
-  | 'dictionary-not-loaded'
-  | 'unknown-locale'
-  | 'partial-dictionary'
-  | (string & {});
-
-export interface LocaleResolution {
-  requested: string;
-  resolved: string;
-  reason: LocaleResolutionReason;
-}
-
-export interface EngineInfo {
-  tag: string;
-  schemaVersion: string;
-  locale: LocaleResolution;
-}
-
-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>;
-  };
+/**
+ * An occurrence as @surea11y/core reports it. One inside a shadow tree
+ * carries `shadowHostSelectors` and a `structuralPath` of null; its
+ * `selector` holds only inside the last host's shadow root.
+ */
+export interface Occurrence extends Core.Occurrence {
   /**
    * 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.
+   * occurrence has no single target element (`selector` is `""`) or no
+   * element matches it any more -- see A11yCoreBuilder#elementRef. Found
+   * through `shadowHostSelectors` for an element in a shadow tree. 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.
    */
   element?: WebdriverIO.Element | null;
 }
 
-export interface CheckResult {
-  ruleId: string;
-  outcome: Outcome;
-  outcomeNormalized: OutcomeNormalized;
-  severity: Severity;
-  confidence: Confidence;
-  type: RuleType;
+export interface CheckResult extends Omit<Core.CheckResult, 'occurrences'> {
   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;
+/**
+ * @surea11y/core's native top-level result shape -- see its
+ * docs/OUTPUT_SCHEMA.md. Since 1.10.0 it also says how the include() scope
+ * resolved (`contextMatch`) and which custom rules did not run
+ * (`skippedCustomRules`).
+ */
+export interface A11yCoreResult extends Omit<Core.ScanResult, 'checksResults'> {
   checksResults: CheckResult[];
-  rulesResults: CompositeResult[];
 }
 
 /** A sub-frame that couldn't be scanned (detached, navigated away, or sandboxed). */
@@ -193,7 +113,12 @@ export class A11yCoreBuilder {
    */
   constructor(opts: { browser: WebdriverIO.Browser; url?: string });
 
-  /** Scope the scan to one region. Call multiple times for a multi-region union. */
+  /**
+   * Scope the scan to one region. Call multiple times for a multi-region
+   * union. A selector that matches nothing scans nothing (see
+   * `contextMatch`); with .frames(true) the scope applies to the top frame
+   * only and each sub-frame is scanned whole.
+   */
   include(selector: string): this;
   /**
    * Skip elements matching this selector anywhere in the scanned scope.
@@ -202,7 +127,11 @@ export class A11yCoreBuilder {
    * from other `.exclude(selector)` calls.
    */
   exclude(selector: string, opts?: { rules?: string | string[] }): this;
-  /** Only run rules carrying at least one of these tags. */
+  /**
+   * Only run rules carrying at least one of these tags. Like the three
+   * methods below, throws a TypeError with `code: 'INVALID_RUN_ONLY'` for
+   * anything but a string or an array of strings.
+   */
   withTags(tags: string | string[]): this;
   /** Never run rules carrying any of these tags (applied after withTags). */
   disableTags(tags: string | string[]): this;
@@ -210,10 +139,23 @@ export class A11yCoreBuilder {
   withRules(ruleIds: string | string[]): this;
   /** Never run these specific rule IDs (applied after withRules). */
   disableRules(ruleIds: string | string[]): this;
+  /**
+   * Run the rules for a WCAG conformance target: `withWcag('2.2', 'AA')`
+   * runs those of WCAG 2.2's A and AA criteria. withTags()/withRules() add
+   * to them. A later call replaces the target.
+   */
+  withWcag(version: WcagVersion | 2.0 | 2.1 | 2.2, level?: WcagLevel): this;
+  /** Also run the best-practice rules, those that name no WCAG criterion. */
+  withBestPractices(enabled?: boolean): 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;
+  /**
+   * Packs from `@surea11y/core/pack` (core 1.11 or later): registered in each
+   * frame before the scan, and named in `engineOptions.packs`.
+   */
+  withPacks(packs: PackLike | PackLike[]): 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). */
@@ -221,16 +163,31 @@ export class A11yCoreBuilder {
   /** 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. */
+  /**
+   * Runs the scan. Returns { topFrame, frames } instead of a single result
+   * when .frames(true) was used. Rejects with an `EngineError` (from
+   * `@surea11y/binding-base`, re-exported here) whose `code` is
+   * `INVALID_RUN_ONLY` when a rule or tag list names nothing @surea11y/core
+   * knows, `INVALID_CONTEXT_SELECTOR` (with `selector`) when an include()
+   * selector does not parse, `INVALID_ENGINE_OPTIONS` for an option
+   * `strictOptions: true` rejects, or `PAGE_BUILTINS_BROKEN` when the page's
+   * scripts broke a JavaScript built-in the engine relies on.
+   */
   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.
+ * Formats a result, or its checksResults array, into a short, human-readable
+ * block -- one entry per fail/cantTell occurrence, not per rule. Given the
+ * whole result, it also lists what the scan left out (an include() scope
+ * that matched nothing, a custom rule or a pack that did not run) and the
+ * @surea11y/core release that produced it. Meant for an assertion
+ * library's failure-message parameter, e.g.
+ * `assert.strictEqual(fails.length, 0, formatFailures(results))`.
+ * Throws a TypeError for anything else, such as a .frames(true) result:
+ * format `topFrame` and each entry of `frames` on its own.
  */
-export function formatFailures(checksResults: CheckResult[], opts?: { outcomes?: Outcome[] }): string;
+export function formatFailures(
+  input: A11yCoreResult | ReadonlyArray<CheckResult>,
+  opts?: { outcomes?: Outcome[] }
+): string;

package/src/A11yCoreBuilder.js

@@ -1,7 +1,19 @@
 'use strict';
 
 const { runa11yCoreInPage } = require('@surea11y/core');
-const { A11yCoreBuilderBase } = require('@surea11y/binding-base');
+const {
+  A11yCoreBuilderBase,
+  createInPageScan,
+  rethrowEngineError,
+  queryOccurrenceElement,
+  getScanGaps
+} = require('@surea11y/binding-base');
+
+// core's runa11yCoreInPage, wrapped so an engine error (INVALID_RUN_ONLY,
+// INVALID_CONTEXT_SELECTOR) keeps its `code` across browser.execute(),
+// which carries only an error's message. Self-contained, so WebdriverIO
+// serializes it exactly as it serialized runa11yCoreInPage.
+const inPageScan = createInPageScan(runa11yCoreInPage);
 
 /**
  * WebdriverIO binding for surea11y -- scans a real, already-rendered page.
@@ -66,6 +78,12 @@ const { A11yCoreBuilderBase } = require('@surea11y/binding-base');
  * Default off, so plain .analyze() keeps returning the single native result
  * object it always has.
  *
+ * An include() scope applies to the top frame only: each sub-frame is
+ * scanned whole (contextSelector null), as @surea11y/core's own
+ * runa11yCoreAcrossFrames does. Since core 1.10.0 a selector that matches
+ * nothing scans nothing, so passing the top frame's scope down would leave
+ * every frame that lacks it unscanned.
+ *
  * By default `analyze()` returns every rule's outcome, including
  * `pass`/`notApplicable` -- @surea11y/core's own deliberate "not a
  * violations-only list" design (see ../core/docs/OUTPUT_SCHEMA.md).
@@ -118,14 +136,14 @@ const { A11yCoreBuilderBase } = require('@surea11y/binding-base');
  *
  * 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
+ * withTags()/disableTags()/options()/withCustomRules()/withPacks() 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.
+ * reportOnly()/frames()/elementRef()/withWcag()/withBestPractices() are the
+ * exception: each call replaces the previous value rather than merging with it.
  */
 class A11yCoreBuilder extends A11yCoreBuilderBase {
   /**
@@ -147,6 +165,11 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
    */
   async analyze() {
     const { contextSelector, engineOptions, runOnly } = this._buildEngineArgs();
+    if (this._scanFrames) {
+      // Make sure we start from the top-level frame, whatever context the
+      // caller happened to leave the browser in.
+      await this._browser.switchFrame(null);
+    }
 
     // Unlike Playwright's page.evaluate(fn, arg), which only accepts a
     // SINGLE argument (forcing a hand-built single-arg wrapper there),
@@ -154,10 +177,10 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
     // 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
+    // the scan's 4 positional args can be passed straight through with no
+    // single-arg wrapper -- 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").
     //
@@ -165,23 +188,36 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
     // 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 () => {
+    //
+    // inPageScan takes the same four arguments as runa11yCoreInPage; an
+    // engine error comes back as a plain object, which rethrowEngineError()
+    // throws again here as an EngineError with its `code`.
+    // The script that registers withPacks()'s packs in a frame, which the
+    // scan names in engineOptions.packs; null without packs. execute() runs
+    // a string as a function body, so the script runs as written.
+    const packScript = this._packScript();
+    const scanCurrent = async (scope) => {
       const frameUrl = this._url || (await this._browser.execute(() => document.location.href));
-      const result = await this._browser.execute(runa11yCoreInPage, frameUrl, contextSelector, engineOptions, runOnly);
+      if (packScript) await this._browser.execute(packScript);
+      const result = rethrowEngineError(
+        await this._browser.execute(inPageScan, frameUrl, scope, engineOptions, runOnly)
+      );
+      this._warnScanGaps(result);
       return this._elementRef ? this._attachElementRefs(result) : result;
     };
 
     if (!this._scanFrames) {
-      return this._applyReportOnly(await scanCurrent());
+      return this._applyReportOnly(await scanCurrent(contextSelector));
     }
 
-    // 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());
+    // The top frame is scanned first, so an INVALID_RUN_ONLY or
+    // INVALID_CONTEXT_SELECTOR error is thrown from it, before any sub-frame.
+    const topFrame = this._applyReportOnly(await scanCurrent(contextSelector));
 
+    // Sub-frames are scanned whole: the include() scope belongs to the top
+    // frame's document (see the class comment).
     const frames = [];
-    await this._scanChildFrames([], scanCurrent, frames);
+    await this._scanChildFrames([], () => scanCurrent(null), 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
@@ -264,24 +300,55 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
   }
 
   /**
-   * 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.
+   * Prints what the scan left out (getScanGaps(): an include() scope that
+   * matched nothing, a custom rule or a pack that did not run) with console.warn.
+   * @surea11y/core warns about these too, but in the page's console, which a
+   * WebdriverIO run does not show; a result whose checksResults alone look
+   * clean would otherwise pass without a word.
+   */
+  _warnScanGaps(result) {
+    let gaps;
+    try {
+      gaps = getScanGaps(result);
+    } catch (e) {
+      return; // not a scan result; the caller sees it as it is
+    }
+    const where = result.url ? ` (${result.url})` : '';
+    for (const gap of gaps) {
+      console.warn(`@surea11y/webdriverio${where}: ${gap.message}`);
+    }
+  }
+
+  /**
+   * Resolves each occurrence to a live WebdriverIO.Element, scoped to
+   * whatever frame the browser is currently switched into (execute() 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.
+   *
+   * The lookup runs in the page through binding-base's
+   * queryOccurrenceElement(), which follows `shadowHostSelectors` (core
+   * 1.10.0 and later): an occurrence inside a shadow tree has a `selector`
+   * that holds only inside its shadow root, so browser.$(selector) found
+   * another element or none. The element reference execute() returns is
+   * wrapped with browser.$(), which makes no further WebDriver call.
+   * `element` is null when the occurrence has no selector (a page-wide
+   * finding can carry "") or nothing matches it any more.
    */
   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;
+        if (!occurrence.selector) {
+          occurrence.element = null;
+          continue;
+        }
+        const ref = await this._browser.execute(
+          queryOccurrenceElement,
+          occurrence.selector,
+          occurrence.shadowHostSelectors || null
+        );
+        occurrence.element = ref ? await this._browser.$(ref) : null;
       }
     }
     return result;

package/src/index.d.ts

@@ -1 +1,8 @@
 export * from './A11yCoreBuilder';
+export {
+  EngineError,
+  ENGINE_ERROR_CODES,
+  getScanGaps,
+  formatOccurrenceLocation
+} from '@surea11y/binding-base';
+export type { EngineErrorCode, ScanGap, ScanResultLike, OccurrenceLocation } from '@surea11y/binding-base';

package/src/index.js

@@ -2,5 +2,18 @@
 
 const { A11yCoreBuilder } = require('./A11yCoreBuilder');
 const { formatFailures } = require('./formatFailures');
+const {
+  EngineError,
+  ENGINE_ERROR_CODES,
+  getScanGaps,
+  formatOccurrenceLocation
+} = require('@surea11y/binding-base');
 
-module.exports = { A11yCoreBuilder, formatFailures };
+module.exports = {
+  A11yCoreBuilder,
+  formatFailures,
+  EngineError,
+  ENGINE_ERROR_CODES,
+  getScanGaps,
+  formatOccurrenceLocation
+};