@surea11y/webdriverio 1.1.0 → 1.2.0

package/README.md

@@ -34,6 +34,7 @@ const results = await new A11yCoreBuilder({ browser })
   .analyze();
 
 console.log(results.checksResults.filter(r => r.outcome === 'fail'));
+console.log(results.engine.version); // the @surea11y/core release that scanned, e.g. "1.10.0"
 await browser.deleteSession();
 ```
 
@@ -51,6 +52,10 @@ WebdriverIO v9 defaults to the WebDriver **BiDi** protocol. A long-lived session
 
 `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.
 
+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.
@@ -63,7 +68,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,7 +76,10 @@ 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 that did not
+    // run, leaves no failure behind: check for them too.
+    assert.deepStrictEqual(getScanGaps(results), [], formatFailures(results));
   });
 });
 ```
@@ -82,18 +90,22 @@ Note the gate above uses `node:assert`, not WebdriverIO's bundled `expect`: Webd
 
 ### 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
+   at #host >>> p > img
    Add an alt attribute (use alt="" only for decorative images).
+
+Scanned with @surea11y/core 1.10.0.
 ```
 
-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 +122,8 @@ 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 `INVALID_RUN_ONLY` or `INVALID_CONTEXT_SELECTOR` error 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 }`.
+
 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
@@ -138,14 +152,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,15 +193,44 @@ 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.
+
+```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`.
+
+`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` or `custom-rule-skipped`), so a gate can fail on them, as the E2E example above does. `formatFailures(results)` lists them too.
 
 ### 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`. `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.
 
 ## Relationship to `@surea11y/playwright` and `@surea11y/puppeteer`
 
@@ -195,7 +238,7 @@ This binding's builder API is deliberately the same shape as [`@surea11y/playwri
 
 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.2.0",
   "description": "WebdriverIO binding for surea11y -- scan real, live-rendered pages for accessibility issues.",
   "keywords": [
     "accessibility",
@@ -40,8 +40,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@surea11y/binding-base": "^1.1.0",
-    "@surea11y/core": "^1.5.0"
+    "@surea11y/binding-base": "^1.2.0",
+    "@surea11y/core": "^1.10.0"
   },
   "peerDependencies": {
     "webdriverio": ">=8.0.0"
@@ -49,8 +49,9 @@
   "devDependencies": {
     "@wdio/cli": "^9.30.0",
     "@wdio/local-runner": "^9.30.0",
-    "@wdio/mocha-framework": "^7.7.3",
+    "@wdio/mocha-framework": "^9.32.0",
     "@wdio/spec-reporter": "^9.29.1",
+    "typescript": "^5.9.3",
     "webdriverio": "^9.0.0"
   },
   "scripts": {

package/src/A11yCoreBuilder.d.ts

@@ -3,150 +3,68 @@
 // 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';
+
+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 +111,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 +125,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;
@@ -221,16 +148,29 @@ 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, or `INVALID_CONTEXT_SELECTOR` (with `selector`) when an include()
+   * selector does not parse.
+   */
   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 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).
@@ -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,31 @@ 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`.
+    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);
+      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 +295,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 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
+};