@surea11y/webdriverio 1.3.0 → 1.4.0

package/README.md

@@ -8,6 +8,10 @@ A WebdriverIO binding for [`@surea11y/core`](https://github.com/SureA11y/core)
 npm install @surea11y/webdriverio webdriverio
 ```
 
+`@surea11y/core` 1.12.0 or later comes with it as a peer dependency, as WebdriverIO does: npm 7 and later, and pnpm 8 and later, install it for you, so the line above is all you need. With Yarn 1 or npm 6, which don't install peers, add `@surea11y/core` to that line.
+
+Being a peer means your project and this binding share one copy of core. That matters as soon as your project uses core directly, to write a SARIF log or an HTML report (`@surea11y/core/sarif`, `/report`), read the rule catalogue, or keep a baseline: those read results with the same core that produced them, so a report never labels a finding with another release's rules. It holds when you bring your own core too: a linked checkout (`file:../core`), a monorepo, a fork, or a pinned release. Before 1.4.0, core was a regular dependency, and a project whose core differed from the binding's got a second copy without a word; such a project needed `"overrides": { "@surea11y/core": "$@surea11y/core" }` in its `package.json`, which it can now drop.
+
 `webdriverio` v9 auto-manages a local `chromedriver` for you the first time it launches Chrome (no separate Selenium server, and no extra browser-download step needed) — so a fresh `npm install` is enough for `npm test` to launch a real headless Chrome on its own.
 
 ## Usage
@@ -34,7 +38,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.11.1"
+console.log(results.engine.version); // the @surea11y/core release that scanned, e.g. "1.12.0"
 await browser.deleteSession();
 ```
 
@@ -42,6 +46,8 @@ The builder takes `{ browser }` — the object WebdriverIO's `remote()` returns
 
 `results` is `@surea11y/core`'s own native result shape — see its [`OUTPUT_SCHEMA.md`](https://github.com/SureA11y/core/blob/main/docs/OUTPUT_SCHEMA.md) — not the `violations`/`passes`/`incomplete`/`inapplicable` shape used by other popular accessibility testing tools. The builder's *method names* are modeled on common conventions in this space for migration familiarity; the richer result schema is kept as-is.
 
+From 1.4.0 this package needs `@surea11y/core` 1.12.0 or later; see [What changes with `@surea11y/core` 1.12](#what-changes-with-surea11ycore-112).
+
 Also see `examples/basic-scan.js` for a runnable script (`npm run example -- <url>`).
 
 ### A note on the protocol: prefer classic WebDriver for this workload
@@ -50,9 +56,42 @@ WebdriverIO v9 defaults to the WebDriver **BiDi** protocol. A long-lived session
 
 ### Composing the rule filters
 
-`.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.
+`.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. The level is read in any case (`'aa'` is `'AA'`). 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, unless you ask for that with `.includeMode('or')` (below).
+
+`.includeMode(mode)` decides how `.withRules()` and `.withTags()` combine when both are given: `'and'`, the default, runs only the rules that match both, and `'or'` runs those that match either. That's what lets a scan say "this area, plus these checks". A team that owns a design system's form components, say, can run every rule about forms and the contrast check too, in one scan:
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .withTags('forms')
+  .withRules('contrast-computable')
+  .includeMode('or')             // every forms rule, plus the contrast check
+  .analyze();
+```
+
+Without `.includeMode('or')`, the same lines run no rule at all, since `contrast-computable` isn't tagged `forms`, and a scan of no rules looks clean. The same goes for a WCAG level tag beside a best practice: `.withTags('wcag2a').withRules('region')` runs nothing, and with `'or'` runs the `wcag2a` rules plus `region`. On its own, with no other selection, it changes nothing. A value other than `'and'` or `'or'` throws a `TypeError` with `code: 'INVALID_RUN_ONLY'` at the call. A `.withWcag()` target doesn't need it: its rules are always added to what tags and rules select.
+
+`.wcagLevel(level)` sets the WCAG level of the criteria a scan reports, without changing which rules run: criteria above it are left out of `results.rulesResults`, while every selected rule still runs and reports in `results.checksResults`. It's what lets a scan that names a few checks say it is meant as WCAG AA. A team that gates each pull request on colour contrast alone, say, runs one check, which covers both 1.4.3 (AA) and 1.4.6 (AAA):
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .withRules('contrast-computable')
+  .wcagLevel('AA')               // report 1.4.3, not the AAA 1.4.6
+  .analyze();
+```
+
+Without `.wcagLevel('AA')`, that scan reports 1.4.6 as well, so a site that meets AA can show a failing AAA criterion it never aimed for. With it, the scan reports 1.4.3 alone, and `results.engine.wcagLevel` says `'AA'`. A `.withWcag()` target already implies its level; `.wcagLevel()` is for selections that don't, and wins when both are given, as it does over a level given through `.options()`. `'A'`, `'AA'` or `'AAA'` in any case is accepted. Anything else throws a `TypeError` with `code: 'INVALID_ENGINE_OPTIONS'` at the call, and `null` clears it. Needs `@surea11y/core` 1.12.0 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.
+`.plannedChecks()` and `.plannedCriteria()` say what a scan *will* check before you run it: the rules it runs (entries with `ruleId`) and the criteria it reports in `rulesResults` (entries with `id`), worked out in Node from the same selection and options, with no browser. Use them to record what a run covered next to its result, or to catch a selection that runs nothing, which would otherwise look like a clean scan:
+
+```js
+const builder = new A11yCoreBuilder({ browser }).withTags('forms').withRules('contrast-computable');
+if (builder.plannedChecks().length === 0) {
+  throw new Error('This selection runs no rule. Did you mean .includeMode("or")?');
+}
+const results = await builder.analyze();
+```
 
 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.
 
@@ -60,7 +99,7 @@ Rule IDs change rarely, but core 1.10.0 changed two: `label-title-only` is depre
 
 `.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()`/`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.
+**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()`/`.includeMode()`/`.wcagLevel()`/`.logger()` 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.
 
@@ -102,9 +141,11 @@ A bare length/equality assertion alone gets you a *working* gate, but the failur
    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.
+Scanned with @surea11y/core 1.12.0.
 ```
 
+Before the version line, it also prints the result's notes (`getScanNotes()`, below), such as `The page was shown in forced colors (high contrast); contrast findings may differ with forced colors off.`
+
 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.
@@ -175,6 +216,60 @@ Two WebdriverIO-specific differences from the sibling bindings' `.elementRef(tru
 
 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.
 
+### Web components: the internals hook
+
+Many web components keep their `ElementInternals` in a private field and name themselves, set their states or give themselves a role through it:
+
+```js
+class SubscribeCheckbox extends HTMLElement {
+  #internals = this.attachInternals();
+  constructor() {
+    super();
+    this.#internals.ariaLabel = 'Subscribe';
+    this.#internals.ariaChecked = 'false';
+  }
+}
+```
+
+The browser exposes that name, but no page script can read it back, so by default the scan asks about such a component (`cantTell`) instead of judging it. A component that's a `switch` only through `this.#internals.role` isn't even asked about: the scan doesn't see its role, so it isn't checked at all.
+
+`A11yCoreBuilder.installInternalsHook(browser)` installs `@surea11y/core`'s opt-in hook, which records each component's internals for the scan to read. It has to run before the page's own scripts, so it uses:
+
+- **`browser.addInitScript()`** when the session speaks WebDriver BiDi (WebdriverIO 9's default): Chrome, Edge and Firefox;
+- otherwise, on **Chrome and Edge**, the DevTools protocol through chromedriver (`Page.addScriptToEvaluateOnNewDocument`). That covers the classic sessions this README [recommends for scanning](#a-note-on-the-protocol-prefer-classic-webdriver-for-this-workload), and WebdriverIO 8.
+
+Either way it runs in every frame and after each navigation. Call it **before** `browser.url()`:
+
+```js
+await A11yCoreBuilder.installInternalsHook(browser); // 'bidi' or 'cdp'
+await browser.url('https://example.com/');
+
+const results = await new A11yCoreBuilder({ browser }).analyze();
+results.engine.environment.internalsHook; // 'early': the hook ran before the page's scripts
+```
+
+In the WDIO testrunner, call it in a `before` hook. With it, the checkbox above passes, an unnamed component that attaches internals fails like any unnamed control, and the switch is checked as a switch, so it fails without a name. It resolves to `'bidi'` or `'cdp'`, the way it was installed.
+
+- **A classic session on Firefox or Safari** has no way to run a script before the page loads: the call rejects. There, such components stay questions, and roles set through internals aren't checked. A BiDi session reaches Firefox.
+- **Before the page loads.** On a page that's already loaded, the call has no effect until the next navigation (a refresh will do), and the result has no `internalsHook`.
+- **For test and audit runs.** The hook wraps `HTMLElement.prototype.attachInternals` (components get the same internals back), adds a stack frame to errors thrown through it, and keeps its record under a global symbol, where any script on the page can read every component's internals. That's why it's opt-in.
+- **Without it**, `analyze()` says so once per scan when it asked about such components (`1 custom element was asked about because the scan could not read...`), and `getScanNotes()` gives that note as `kind: 'internals-hook'`.
+
+### Forced colors
+
+A page shown in forced colors (Windows high contrast) draws in the user's colors, not its own. `results.engine.environment.forcedColors` says which it was: `'active'` or `'none'`. To check a page under forced colors on purpose in Chrome or Edge, emulate it through chromedriver's DevTools commands before scanning, in a classic or a BiDi session:
+
+```js
+await browser.sendCommand('Emulation.setEmulatedMedia', {
+  features: [{ name: 'forced-colors', value: 'active' }]
+});
+const results = await new A11yCoreBuilder({ browser }).analyze();
+results.engine.environment.forcedColors; // 'active'
+await browser.sendCommand('Emulation.setEmulatedMedia', { features: [] }); // back to normal
+```
+
+`browser.sendCommand()` is one of WebdriverIO's Chromium commands, so there's no equivalent for Firefox or Safari. The contrast rules still measure the page's own colors under forced colors, since WCAG judges contrast in those, so results match a scan with forced colors off; a contrast finding the engine couldn't measure that way carries `details.forcedColors: true`. When forced colors were active, `formatFailures()` adds a line saying so, since it's easy to miss on a CI agent with high contrast turned on.
+
 ### Registering a custom rule at runtime
 
 `@surea11y/core` supports registering additional rules per-scan via `engineOptions.customRules`. Use `.withCustomRules()` to register one:
@@ -207,6 +302,8 @@ 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.
 
+A custom rule you turn off for one scan (`.withCustomRules(rules).disableRules('org-banner-text')`) is listed in `skippedCustomRules` with `excluded: true` and isn't a scan gap, so it isn't warned about (core 1.12.0 and later).
+
 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
@@ -234,11 +331,39 @@ try {
 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 custom rule that did not run**, listed with its reason in `results.skippedCustomRules`. One you excluded yourself with `.disableRules()` is listed too, with `excluded: true`, and isn't a gap.
 - **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.
 
+That warning is the right default for a test run. A project that already handles gaps itself can take them over with `.logger(fn)`: `fn(gap, result)` is called once per gap, with the gap as `getScanGaps()` gives it and the result of the frame it came from, instead of `console.warn`. A scanning service that shows gaps to its users, say, can send them once to its own structured log, rather than also printing a loose line on the server's console for every scan:
+
+```js
+const results = await new A11yCoreBuilder({ browser })
+  .include('#checkout')
+  .logger((gap, frame) => log.warn({ url: frame.url, kind: gap.kind }, gap.message))
+  .analyze();
+```
+
+A batch job that writes `getScanGaps(results)` into its own report can pass `.logger(() => {})` to keep its output to the report, and `.logger(null)` brings `console.warn` back. Anything other than a function or `null` throws a `TypeError` at the call, and a later call replaces the logger. Either way, `getScanGaps(results)` still lists every gap.
+
+`getScanNotes(results)` says how the page was scanned, which a gap doesn't cover, and nothing was left out: `'forced-colors'` when the page was shown in [forced colors](#forced-colors), and `'internals-hook'` when the scan asked about web components it could have read with the [internals hook](#web-components-the-internals-hook). `analyze()` also prints the internals note, once per scan, and a `.logger()` receives it (check `kind` to tell a note from a gap).
+
+### Checking against EN 301 549
+
+EN 301 549, the standard the European Accessibility Act refers to, restates WCAG's Level A and AA criteria in its chapter 9. `.options({ profile })` runs the rules for its version, and each finding carries its EN 301 549 clause beside its WCAG criterion, in `meta.normativeMappings` (WCAG 1.1.1 is clause 9.1.1.1):
+
+```js
+// EN 301 549 V4.1.1 (WCAG 2.2 A and AA); 'en301549-v3.2.1' for V3.2.1 (WCAG 2.1 A and AA)
+const results = await new A11yCoreBuilder({ browser })
+  .options({ profile: 'en301549-v4.1.1' })
+  .analyze();
+
+results.engine.profile; // 'en301549-v4.1.1'
+```
+
+`.withWcag()`, `.withRules()` and `.withTags()` select rules instead of a profile, so leave them out when scanning with one. As with any target, a scan with no failures means no rule found a violation, not that the page conforms: most criteria need a person to check them. A profile name core doesn't know is not an error: the scan runs without it, core warns in the page's console, and `results.engine.profile` is left out.
+
 ### 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.
@@ -274,7 +399,23 @@ An element inside a shadow tree is different: its `selector` holds only inside i
 
 ## TypeScript
 
-`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.
+`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`, `ScanGap` and `ScanNote` come from `@surea11y/binding-base`, and so do the types of `withWcag()` and `wcagLevel()` (`WcagVersion`, `WcagLevelInput`), `plannedChecks()`/`plannedCriteria()` (`PlannedCheck`, `PlannedCriterion`), and `withPacks()`, which takes a pack made with `definePack` (`PackLike`). The static `installInternalsHook()` and `getScanNotes()` are typed too. 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.12
+
+This release needs `@surea11y/core` 1.12.0. What a scan through this binding shows differently (core's [`CHANGELOG.md`](https://github.com/SureA11y/core/blob/main/CHANGELOG.md) has the full list):
+
+- **An empty heading now fails an unscoped scan.** `empty-heading` used to ask about a heading with no accessible name; it now fails it. It's a best practice, so it runs in a scan that selects nothing and with `.withBestPractices()`, not under `.withWcag()`, tags or a profile. A gate on a page with `<h2></h2>` that asserted no failures now fails: fix the heading, or scan a WCAG target.
+- **Scans that pick rules report their criteria.** `.withRules('img-alt-present')`, a non-WCAG tag or `.withBestPractices()` now fill `rulesResults` with the WCAG criteria those rules belong to, where it was empty. A criterion whose other rules weren't selected is `cantTell` (`reasonCode` `composite.rollup.cantTell.notSelectedChild`), and each check's `rollupIds` names the criteria it was added for. `.wcagLevel()` keeps those criteria to a level.
+- **Four rules count towards more criteria**, as W3C's ACT rules map them: `input-image-alt-present` adds 4.1.2, `aria-roles-valid` 1.3.1, `link-name-present` 2.4.9 (AAA), and `meta-refresh-timing-absent` 2.2.4 and 3.2.5 (AAA). The findings don't change; the 1.3.1 and 4.1.2 rollups can now fail where they passed.
+- **Unnamed custom elements are questions.** A defined custom element with no visible name may name itself through `ElementInternals`, so it's `cantTell` (`name_internals`) where it used to fail. [`installInternalsHook()`](#web-components-the-internals-hook) lets the engine decide, where the session allows it.
+- **`engine.wcagLevel`** records the level a scan was gated by, and [`.wcagLevel()`](#composing-the-rule-filters) sets it.
+- **`engine.environment.forcedColors`** records whether the page was in [forced colors](#forced-colors).
+- **A custom rule you exclude** isn't a scan gap any more, so `.disableRules()` of one prints no warning.
+- **Rule IDs in another case select their rule**: `.withRules('IMG-ALT-PRESENT')` used to throw `INVALID_RUN_ONLY` or be ignored.
+- **`runOnly.optInTags` on its own throws** `INVALID_RUN_ONLY`; it was accepted and did nothing. Opt-in rules are unlocked with `.options({ optInRules })`.
+- **A finding in a shadow tree is located through its hosts**, as `#card >>> img`, in core's HTML report, SARIF, JUnit and baselines, as `formatFailures()` already did.
+- **An inline `policyContract`** with an unknown value in `allowedOutcomes` or `allowedConfidence` drops that value with a warning, where it turned every check into `cantTell`.
 
 ## What changes with `@surea11y/core` 1.11
 
@@ -288,7 +429,7 @@ The binding passes rule IDs, tags and options through to the engine, so these sh
 
 ## 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`/`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.
+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`/`includeMode`/`wcagLevel`/`logger`/`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:
 

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@surea11y/webdriverio",
-  "version": "1.3.0",
-  "description": "WebdriverIO binding for surea11y -- scan real, live-rendered pages for accessibility issues.",
+  "version": "1.4.0",
+  "description": "Accessibility (a11y, WCAG) checks for WebdriverIO tests: scan the live page with new A11yCoreBuilder({ browser }).analyze() and get only proven violations, with findings that need human review listed separately.",
   "keywords": [
     "accessibility",
     "a11y",
+    "a11y-testing",
     "wcag",
+    "wcag21",
     "wcag22",
+    "en301549",
+    "en-301-549",
+    "european-accessibility-act",
     "accessibility-testing",
     "webdriverio",
     "wdio",
     "webdriver",
     "e2e",
     "e2e-testing",
+    "end-to-end",
     "audit",
+    "aria",
     "surea11y"
   ],
   "main": "src/index.js",
@@ -40,13 +47,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@surea11y/binding-base": "^1.3.1",
-    "@surea11y/core": "^1.11.1"
+    "@surea11y/binding-base": "^1.4.0"
   },
   "peerDependencies": {
+    "@surea11y/core": ">=1.12.0",
     "webdriverio": ">=8.0.0"
   },
   "devDependencies": {
+    "@surea11y/core": "^1.12.0",
     "@wdio/cli": "^9.32.0",
     "@wdio/local-runner": "^9.32.0",
     "@wdio/mocha-framework": "^9.32.0",

package/src/A11yCoreBuilder.d.ts

@@ -10,7 +10,7 @@ import type {} from 'webdriverio';
 // { 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';
+import type { PackLike, WcagVersion, WcagLevelInput, ScanGap, ScanNote, PlannedCheck, PlannedCriterion } from '@surea11y/binding-base';
 export type { PackLike, WcagVersion, WcagLevel } from '@surea11y/binding-base';
 
 export type Outcome = Core.Outcome;
@@ -113,6 +113,15 @@ export class A11yCoreBuilder {
    */
   constructor(opts: { browser: WebdriverIO.Browser; url?: string });
 
+  /**
+   * Installs @surea11y/core's opt-in internals hook, so a scan can read
+   * names, states and roles web components set through a private
+   * ElementInternals. Call it before browser.url(). Uses addInitScript()
+   * in a BiDi session, else the DevTools protocol on Chrome and Edge, else
+   * rejects. Resolves to the way it was installed.
+   */
+  static installInternalsHook(browser: WebdriverIO.Browser): Promise<'bidi' | 'cdp'>;
+
   /**
    * Scope the scan to one region. Call multiple times for a multi-region
    * union. A selector that matches nothing scans nothing (see
@@ -144,9 +153,28 @@ export class A11yCoreBuilder {
    * 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;
+  withWcag(version: WcagVersion | 2.0 | 2.1 | 2.2, level?: WcagLevelInput): this;
   /** Also run the best-practice rules, those that name no WCAG criterion. */
   withBestPractices(enabled?: boolean): this;
+  /**
+   * How withRules() and withTags() combine when both are given: 'and' (the
+   * default) runs the rules matching both, 'or' those matching either. A
+   * later call replaces the mode.
+   */
+  includeMode(mode: 'and' | 'or'): this;
+  /**
+   * The WCAG level of the criteria the scan reports, without changing which
+   * rules run: `.withRules('contrast-computable').wcagLevel('AA')` reports
+   * 1.4.3 and not 1.4.6. Any case; null clears it. A later call replaces it.
+   */
+  wcagLevel(level: WcagLevelInput | null): this;
+  /**
+   * Where analyze() sends each scan gap instead of console.warn: called once
+   * per gap, with the result of the frame it came from, and once per scan
+   * for the internals-hook note (tell them apart by `kind`). `() => {}`
+   * silences them, `null` goes back to console.warn. A later call replaces it.
+   */
+  logger(fn: ((entry: ScanGap | ScanNote, result: A11yCoreResult) => void) | null): 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. */
@@ -162,6 +190,10 @@ export class A11yCoreBuilder {
   frames(enabled?: boolean): this;
   /** Opt in to resolving each fail/cantTell occurrence's selector to a live WebdriverIO.Element. */
   elementRef(enabled?: boolean): this;
+  /** The rules this scan will run, worked out in Node with no page (@surea11y/core 1.12.0 and later). */
+  plannedChecks(): PlannedCheck[];
+  /** The criteria this scan will report in rulesResults, worked out in Node with no page. */
+  plannedCriteria(): PlannedCriterion[];
 
   /**
    * Runs the scan. Returns { topFrame, frames } instead of a single result

package/src/A11yCoreBuilder.js

@@ -1,12 +1,11 @@
 'use strict';
 
-const { runa11yCoreInPage } = require('@surea11y/core');
+const { runa11yCoreInPage, internalsHookScript } = require('@surea11y/core');
 const {
   A11yCoreBuilderBase,
   createInPageScan,
   rethrowEngineError,
-  queryOccurrenceElement,
-  getScanGaps
+  queryOccurrenceElement
 } = require('@surea11y/binding-base');
 
 // core's runa11yCoreInPage, wrapped so an engine error (INVALID_RUN_ONLY,
@@ -146,6 +145,47 @@ const inPageScan = createInPageScan(runa11yCoreInPage);
  * exception: each call replaces the previous value rather than merging with it.
  */
 class A11yCoreBuilder extends A11yCoreBuilderBase {
+  /**
+   * Installs @surea11y/core's opt-in internals hook, so a scan can read the
+   * names, states and roles web components set through a private
+   * ElementInternals. Call it before browser.url(). It uses:
+   *
+   * - browser.addInitScript() when the session speaks WebDriver BiDi
+   *   (WebdriverIO 9's default);
+   * - otherwise, on Chrome and Edge, the DevTools protocol through
+   *   chromedriver (Page.addScriptToEvaluateOnNewDocument, sent with
+   *   browser.sendCommandAndGetResult()), as in a WebdriverIO 8 or
+   *   classic session.
+   *
+   * Both run the script in every frame of the page, before its scripts, and
+   * after each navigation. Any other session gets an error saying it has no
+   * way to run a script before the page loads. Resolves to the way it was
+   * installed, 'bidi' or 'cdp'.
+   * @param {WebdriverIO.Browser} browser
+   * @returns {Promise<'bidi' | 'cdp'>}
+   */
+  static async installInternalsHook(browser) {
+    if (!browser || typeof browser.execute !== 'function') {
+      throw new TypeError('A11yCoreBuilder.installInternalsHook() requires a WebdriverIO browser.');
+    }
+    const source = internalsHookScript();
+    if (browser.isBidi && typeof browser.addInitScript === 'function') {
+      // addInitScript() takes a function, and sends its source as a BiDi
+      // preload script.
+      await browser.addInitScript(new Function(source));
+      return 'bidi';
+    }
+    if (typeof browser.sendCommandAndGetResult === 'function') {
+      await browser.sendCommandAndGetResult('Page.addScriptToEvaluateOnNewDocument', { source });
+      return 'cdp';
+    }
+    throw new Error(
+      'A11yCoreBuilder.installInternalsHook(): this session has no way to run a script before the page loads. ' +
+      'Use a WebDriver BiDi session (WebdriverIO 9\'s default, in Chrome, Edge or Firefox), or Chrome or Edge, ' +
+      'whose DevTools protocol can.'
+    );
+  }
+
   /**
    * @param {{ browser: import('webdriverio').Browser, url?: string }} opts
    *   `browser` must already be navigated to and settled at the URL to scan --
@@ -202,7 +242,7 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
       const result = rethrowEngineError(
         await this._browser.execute(inPageScan, frameUrl, scope, engineOptions, runOnly)
       );
-      this._warnScanGaps(result);
+      this._warnScanGaps(result, '@surea11y/webdriverio');
       return this._elementRef ? this._attachElementRefs(result) : result;
     };
 
@@ -299,26 +339,6 @@ class A11yCoreBuilder extends A11yCoreBuilderBase {
     }
   }
 
-  /**
-   * 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

package/src/index.d.ts

@@ -3,6 +3,16 @@ export {
   EngineError,
   ENGINE_ERROR_CODES,
   getScanGaps,
+  getScanNotes,
   formatOccurrenceLocation
 } from '@surea11y/binding-base';
-export type { EngineErrorCode, ScanGap, ScanResultLike, OccurrenceLocation } from '@surea11y/binding-base';
+export type {
+  EngineErrorCode,
+  ScanGap,
+  ScanNote,
+  ScanResultLike,
+  OccurrenceLocation,
+  PlannedCheck,
+  PlannedCriterion,
+  WcagLevelInput
+} from '@surea11y/binding-base';

package/src/index.js

@@ -6,6 +6,7 @@ const {
   EngineError,
   ENGINE_ERROR_CODES,
   getScanGaps,
+  getScanNotes,
   formatOccurrenceLocation
 } = require('@surea11y/binding-base');
 
@@ -15,5 +16,6 @@ module.exports = {
   EngineError,
   ENGINE_ERROR_CODES,
   getScanGaps,
+  getScanNotes,
   formatOccurrenceLocation
 };