polite-media 0.4.3 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,129 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org); while
 this is `0.x`, a minor bump may still break things and will say so here.
 
+## 0.6.0 (2026-10-07)
+
+### Breaking
+
+- **`data-polite-active` is on `<html>` only while a registered video may play.** It used to stay
+  for as long as any video was registered, so under reduced motion, on Save-Data or a 2g connection,
+  or with `atOnce` at `0`, the README's recipe showed a pause control with nothing to stop. It now
+  follows those gates on every reconcile, and a user pause keeps it, since the control is then what
+  resumes. CSS that used the attribute to mean "a video is registered" needs another hook.
+
+- **A revealed poster is hidden with `opacity`, so its `alt` stays in the accessibility tree.**
+  `video.css` hid it with `visibility: hidden`, which removes it from the tree, while the README
+  tells you to put the meaning in the poster's `alt` and hide the video. It now sets
+  `opacity: 0 !important` and `pointer-events: none` on the poster image, inside a `<picture>` too,
+  after the same `--polite-fade` delay. `!important` because image.css's failsafe animation would
+  otherwise keep a marked poster that nothing manages opaque. A rule of yours that changes the
+  poster's opacity after the reveal now needs `!important` as well, and a test that waited for the
+  poster with Playwright's `toBeHidden()` must wait for computed opacity `0`, since Playwright
+  counts an element at opacity 0 as visible.
+
+- **`smallViewport` defaults to `'(max-width: 767.98px)'`**, from `'(max-width: 767px)'`. Beside a
+  `(min-width: 768px)` the old default left every width between 767px and 768px, which page zoom
+  produces, matching neither, so arbitration treated those viewports as large. The gap is now
+  0.02px. Range syntax would close it fully, but Safari before 16.4 never matches it. Pass
+  `smallViewport` yourself to keep the old value.
+
+### Added
+
+- **A warning when a registered video is not decorative.** The markup contract asks for
+  `tabindex="-1" aria-hidden="true"` on the video, and nothing checked it. `register()` now warns
+  once per page, naming the video, when its `tabindex` attribute is not `-1` or no
+  `aria-hidden="true"` sits on the video or a box around it.
+
+- **A warning when `--polite-fade` is not a CSS time.** A value such as `0.6` computes to `0s`
+  rather than to the stylesheet's default, so it silently removed the image fade. The first video
+  box and the first fading image that see such a value are named once per page. The browser parses
+  the value, so `calc(0.3s * 2)` passes, and a bare `0` stays quiet because it gives the cut it
+  looks like.
+
+- **`register(video, { until, prefetchWhileGated: true })`** lets a gated video download while it
+  waits, so a splash buys it load time. A gate used to hold the fetch as well as playback, and that
+  stays the default, since a page may rely on a consent dialog holding the bytes too. The download
+  still waits for `startWhen`, reduced motion, Save-Data and a user pause, and starts once the video
+  is on screen or within `prefetchMargin`. A host can end its splash on the video's own
+  `canplaythrough`, which fires while the gate still holds; the README shows the recipe.
+
+### Fixed
+
+- **`warm()` with `sources` fetched the candidate for the full viewport width.** A `<source>`
+  without its own `sizes` is selected as if it said `100vw`, and `sizes` went on the `<img>` alone,
+  so a desktop warm could fetch a file several times the size the destination then picked. Every
+  `<source>` now carries the `sizes` it was passed.
+
+- **A video buffered ahead through `prefetchMargin` started playing off screen when its first source
+  could not be decoded.** The source fallback revealed and played whatever came next, whether or not
+  anything had asked the video to play. It now moves to the next source and waits.
+
+- **A lazy image still faded in under reduced motion.** `image.css`'s reduced-motion rule lost on
+  specificity to the rule that sets the fade, so the README's promise that reduced motion overrides
+  `--polite-fade` held only for eager images that opted in. Lazy images now arrive at once there.
+
+- **A paused page still buffered videos within `prefetchMargin`.** The prefetch observer fetched
+  without asking whether the visitor had paused. It now waits, and resuming starts the fetch.
+
+### Documentation
+
+- **`register()` and `pauseAll()` carry their documentation in the published types.** Their doc
+  comments sat above other functions, so an editor hovering either showed nothing.
+
+- **An `until` gate does not protect LCP**, and the README no longer says it does. The video's
+  first frame is an LCP candidate whenever it paints; only `startWhen: 'interaction'` keeps it out.
+  The poster-`load` gate example is gone for the same reason.
+- **A gate that never settles holds its video for good.** The README shows racing it against a
+  timeout of your own.
+- **The wrapper recipe in "Composing your own animation" gates only on images that will load.**
+  Lazy images in a horizontal scroller may never be fetched, so a wrapper waiting on all of them
+  waits for its failsafe.
+
+## 0.5.0 (2026-09-12)
+
+### Breaking
+
+- **`data-polite-media` no longer has to be the video's direct parent.** The library writes its
+  state to the nearest `[data-polite-media]` ancestor, and `video.css` and `layer.css` match the
+  video as a descendant of the box rather than a child. The poster rules are unchanged: a poster is
+  still a direct child, so a logo deeper in the box is still left alone. One box holds one video, and
+  boxes must not nest, because the box's ready state reveals every video inside it. If your CSS
+  extended `[data-polite-media] > video`, drop the `>`.
+
+- **`image.css` hides only lazy images.** An eager image may be the LCP element, and a deferred
+  module cannot reveal it before first paint, so the stylesheet now leaves `loading="eager"` (and
+  images with no `loading`) alone. To fade one anyway, write `data-polite-reveal="eager"` on it.
+  `revealImages()`'s `allowEager` option is ignored and warns, because the opt-in has to be where
+  the stylesheet can see it.
+
+### Added
+
+- **`registerAll()` and `revealImages()` take no argument** and default to
+  `'[data-polite-media] video'` and `'img[data-polite-reveal]'`, which is what both known consumers
+  had written out.
+
+- **`polite-video:blocked`, and `data-polite-blocked` on the box**, while the browser refuses
+  `play()` until a gesture. The retry was already there; what was missing was any way for a host to
+  know it was waiting, so a play affordance could not be shown. Fires once per refusal, not on every
+  retried attempt, and the attribute is removed once playback starts.
+
+### Fixed
+
+- **A pause was lost from `<html>` on a client-side navigation.** A router such as Astro's
+  `<ClientRouter />` replaces the root element's attributes with the next document's, and the pause
+  state was only written on the first registration of a page load. The videos stayed paused, but
+  `data-polite-paused` and a declared `aria-pressed` said otherwise. Both are now re-asserted on
+  every `register()`.
+
+- **`polite-video:ready` fired again each time a video scrolled back into view.** The frame was
+  still on screen, so nothing had been revealed. It now fires once per reveal; a retraction (reduced
+  motion, Save-Data, a source fallback) still announces the re-reveal.
+
+### Documentation
+
+- The README now lists all four places the library changes an element you authored: `preload`
+  (twice), `muted`, and `src` plus `load()` when a `<source>` list is resolved.
+
 ## 0.4.3 (2026-09-06)
 
 ### Fixed

package/README.md

@@ -11,7 +11,7 @@ npm install polite-media
 ```
 
 ```html
-<!-- data-polite-media goes on the video's direct parent -->
+<!-- data-polite-media goes on the box that holds poster and video -->
 <div class="your-own-box" data-polite-media>
   <img src="poster.avif" alt="" />
   <!-- decorative: the video is not in the tab order, the poster's alt carries any meaning -->
@@ -122,7 +122,7 @@ one before it arrives.
 import { revealImages } from 'polite-media/image';
 import 'polite-media/image.css';
 
-revealImages('.card img');
+revealImages(); // every img[data-polite-reveal] on the page
 ```
 
 ### Warming the next page's hero
@@ -143,7 +143,7 @@ warmOnIntent('a[data-hero]', (link) => ({
 
 ## The attributes
 
-Eight in total. The distinction that catches people is the middle column: two of
+Nine in total. The distinction that catches people is the middle column: two of
 the ones you write are live on their own, and one is inert until you call
 something.
 
@@ -154,19 +154,24 @@ something.
 | `data-polite-pause-control` | your `<button>`             | **yes**, no call anywhere on the page                     |
 | `data-polite-ready`         | the box, or the image       | written by the library                                    |
 | `data-polite-failed`        | the box                     | written by the library                                    |
+| `data-polite-blocked`       | the box                     | written by the library                                    |
 | `data-polite-paused`        | `<html>`                    | written by the library                                    |
 | `data-polite-active`        | `<html>`                    | written by the library                                    |
 | `data-polite-managed`       | the `<img>`                 | written by the library                                    |
 
 `data-polite-reveal` is the one to be careful with. `image.css` hides a marked
-image immediately, so marking one you never pass to `revealImages()` leaves it
-hidden until the failsafe shows it, five seconds later and without a fade. The
+lazy image immediately, so marking one you never pass to `revealImages()` leaves
+it hidden until the failsafe shows it, five seconds later and without a fade. The
 console names any image in that state, so widen the selector or drop the
-attribute.
+attribute. An eager image is never hidden; give the attribute the value `eager`
+to opt one into the fade anyway.
 
-`data-polite-active` is on `<html>` for as long as at least one video is
-registered. A pause control is markup on every page, but it must not offer to
-stop something that was never registered, and nothing else lets CSS answer that:
+`data-polite-active` is on `<html>` while a registered video may play. It is
+absent when nothing is registered, under reduced motion, on Save-Data or a 2g
+connection, and where `atOnce` is `0` for the viewport; a user pause keeps it,
+since the control is then what resumes. A pause control is markup on every page,
+but it must not offer to stop something that cannot move, and CSS alone cannot
+see most of those reasons:
 
 ```css
 [data-polite-pause-control] {
@@ -177,9 +182,14 @@ stop something that was never registered, and nothing else lets CSS answer that:
 }
 ```
 
-The bottom five are yours to style against and never to write yourself. They are
+The bottom six are yours to style against and never to write yourself. They are
 the public CSS API, along with `--polite-fade` and `--polite-failsafe`.
 
+`data-polite-blocked` is on the box while the browser refuses `play()` until a
+gesture, which MDN reports as `NotAllowedError`. The library keeps retrying on its
+own; the attribute is there so your CSS can show a play affordance in the
+meantime, and it is removed once playback starts.
+
 ### Composing your own animation with the reveal
 
 Gating an animation of your own on `data-polite-ready` works, and needs one thing
@@ -200,6 +210,14 @@ bundle that never arrives leaves your wrapper hidden for good even though the
 library's own failsafe fired. Give any rule of yours that hides on
 `:not([data-polite-ready])` its own failsafe on the same delay.
 
+**Gate a wrapper only on images that will load.** The `:has()` above waits on
+every marked image inside the card, and lazy loading may never fetch some of
+them. Measured in Chromium, in a 412px-wide horizontal scroller of nine lazy
+images, only the first three loaded, and three in the middle never did, even
+after scrolling past them. A card holding that scroller waits for your failsafe
+and then appears unfaded. Gate it on the images in view when it appears, such as
+the first, or leave scrollers out of the rule.
+
 One limit worth knowing: a skipped `content-visibility: auto` subtree runs no
 animations, so neither failsafe fires there until the section is scrolled into
 view. It resolves itself the moment anyone looks at it, which is the only moment
@@ -213,21 +231,20 @@ it could have mattered.
    arrived once JS ran, a page whose bundle failed would stack that over the
    poster. Authored, the safe state is the default.
 
-   That box must be the video's **direct parent**. This is the one rule with a
-   silent failure mode: the library writes `data-polite-ready` to
-   `video.parentElement`, while the stylesheet matches
-   `[data-polite-media][data-polite-ready] > video`. Put the attribute a level
-   too high and the two never meet, every rule misses, and the video is visible
-   from the start with no error anywhere. The library warns on the console when
-   it can detect this.
+   The video may sit anywhere inside that box: the library writes its state to
+   the nearest `[data-polite-media]` ancestor, and the stylesheet matches the
+   video as a descendant. One box holds one video, and boxes must not nest,
+   because the box's ready state reveals every video inside it: a second one
+   would appear before it had painted. With no box above the video at all,
+   nothing hides it and the library warns on the console.
 
 3. The poster is ideally the video's **frame 0**, which is what makes the handoff
    invisible, but only together with cutting rather than fading. See
    [The fade](#the-fade).
-4. Poster and video are direct children of the box. The box may hold anything
-   else it likes, a scrim, a caption, a pause control, and those are left alone.
-   But **every** direct-child `img` or `picture` is treated as the poster and
-   hidden on reveal, so a logo or badge belongs deeper, not beside the video.
+4. The poster is a direct child of the box. The box may hold anything else it
+   likes, a scrim, a caption, a pause control, and those are left alone. But
+   **every** direct-child `img` or `picture` is treated as the poster and hidden
+   on reveal, so a logo or badge belongs deeper, not beside the video.
 5. Order several `<source>` elements narrowest first: the first one that claims
    the viewport wins. **You do not need an unconditional fallback.** Two queries
    meant to partition the viewport often do not quite meet, and
@@ -243,21 +260,25 @@ it could have mattered.
 6. The video carries `tabindex="-1" aria-hidden="true"`. It is decorative, and
    without this it lands in the tab order: measured in Firefox, twelve background
    videos sat ahead of the pause button, so a keyboard user reached it on the
-   thirteenth Tab.
+   thirteenth Tab. The console says so once per page when a registered video
+   lacks either; `aria-hidden` on a box around it counts too. Anything the
+   picture means goes in the poster's `alt`: the reveal hides the poster with
+   `opacity`, not `visibility`, so it stays in the accessibility tree while the
+   video plays.
 
 ## API
 
 ```js
 // polite-media/video
-register(video, { until, observe, startWhen }); // manage a video
-registerAll(target, { until, startWhen }); //      manage everything a selector names
+register(video, { until, observe, startWhen, prefetchWhileGated }); // manage a video
+registerAll(target?, { until, startWhen, prefetchWhileGated }); // every [data-polite-media] video by default
 unregister(video); //                              stop managing it, release everything
 unregisterAll(); //                                tear down the whole page
 configure({ ... }); //                             before the first register, or it throws
 pauseAll(); resumeAll(); //                        WCAG 2.2.2 control, emits pausechange
 
 // polite-media/image
-const stop = revealImages(target, { allowEager }); // reveal on decode
+const stop = revealImages(target?); //  reveal on decode; every marked image by default
 stop(); //                                            cancel anything pending
 
 // polite-media/warm
@@ -273,9 +294,15 @@ Types: `ConfigureOptions`, `RegisterOptions`, `RevealImagesOptions`,
 `WarmOptions`, `WarmSource`, `VideoTarget`, `ImageTarget`, `AtOnce`,
 `PoliteVideoEventDetail`, `PoliteImageEventDetail`, `PolitePauseEventDetail`.
 Event names ship as constants
-(`POLITE_VIDEO_READY`, `POLITE_VIDEO_FAILED`, `POLITE_IMAGE_READY`,
-`POLITE_VIDEO_PAUSECHANGE`), because a mistyped event string still compiles
-against lib.dom's `type: string` overload.
+(`POLITE_VIDEO_READY`, `POLITE_VIDEO_FAILED`, `POLITE_VIDEO_BLOCKED`,
+`POLITE_IMAGE_READY`, `POLITE_VIDEO_PAUSECHANGE`), because a mistyped event
+string still compiles against lib.dom's `type: string` overload.
+
+`polite-video:ready` fires once per reveal. A video that scrolls away and back
+keeps its last frame on screen, so it is not announced again; one whose reveal
+was retracted, by reduced motion, Save-Data or a source fallback, is announced
+again when it re-reveals. `polite-video:blocked` fires once when the browser
+refuses `play()` until a gesture, and not again on each refused retry.
 
 `polite-video:pausechange` is the odd one out: a user pause is page-wide rather
 than about one video, so it is dispatched on `document` with
@@ -297,7 +324,13 @@ rather than guessed.
 | option          | default                      | reach for it when                                          |
 | --------------- | ---------------------------- | ---------------------------------------------------------- |
 | `atOnce`        | `{ small: 1, large: 'all' }` | a feed wants one at a time everywhere, or phones want none |
-| `smallViewport` | `'(max-width: 767px)'`       | your breakpoint is not ours                                |
+| `smallViewport` | `'(max-width: 767.98px)'`    | your breakpoint is not ours                                |
+
+The `smallViewport` default meets a `(min-width: 768px)` with a 0.02px gap rather
+than a whole pixel, so a fractional width from page zoom lands on one side. Pair
+your own queries the same way. Range syntax, `(width < 768px)`, would close the
+gap entirely, but Safari before 16.4 never matches it, so phones there would
+count as large and play every visible video at once.
 
 **When may it begin?**
 
@@ -326,35 +359,77 @@ effect on the next pass.
 callers: a `2` would otherwise fall through to the single-slot branch and quietly
 mean `1`.
 
-**A malformed `smallViewport` cannot be detected.** An invalid media query does
-not throw and does not normalise to anything recognisable; Chromium echoes the
-text straight back and never matches. So `smallViewport: '(max-width: 767)'`,
+**A malformed `smallViewport` is not checked for you.** An invalid media query
+does not throw and does not normalise to anything recognisable; Chromium echoes
+the text straight back and never matches. So `smallViewport: '(max-width: 767)'`,
 missing its unit, means arbitration silently never engages and phones behave like
-desktops. Check that value by eye.
+desktops. Check it in the console on both sides of your breakpoint:
+`matchMedia(query).matches` should be `true` below it and `false` above. A
+malformed query is `false` on both.
 
 ### Per-video gates
 
 `register(video, { until: promise })` holds a video back until the promise
-settles: for a splash screen, a consent dialog, or protecting your LCP. A hero at
-scroll-top is reported visible in the observer's very first batch, so without
-this it starts before whatever the page is waiting on has finished.
+settles: for a splash screen or a consent dialog. A hero at scroll-top is
+reported visible in the observer's very first batch, so without this it starts
+before whatever the page is waiting on has finished.
+
+**A gate delays the video; it does not keep it out of Largest Contentful Paint.**
+The first frame is an LCP candidate like any image, whenever it paints: measured
+in Chromium on a real hero gated behind a splash, the video's first frame
+replaced the poster as the LCP element just after the gate opened. Only
+[`startWhen: 'interaction'`](#startwhen) keeps a video out of LCP.
+
+The gate opens when the promise settles, fulfilled or rejected, and not
+otherwise: one that never settles holds the video on its poster for the life of
+the page. If whatever resolves it might never run, race it against a timeout of
+your own:
 
 ```js
-// If the poster is your LCP element, gate the video on it having loaded.
-register(video, {
-  until: new Promise((done) => {
-    const poster = document.querySelector('img.hero-poster');
-    if (!poster || poster.complete) done();
-    else poster.addEventListener('load', () => done(), { once: true });
-  }),
-});
+const timeout = (ms) => new Promise((done) => setTimeout(done, ms));
+
+register(video, { until: Promise.race([splashDone, timeout(15000)]) });
+```
+
+**A splash can buy the video load time.** A gate holds the download as well as
+playback, so a hero behind a five-second splash only starts fetching once the
+splash ends. `prefetchWhileGated: true` lets it download while it waits: only
+playback waits for the gate, while `startWhen`, reduced motion, Save-Data and a
+pause still hold the fetch. The browser fires `canplaythrough` once it can play
+through, which a splash can end on, with a floor and a cap of its own:
+
+```js
+const wait = (ms) => new Promise((done) => setTimeout(done, ms));
+let endSplash;
+const splashDone = new Promise((done) => (endSplash = done));
+
+register(hero, { until: splashDone, prefetchWhileGated: true });
+
+// Nothing downloads where nothing will play (reduced motion, Save-Data,
+// atOnce: 0), or while the visitor has paused.
+const root = document.documentElement;
+const buffered =
+  root.hasAttribute('data-polite-active') && !root.hasAttribute('data-polite-paused')
+    ? new Promise((done) => hero.addEventListener('canplaythrough', done, { once: true }))
+    : Promise.resolve();
+
+// At least 1.5s of splash, at most 4.5s, and in between until the hero can play through.
+await Promise.race([Promise.all([buffered, wait(1500)]), wait(4500)]);
+hideSplash();
+endSplash();
 ```
 
+Keep the cap. Whether iOS Safari buffers under `preload="auto"` before anything
+calls `play()` is untested, and the cap is what ends the splash if the event
+never comes.
+
 `register(video, { observe: box })` observes a wrapper instead of the video, for
 when the video is `inset: 0` inside the element that carries the layout.
 
 `registerAll(target)` takes the same shapes `revealImages` does (a selector, an
-element, or any collection) and registers each. It does not accept `observe`:
+element, or any collection) and registers each; called with nothing it takes
+`'[data-polite-media] video'`, which is what every known caller had written out.
+It does not accept `observe`:
 each observed element maps to exactly one video, and `register` refuses a second
 video on a target it already watches, with a warning.
 
@@ -401,10 +476,14 @@ with `'interaction'`, so "wait for the visitor, and also wait for the buffer"
 could not be expressed at all.
 
 Two consequences. A page whose `load` never fires never starts its videos, and
-`requireBuffered` is one of two places the library changes markup you authored:
-`prefetch()` also promotes `preload` to `'auto'` for any video within a
-configured `prefetchMargin`. `until` composes with all of it, and a video waits
-for every gate that applies to it.
+`requireBuffered` is one of four places the library changes the element you
+authored. `prefetch()` also promotes `preload` to `'auto'` for any video within
+a configured `prefetchMargin`; `muted` is set before every `play()`, since muted
+is the one condition autoplay can rely on; and when a `<source>` list is
+resolved, `src` is assigned the chosen file and `load()` is called, so
+`currentSrc` reflects that choice and the `<source>` children are no longer
+consulted. `until` composes with all of it, and a video waits for every gate
+that applies to it.
 
 ### `pauseBelow`
 
@@ -544,7 +623,9 @@ Two things that surprise people:
   that is invalid at computed-value time falls back to the property's initial
   value, and the `var()` fallback only applies when the property is undefined.
   Harmless on video, which cuts anyway; on images it silently removes the 350ms
-  fade.
+  fade. The console names the first image or video box where it is set to
+  something that is not a time. A bare `0` is left alone, since the cut it gives
+  is what it looks like it asks for.
 
 Reduced motion overrides you either way: the stylesheet sets `transition: none`
 there, so a fade you asked for never runs for someone who asked not to see one.
@@ -567,6 +648,11 @@ warmOnIntent('a[data-hero]', (link) => ({
 }));
 ```
 
+Give a format through `sources` with its `type`, as above, rather than as a bare `srcset`: a
+browser that cannot decode AVIF then skips it and warms the fallback, instead of fetching a file it
+cannot show. `sizes` goes on every `<source>` and on the image, since a `<source>` without its own
+is chosen as if it said `100vw`.
+
 **Nothing in this package parses a media query**, which is the point: the
 candidates are assembled as a detached `<picture>` and the browser picks, running
 the same algorithm it will run on the destination. Hand-rolling that selection
@@ -615,6 +701,24 @@ document.addEventListener('astro:page-load', () => registerAll('[data-polite-med
 registered twice. Videos that did not survive need no cleanup: the coordinator
 drops any entry whose element has left the document on its next pass.
 
+## Astro
+
+This is developed against Astro projects, and the same three things come up.
+
+**Import each stylesheet from the component that emits its attribute.** A build folds every
+component's CSS into one file, so a stylesheet imported anywhere covers everywhere, while a dev
+server serves it per component and does not. Import `image.css` from some other component and the
+fade works in the build and is missing in dev, on exactly the pages that do not render whichever
+component happened to import it. The console says so when the stylesheet never arrives.
+
+**Put the `<script>` in the component that renders the media**, not in the layout. Astro bundles a
+component's script once per page, so a page that never renders that component never downloads the
+coordinator.
+
+**A strict CSP needs nothing from this package.** It writes attributes and never an inline `style`,
+which the end-to-end suite asserts on every demo, so `style-src` needs no `'unsafe-inline'` on its
+account.
+
 ## What it does
 
 - Reveals on a genuinely presented frame, never on `playing`.
@@ -622,9 +726,11 @@ drops any entry whose element has left the document on its next pass.
 - Caps how many videos run at once, on any viewport, not just small ones.
 - Falls through to the next `<source>` when one can't be decoded.
 - Honours `prefers-reduced-motion` live, and Save-Data on the next reconcile.
-- Recovers from bfcache restores, tab refocus and blocked autoplay.
+- Recovers from bfcache restores, tab refocus and blocked autoplay, and says so
+  while it waits.
 - Ships a pause control hook for [WCAG 2.2.2][wcag].
-- Emits `polite-video:ready`, `polite-video:failed` and `polite-video:pausechange`.
+- Emits `polite-video:ready`, `polite-video:failed`, `polite-video:blocked` and
+  `polite-video:pausechange`.
 
 ## What it deliberately doesn't do
 
@@ -641,9 +747,12 @@ candidates you already build, and generates none.
 every image inside it, including ones the library then declines to fade, so each
 one waits out the failsafe instead of fading.
 
-**Eager images are revealed instantly rather than faded.** LCP excludes elements
-at `opacity: 0` and revealing one doesn't restore its candidacy. Pass
-`{ allowEager: true }` to fade anyway.
+**Eager images are never hidden, so they cut rather than fade.** LCP excludes
+elements at `opacity: 0`, and a deferred module cannot reveal one before first
+paint, so `image.css` hides only `loading="lazy"` images and the module marks an
+eager one ready at once. To fade an eager image anyway, write
+`data-polite-reveal="eager"` on it: the choice has to be in the markup, where
+the stylesheet can see it, which is why the old `allowEager` option is gone.
 
 **An image needs a backdrop.** Video degrades to its poster; a lone image
 degrades to nothing, so its container must carry a visible `background-color`.
@@ -717,11 +826,12 @@ Framework-agnostic by construction: no framework dependency, standard DOM only,
 developed against Astro projects.
 
 **Tested on Chromium, Firefox and WebKit**, all three driven by Playwright
-against real media on every change, alongside 222 unit tests. Other engines are
+against real media on every change, alongside 233 unit tests. Other engines are
 unexercised rather than unsupported.
 
 **iOS Safari is outside the matrix**, and Playwright's WebKit does not stand in
-for it. The path that rests on it is the retry after a refused `play()`, which
+for it. The path that rests on it is the retry after a refused `play()`, announced
+as `polite-video:blocked` so it can be seen in the field, which
 rejects with `NotAllowedError`; the library follows MDN's documented remedy of
 surfacing a control and waiting for a gesture.
 

package/dist/coordinator.d.ts

@@ -52,8 +52,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;
     /**
@@ -158,6 +163,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>;
     /**
@@ -173,14 +181,38 @@ 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;
 }
 export declare function reconcile(): void;
+/**
+ * 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 declare function register(video: HTMLVideoElement, options?: RegisterOptions): void;
 /** Anything that names one or more videos. See {@link Target}. */
 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
@@ -190,13 +222,29 @@ export type VideoTarget = Target<HTMLVideoElement>;
  * Idempotent, because `register` is: safe to call on every navigation of a
  * client-side router, where module scripts do not re-run.
  */
-export declare function registerAll(target: VideoTarget, options?: Omit<RegisterOptions, 'observe'>): void;
+export declare function registerAll(target?: VideoTarget, options?: Omit<RegisterOptions, 'observe'>): void;
 /**
  * Stops managing a video and releases everything it owned: the observer entry,
  * any pending pause timer, its listeners, and the page-level listeners once it
  * was the last one. Safe to call for a video that was never registered.
  */
 export declare 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.
+ *
+ * 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 declare function pauseAll(): void;
 /** Lets playback resume, undoing {@link pauseAll}. */
 export declare function resumeAll(): void;

package/dist/coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../src/coordinator.ts"],"names":[],"mappings":"AAUA,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA4ED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAcvD;AAwDD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAuhBD,wBAAgB,SAAS,IAAI,IAAI,CAsFhC;AA+OD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CA0DrF;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAM,GAC7C,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAwBxD;AAoED,wBAAgB,QAAQ,IAAI,IAAI,CAG/B;AAED,sDAAsD;AACtD,wBAAgB,SAAS,IAAI,IAAI,CAGhC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAQpC;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,IAAI,IAAI,CAQpC;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAErF"}
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../src/coordinator.ts"],"names":[],"mappings":"AAYA,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA4ED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAcvD;AA0DD,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AA0lBD,wBAAgB,SAAS,IAAI,IAAI,CA4FhC;AAmOD;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAgErF;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,MAAM,GAAE,WAAyC,EACjD,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAM,GAC7C,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAwBxD;AAiDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,IAAI,IAAI,CAG/B;AAED,sDAAsD;AACtD,wBAAgB,SAAS,IAAI,IAAI,CAGhC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAIpC;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,IAAI,IAAI,CAQpC;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAErF"}