polite-media 0.4.2 → 0.5.0

package/dist/events.d.ts

@@ -24,6 +24,12 @@
 export declare const POLITE_VIDEO_READY = "polite-video:ready";
 /** Dispatched on the video when no source could be decoded. Bubbles. */
 export declare const POLITE_VIDEO_FAILED = "polite-video:failed";
+/**
+ * Dispatched on the video when the browser refused `play()` until a user gesture.
+ * Bubbles. The library keeps retrying on its own; this exists so a host can show
+ * a play affordance in the meantime, which the library cannot do for it.
+ */
+export declare const POLITE_VIDEO_BLOCKED = "polite-video:blocked";
 /** Dispatched on the image once it has decoded. Bubbles. */
 export declare const POLITE_IMAGE_READY = "polite-image:ready";
 /**
@@ -58,11 +64,13 @@ declare global {
     interface ElementEventMap {
         'polite-video:ready': CustomEvent<PoliteVideoEventDetail>;
         'polite-video:failed': CustomEvent<PoliteVideoEventDetail>;
+        'polite-video:blocked': CustomEvent<PoliteVideoEventDetail>;
         'polite-image:ready': CustomEvent<PoliteImageEventDetail>;
     }
     interface DocumentEventMap {
         'polite-video:ready': CustomEvent<PoliteVideoEventDetail>;
         'polite-video:failed': CustomEvent<PoliteVideoEventDetail>;
+        'polite-video:blocked': CustomEvent<PoliteVideoEventDetail>;
         'polite-image:ready': CustomEvent<PoliteImageEventDetail>;
         'polite-video:pausechange': CustomEvent<PolitePauseEventDetail>;
     }

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,eAAe;QACvB,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC1D,qBAAqB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC3D,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;KAC3D;IAED,UAAU,gBAAgB;QACxB,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC1D,qBAAqB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC3D,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC1D,0BAA0B,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;KACjE;CACF"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,eAAe;QACvB,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC1D,qBAAqB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC3D,sBAAsB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC5D,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;KAC3D;IAED,UAAU,gBAAgB;QACxB,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC1D,qBAAqB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC3D,sBAAsB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC5D,oBAAoB,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;QAC1D,0BAA0B,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;KACjE;CACF"}

package/dist/events.js

@@ -24,6 +24,12 @@
 export const POLITE_VIDEO_READY = 'polite-video:ready';
 /** Dispatched on the video when no source could be decoded. Bubbles. */
 export const POLITE_VIDEO_FAILED = 'polite-video:failed';
+/**
+ * Dispatched on the video when the browser refused `play()` until a user gesture.
+ * Bubbles. The library keeps retrying on its own; this exists so a host can show
+ * a play affordance in the meantime, which the library cannot do for it.
+ */
+export const POLITE_VIDEO_BLOCKED = 'polite-video:blocked';
 /** Dispatched on the image once it has decoded. Bubbles. */
 export const POLITE_IMAGE_READY = 'polite-image:ready';
 /**

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD,wEAAwE;AACxE,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD,wEAAwE;AACxE,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC"}

package/dist/image.css

@@ -1 +1 @@
-@media(scripting:enabled){img[data-polite-reveal]{opacity:0;transition:opacity var(--polite-fade, .35s) ease}img[data-polite-reveal]:not([data-polite-ready]){animation:polite-reveal-failsafe 0s var(--polite-failsafe, 5s) forwards}img[data-polite-reveal][data-polite-ready]{opacity:1}@keyframes polite-reveal-failsafe{to{opacity:1}}}@media(prefers-reduced-motion:reduce){img[data-polite-reveal]{transition:none}}
+@media(scripting:enabled){img[data-polite-reveal][loading=lazy],img[data-polite-reveal=eager]{opacity:0;transition:opacity var(--polite-fade, .35s) ease}img[data-polite-reveal][loading=lazy]:not([data-polite-ready]):not([data-polite-managed]),img[data-polite-reveal=eager]:not([data-polite-ready]):not([data-polite-managed]){animation:polite-reveal-failsafe 0s var(--polite-failsafe, 5s) forwards}img[data-polite-reveal][data-polite-ready]{opacity:1}@keyframes polite-reveal-failsafe{to{opacity:1}}}@media(prefers-reduced-motion:reduce){img[data-polite-reveal]{transition:none}}

package/dist/image.d.ts

@@ -20,26 +20,19 @@ import { type Target } from './targets.js';
 export type ImageTarget = Target<HTMLImageElement>;
 export interface RevealImagesOptions {
     /**
-     * Manage images that are not `loading="lazy"`.
-     *
-     * Off by default because LCP excludes elements at `opacity: 0`, and revealing
-     * one does not restore its candidacy -- so fading an eager, above-the-fold
-     * image can forfeit the metric it was meant to improve. A lazy image was never
-     * an LCP candidate, so the default is risk-free.
-     *
-     * Turning this on is legitimate and sometimes right: an eager grid that would
-     * otherwise cut from its backdrop to the photo on whatever frame the async
-     * decode lands looks worse without a fade. It just has to be a decision rather
-     * than an accident.
+     * @deprecated Ignored since 0.5, and warns. image.css no longer hides an eager
+     * image at all, so the opt-in has to be in the markup where the stylesheet can
+     * see it: `data-polite-reveal="eager"` on the image.
      */
     allowEager?: boolean;
 }
 /**
- * Reveals each matching image once it has decoded.
+ * Reveals each matching image once it has decoded. With no target it takes every
+ * marked image on the page.
  *
  * Returns a function that stops any reveals still pending, for a client-side
  * router tearing the page down before the images resolved.
  */
-export declare function revealImages(target: ImageTarget, options?: RevealImagesOptions): () => void;
+export declare function revealImages(target?: ImageTarget, options?: RevealImagesOptions): () => void;
 export { POLITE_IMAGE_READY, type PoliteImageEventDetail } from './events.js';
 //# sourceMappingURL=image.d.ts.map

package/dist/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA6FD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,IAAI,CA0D/F;AAKD,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAmGD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,GAAE,WAAuC,EAC/C,OAAO,GAAE,mBAAwB,GAChC,MAAM,IAAI,CAiFZ;AAKD,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/image.js

@@ -18,6 +18,8 @@
 import { POLITE_IMAGE_READY } from './events.js';
 import { resolveTargets } from './targets.js';
 const READY = 'data-polite-ready';
+/** Written while this module owns an image's reveal, so image.css can stand down. */
+const MANAGED = 'data-polite-managed';
 function markReady(image) {
     image.setAttribute(READY, '');
     image.dispatchEvent(new CustomEvent(POLITE_IMAGE_READY, {
@@ -26,11 +28,12 @@ function markReady(image) {
     }));
 }
 /**
- * Every image this module has taken responsibility for.
- *
- * A WeakSet rather than an attribute: the stylesheet no longer needs to know
- * which images are managed, so writing it into the DOM would be state kept for
- * nobody. Weak so a released image is not pinned by the bookkeeping.
+ * Every image a `revealImages()` call has ever claimed, for the stray-image
+ * warning. Distinct from `data-polite-managed`, which marks an image only while
+ * this module still owns its reveal so the stylesheet's failsafe stands down: a
+ * teardown removes the attribute but the claim stays, since the warning is about
+ * selectors that never reached an image at all. Weak so a released image is not
+ * pinned by the bookkeeping.
  */
 const managed = new WeakSet();
 let unmanagedCheck;
@@ -59,6 +62,7 @@ function scheduleUnmanagedCheck() {
     }, 1000);
 }
 let warnedNoStylesheet = false;
+let warnedAllowEager = false;
 /**
  * image.css is the only thing that hides a marked image. Without it `data-polite-reveal` is inert:
  * the image is never hidden, so it never fades and everything this module does is invisible.
@@ -82,6 +86,8 @@ function warnIfUnstyled() {
     // removed in this same task so nothing paints it and no scan above ever sees it.
     const probe = document.createElement('img');
     probe.setAttribute('data-polite-reveal', '');
+    // The stylesheet hides only lazy images, so an eager probe would read as unstyled everywhere.
+    probe.setAttribute('loading', 'lazy');
     document.body.appendChild(probe);
     const opacity = getComputedStyle(probe).opacity;
     probe.remove();
@@ -95,31 +101,43 @@ function warnIfUnstyled() {
         "images will not fade. Import 'polite-media/image.css' from wherever the attribute is emitted.");
 }
 /**
- * Reveals each matching image once it has decoded.
+ * Reveals each matching image once it has decoded. With no target it takes every
+ * marked image on the page.
  *
  * Returns a function that stops any reveals still pending, for a client-side
  * router tearing the page down before the images resolved.
  */
-export function revealImages(target, options = {}) {
+export function revealImages(target = 'img[data-polite-reveal]', options = {}) {
     const controller = new AbortController();
     const { signal } = controller;
+    if (options.allowEager && !warnedAllowEager) {
+        warnedAllowEager = true;
+        console.warn('polite-media: allowEager is ignored. To fade an eager image, put ' +
+            'data-polite-reveal="eager" on it, where the stylesheet can see the choice.');
+    }
     scheduleUnmanagedCheck();
+    const claimed = [];
     for (const image of resolveTargets(target)) {
         managed.add(image);
-        // Eager images are revealed at once rather than skipped.
-        //
-        // Skipping looks like the cautious choice and is the opposite: image.css
-        // has already hidden anything carrying data-polite-reveal, so declining to
-        // manage it leaves it invisible permanently instead of merely unfaded.
-        // Revealing immediately keeps the LCP candidate visible from its first
-        // paint, which is the whole reason eager images are treated differently.
+        // Tells the stylesheet to leave this one alone. The failsafe there is for images nothing
+        // reveals, and firing it on one this module owns is worse than not firing it at all: opacity
+        // reaches 1 while the picture is still in flight, so when it arrives there is no fade left to
+        // run. Measured on a real page, eleven below-the-fold images were revealed that way five
+        // seconds in, none of them loaded.
+        image.setAttribute(MANAGED, '');
+        claimed.push(image);
+        // An eager image is never hidden by image.css, because LCP excludes elements at
+        // opacity 0 and a deferred module cannot reveal one before first paint. So it
+        // is marked ready at once, unless the markup opted it into the fade with the
+        // same value the stylesheet keys on.
         //
         // Tested against 'lazy' rather than for 'eager' deliberately. Engines
         // disagree on what an absent or invalid attribute reports: MDN documents
         // only 'eager' and 'lazy', while happy-dom returns 'auto'. Only "lazy" has
         // one agreed spelling, so asking whether it is lazy is answerable
         // everywhere, and everything else correctly falls into the eager branch.
-        if (!options.allowEager && image.loading !== 'lazy') {
+        const optedIn = image.getAttribute('data-polite-reveal') === 'eager';
+        if (!optedIn && image.loading !== 'lazy') {
             markReady(image);
             continue;
         }
@@ -155,7 +173,16 @@ export function revealImages(target, options = {}) {
             image.addEventListener('error', () => markReady(image), { once: true, signal });
         });
     }
-    return () => controller.abort();
+    // Hands anything still unrevealed back to the stylesheet. A router tearing the page down before
+    // the images resolved would otherwise leave them owned by a module that has stopped listening,
+    // and with the failsafe suppressed that is hidden forever rather than merely unfaded.
+    return () => {
+        controller.abort();
+        for (const image of claimed) {
+            if (!image.hasAttribute(READY))
+                image.removeAttribute(MANAGED);
+        }
+    };
 }
 // Re-exported so `polite-media/image` carries the ElementEventMap and
 // DocumentEventMap augmentation too: it only reaches a consumer whose program

package/dist/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,kBAAkB,EAA+B,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAe,MAAM,cAAc,CAAC;AAsB3D,MAAM,KAAK,GAAG,mBAAmB,CAAC;AAElC,SAAS,SAAS,CAAC,KAAuB;IACxC,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC9B,KAAK,CAAC,aAAa,CACjB,IAAI,WAAW,CAAyB,kBAAkB,EAAE;QAC1D,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,EAAE,KAAK,EAAE;KAClB,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAoB,CAAC;AAEhD,IAAI,cAAyD,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,SAAS,sBAAsB;IAC7B,YAAY,CAAC,cAAc,CAAC,CAAC;IAC7B,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;QAC/B,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,gBAAgB,CAAmB,yBAAyB,CAAC,EAAE,CAAC;YAC3F,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,SAAS;YACjC,OAAO,CAAC,IAAI,CACV,oFAAoF;gBAClF,sEAAsE,EACxE,KAAK,CACN,CAAC;YACF,OAAO;QACT,CAAC;QACD,cAAc,EAAE,CAAC;IACnB,CAAC,EAAE,IAAI,CAAC,CAAC;AACX,CAAC;AAED,IAAI,kBAAkB,GAAG,KAAK,CAAC;AAE/B;;;;;;;;;;;;;;;GAeG;AACH,SAAS,cAAc;IACrB,IAAI,kBAAkB;QAAE,OAAO;IAE/B,+FAA+F;IAC/F,iFAAiF;IACjF,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5C,KAAK,CAAC,YAAY,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;IAC7C,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;IAChD,KAAK,CAAC,MAAM,EAAE,CAAC;IAEf,kGAAkG;IAClG,gGAAgG;IAChG,+DAA+D;IAC/D,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO;IAE5B,kBAAkB,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,IAAI,CACV,0FAA0F;QACxF,+FAA+F,CAClG,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB,EAAE,UAA+B,EAAE;IACjF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAE9B,sBAAsB,EAAE,CAAC;IAEzB,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,yDAAyD;QACzD,EAAE;QACF,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,uEAAuE;QACvE,yEAAyE;QACzE,EAAE;QACF,sEAAsE;QACtE,yEAAyE;QACzE,2EAA2E;QAC3E,kEAAkE;QAClE,yEAAyE;QACzE,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YACpD,SAAS,CAAC,KAAK,CAAC,CAAC;YACjB,SAAS;QACX,CAAC;QAED,0EAA0E;QAC1E,6EAA6E;QAC7E,sEAAsE;QACtE,6CAA6C;QAC7C,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YAC7C,qBAAqB,CAAC,GAAG,EAAE;gBACzB,IAAI,CAAC,MAAM,CAAC,OAAO;oBAAE,SAAS,CAAC,KAAK,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,KAAK;aACF,MAAM,EAAE;aACR,IAAI,CAAC,GAAG,EAAE;YACT,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,SAAS,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,qEAAqE;YACrE,sEAAsE;YACtE,uEAAuE;YACvE,yEAAyE;YACzE,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC3B,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACnB,SAAS,CAAC,KAAK,CAAC,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/E,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;IACP,CAAC;IAED,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;AAClC,CAAC;AAED,sEAAsE;AACtE,8EAA8E;AAC9E,wCAAwC;AACxC,OAAO,EAAE,kBAAkB,EAA+B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"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"}

package/dist/layer.css

@@ -1 +1 @@
-[data-polite-media]{position:relative}[data-polite-media]>:is(img,video),[data-polite-media]>picture>img{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
+[data-polite-media]{position:relative}[data-polite-media]>img,[data-polite-media]>picture>img,[data-polite-media] video{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}

package/dist/video.css

@@ -1 +1 @@
-[data-polite-media]>video{opacity:0;transition:opacity var(--polite-fade, 0s) ease}[data-polite-media][data-polite-ready]>video{opacity:1}[data-polite-media][data-polite-ready]>:is(img,picture){visibility:hidden;transition:visibility 0s linear var(--polite-fade, 0s)}[data-polite-media][data-polite-failed]>video{opacity:0}@media(prefers-reduced-motion:reduce){[data-polite-media]>video,[data-polite-media]>:is(img,picture){transition:none}}
+[data-polite-media] video{opacity:0;transition:opacity var(--polite-fade, 0s) ease}[data-polite-media][data-polite-ready] video{opacity:1}[data-polite-media][data-polite-ready]>:is(img,picture){visibility:hidden;transition:visibility 0s linear var(--polite-fade, 0s)}[data-polite-media][data-polite-failed] video{opacity:0}@media(prefers-reduced-motion:reduce){[data-polite-media] video,[data-polite-media]>:is(img,picture){transition:none}}

package/dist/video.d.ts

@@ -11,5 +11,5 @@
  */
 export { configure, pauseAll, register, registerAll, resumeAll, unregister, unregisterAll, } from './coordinator.js';
 export type { AtOnce, ConfigureOptions, RegisterOptions, VideoTarget } from './coordinator.js';
-export { POLITE_VIDEO_PAUSECHANGE, POLITE_VIDEO_FAILED, POLITE_VIDEO_READY, type PolitePauseEventDetail, type PoliteVideoEventDetail, } from './events.js';
+export { POLITE_VIDEO_BLOCKED, POLITE_VIDEO_PAUSECHANGE, POLITE_VIDEO_FAILED, POLITE_VIDEO_READY, type PolitePauseEventDetail, type PoliteVideoEventDetail, } from './events.js';
 //# sourceMappingURL=video.d.ts.map

package/dist/video.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../src/video.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAK/F,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../src/video.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAK/F,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC"}

package/dist/video.js

@@ -13,5 +13,5 @@ export { configure, pauseAll, register, registerAll, resumeAll, unregister, unre
 // Loaded for its `declare global` block as much as for the constants: the
 // ElementEventMap and DocumentEventMap augmentation only reaches a consumer if
 // this module is part of their program.
-export { POLITE_VIDEO_PAUSECHANGE, POLITE_VIDEO_FAILED, POLITE_VIDEO_READY, } from './events.js';
+export { POLITE_VIDEO_BLOCKED, POLITE_VIDEO_PAUSECHANGE, POLITE_VIDEO_FAILED, POLITE_VIDEO_READY, } from './events.js';
 //# sourceMappingURL=video.js.map

package/dist/video.js.map

@@ -1 +1 @@
-{"version":3,"file":"video.js","sourceRoot":"","sources":["../src/video.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,0EAA0E;AAC1E,+EAA+E;AAC/E,wCAAwC;AACxC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,GAGnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"video.js","sourceRoot":"","sources":["../src/video.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,0EAA0E;AAC1E,+EAA+E;AAC/E,wCAAwC;AACxC,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,GAGnB,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polite-media",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Background video, image reveals and next-page image warming. Reveals on the frame that actually painted, plays only what is on screen, respects data and motion.",
   "keywords": [
     "video",

package/src/coordinator.ts

@@ -1,5 +1,6 @@
 import { connectionAllowsMedia, mediaQuery, motionAllowed } from './env.js';
 import {
+  POLITE_VIDEO_BLOCKED,
   POLITE_VIDEO_PAUSECHANGE,
   POLITE_VIDEO_FAILED,
   POLITE_VIDEO_READY,
@@ -333,7 +334,11 @@ export interface RegisterOptions {
 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;
@@ -543,12 +548,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 +564,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,6 +574,9 @@ 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));
 }
@@ -644,11 +652,10 @@ 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
@@ -667,8 +674,9 @@ function warnIfNothingToReveal(entry: Entry): void {
 
   warnedNothingToReveal = 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
   );
 }
@@ -679,11 +687,27 @@ function warnIfNothingToReveal(entry: Entry): void {
  */
 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 +758,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 {
@@ -1067,19 +1095,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,7 +1169,6 @@ function writeStoredPause(paused: boolean): void {
 function restorePaused(): void {
   if (userPaused || !readStoredPause()) return;
   userPaused = true;
-  document.documentElement.setAttribute('data-polite-paused', '');
   reflectPaused();
 }
 
@@ -1211,7 +1241,7 @@ export function register(video: HTMLVideoElement, options: RegisterOptions = {})
   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),
@@ -1227,6 +1257,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 +1286,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 +1299,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);
@@ -1341,9 +1376,6 @@ 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();
 

package/src/events.ts

@@ -27,6 +27,13 @@ export const POLITE_VIDEO_READY = 'polite-video:ready';
 /** Dispatched on the video when no source could be decoded. Bubbles. */
 export const POLITE_VIDEO_FAILED = 'polite-video:failed';
 
+/**
+ * Dispatched on the video when the browser refused `play()` until a user gesture.
+ * Bubbles. The library keeps retrying on its own; this exists so a host can show
+ * a play affordance in the meantime, which the library cannot do for it.
+ */
+export const POLITE_VIDEO_BLOCKED = 'polite-video:blocked';
+
 /** Dispatched on the image once it has decoded. Bubbles. */
 export const POLITE_IMAGE_READY = 'polite-image:ready';
 
@@ -66,12 +73,14 @@ declare global {
   interface ElementEventMap {
     'polite-video:ready': CustomEvent<PoliteVideoEventDetail>;
     'polite-video:failed': CustomEvent<PoliteVideoEventDetail>;
+    'polite-video:blocked': CustomEvent<PoliteVideoEventDetail>;
     'polite-image:ready': CustomEvent<PoliteImageEventDetail>;
   }
 
   interface DocumentEventMap {
     'polite-video:ready': CustomEvent<PoliteVideoEventDetail>;
     'polite-video:failed': CustomEvent<PoliteVideoEventDetail>;
+    'polite-video:blocked': CustomEvent<PoliteVideoEventDetail>;
     'polite-image:ready': CustomEvent<PoliteImageEventDetail>;
     'polite-video:pausechange': CustomEvent<PolitePauseEventDetail>;
   }

package/src/image.css

@@ -9,6 +9,12 @@
  * them invisible forever rather than merely unfaded. Per image, an image is
  * hidden only if something is going to reveal it.
  *
+ * Only a lazy image is hidden. An eager one may be the Largest Contentful Paint
+ * element, LCP excludes anything at opacity 0, and a deferred module cannot
+ * reveal it before first paint, so the stylesheet never touches it and the
+ * module marks it ready at once. To fade an eager image anyway, say so where
+ * this file can see it: `data-polite-reveal="eager"`.
+ *
  * A REQUIREMENT rather than a suggestion: the container needs its own visible
  * backdrop, usually a background-color. Unlike video, an image has no poster
  * behind it, so a hidden image over a transparent container shows nothing.
@@ -33,7 +39,8 @@
  */
 
 @media (scripting: enabled) {
-  img[data-polite-reveal] {
+  img[data-polite-reveal][loading='lazy'],
+  img[data-polite-reveal='eager'] {
     opacity: 0;
     transition: opacity var(--polite-fade, 350ms) ease;
   }
@@ -50,11 +57,9 @@
    * stylesheet applied stayed at 0 for the whole delay and then snapped to 1
    * unfaded, while Chromium and WebKit revealed it. Cancelling only the animation
    * on such an image put it at 1 immediately.
-   *
-   * Eager images hid the bug, because they are marked ready inside the same task
-   * that applies the stylesheet, before this can take effect.
    */
-  img[data-polite-reveal]:not([data-polite-ready]) {
+  img[data-polite-reveal][loading='lazy']:not([data-polite-ready]):not([data-polite-managed]),
+  img[data-polite-reveal='eager']:not([data-polite-ready]):not([data-polite-managed]) {
     animation: polite-reveal-failsafe 0s var(--polite-failsafe, 5s) forwards;
   }