@a11y-pulse/moving-content-audit 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,166 @@
1
+ Copyright (c) 2026-present, A11y Pulse (https://www.a11ypulse.com/). All rights reserved.
2
+
3
+ # PolyForm Shield License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/shield/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree
10
+ to them as both strict obligations and conditions to all
11
+ your licenses.
12
+
13
+ ## Copyright License
14
+
15
+ The licensor grants you a copyright license for the
16
+ software to do everything you might do with the software
17
+ that would otherwise infringe the licensor's copyright
18
+ in it for any permitted purpose. However, you may
19
+ only distribute the software according to [Distribution
20
+ License](#distribution-license) and make changes or new works
21
+ based on the software according to [Changes and New Works
22
+ License](#changes-and-new-works-license).
23
+
24
+ ## Distribution License
25
+
26
+ The licensor grants you an additional copyright license
27
+ to distribute copies of the software. Your license
28
+ to distribute covers distributing the software with
29
+ changes and new works permitted by [Changes and New Works
30
+ License](#changes-and-new-works-license).
31
+
32
+ ## Notices
33
+
34
+ You must ensure that anyone who gets a copy of any part of
35
+ the software from you also gets a copy of these terms or the
36
+ URL for them above, as well as copies of any plain-text lines
37
+ beginning with `Required Notice:` that the licensor provided
38
+ with the software. For example:
39
+
40
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
41
+
42
+ ## Changes and New Works License
43
+
44
+ The licensor grants you an additional copyright license to
45
+ make changes and new works based on the software for any
46
+ permitted purpose.
47
+
48
+ ## Patent License
49
+
50
+ The licensor grants you a patent license for the software that
51
+ covers patent claims the licensor can license, or becomes able
52
+ to license, that you would infringe by using the software.
53
+
54
+ ## Noncompete
55
+
56
+ Any purpose is a permitted purpose, except for providing any
57
+ product that competes with the software or any product the
58
+ licensor or any of its affiliates provides using the software.
59
+
60
+ ## Competition
61
+
62
+ Goods and services compete even when they provide functionality
63
+ through different kinds of interfaces or for different technical
64
+ platforms. Applications can compete with services, libraries
65
+ with plugins, frameworks with development tools, and so on,
66
+ even if they're written in different programming languages
67
+ or for different computer architectures. Goods and services
68
+ compete even when provided free of charge. If you market a
69
+ product as a practical substitute for the software or another
70
+ product, it definitely competes.
71
+
72
+ ## New Products
73
+
74
+ If you are using the software to provide a product that does
75
+ not compete, but the licensor or any of its affiliates brings
76
+ your product into competition by providing a new version of
77
+ the software or another product using the software, you may
78
+ continue using versions of the software available under these
79
+ terms beforehand to provide your competing product, but not
80
+ any later versions.
81
+
82
+ ## Discontinued Products
83
+
84
+ You may begin using the software to compete with a product
85
+ or service that the licensor or any of its affiliates has
86
+ stopped providing, unless the licensor includes a plain-text
87
+ line beginning with `Licensor Line of Business:` with the
88
+ software that mentions that line of business. For example:
89
+
90
+ > Licensor Line of Business: YoyodyneCMS Content Management
91
+ System (http://example.com/cms)
92
+
93
+ ## Sales of Business
94
+
95
+ If the licensor or any of its affiliates sells a line of
96
+ business developing the software or using the software
97
+ to provide a product, the buyer can also enforce
98
+ [Noncompete](#noncompete) for that product.
99
+
100
+ ## Fair Use
101
+
102
+ You may have "fair use" rights for the software under the
103
+ law. These terms do not limit them.
104
+
105
+ ## No Other Rights
106
+
107
+ These terms do not allow you to sublicense or transfer any of
108
+ your licenses to anyone else, or prevent the licensor from
109
+ granting licenses to anyone else. These terms do not imply
110
+ any other licenses.
111
+
112
+ ## Patent Defense
113
+
114
+ If you make any written claim that the software infringes or
115
+ contributes to infringement of any patent, your patent license
116
+ for the software granted under these terms ends immediately. If
117
+ your company makes such a claim, your patent license ends
118
+ immediately for work on behalf of your company.
119
+
120
+ ## Violations
121
+
122
+ The first time you are notified in writing that you have
123
+ violated any of these terms, or done anything with the software
124
+ not covered by your licenses, your licenses can nonetheless
125
+ continue if you come into full compliance with these terms,
126
+ and take practical steps to correct past violations, within
127
+ 32 days of receiving notice. Otherwise, all your licenses
128
+ end immediately.
129
+
130
+ ## No Liability
131
+
132
+ ***As far as the law allows, the software comes as is, without
133
+ any warranty or condition, and the licensor will not be liable
134
+ to you for any damages arising out of these terms or the use
135
+ or nature of the software, under any kind of legal claim.***
136
+
137
+ ## Definitions
138
+
139
+ The **licensor** is the individual or entity offering these
140
+ terms, and the **software** is the software the licensor makes
141
+ available under these terms.
142
+
143
+ A **product** can be a good or service, or a combination
144
+ of them.
145
+
146
+ **You** refers to the individual or entity agreeing to these
147
+ terms.
148
+
149
+ **Your company** is any legal entity, sole proprietorship,
150
+ or other kind of organization that you work for, plus all
151
+ its affiliates.
152
+
153
+ **Affiliates** means the other organizations than an
154
+ organization has control over, is under the control of, or is
155
+ under common control with.
156
+
157
+ **Control** means ownership of substantially all the assets of
158
+ an entity, or the power to direct its management and policies
159
+ by vote, contract, or otherwise. Control can be direct or
160
+ indirect.
161
+
162
+ **Your licenses** are all the licenses granted to you for the
163
+ software under these terms.
164
+
165
+ **Use** means anything you do with the software requiring one
166
+ of your licenses.
package/README.md CHANGED
@@ -1,3 +1,222 @@
1
- # Temporary Holding Version
1
+ # @a11y-pulse/moving-content-audit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/@a11y-pulse/moving-content-audit)](https://www.npmjs.com/package/@a11y-pulse/moving-content-audit)
4
+ [![CI](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml/badge.svg)](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml)
5
+ [![License: PolyForm Shield 1.0.0](https://img.shields.io/badge/license-PolyForm%20Shield%201.0.0-blue)](./LICENSE.md)
6
+
7
+ An accessibility audit for [**WCAG 2.2: 2.2.2 Pause, Stop, Hide**](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide). Content that starts moving on its own, keeps moving for more than five seconds and sits beside other content needs a way to pause, stop or hide it. Carousels on a timer, news tickers and background videos are the usual offenders: they pull attention away from the rest of the page, and some people cannot read past them at all.
8
+
9
+ Static analysis cannot see movement. This audit loads nothing and presses nothing: it watches the page for five seconds, works out which regions are still moving at the end, and looks for a control that pauses them.
10
+
11
+ This audit was developed by [A11y Pulse](https://www.a11ypulse.com/) for its accessibility monitoring service. It is released as source-available under the [PolyForm Shield License 1.0.0](#license).
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install @a11y-pulse/moving-content-audit @a11y-pulse/browser-adaptor puppeteer
17
+ ```
18
+
19
+ ## Quickstart
20
+
21
+ ```js
22
+ import { runMovingContentAudit } from "@a11y-pulse/moving-content-audit";
23
+ import { PuppeteerAdaptor } from "@a11y-pulse/browser-adaptor/puppeteer";
24
+ import puppeteer from "puppeteer";
25
+
26
+ const browser = await puppeteer.launch();
27
+ const page = await browser.newPage();
28
+ await page.goto("https://who.likesdogs.nz/");
29
+
30
+ const result = await runMovingContentAudit(new PuppeteerAdaptor(page));
31
+
32
+ console.log(result.summary);
33
+ // { checked: 2, failed: 1, needsReview: 0, passed: 1, unchecked: 0,
34
+ // ignored: { essential: 1, tooSmall: 0 } }
35
+
36
+ console.log(result.failed);
37
+ // [
38
+ // {
39
+ // selector: "#offers",
40
+ // html: '<div class="carousel__viewport" id="offers">',
41
+ // rect: { x: 20, y: 132, width: 760, height: 280 },
42
+ // motion: "script",
43
+ // detectedBy: "dom-observation",
44
+ // finding: "no-pause-control",
45
+ // observedMs: 4900,
46
+ // animations: [],
47
+ // pauseControl: null,
48
+ // pausesOn: [],
49
+ // reducedMotion: null,
50
+ // screenshot: Uint8Array(…),
51
+ // laterScreenshot: Uint8Array(…)
52
+ // }
53
+ // ]
54
+
55
+ await browser.close();
56
+ ```
57
+
58
+ The audit takes at least as long as its observation window: five seconds by default, plus up to about a second and a half for screenshots when something is reported. Run it on a page nothing else is driving, since focus changes, key presses and scrolling by another audit would be seen as movement.
59
+
60
+ ## How it decides
61
+
62
+ ### What counts as moving
63
+
64
+ | Movement | How it is found | `motion` / `detectedBy` |
65
+ | --- | --- | --- |
66
+ | A CSS animation that is endless, or runs for more than five seconds in total, and changes at least one property | `document.getAnimations()` at the end of the window | `css-animation` / `animation-api` |
67
+ | The same, started by a script with `element.animate()` | `document.getAnimations()` | `web-animation` / `animation-api` |
68
+ | A carousel, ticker or slideshow driven by a script | Elements a script touches during the window (their style, class or SVG geometry attributes, their children, their scroll offset) are sampled about fifty times; a region counts when its position, size, opacity, visibility, transform, scroll offset or image keeps changing, or short animations keep starting on it | `script` / `dom-observation` |
69
+ | `<marquee>` | The element itself | `marquee` / `element` |
70
+ | A `<video>` that is playing | Its playback state at the start and end of the window | `video` / `media-element` |
71
+
72
+ Script-driven movement has to be sustained and still going in the last two fifths of the window. Changes are grouped into bursts, a burst ending when the region holds still for a tenth of the window. Sustained means the movement came back after a pause (a carousel turning at least twice) or ran on without one for two fifths of the window (a ticker a script moves every frame). One burst late in the window, such as one turn of a slow carousel, is reported for review as `changed-once`.
73
+
74
+ Content arriving is not movement. The changes that bring an element into view (a consent bar sliding up, a slide fading in, a slot being filled) are left out, and a region whose moving elements all arrived during the window has to change more than once after that to be reported. So a region that settles early or arrives once (an entrance effect, a lazy-loaded banner, a notice that appears, an ad slot filled and then resized to its creative) is not reported. Animations that end within five seconds are allowed by the criterion and never reported, however short the observation window is.
75
+
76
+ At most 150 touched elements are watched at a time. Ones that were touched without changing, or that changed and have been still since, make room for new ones, so a burst of one-off changes while the page loads does not hide a carousel that starts later.
77
+
78
+ Moving elements are gathered into regions. A track sliding inside a smaller `overflow: hidden` box is reported as that box, an element moving inside another moving element is part of it, and slides stacked on top of each other are joined under their common parent. A region's `rect` is the part of it that can be seen.
79
+
80
+ ### What is left alone
81
+
82
+ - **Loading and status indicators**: anything inside `role="progressbar"`, `status`, `alert`, `timer` or `log`, inside `aria-busy="true"`, a `<progress>` or `<meter>`, or with a class or id of `spinner`, `loader`, `loading`, `skeleton`, `shimmer` or `progress`. These are counted in `summary.ignored.essential`.
83
+ - **Small regions**: under `minRegionArea` (5000 CSS px², about 70 × 70). Counted in `summary.ignored.tooSmall`. An animated pseudo-element is measured by its own `width` and `height` where they can be read, so a ten-pixel "live" dot in the corner of a card is small however large the card is.
84
+ - **What nobody can see**: an element that is `visibility: hidden`, fully transparent (itself or through an ancestor), outside the page, or fixed outside the viewport, and that was not seen showing at any point in the window. A hidden preloader whose animation never stops is not reported; a slide that had just faded out when the window closed still counts.
85
+ - **Text updates**: a clock, counter or score changing its text is updating, not moving.
86
+
87
+ ### Looking for a way to pause
88
+
89
+ For each moving region the audit looks for, in order:
90
+
91
+ 1. A button, switch, checkbox or `<summary>` (an element with `role="button"` counts, a plain link does not) inside the region, or inside up to three ancestors that are no more than six times its size, or pointing at it with `aria-controls`, whose label says pause, stop, hide, close or dismiss (English plus Spanish, German, French, Dutch, Italian and Swedish words; see `controlNamePattern`). "Play" counts as the whole label, paired with pause ("Play/Pause"), or followed by what is moving ("Play slideshow"); "Play trailer" does not. Labels over 40 characters are ignored, so a slide headline such as "Stop wasting money on tents" is not taken for a control.
92
+ 2. The same kind of control with no label but a class or id of `pause`, `play-pause` or `stop`. The missing label is another audit's finding.
93
+ 3. A control or link anywhere on the page that turns animation off ("Pause animations", "Reduce motion").
94
+ 4. For a video, the browser's own `controls`.
95
+
96
+ The audit does not press the control, so it does not check that it works.
97
+
98
+ ### Verdicts
99
+
100
+ | List | `finding` | When |
101
+ | --- | --- | --- |
102
+ | `failed` | `no-pause-control` | A region of at least `largeRegionArea` (20000 CSS px², for example a 760 × 48 ticker) kept moving past the window and nothing above was found |
103
+ | `passed` | `pause-control` | A pause control was found |
104
+ | `passed` | `native-controls` | A playing video has `controls` |
105
+ | `needsReview` | `pauses-on-hover` | A stylesheet rule pauses the CSS animation on `:hover`. A keyboard user cannot hover |
106
+ | `needsReview` | `pauses-on-focus` | A stylesheet rule pauses the CSS animation on `:focus` or `:focus-within` |
107
+ | `needsReview` | `small-region` | The region is under `largeRegionArea` and may be decoration |
108
+ | `needsReview` | `subtle-animation` | The animation changes only colour, shadow or filter |
109
+ | `needsReview` | `changed-once` | The region changed in one burst late in the window, such as one slide of a carousel on a four-second timer |
110
+ | `needsReview` | `pseudo-element` | Only a pseudo-element is animated and its size could not be read (an inline `::after` cursor, for example). A pseudo-element of at least `largeRegionArea` is treated as the region itself |
111
+ | `needsReview` | `finite-loop` | A `<marquee>` with a `loop` count |
112
+ | `needsReview` | `uncertain-playback` | A video that started during the window, or whose length is unknown |
113
+
114
+ `reducedMotion` records whether a `prefers-reduced-motion` rule applies to the region's CSS animation. It is supporting evidence and never changes the verdict: the criterion asks for a mechanism on the page.
115
+
116
+ ## Browser support
117
+
118
+ The audit uses `document.getAnimations()`, `MutationObserver` and `Element.checkVisibility()`, all available in current Chromium, Firefox and WebKit. Its integration suite runs on every engine the repository's CI covers; at the time of writing it has been run against Chromium through Puppeteer and Playwright. How `<marquee>` and stream-backed videos report themselves varies between engines, so treat Firefox and WebKit results for those two as less certain.
119
+
120
+ The adaptor must provide `evaluate`, `evaluateHandle`, `disposeRef` and `screenshotClip`. The bundled `PuppeteerAdaptor` and `PlaywrightAdaptor` do.
121
+
122
+ ## Options
123
+
124
+ | Option | Default | Description |
125
+ | --- | --- | --- |
126
+ | `observationWindow` | `5000` | How long to watch the page, in ms. Content still moving at the end is reported. Five seconds is the limit in the criterion; a shorter window makes script-driven findings less certain, a longer one catches slower carousels. |
127
+ | `minRegionArea` | `5000` | Smallest visible area, in CSS px², of a moving region worth reporting. |
128
+ | `largeRegionArea` | `20000` | Smallest visible area, in CSS px², of a region that can fail. Smaller regions are reported for review. |
129
+ | `regionLimit` | `20` | Max moving regions to examine, largest first. |
130
+ | `controlNamePattern` | see `DEFAULT_CONTROL_NAME_PATTERN` | Regular expression source, matched case-insensitively (with the `u` flag) against the label of controls near a moving region. |
131
+ | `screenshotLimit` | `5` | Max failed and needs-review regions to screenshot, failed first. `0` takes none. |
132
+ | `screenshotInterval` | `1000` | Time between a region's two screenshots, in ms. |
133
+
134
+ ## Result shape
135
+
136
+ ```ts
137
+ type MovingContentRegion = {
138
+ /** Selector for the moving region. */
139
+ selector: string;
140
+ /** Truncated opening tag. */
141
+ html: string;
142
+ /** The visible part of the region, in document coordinates. */
143
+ rect: { x: number; y: number; width: number; height: number };
144
+ motion: "video" | "marquee" | "css-animation" | "web-animation" | "script";
145
+ detectedBy: "media-element" | "element" | "animation-api" | "dom-observation";
146
+ /** Why the region is in the list it is in. See the verdicts table. */
147
+ finding: MovingContentFinding;
148
+ /** How long into the observation window the region was last seen moving. */
149
+ observedMs: number;
150
+ /** The long-running animations on the region. */
151
+ animations: {
152
+ name: string | null;
153
+ infinite: boolean;
154
+ activeDurationMs: number | null;
155
+ /** The CSS properties whose value changes over the animation. */
156
+ properties: string[];
157
+ /** The pseudo-element the animation runs on, such as "::after", or null. */
158
+ pseudoElement: string | null;
159
+ }[];
160
+ pauseControl: {
161
+ selector: string;
162
+ html: string;
163
+ name: string;
164
+ foundBy: "name" | "attribute" | "page-control";
165
+ } | null;
166
+ /** States in which a stylesheet rule pauses the region's CSS animation. */
167
+ pausesOn: ("hover" | "focus")[];
168
+ /** Whether a prefers-reduced-motion rule applies. Null when it is not a CSS animation. */
169
+ reducedMotion: boolean | null;
170
+ /** PNG bytes of the region at the end of the window, for failed and needs-review regions. */
171
+ screenshot?: Uint8Array;
172
+ /** PNG bytes of the region `screenshotInterval` later. */
173
+ laterScreenshot?: Uint8Array;
174
+ };
175
+
176
+ type MovingContentResult = {
177
+ failed: MovingContentRegion[];
178
+ needsReview: MovingContentRegion[];
179
+ passed: MovingContentRegion[];
180
+ /** How long the page was observed for. */
181
+ observedMs: number;
182
+ summary: {
183
+ checked: number;
184
+ failed: number;
185
+ needsReview: number;
186
+ passed: number;
187
+ /** Moving regions past `regionLimit`. */
188
+ unchecked: number;
189
+ ignored: { essential: number; tooSmall: number };
190
+ };
191
+ };
192
+ ```
193
+
194
+ The two screenshots are evidence for a person, and the audit does not compare them: a carousel can look the same in both if they fall between slides. Each region is scrolled into view for its captures and the page is scrolled back afterwards. The audit removes its observers and everything it left on `window` before it returns.
195
+
196
+ ## Limitations
197
+
198
+ - **Slow carousels.** A carousel that advances less often than about every two and a half seconds changes once in the window and is reported for review; one on a timer longer than the window is not seen at all. Raise `observationWindow` to catch them.
199
+ - **Content that arrives and then moves slowly.** A carousel that is itself inserted during the window has its first changes read as its entrance, so it needs two further turns in the window to be reported.
200
+ - **Canvas, WebGL and animated images.** Movement drawn inside a `<canvas>`, an animated GIF, APNG or WebP, and an animated SVG using SMIL are not detected.
201
+ - **Only what a script touches is watched.** Script-driven movement is found through changes to `style`, `class`, `hidden`, `src`, `open` and SVG geometry attributes (`transform`, `d`, `points`, `x`, `y`, `cx`, `cy`, `r`, `width`, `height`, `viewBox` and the like), child changes and scroll events. Movement driven through any other attribute or through a CSS custom property set on a distant ancestor is not seen. Movement inside closed shadow roots, cross-origin iframes, or shadow roots attached after the audit starts is not seen.
202
+ - **Auto-updating content.** The second half of the criterion, content that updates on its own such as a live score, is out of scope.
203
+ - **The control is not operated.** A button labelled "Pause" that does nothing passes. So does a region whose only nearby match is an unrelated "Close" button. A pause control that is a plain link (`<a href="#">Pause</a>` with no `role="button"`) is not recognised.
204
+ - **Hover and focus pausing is read from stylesheets only.** A script that pauses a carousel on `mouseenter` or `focusin` is not recognised, and cross-origin stylesheets cannot be read.
205
+ - **Listed languages only.** A pause control labelled in another language is not recognised unless `controlNamePattern` covers it.
206
+ - **Parallax and scroll-linked effects** do not start on their own and are not reported, since nothing scrolls during the window.
207
+
208
+ ## Known false positives
209
+
210
+ - **Decorative background animation.** A large hero with a slowly drifting gradient or floating shapes fails when it moves, resizes or fades. Whether that is "presented in parallel with other content" in a way that matters is a judgement call; a page-wide "Pause animations" control passes it.
211
+ - **Large loading placeholders with no semantics.** A skeleton screen that never resolves and has no `aria-busy`, status role or recognisable class is reported.
212
+ - **Live video feeds.** A webcam or stream preview with custom controls labelled in an unlisted language fails.
213
+
214
+ ## License
215
+
216
+ Released under the [PolyForm Shield License 1.0.0](./LICENSE.md), in plain language:
217
+
218
+ - **Source-available.** The source is public and you can read, fork, and modify it.
219
+ - **Permitted for non-competing use.** You can use this package freely in your own products and services, as long as they don't compete with A11y Pulse.
220
+ - **Competing products are forbidden.** You may not use this software (or a modified version of it) to build a product or service that competes with A11y Pulse's accessibility monitoring offering.
221
+
222
+ See [LICENSE.md](./LICENSE.md) for the full, binding terms.
@@ -0,0 +1,57 @@
1
+ import { type BrowserAdaptor } from "@a11y-pulse/browser-adaptor";
2
+ import type { MovingContentResult } from "./result";
3
+ /** WCAG 2.2.2 allows movement that stops within five seconds. */
4
+ export declare const DURATION_LIMIT_MS = 5000;
5
+ export declare const DEFAULT_OBSERVATION_WINDOW = 5000;
6
+ export declare const DEFAULT_MIN_REGION_AREA = 5000;
7
+ export declare const DEFAULT_LARGE_REGION_AREA = 20000;
8
+ export declare const DEFAULT_REGION_LIMIT = 20;
9
+ export declare const DEFAULT_SCREENSHOT_LIMIT = 5;
10
+ export declare const DEFAULT_SCREENSHOT_INTERVAL = 1000;
11
+ /**
12
+ * Labels of a control that pauses, stops or hides moving content. "Play" only counts as the whole
13
+ * label, paired with "pause", or followed by what is moving ("Play slideshow"): "Play trailer"
14
+ * starts something else.
15
+ */
16
+ export declare const DEFAULT_CONTROL_NAME_PATTERN = "(^|[^\\p{L}])(pause|paused|unpause|stop|halt|freeze|hide|close|dismiss|pausar|pausa|detener|parar|pausieren|anhalten|stopp|stoppen|arr\u00EAter|pauzeren|fermare|pausera|stoppa|play\\s*(/|\\||&|and|or)\\s*pause|play(ing)?\\s+(the\\s+)?(slideshow|slide\\s?show|slides|carousel|animations?|rotation|ticker|marquee|background\\s+video))($|[^\\p{L}])|^\\s*(play|playing)\\s*$";
17
+ export type MovingContentOptions = {
18
+ /**
19
+ * How long to watch the page for, in ms. Content still moving at the end is reported. Defaults
20
+ * to 5000, the limit in WCAG 2.2.2; the audit takes at least this long.
21
+ */
22
+ observationWindow?: number;
23
+ /** Smallest visible area, in CSS px², of a moving region worth reporting. Defaults to 5000. */
24
+ minRegionArea?: number;
25
+ /**
26
+ * Smallest visible area, in CSS px², of a region that can fail. Smaller regions are reported
27
+ * for review. Defaults to 20000.
28
+ */
29
+ largeRegionArea?: number;
30
+ /** Max moving regions to examine, largest first. Defaults to 20. */
31
+ regionLimit?: number;
32
+ /**
33
+ * Regular expression source, matched case-insensitively against the label of controls near a
34
+ * moving region to find one that pauses, stops or hides it.
35
+ */
36
+ controlNamePattern?: string;
37
+ /**
38
+ * Max failed and needs-review regions to screenshot, failed first. Each gets two captures,
39
+ * `screenshotInterval` apart. Defaults to 5; 0 takes none.
40
+ */
41
+ screenshotLimit?: number;
42
+ /** Time between a region's two screenshots, in ms. Defaults to 1000. */
43
+ screenshotInterval?: number;
44
+ };
45
+ /** How often, in ms, the page is sampled over an observation window of `observationWindow` ms. */
46
+ export declare function pollInterval(observationWindow: number): number;
47
+ /**
48
+ * How long, in ms, an element has to hold still for its next change to count as a separate burst
49
+ * of movement.
50
+ */
51
+ export declare function quietGap(observationWindow: number): number;
52
+ /**
53
+ * Watch the page for content that keeps moving on its own and look for a way to pause it. Nothing
54
+ * is pressed or hovered, and the page is left as it was found. Takes `observationWindow` ms, 5
55
+ * seconds by default, plus the time for screenshots.
56
+ */
57
+ export declare function runMovingContentAudit(adaptor: BrowserAdaptor, options?: MovingContentOptions): Promise<MovingContentResult>;
@@ -0,0 +1,113 @@
1
+ /**
2
+ * IMPORTANT: The `*Script` functions in this file are serialized and injected into the audited
3
+ * page, so they must not reference any symbols outside their own scope.
4
+ */
5
+ import type { Rect } from "@a11y-pulse/browser-adaptor";
6
+ export type CollectedAnimation = {
7
+ name: string | null;
8
+ /** A CSS animation, as opposed to one a script started through the Web Animations API. */
9
+ css: boolean;
10
+ infinite: boolean;
11
+ activeDurationMs: number | null;
12
+ /** Properties whose value changes over the animation. Empty when they could not be read. */
13
+ properties: string[];
14
+ /** The pseudo-element the animation runs on, such as `::after`. Null for the element itself. */
15
+ pseudoElement: string | null;
16
+ /** The pseudo-element's own area in CSS px², or null when its size could not be read. */
17
+ pseudoArea: number | null;
18
+ };
19
+ export type CollectedVideo = {
20
+ controls: boolean;
21
+ /** The video loops, or is a live stream with no end. */
22
+ endless: boolean;
23
+ /** Null for a live stream or a video whose length is not known yet. */
24
+ durationS: number | null;
25
+ /** The video was already playing when observation started. */
26
+ playingAtStart: boolean;
27
+ /** Its playback position moved during observation. */
28
+ advanced: boolean;
29
+ };
30
+ export type CollectedControl = {
31
+ /** Index of the control in the stash. */
32
+ elementIndex: number;
33
+ html: string;
34
+ name: string;
35
+ foundBy: "name" | "attribute" | "page-control";
36
+ };
37
+ export type CollectedRegion = {
38
+ /** Index of the region's element in the stash. */
39
+ elementIndex: number;
40
+ /** Shallow outerHTML. */
41
+ html: string;
42
+ /** The visible part of the region, in document coordinates. */
43
+ rect: Rect;
44
+ /**
45
+ * When, in ms since observation started, an element in the region was seen to change position,
46
+ * size, visibility or scroll offset, or a short animation was seen to start on it. The changes
47
+ * that first brought an element into view are left out.
48
+ */
49
+ times: number[];
50
+ /** Every element seen changing only came into view, or was only inserted, during the watch. */
51
+ appeared: boolean;
52
+ /** Animations still running that last longer than the limit. */
53
+ animations: CollectedAnimation[];
54
+ /** Set for a `<marquee>`: its `loop` count, -1 for endless. */
55
+ marquee: {
56
+ loop: number;
57
+ } | null;
58
+ video: CollectedVideo | null;
59
+ control: CollectedControl | null;
60
+ pausesOn: ("hover" | "focus")[];
61
+ reducedMotion: boolean | null;
62
+ };
63
+ export type RegionCollection = {
64
+ /** How long the page was observed for. */
65
+ elapsedMs: number;
66
+ regions: CollectedRegion[];
67
+ /** Every moving region, including those past the region limit. */
68
+ total: number;
69
+ /** Moving regions under the size threshold. */
70
+ tooSmall: number;
71
+ /** Moving progress indicators, status messages and busy regions. */
72
+ essential: number;
73
+ };
74
+ export type CollectOptions = {
75
+ /** Animations no longer than this are allowed to run to their end. */
76
+ durationLimitMs: number;
77
+ minRegionArea: number;
78
+ regionLimit: number;
79
+ /** Regular expression source matched against a nearby control's label. */
80
+ controlNamePattern: string;
81
+ /** Regular expression source matched against an unlabelled nearby control's class and id. */
82
+ controlAttributePattern: string;
83
+ /** Regular expression source matched against the label of any control on the page. */
84
+ pageControlPattern: string;
85
+ /** Regular expression source matched against the class and id of loading indicators. */
86
+ essentialPattern: string;
87
+ };
88
+ /**
89
+ * Start watching the page for movement nothing asked for. Records, on `window[stateKey]`, when
90
+ * elements a script touches change position, size, visibility or scroll offset, and when short
91
+ * animations start. Changes that bring an element into view (a banner sliding in, a slot being
92
+ * filled) are its entrance, not movement, and are left out: a run of changes ends once
93
+ * `quietGapMs` passes without one. collectRegionsScript reads the record and stops the watch.
94
+ */
95
+ export declare function startObservationScript(stateKey: string, pollMs: number, durationLimitMs: number, trackLimit: number, quietGapMs: number): void;
96
+ /**
97
+ * Stop the watch started by startObservationScript, if it is still running.
98
+ */
99
+ export declare function stopObservationScript(stateKey: string): void;
100
+ /**
101
+ * Stop the watch started by startObservationScript and gather what moved into regions, each with
102
+ * the facts needed to judge it. The region elements and any pause controls found are left on
103
+ * `window[stashKey]`.
104
+ */
105
+ export declare function collectRegionsScript(stateKey: string, stashKey: string, options: CollectOptions): RegionCollection;
106
+ export declare function scrollPositionScript(): {
107
+ x: number;
108
+ y: number;
109
+ };
110
+ export declare function restoreScrollScript(position: {
111
+ x: number;
112
+ y: number;
113
+ }): void;
@@ -0,0 +1,54 @@
1
+ import type { CollectedRegion } from "./browser-scripts";
2
+ export type MotionKind = "video" | "marquee" | "css-animation" | "web-animation" | "script";
3
+ export type DetectedBy = "media-element" | "element" | "animation-api" | "dom-observation";
4
+ export type MovingContentFinding =
5
+ /** Failed: a large region kept moving and nothing pauses it. */
6
+ "no-pause-control"
7
+ /** Passed: a control that pauses, stops or hides the movement was found. */
8
+ | "pause-control"
9
+ /** Passed: the video has the browser's own controls. */
10
+ | "native-controls"
11
+ /** Review: the movement only pauses while hovered, which a keyboard user cannot do. */
12
+ | "pauses-on-hover"
13
+ /** Review: the movement pauses while focus is inside it. */
14
+ | "pauses-on-focus"
15
+ /** Review: the region is small enough that it may be decoration. */
16
+ | "small-region"
17
+ /** Review: the animation changes colour or shading, not position, size or visibility. */
18
+ | "subtle-animation"
19
+ /** Review: the region changed late in the window but was not seen to keep changing. */
20
+ | "changed-once"
21
+ /** Review: only a pseudo-element is animated, and its size could not be read. */
22
+ | "pseudo-element"
23
+ /** Review: the `<marquee>` stops by itself after a set number of loops. */
24
+ | "finite-loop"
25
+ /** Review: the video started during the window, or its length is unknown. */
26
+ | "uncertain-playback";
27
+ export type Verdict = "failed" | "needsReview" | "passed";
28
+ export type Classification = {
29
+ verdict: Verdict;
30
+ finding: MovingContentFinding;
31
+ motion: MotionKind;
32
+ detectedBy: DetectedBy;
33
+ observedMs: number;
34
+ };
35
+ export type ClassifyOptions = {
36
+ /** How long the page was observed for. */
37
+ observedMs: number;
38
+ /** WCAG's limit: movement that stops within this long is allowed. */
39
+ durationLimitMs: number;
40
+ /** Regions at least this large can fail. */
41
+ largeRegionArea: number;
42
+ /**
43
+ * Changes further apart than this belong to separate bursts of movement. Defaults to a tenth of
44
+ * the window.
45
+ */
46
+ quietGapMs?: number;
47
+ };
48
+ /** The quiet gap used when none is given, as a fraction of the observation window. */
49
+ export declare const QUIET_GAP_FRACTION = 0.1;
50
+ /**
51
+ * Decide which list a moving region belongs in, or return null when the page facts do not show it
52
+ * moving past the observation window.
53
+ */
54
+ export declare function classifyRegion(region: CollectedRegion, options: ClassifyOptions): Classification | null;
@@ -0,0 +1,5 @@
1
+ export type { BrowserAdaptor, ElementRef, Rect } from "@a11y-pulse/browser-adaptor";
2
+ export type { MovingContentOptions } from "./audit";
3
+ export { DEFAULT_CONTROL_NAME_PATTERN, DEFAULT_LARGE_REGION_AREA, DEFAULT_MIN_REGION_AREA, DEFAULT_OBSERVATION_WINDOW, DEFAULT_REGION_LIMIT, DEFAULT_SCREENSHOT_INTERVAL, DEFAULT_SCREENSHOT_LIMIT, DURATION_LIMIT_MS, runMovingContentAudit, } from "./audit";
4
+ export type { DetectedBy, MotionKind, MovingContentFinding } from "./classify";
5
+ export type { MovingContentAnimation, MovingContentPauseControl, MovingContentRegion, MovingContentResult, } from "./result";