polite-media 0.4.3 → 0.6.0

package/src/coordinator.ts

@@ -1,11 +1,13 @@
 import { connectionAllowsMedia, mediaQuery, motionAllowed } from './env.js';
 import {
+  POLITE_VIDEO_BLOCKED,
   POLITE_VIDEO_PAUSECHANGE,
   POLITE_VIDEO_FAILED,
   POLITE_VIDEO_READY,
   type PolitePauseEventDetail,
   type PoliteVideoEventDetail,
 } from './events.js';
+import { warnIfFadeInvalid } from './fade.js';
 import { revealWhenPainted } from './reveal.js';
 import { isUnusable, manageSources, resetSourceWarnings, type SourceManager } from './sources.js';
 import { resolveTargets, type Target } from './targets.js';
@@ -66,8 +68,13 @@ export interface ConfigureOptions {
    */
   prefetchMargin?: string;
   /**
-   * Which viewports count as small. Configurable because 767px is one project's
+   * Which viewports count as small. Configurable because 768px is one project's
    * breakpoint, not a fact about phones.
+   *
+   * The default stops at 767.98px, leaving 0.02px beside a `(min-width: 768px)`
+   * rather than the whole pixel a zoomed page's fractional width can fall into.
+   * Range syntax would close the gap, but Safari before 16.4 never matches it, so
+   * phones there would count as large.
    */
   smallViewport?: string;
   /**
@@ -163,7 +170,7 @@ type ResolvedConfig = Required<ConfigureOptions>;
 
 const defaults: ResolvedConfig = {
   prefetchMargin: '0px',
-  smallViewport: '(max-width: 767px)',
+  smallViewport: '(max-width: 767.98px)',
   atOnce: { small: 1, large: 'all' },
   pauseBelow: 0.5,
   startWhen: 'page-loaded',
@@ -222,8 +229,8 @@ const HAVE_ENOUGH_DATA = 4;
  *   ladder was fixed at construction, so a late 0.4 takes effect at 0.25, the
  *   nearest crossing the observer still reports. That is the exact silent lie
  *   `thresholds()` exists to prevent, reached through a second door.
- * - `smallViewport` used to strand a listener. `mediaQuery` memoises by string,
- *   so detaching would resolve a different MediaQueryList than attaching did.
+ * - `smallViewport` strands a listener. `mediaQuery` memoises by string, so detaching resolves a
+ *   different MediaQueryList than attaching did.
  * - `prefetchMargin` builds the prefetch observer, at that same first `register()`.
  *   A late patch would not reach the one already built.
  */
@@ -261,12 +268,14 @@ export function configure(patch: ConfigureOptions): void {
  * `register()`, arbitrarily far from the `configure()` call responsible. So these
  * checks relocate the browser's own error to the call that caused it.
  *
- * `smallViewport` is the one that cannot be checked. An invalid media query does
- * not throw and does not normalise to something recognisable: Chromium echoes
- * the malformed text straight back through `MediaQueryList.media` and simply
- * never matches. So `smallViewport: '(max-width: 767)'`, one missing unit, means
- * arbitration silently never engages and phones behave like desktops. Only the
- * obviously empty case is caught; the rest is a documentation problem.
+ * `smallViewport` is not checked. An invalid media query does not throw and does
+ * not normalise to something recognisable: Chromium echoes the malformed text
+ * straight back through `MediaQueryList.media` and simply never matches. So
+ * `smallViewport: '(max-width: 767)'`, one missing unit, means arbitration
+ * silently never engages and phones behave like desktops. Chromium also never
+ * matches `not (query)` for such a query, which could detect it, but how Safari
+ * before 16.4 parses that form is not known, and a check that warned on valid
+ * queries there would be worse than none. Only the empty case is caught.
  */
 function validate(patch: ConfigureOptions): void {
   const { pauseBelow } = patch;
@@ -313,6 +322,9 @@ export interface RegisterOptions {
    * at scroll-top is reported visible in the observer's very first batch, so
    * without a gate it starts before whatever the page is waiting on (a splash
    * screen, a consent dialog) has finished.
+   *
+   * Settling, fulfilled or rejected, is the only release: a promise that never
+   * settles holds the video on its poster for the life of the page.
    */
   until?: Promise<unknown>;
   /**
@@ -328,12 +340,26 @@ export interface RegisterOptions {
    * the same rule buys nothing.
    */
   startWhen?: StartWhen;
+  /**
+   * Let the video download while `until` holds it, so a splash buys it load time.
+   * Only playback waits for the gate; the download still waits for `startWhen`,
+   * Save-Data, reduced motion and a user pause, and starts once the video is on
+   * screen or within `prefetchMargin`.
+   *
+   * Opt-in, because a gate holding the fetch too is what `until` has always
+   * done, and a page gating a video behind a consent dialog may rely on it.
+   */
+  prefetchWhileGated?: boolean;
 }
 
 interface Entry {
   video: HTMLVideoElement;
   target: Element;
-  /** Element carrying reveal state, so CSS can drive poster and video together. */
+  /**
+   * Element carrying reveal state, so CSS can drive poster and video together: the nearest
+   * `[data-polite-media]` ancestor, or the parent where none is authored so the warning below has
+   * an element to check.
+   */
   host: Element;
   /** How much of the target is visible; 0 when offscreen. */
   ratio: number;
@@ -341,6 +367,8 @@ interface Entry {
   gated: boolean;
   /** Whether a gate was ever supplied. `gated` clears on settle, so it cannot answer this. */
   hadGate: boolean;
+  /** May download while `gated`. */
+  prefetchWhileGated: boolean;
   /**
    * This element has been in the document at least once.
    *
@@ -513,9 +541,8 @@ function pauseNow(entry: Entry): void {
 /**
  * Everything `startWhen` is still waiting for, for this video.
  *
- * One function rather than the condition written out at each site: it was
- * duplicated in reconcile() and prefetch(), and the prefetch copy was added a
- * commit later than the other, having originally been forgotten.
+ * One function rather than the condition written out at each site, because reconcile() and
+ * prefetch() have to apply the same gate and two copies of it drift.
  */
 function waitingToStart(entry: Entry): boolean {
   const startWhen = entry.startWhen ?? config.startWhen;
@@ -543,12 +570,12 @@ function pauseAfterGrace(entry: Entry): void {
  * Events, so a host can react without observing attributes or forking. Bubbling
  * because the useful listener is usually on a container, not on each video.
  */
-function emit(entry: Entry, type: 'ready' | 'failed'): void {
+function emit(
+  entry: Entry,
+  type: typeof POLITE_VIDEO_READY | typeof POLITE_VIDEO_FAILED | typeof POLITE_VIDEO_BLOCKED
+): void {
   entry.video.dispatchEvent(
-    new CustomEvent<PoliteVideoEventDetail>(
-      type === 'ready' ? POLITE_VIDEO_READY : POLITE_VIDEO_FAILED,
-      { bubbles: true, detail: { video: entry.video } }
-    )
+    new CustomEvent<PoliteVideoEventDetail>(type, { bubbles: true, detail: { video: entry.video } })
   );
 }
 
@@ -559,7 +586,7 @@ function emit(entry: Entry, type: 'ready' | 'failed'): void {
  */
 function markReady(entry: Entry): void {
   entry.host.setAttribute('data-polite-ready', '');
-  emit(entry, 'ready');
+  emit(entry, POLITE_VIDEO_READY);
 }
 
 function clearReady(entry: Entry): void {
@@ -569,10 +596,32 @@ function clearReady(entry: Entry): void {
 }
 
 function armReveal(entry: Entry): void {
+  // Still revealed from before it scrolled away, so the frame is on screen and re-arming would
+  // only announce `ready` a second time. Only a retraction, which removes the attribute, re-arms.
+  if (entry.host.hasAttribute('data-polite-ready')) return;
   entry.cancelReveal?.();
   entry.cancelReveal = revealWhenPainted(entry.video, () => markReady(entry));
 }
 
+/**
+ * One shot per page for each report that would otherwise repeat on every video, in one record so
+ * a teardown cannot reset three of four. `pauseControl` is spent when its check is scheduled, the
+ * rest when the warning fires.
+ */
+const warned = {
+  unreachableStart: false,
+  nothingToReveal: false,
+  droppedOptions: false,
+  pauseControl: false,
+  notDecorative: false,
+  invalidFade: false,
+};
+
+function resetWarnings(): void {
+  for (const key of Object.keys(warned) as (keyof typeof warned)[]) warned[key] = false;
+  resetSourceWarnings();
+}
+
 /**
  * A video taller than the viewport can never be fully intersecting, because
  * `intersectionRatio` is a fraction of the *element*. So a `pauseBelow` it cannot
@@ -585,7 +634,7 @@ function armReveal(entry: Entry): void {
  * first report instead of waiting for a scroll that can never help.
  */
 function warnIfStartUnreachable(entry: Entry): void {
-  if (warnedUnreachable) return;
+  if (warned.unreachableStart) return;
 
   const { pauseBelow } = config;
   if (pauseBelow === 0) return;
@@ -598,7 +647,7 @@ function warnIfStartUnreachable(entry: Entry): void {
   const ceiling = Math.min(1, window.innerHeight / height);
   if (ceiling > pauseBelow) return;
 
-  warnedUnreachable = true;
+  warned.unreachableStart = true;
   console.warn(
     'polite-media: this video is too tall to ever be visible enough to play. ' +
       `pauseBelow is ${pauseBelow}, but its highest possible visible fraction is ` +
@@ -608,10 +657,6 @@ function warnIfStartUnreachable(entry: Entry): void {
   );
 }
 
-let warnedUnreachable = false;
-
-let pauseControlChecked = false;
-
 /**
  * The package's headline claim is that it never autoplays without a way to stop
  * it, and that is the one part it cannot deliver alone: the hook ships, the
@@ -624,8 +669,8 @@ let pauseControlChecked = false;
  * clip that ends on its own is outside the criterion.
  */
 function warnIfNoPauseControl(video: HTMLVideoElement): void {
-  if (pauseControlChecked || !video.loop) return;
-  pauseControlChecked = true;
+  if (warned.pauseControl || !video.loop) return;
+  warned.pauseControl = true;
 
   setTimeout(() => {
     // Nothing is moving any more, so there is nothing to demand a control for.
@@ -639,16 +684,13 @@ function warnIfNoPauseControl(video: HTMLVideoElement): void {
   }, 5000);
 }
 
-let warnedNothingToReveal = false;
-
 /**
  * The one misconfiguration that is otherwise undetectable.
  *
- * `host` is derived as the video's parent, while video.css keys off
- * `data-polite-media` authored on that same element. Nothing forces the two to
- * agree, so putting the attribute one level too high leaves every rule
- * unmatched: the video is visible from the start, the poster never hides, and
- * the library looks installed while doing nothing at all.
+ * video.css hides a video only inside an authored `[data-polite-media]` box. With
+ * none above the video, `host` falls back to its parent, every rule misses, the
+ * video is visible from the start, the poster never hides, and the library looks
+ * installed while doing nothing at all.
  *
  * Checked here rather than at registration because stylesheets have certainly
  * applied by the time a video starts. The visual test is what separates a genuine
@@ -659,31 +701,69 @@ let warnedNothingToReveal = false;
  * saves: it teaches people to ignore the one that matters.
  */
 function warnIfNothingToReveal(entry: Entry): void {
-  if (warnedNothingToReveal) return;
+  if (warned.nothingToReveal) return;
   if (entry.host.hasAttribute('data-polite-media')) return;
 
   const style = getComputedStyle(entry.video);
   if (style.opacity !== '1' || style.visibility !== 'visible') return;
 
-  warnedNothingToReveal = true;
+  warned.nothingToReveal = true;
   console.warn(
-    "polite-media: no data-polite-media on this video's parent, so revealing it does " +
-      'nothing. Put the attribute there, or hide the video with your own CSS.',
+    'polite-media: no data-polite-media on any box around this video, so revealing it does ' +
+      'nothing. Put the attribute on the box holding poster and video, or hide the video with ' +
+      'your own CSS.',
     entry.video
   );
 }
 
+/**
+ * The markup contract makes a managed video decorative, and missing that is otherwise silent:
+ * measured in Firefox, twelve background videos sat in the tab order ahead of the pause button.
+ *
+ * The attribute rather than `tabIndex`, which reads 0 in Chromium and Firefox but -1 in WebKit when
+ * none is authored, so it would judge the same markup per engine. Any `aria-hidden` ancestor counts,
+ * since it removes the video from the tree as surely as its own.
+ */
+function warnIfNotDecorative(video: HTMLVideoElement): void {
+  if (warned.notDecorative) return;
+  if (video.getAttribute('tabindex') === '-1' && video.closest('[aria-hidden="true"]')) return;
+
+  warned.notDecorative = true;
+  console.warn(
+    'polite-media: this video is in the tab order or exposed to screen readers. A background ' +
+      'video is decorative: give it tabindex="-1" aria-hidden="true", and put any meaning in the ' +
+      "poster's alt.",
+    video
+  );
+}
+
 /**
  * Nothing decodable is left. The poster stays and the host is told, rather than
  * leaving a permanently black box and no way to know about it.
  */
 function markFailed(entry: Entry): void {
   clearReady(entry);
+  clearBlocked(entry);
   entry.host.setAttribute('data-polite-failed', '');
-  emit(entry, 'failed');
+  emit(entry, POLITE_VIDEO_FAILED);
   unregister(entry.video);
 }
 
+/**
+ * The browser refused to start playback until a gesture, which MDN reports as `NotAllowedError`.
+ * The retry rungs handle recovery; this tells the host, the only party that can offer a play
+ * affordance. The other rejection, nothing buffered yet, is transient and not announced.
+ */
+function markBlocked(entry: Entry): void {
+  if (entry.host.hasAttribute('data-polite-blocked')) return;
+  entry.host.setAttribute('data-polite-blocked', '');
+  emit(entry, POLITE_VIDEO_BLOCKED);
+}
+
+function clearBlocked(entry: Entry): void {
+  entry.host.removeAttribute('data-polite-blocked');
+}
+
 /**
  * Waits for the next user gesture, then re-runs the arbiter.
  *
@@ -734,20 +814,24 @@ function tryPlay(entry: Entry): void {
   // muted is the only condition it can rely on. Set rather than trusted, which
   // also covers markup whose property was changed after parse.
   entry.video.muted = true;
-  void entry.video.play().catch(() => {
-    armGestureRetry();
-
-    if (entry.retryArmed) return;
-    entry.retryArmed = true;
-    entry.video.addEventListener(
-      'canplay',
-      () => {
-        entry.retryArmed = false;
-        reconcile();
-      },
-      { once: true, signal: entry.listeners.signal }
-    );
-  });
+  void entry.video.play().then(
+    () => clearBlocked(entry),
+    (error: unknown) => {
+      if ((error as DOMException | null)?.name === 'NotAllowedError') markBlocked(entry);
+      armGestureRetry();
+
+      if (entry.retryArmed) return;
+      entry.retryArmed = true;
+      entry.video.addEventListener(
+        'canplay',
+        () => {
+          entry.retryArmed = false;
+          reconcile();
+        },
+        { once: true, signal: entry.listeners.signal }
+      );
+    }
+  );
 }
 
 function onMediaError(entry: Entry): void {
@@ -759,6 +843,8 @@ function onMediaError(entry: Entry): void {
     markFailed(entry);
     return;
   }
+  // Prefetched before anything asked it to play, so start() will reveal and play it.
+  if (!entry.started) return;
   armReveal(entry);
   tryPlay(entry);
 }
@@ -799,7 +885,9 @@ function prepare(entry: Entry): boolean {
  * fetching on the promotion alone.
  */
 function prefetch(entry: Entry): void {
-  if (entry.gated || !videoAllowed()) return;
+  // A user pause holds the bytes too. The prefetch observer calls in here directly rather than
+  // through reconcile(), which stops at a pause; resuming reconciles, and that retries.
+  if ((entry.gated && !entry.prefetchWhileGated) || userPaused || !videoAllowed()) return;
   // The same page gate reconcile applies. Without it a prefetchMargin defeats
   // startWhen entirely, because the fetch this triggers lands inside page load,
   // which is the contention `'page-loaded'` exists to avoid. Measured on
@@ -813,6 +901,7 @@ function start(entry: Entry): void {
   entry.started = true;
 
   warnIfNothingToReveal(entry);
+  warned.invalidFade ||= warnIfFadeInvalid(entry.host);
   warnIfNoPauseControl(entry.video);
   if (!prepare(entry)) return;
 
@@ -865,6 +954,7 @@ function pickWinners(candidates: Entry[]): Set<Entry> {
 
 export function reconcile(): void {
   const pass = ++generation;
+  reflectActive();
 
   // A client-side router swaps the whole body and does not re-run module
   // scripts, so nothing calls unregister for the elements it discarded. Left
@@ -944,10 +1034,15 @@ export function reconcile(): void {
   }
 
   // Retried here because the prefetch observer reports a target once, and a
-  // refusal may since have been lifted: page load, or the first interaction.
+  // refusal may since have been lifted: page load, or the first interaction. A
+  // gated video that may download is fetched from here once on screen, since at
+  // the default prefetchMargin no prefetch observer exists to report it.
   // Last, so it can never influence the decisions this pass just made.
   for (const entry of [...entries.values()]) {
-    if (entry.nearby && !entry.prepared) prefetch(entry);
+    if (entries.get(entry.video) !== entry || entry.prepared) continue;
+    if (entry.nearby || (entry.gated && entry.prefetchWhileGated && entry.ratio > 0)) {
+      prefetch(entry);
+    }
   }
 }
 
@@ -1023,12 +1118,10 @@ function onPauseControlClick(event: Event): void {
  * One controller for every page-level listener, rather than six hand-mirrored
  * add/remove pairs.
  *
- * This is not only tidier, it removes a leak. `detachLifecycle` used to call
- * `mediaQuery(config.smallViewport)` a second time, and `mediaQuery` memoises by
- * query string -- so a `configure({ smallViewport })` between register and
- * unregister meant detaching from a *different* MediaQueryList and stranding the
- * listener on the original. Aborting cannot re-resolve the config, so the whole
- * failure mode stops existing rather than being remembered about.
+ * Aborting is what makes it safe rather than merely tidy: it cannot re-resolve the config.
+ * `mediaQuery` memoises by query string, so a hand-written detach after a
+ * `configure({ smallViewport })` would resolve a different MediaQueryList and strand the listener
+ * on the original.
  */
 function attachLifecycle(): void {
   if (lifecycle) return;
@@ -1067,19 +1160,22 @@ function detachLifecycle(): void {
 }
 
 /**
- * Keeps `aria-pressed` current on any pause control that already declares it.
+ * Puts `<html>` and every declared pause control in step with `userPaused`.
  *
- * Maintained rather than added, because MDN describes two valid patterns and
- * setting it unconditionally would break one of them: `aria-pressed` is for a
- * control whose label stays constant, while a control that swaps its label
- * between "Pause" and "Play" should not carry it at all -- a screen reader would
- * announce "Play, pressed". Declaring the attribute in markup is the author
+ * `aria-pressed` is maintained rather than added, because MDN describes two valid
+ * patterns and setting it unconditionally would break one of them: `aria-pressed`
+ * is for a control whose label stays constant, while a control that swaps its
+ * label between "Pause" and "Play" should not carry it at all -- a screen reader
+ * would announce "Play, pressed". Declaring the attribute in markup is the author
  * saying which pattern they are in.
  *
  * Restricted to a button role because that is the only role `aria-pressed` is
  * valid on, so this cannot emit ARIA that a validator would reject.
  */
 function reflectPaused(): void {
+  if (userPaused) document.documentElement.setAttribute('data-polite-paused', '');
+  else document.documentElement.removeAttribute('data-polite-paused');
+
   for (const control of document.querySelectorAll('[data-polite-pause-control][aria-pressed]')) {
     if (control.matches('button, [role="button"]')) {
       control.setAttribute('aria-pressed', String(userPaused));
@@ -1138,24 +1234,9 @@ function writeStoredPause(paused: boolean): void {
 function restorePaused(): void {
   if (userPaused || !readStoredPause()) return;
   userPaused = true;
-  document.documentElement.setAttribute('data-polite-paused', '');
   reflectPaused();
 }
 
-/**
- * Starts managing a video: reveals it on its first genuinely painted frame,
- * plays it only while it is visible, falls through its `<source>` list when one
- * cannot be decoded, and stops it when a gate closes.
- *
- * The video and its poster must already share a box carrying `data-polite-media`
- * in the authored markup, and the video should be `muted loop playsinline
- * preload="none"`. Calling this twice on the same element is a no-op.
- *
- * @param video the element to manage
- * @param options see {@link RegisterOptions}
- */
-let warnedDroppedOptions = false;
-
 /**
  * A second `register()` for a live video keeps the first registration, so whatever the second call
  * asked for is discarded. Silence is right where the values match, which is how a client-side
@@ -1171,15 +1252,17 @@ function warnIfOptionsDropped(
   video: HTMLVideoElement,
   options: RegisterOptions
 ): void {
-  if (warnedDroppedOptions) return;
+  if (warned.droppedOptions) return;
 
   const differs =
     (options.until !== undefined && !entry.hadGate) ||
     (options.startWhen !== undefined && options.startWhen !== entry.startWhen) ||
-    (options.observe !== undefined && options.observe !== entry.target);
+    (options.observe !== undefined && options.observe !== entry.target) ||
+    (options.prefetchWhileGated !== undefined &&
+      options.prefetchWhileGated !== entry.prefetchWhileGated);
   if (!differs) return;
 
-  warnedDroppedOptions = true;
+  warned.droppedOptions = true;
   console.warn(
     'polite-media: this video is already registered, so the options passed to this second ' +
       'register() call were discarded and the first registration still stands. Register it once ' +
@@ -1188,6 +1271,18 @@ function warnIfOptionsDropped(
   );
 }
 
+/**
+ * Starts managing a video: reveals it on its first genuinely painted frame,
+ * plays it only while it is visible, falls through its `<source>` list when one
+ * cannot be decoded, and stops it when a gate closes.
+ *
+ * The video and its poster must already share a box carrying `data-polite-media`
+ * in the authored markup, and the video should be `muted loop playsinline
+ * preload="none"`. Calling this twice on the same element is a no-op.
+ *
+ * @param video the element to manage
+ * @param options see {@link RegisterOptions}
+ */
 export function register(video: HTMLVideoElement, options: RegisterOptions = {}): void {
   const registered = entries.get(video);
   if (registered) {
@@ -1208,13 +1303,16 @@ export function register(video: HTMLVideoElement, options: RegisterOptions = {})
     );
     return;
   }
+  warnIfNotDecorative(video);
+
   const entry: Entry = {
     video,
     target,
-    host: video.parentElement ?? video,
+    host: video.closest('[data-polite-media]') ?? video.parentElement ?? video,
     ratio: 0,
     gated: Boolean(options.until),
     hadGate: Boolean(options.until),
+    prefetchWhileGated: Boolean(options.prefetchWhileGated),
     startWhen: options.startWhen,
     seenConnected: video.isConnected,
     prepared: false,
@@ -1227,6 +1325,9 @@ export function register(video: HTMLVideoElement, options: RegisterOptions = {})
   byTarget.set(target, entry);
   reflectActive();
   attachLifecycle();
+  // A client-side router replaces <html>'s attributes and the control with the next page's while
+  // this module, and a pause made before the swap, survive. So it is re-asserted per registration.
+  if (userPaused) reflectPaused();
   getObserver().observe(target);
   getPrefetchObserver()?.observe(target);
 
@@ -1253,7 +1354,9 @@ export type VideoTarget = Target<HTMLVideoElement>;
 
 /**
  * Registers every video a target names, so the common case is one line and
- * matches `revealImages` on the image side rather than being a second idea.
+ * matches `revealImages` on the image side rather than being a second idea. With
+ * no target it takes every video inside a `[data-polite-media]` box, which is
+ * what every known caller passed by hand.
  *
  * `observe` is deliberately not accepted. Each observed element maps to exactly
  * one entry, so handing the same wrapper to several videos would silently
@@ -1264,7 +1367,7 @@ export type VideoTarget = Target<HTMLVideoElement>;
  * client-side router, where module scripts do not re-run.
  */
 export function registerAll(
-  target: VideoTarget,
+  target: VideoTarget = '[data-polite-media] video',
   options: Omit<RegisterOptions, 'observe'> = {}
 ): void {
   for (const video of resolveTargets(target)) register(video, options);
@@ -1302,48 +1405,28 @@ export function unregister(video: HTMLVideoElement): void {
 }
 
 /**
- * Stops every managed video and keeps them stopped.
- *
- * WCAG 2.2.2 applies to content that moves automatically, runs for more than
- * five seconds, and sits alongside other content -- which a looping background
- * video does. Honouring `prefers-reduced-motion` is necessary but, per the W3C
- * understanding document, is not listed as satisfying the criterion, so a
- * mechanism the user can actually operate has to exist.
+ * Marks the document while a managed video may play, so a pause control can hide when there is
+ * nothing to stop: nothing registered, reduced motion, Save-Data or 2g, or `atOnce: 0`. CSS can see
+ * only the motion preference. Both known consumers had invented the same attribute, which is what
+ * makes this the library's job. A user pause keeps it, since the control is then what resumes.
  *
- * The host supplies the button and its styling; the library ships no markup and
- * no CSS for it. A `<button>` carrying `data-polite-pause-control` toggles this.
- *
- * It has to be a real `<button>`. The binding is a delegated `click`, and a
- * browser only synthesises that from Enter and Space for a native button, so a
- * `div[role="button"][tabindex="0"]` responds to a mouse and not to a keyboard.
+ * Driven from where `entries` changes and from every reconcile, which is where the gates are read.
  */
+function reflectActive(): void {
+  const active = entries.size > 0 && videoAllowed() && slots() !== 0;
+  document.documentElement.toggleAttribute('data-polite-active', active);
+}
+
 /**
  * The only place `userPaused` changes, so the attribute, `aria-pressed` and the
  * event cannot drift apart. Returns early when nothing actually changed: calling
  * `pauseAll()` twice is idempotent, and announcing a transition that did not
  * happen would make a host's own state wrong.
  */
-/**
- * Marks the document while at least one video is managed.
- *
- * A pause control is markup on every page, but it must not offer to stop something that was never
- * registered, and a host cannot answer that in CSS on its own. Both known consumers had invented
- * the same attribute in their own namespace to do it, which is what makes this the library's job.
- *
- * Driven from the only two places `entries` changes, so it cannot drift from what is tracked.
- */
-function reflectActive(): void {
-  if (entries.size > 0) document.documentElement.setAttribute('data-polite-active', '');
-  else document.documentElement.removeAttribute('data-polite-active');
-}
-
 function setPaused(paused: boolean): void {
   if (userPaused === paused) return;
   userPaused = paused;
 
-  if (paused) document.documentElement.setAttribute('data-polite-paused', '');
-  else document.documentElement.removeAttribute('data-polite-paused');
-
   reflectPaused();
   reconcile();
 
@@ -1367,6 +1450,23 @@ function setPaused(paused: boolean): void {
  *   across a client-side router's unregister/register cycle as well as a real
  *   navigation.
  */
+
+/**
+ * Stops every managed video and keeps them stopped.
+ *
+ * WCAG 2.2.2 applies to content that moves automatically, runs for more than
+ * five seconds, and sits alongside other content -- which a looping background
+ * video does. Honouring `prefers-reduced-motion` is necessary but, per the W3C
+ * understanding document, is not listed as satisfying the criterion, so a
+ * mechanism the user can actually operate has to exist.
+ *
+ * The host supplies the button and its styling; the library ships no markup and
+ * no CSS for it. A `<button>` carrying `data-polite-pause-control` toggles this.
+ *
+ * It has to be a real `<button>`. The binding is a delegated `click`, and a
+ * browser only synthesises that from Enter and Space for a native button, so a
+ * `div[role="button"][tabindex="0"]` responds to a mouse and not to a keyboard.
+ */
 export function pauseAll(): void {
   writeStoredPause(true);
   setPaused(true);
@@ -1388,11 +1488,7 @@ export function resumeAll(): void {
 export function unregisterAll(): void {
   for (const video of [...entries.keys()]) unregister(video);
   setPaused(false);
-  warnedNothingToReveal = false;
-  warnedUnreachable = false;
-  warnedDroppedOptions = false;
-  pauseControlChecked = false;
-  resetSourceWarnings();
+  resetWarnings();
 }
 
 /** Internal reset for tests. Not exported from the package entry point. */