polite-media 0.3.0

package/dist/sources.js

@@ -0,0 +1,148 @@
+import { mediaQuery } from './env.js';
+/**
+ * Picks which `<source>` a video actually loads, and moves on when one turns out
+ * to be undecodable.
+ *
+ * Two problems, one mechanism.
+ *
+ * `<source media>` is evaluated once, during resource selection, and never
+ * again -- in every engine, not just Safari. Verified in Chromium: after loading
+ * at 1200px, resizing to 500px left `currentSrc` on the wide source even though
+ * the narrow query then matched. The spec has no hook for it, since resource
+ * selection only re-runs when `src` or the `<source>` children change. So a
+ * source list alone cannot respond to a viewport that moved since parse.
+ * Resolving the list here and assigning `video.src` directly sidesteps that
+ * entirely: one assignment, no negotiation left to go stale.
+ *
+ * And `canPlayType` is only ever a claim. The HTML Standard sets the bar at the
+ * user agent being "confident that the type represents a media resource that it
+ * can render", and confidence is not a guarantee: in this project's own fixtures
+ * Chromium answered "probably" for AV1 and then failed at
+ * `dav1d_send_data()`. So the codec check only drops the flat "no" answers;
+ * among what survives, document order sets the try order and the `error` event
+ * decides the outcome.
+ *
+ * Deliberately *not* re-selecting on resize. Reassigning `src` restarts
+ * playback from frame 0, so a phone rotating mid-scroll would visibly rewind the
+ * video. The first choice sticks for the page's lifetime.
+ */
+/** `MediaError.MEDIA_ERR_DECODE` and `MEDIA_ERR_SRC_NOT_SUPPORTED`. */
+const MEDIA_ERR_DECODE = 3;
+const MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
+/**
+ * Whether an error means "this file is unusable, try another" as opposed to
+ * "something happened to this attempt".
+ *
+ * Codes matter here. `MEDIA_ERR_ABORTED` (1) is what the element reports when
+ * its `src` is reassigned -- which this module does itself -- so treating every
+ * error as fatal would cascade through the whole candidate list on the first
+ * assignment. `MEDIA_ERR_NETWORK` (2) means the fetch failed on a resource that
+ * was previously fine; another candidate is unlikely to fare better on the same
+ * connection, and burning the list would leave nothing to retry with.
+ */
+export function isUnusable(error) {
+    if (!error)
+        return false;
+    return error.code === MEDIA_ERR_DECODE || error.code === MEDIA_ERR_SRC_NOT_SUPPORTED;
+}
+let warnedMediaGap = false;
+/**
+ * Which `<source>` this video could actually load, best first.
+ *
+ * `media` is treated as a *preference*, not an exclusion. Two queries meant to
+ * partition the viewport often do not quite meet: `(max-width: 50rem)` beside
+ * `(min-width: 50.001rem)` leaves 0.016px matching neither at a 16px root, and
+ * a root font-size that is not 16px moves the boundary somewhere else again.
+ * Widths in the gap select nothing and the video has nothing to play. The
+ * browser behaves that way too, which is no help to anyone.
+ *
+ * So when no source claims the current viewport, every decodable one is a
+ * candidate and document order decides. The alternative was a markup rule, "the
+ * last <source> must carry no media attribute", which every consumer had to
+ * remember and which a real project had already got wrong.
+ *
+ * The cost is that `media` can no longer mean "and otherwise play nothing". It
+ * never reliably could, since the markup contract already required an
+ * unconditional fallback, and `atOnce: { small: 0 }` says that properly.
+ */
+function candidatesFor(video) {
+    // `:scope >` so a <source> belonging to some nested media element is never
+    // mistaken for this one's.
+    const sources = [...video.querySelectorAll(':scope > source')];
+    const decodable = sources.filter((source) => {
+        // The attribute, not the property: `.src` resolves against the document
+        // base, so `<source src="">` comes back as the page's own URL -- truthy,
+        // and it would then be handed to the video as if it were a media file.
+        if (!source.getAttribute('src'))
+            return false;
+        // Empty string is the only definite "no" canPlayType offers. "maybe" is
+        // kept, because "maybe" is what browsers say about most things.
+        return !source.type || video.canPlayType(source.type) !== '';
+    });
+    const claiming = decodable.filter((source) => {
+        const media = source.getAttribute('media');
+        return !media || mediaQuery(media).matches;
+    });
+    if (claiming.length === 0 && decodable.length > 0)
+        warnMediaGap(video);
+    return {
+        declared: sources.length,
+        playable: (claiming.length > 0 ? claiming : decodable).map((source) => source.src),
+    };
+}
+/**
+ * Fires only when the gap actually opens, rather than whenever the markup looks
+ * capable of it. A static check would have to nag every page whose sources are
+ * all conditional, including the overwhelming majority whose queries really do
+ * cover every width they will ever see.
+ */
+function warnMediaGap(video) {
+    if (warnedMediaGap)
+        return;
+    warnedMediaGap = true;
+    console.warn('polite-media: no <source> claims this viewport, so the first decodable one was used ' +
+        'instead of nothing. Give the last <source> no media attribute to choose the fallback ' +
+        'yourself.', video);
+}
+export function manageSources(video) {
+    const { declared, playable: candidates } = candidatesFor(video);
+    let index = -1;
+    const load = () => {
+        const next = candidates[index];
+        if (next === undefined)
+            return false;
+        video.src = next;
+        // Required: assigning `src` alone does not restart resource selection on an
+        // element that has already loaded.
+        video.load();
+        return true;
+    };
+    return {
+        select() {
+            // "No <source> children at all" and "sources were declared but none
+            // qualified" are different situations and must not share a branch. The
+            // first is a video authored with a plain `src` -- somebody else's
+            // arrangement, left exactly as it is. The second is a video with nothing
+            // playable, which has to report failure so the poster stays and the host
+            // is told.
+            if (declared === 0)
+                return Boolean(video.currentSrc || video.getAttribute('src'));
+            // Re-checked rather than assumed: a first select() that found nothing
+            // playable still advanced the index, so answering a later call with a bare
+            // `true` would report success for a video that never loaded anything.
+            if (index >= 0)
+                return candidates[index] !== undefined;
+            index = 0;
+            return load();
+        },
+        advance() {
+            index += 1;
+            return load();
+        },
+    };
+}
+/** Internal reset for tests. Not exported from the package entry point. */
+export function resetSourceWarnings() {
+    warnedMediaGap = false;
+}
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,uEAAuE;AACvE,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,KAAK,CAAC,IAAI,KAAK,gBAAgB,IAAI,KAAK,CAAC,IAAI,KAAK,2BAA2B,CAAC;AACvF,CAAC;AASD,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,aAAa,CAAC,KAAuB;IAC5C,2EAA2E;IAC3E,2BAA2B;IAC3B,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAoB,iBAAiB,CAAC,CAAC,CAAC;IAElF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;QAC1C,wEAAwE;QACxE,yEAAyE;QACzE,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9C,wEAAwE;QACxE,gEAAgE;QAChE,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC3C,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IAEvE,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,MAAM;QACxB,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC;KACnF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAuB;IAC3C,IAAI,cAAc;QAAE,OAAO;IAC3B,cAAc,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,IAAI,CACV,sFAAsF;QACpF,uFAAuF;QACvF,WAAW,EACb,KAAK,CACN,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAuB;IACnD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;IAEf,MAAM,IAAI,GAAG,GAAY,EAAE;QACzB,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACrC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC;QACjB,4EAA4E;QAC5E,mCAAmC;QACnC,KAAK,CAAC,IAAI,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,OAAO;QACL,MAAM;YACJ,oEAAoE;YACpE,uEAAuE;YACvE,kEAAkE;YAClE,yEAAyE;YACzE,yEAAyE;YACzE,WAAW;YACX,IAAI,QAAQ,KAAK,CAAC;gBAAE,OAAO,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;YAClF,sEAAsE;YACtE,2EAA2E;YAC3E,sEAAsE;YACtE,IAAI,KAAK,IAAI,CAAC;gBAAE,OAAO,UAAU,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;YACvD,KAAK,GAAG,CAAC,CAAC;YACV,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,OAAO;YACL,KAAK,IAAI,CAAC,CAAC;YACX,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB;IACjC,cAAc,GAAG,KAAK,CAAC;AACzB,CAAC"}

package/dist/targets.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module
+ * How both halves name the elements they act on, so `revealImages('.card img')`
+ * and `registerAll('[data-polite-media] video')` mean the same thing rather than
+ * being two similar-looking ideas.
+ */
+/**
+ * Anything that names one or more elements: a selector, a single element, or any
+ * collection of them.
+ *
+ * `ArrayLike` is listed alongside `Iterable` deliberately. `NodeListOf` and
+ * `HTMLCollectionOf` are iterable at runtime, but their `[Symbol.iterator]` lives
+ * in `lib.dom.iterable`, so a consumer whose `lib` omits it cannot pass
+ * `document.querySelectorAll('img')` to an `Iterable`-only parameter even though
+ * it works. `ArrayLike` is structural and needs no `lib` support.
+ */
+export type Target<T extends Element> = string | T | ArrayLike<T> | Iterable<T>;
+/** Resolves a {@link Target} to the elements it names. */
+export declare function resolveTargets<T extends Element>(target: Target<T>): T[];
+//# sourceMappingURL=targets.d.ts.map

package/dist/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,OAAO,IAAI,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEhF,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAMxE"}

package/dist/targets.js

@@ -0,0 +1,17 @@
+/**
+ * @module
+ * How both halves name the elements they act on, so `revealImages('.card img')`
+ * and `registerAll('[data-polite-media] video')` mean the same thing rather than
+ * being two similar-looking ideas.
+ */
+/** Resolves a {@link Target} to the elements it names. */
+export function resolveTargets(target) {
+    if (typeof target === 'string')
+        return [...document.querySelectorAll(target)];
+    // A single element is the obvious thing to pass when you already hold one, and
+    // it used to be rejected: `revealImages(myImg)` did not compile.
+    if (target instanceof Element)
+        return [target];
+    return Array.from(target);
+}
+//# sourceMappingURL=targets.js.map

package/dist/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,0DAA0D;AAC1D,MAAM,UAAU,cAAc,CAAoB,MAAiB;IACjE,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAI,MAAM,CAAC,CAAC,CAAC;IACjF,+EAA+E;IAC/E,iEAAiE;IACjE,IAAI,MAAM,YAAY,OAAO;QAAE,OAAO,CAAC,MAAW,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAsB,CAAC,CAAC;AAC5C,CAAC"}

package/dist/video.css

@@ -0,0 +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}}

package/dist/video.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module
+ * Everything for background video. Imported on its own so an image-only page
+ * never pays for the IntersectionObserver, source selection or arbitration.
+ *
+ * The export list is deliberately small. Every name here is permanent once
+ * published, and adding one later is not a breaking change while removing one
+ * is -- so anything without a caller that can be named stays internal. The
+ * environment gates and the reveal primitive are used by this package and are
+ * not part of its interface.
+ */
+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';
+//# sourceMappingURL=video.d.ts.map

package/dist/video.d.ts.map

@@ -0,0 +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"}

package/dist/video.js

@@ -0,0 +1,17 @@
+/**
+ * @module
+ * Everything for background video. Imported on its own so an image-only page
+ * never pays for the IntersectionObserver, source selection or arbitration.
+ *
+ * The export list is deliberately small. Every name here is permanent once
+ * published, and adding one later is not a breaking change while removing one
+ * is -- so anything without a caller that can be named stays internal. The
+ * environment gates and the reveal primitive are used by this package and are
+ * not part of its interface.
+ */
+export { configure, pauseAll, register, registerAll, resumeAll, unregister, unregisterAll, } from './coordinator.js';
+// 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';
+//# sourceMappingURL=video.js.map

package/dist/video.js.map

@@ -0,0 +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"}

package/dist/warm.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module
+ * Warming a destination page's image before the visitor gets there. Imported on
+ * its own, so a page that only warms never pays for the video coordinator.
+ *
+ * A barrel for the same reason `video.ts` is one: this file is what the `./warm`
+ * subpath resolves to, so every name it exports is public and permanent once
+ * published. `resetWarmed` clears the dedup record for a test and has no caller
+ * outside the suite, so it stays in `warming.ts` where tests reach it directly.
+ */
+export { warm, warmOnIntent } from './warming.js';
+export type { WarmOptions, WarmSource } from './warming.js';
+//# sourceMappingURL=warm.d.ts.map

package/dist/warm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warm.d.ts","sourceRoot":"","sources":["../src/warm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/warm.js

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * Warming a destination page's image before the visitor gets there. Imported on
+ * its own, so a page that only warms never pays for the video coordinator.
+ *
+ * A barrel for the same reason `video.ts` is one: this file is what the `./warm`
+ * subpath resolves to, so every name it exports is public and permanent once
+ * published. `resetWarmed` clears the dedup record for a test and has no caller
+ * outside the suite, so it stays in `warming.ts` where tests reach it directly.
+ */
+export { warm, warmOnIntent } from './warming.js';
+//# sourceMappingURL=warm.js.map

package/dist/warm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warm.js","sourceRoot":"","sources":["../src/warm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/warming.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module
+ * Warming a destination page's image before the visitor gets there, so the click
+ * lands on a picture that is already in the cache.
+ *
+ * Every document prefetcher fetches the HTML and stops: Astro's `data-astro-prefetch`,
+ * Next's `<Link>`, quicklink. The image inside that HTML is discovered only after
+ * the new document parses, which is exactly when it is too late to matter.
+ *
+ * The platform has the pieces but not in one place. `imagesrcset` and `imagesizes`
+ * do responsive selection, but MDN scopes them to `rel="preload"` with `as="image"`
+ * only, and scopes preload itself to resources "your page will need very soon". A
+ * speculative navigation wants `prefetch` semantics, where those attributes do not
+ * apply. So you can have the right selection or the right timing, not both, and
+ * anyone who wants both ends up re-implementing the browser's own rules in JS:
+ * parsing `sizes`, comparing `w` descriptors, guessing format support.
+ *
+ * This module does none of that. It builds the candidates as a detached
+ * `<picture>` and lets the browser choose, which is measurably the same algorithm
+ * the destination page will run (e2e/warm.spec.ts, all three engines). Nothing
+ * here parses a media query, so nothing here can disagree with one.
+ *
+ * A detached `<img>` also *fetches* what it selects, so no `<link>` is injected at
+ * all. That sidesteps the two documented failures of the link approach: Safari
+ * does not support `<link rel="prefetch">`, and Firefox aborts it with
+ * NS_BINDING_ABORTED when the response carries no explicit cache header.
+ *
+ * Not an image pipeline. It generates no URLs and knows no widths; it warms the
+ * candidates you already build.
+ */
+/** One `<picture>` candidate: a format, and the variants available in it. */
+export interface WarmSource {
+    /** A MIME type such as `image/avif`. Omitted means "always a candidate". */
+    type?: string;
+    srcset: string;
+}
+export interface WarmOptions {
+    /** Ordered, first supported wins, exactly as `<source>` children behave. */
+    sources?: WarmSource[];
+    srcset?: string;
+    /** A single URL, for an image with no variants. */
+    src?: string;
+    /** Handed to the browser verbatim. Nothing in this package parses it. */
+    sizes?: string;
+}
+/** Warms one image: selects the variant this browser would request, and fetches it. */
+export declare function warm(options: WarmOptions): void;
+/**
+ * Warms whatever `resolve` names when the visitor shows intent toward `selector`.
+ *
+ * Delegated on the document, so links added later are covered without rebinding
+ * and one listener serves a whole grid. `resolve` returns the candidates rather
+ * than the library inventing a `data-*` vocabulary for them: where an app keeps
+ * its srcsets is the app's business.
+ *
+ * Returns a teardown. Listeners on `document` survive a `<ClientRouter />` swap,
+ * so a caller that re-binds per navigation stacks duplicates without one.
+ */
+export declare function warmOnIntent(selector: string, resolve: (element: Element) => WarmOptions | null | undefined): () => void;
+/** Drops the dedup record so a test can warm the same thing twice. Not public API. */
+export declare function resetWarmed(): void;
+//# sourceMappingURL=warming.d.ts.map

package/dist/warming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warming.d.ts","sourceRoot":"","sources":["../src/warming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA4BD,uFAAuF;AACvF,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAyC/C;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,WAAW,GAAG,IAAI,GAAG,SAAS,GAC5D,MAAM,IAAI,CAcZ;AAED,sFAAsF;AACtF,wBAAgB,WAAW,IAAI,IAAI,CAGlC"}

package/dist/warming.js

@@ -0,0 +1,136 @@
+/**
+ * @module
+ * Warming a destination page's image before the visitor gets there, so the click
+ * lands on a picture that is already in the cache.
+ *
+ * Every document prefetcher fetches the HTML and stops: Astro's `data-astro-prefetch`,
+ * Next's `<Link>`, quicklink. The image inside that HTML is discovered only after
+ * the new document parses, which is exactly when it is too late to matter.
+ *
+ * The platform has the pieces but not in one place. `imagesrcset` and `imagesizes`
+ * do responsive selection, but MDN scopes them to `rel="preload"` with `as="image"`
+ * only, and scopes preload itself to resources "your page will need very soon". A
+ * speculative navigation wants `prefetch` semantics, where those attributes do not
+ * apply. So you can have the right selection or the right timing, not both, and
+ * anyone who wants both ends up re-implementing the browser's own rules in JS:
+ * parsing `sizes`, comparing `w` descriptors, guessing format support.
+ *
+ * This module does none of that. It builds the candidates as a detached
+ * `<picture>` and lets the browser choose, which is measurably the same algorithm
+ * the destination page will run (e2e/warm.spec.ts, all three engines). Nothing
+ * here parses a media query, so nothing here can disagree with one.
+ *
+ * A detached `<img>` also *fetches* what it selects, so no `<link>` is injected at
+ * all. That sidesteps the two documented failures of the link approach: Safari
+ * does not support `<link rel="prefetch">`, and Firefox aborts it with
+ * NS_BINDING_ABORTED when the response carries no explicit cache header.
+ *
+ * Not an image pipeline. It generates no URLs and knows no widths; it warms the
+ * candidates you already build.
+ */
+import { connectionAllowsMedia } from './env.js';
+const warmed = new Set();
+/**
+ * Images with a fetch still in flight.
+ *
+ * A detached element is reachable from nothing once this function returns, and a
+ * collected image would be an aborted fetch. Precautionary rather than a fix for
+ * something observed: no engine was seen dropping one. It is cheap, and the bug
+ * it forecloses would be silent and load dependent, which is the kind no test
+ * here would catch.
+ */
+const inFlight = new Set();
+/**
+ * Deduped on what the caller asked for rather than on the URL the browser picks,
+ * because the URL is not known until selection has already happened, and the
+ * repeat this exists to stop is the same link hovered twice.
+ */
+function keyOf(options) {
+    const sources = (options.sources ?? []).map((source) => `${source.type ?? ''}|${source.srcset}`);
+    // Joined on NUL rather than a newline: a srcset spanning several lines is
+    // ordinary formatting, and would otherwise let two different candidate sets
+    // build the same key and silently drop the second warm.
+    return [...sources, options.srcset ?? '', options.src ?? '', options.sizes ?? ''].join('\0');
+}
+/** Warms one image: selects the variant this browser would request, and fetches it. */
+export function warm(options) {
+    // Speculative bytes are the first thing to drop on a metered connection. Astro
+    // downgrades to its `tap` strategy here rather than skipping; for an image
+    // nobody has asked for yet, not spending them at all is the better trade.
+    if (!connectionAllowsMedia())
+        return;
+    const sources = options.sources ?? [];
+    // Checked before anything is built, so an empty call allocates nothing, and
+    // before `warmed` is touched, so it cannot make a later correct call a no-op.
+    if (sources.length === 0 && !options.srcset && !options.src) {
+        console.warn('polite-media: warm() was given no src, srcset or sources, so nothing was warmed.');
+        return;
+    }
+    const key = keyOf(options);
+    if (warmed.has(key))
+        return;
+    const picture = document.createElement('picture');
+    for (const source of sources) {
+        const element = document.createElement('source');
+        if (source.type)
+            element.type = source.type;
+        element.srcset = source.srcset;
+        picture.append(element);
+    }
+    const img = document.createElement('img');
+    picture.append(img);
+    // The visitor has not asked for this image and may never ask. It must not
+    // compete with the page they are actually looking at.
+    img.fetchPriority = 'low';
+    if (options.sizes)
+        img.sizes = options.sizes;
+    if (options.srcset)
+        img.srcset = options.srcset;
+    if (options.src)
+        img.src = options.src;
+    warmed.add(key);
+    inFlight.add(img);
+    const settled = () => void inFlight.delete(img);
+    img.addEventListener('load', settled, { once: true });
+    img.addEventListener('error', settled, { once: true });
+}
+/**
+ * The events that mean "about to navigate". `pointerover` and `focusin` cover
+ * Astro's documented `hover` strategy, "when you hover over or focus on the
+ * link"; `touchstart` covers the touch case, where a hover never happens.
+ */
+const INTENT_EVENTS = ['pointerover', 'focusin', 'touchstart'];
+/**
+ * Warms whatever `resolve` names when the visitor shows intent toward `selector`.
+ *
+ * Delegated on the document, so links added later are covered without rebinding
+ * and one listener serves a whole grid. `resolve` returns the candidates rather
+ * than the library inventing a `data-*` vocabulary for them: where an app keeps
+ * its srcsets is the app's business.
+ *
+ * Returns a teardown. Listeners on `document` survive a `<ClientRouter />` swap,
+ * so a caller that re-binds per navigation stacks duplicates without one.
+ */
+export function warmOnIntent(selector, resolve) {
+    const onIntent = (event) => {
+        const element = event.target?.closest?.(selector);
+        if (!element)
+            return;
+        const options = resolve(element);
+        if (options)
+            warm(options);
+    };
+    for (const type of INTENT_EVENTS) {
+        document.addEventListener(type, onIntent, { passive: true });
+    }
+    return () => {
+        for (const type of INTENT_EVENTS)
+            document.removeEventListener(type, onIntent);
+    };
+}
+/** Drops the dedup record so a test can warm the same thing twice. Not public API. */
+export function resetWarmed() {
+    warmed.clear();
+    inFlight.clear();
+}
+//# sourceMappingURL=warming.js.map

package/dist/warming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warming.js","sourceRoot":"","sources":["../src/warming.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "polite-media",
+  "version": "0.3.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",
+    "background-video",
+    "image",
+    "lazy",
+    "poster",
+    "autoplay",
+    "intersection-observer",
+    "requestVideoFrameCallback",
+    "performance",
+    "lcp",
+    "prefetch",
+    "srcset"
+  ],
+  "license": "MIT",
+  "author": "sixra",
+  "packageManager": "pnpm@11.25.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sixra/polite-media.git"
+  },
+  "homepage": "https://github.com/sixra/polite-media#readme",
+  "bugs": "https://github.com/sixra/polite-media/issues",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    "./video": {
+      "types": "./dist/video.d.ts",
+      "default": "./dist/video.js"
+    },
+    "./image": {
+      "types": "./dist/image.d.ts",
+      "default": "./dist/image.js"
+    },
+    "./warm": {
+      "types": "./dist/warm.d.ts",
+      "default": "./dist/warm.js"
+    },
+    "./video.css": "./dist/video.css",
+    "./image.css": "./dist/image.css",
+    "./layer.css": "./dist/layer.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24",
+      "onFail": "error"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/clean.js && tsc -p tsconfig.build.json && esbuild src/video.css src/image.css src/layer.css --minify --outdir=dist",
+    "clean": "node scripts/clean.js",
+    "fixtures": "sh scripts/make-fixtures.sh",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepack": "pnpm run build",
+    "prepare": "lefthook install",
+    "size": "node scripts/size-check.js",
+    "test": "vitest run",
+    "test:e2e": "pnpm run build && playwright test",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build && pnpm size"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^26.4.0",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
+    "happy-dom": "^20.12.0",
+    "lefthook": "^2.1.12",
+    "prettier": "^3.9.6",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^4.1.11"
+  }
+}