polite-media 0.3.0

package/src/env.ts

@@ -0,0 +1,56 @@
+/**
+ * Environment gates: the conditions under which video is allowed to play at all.
+ * The poster is a complete fallback for every one of them, so a gate that says no
+ * costs the user nothing.
+ */
+
+const queries = new Map<string, MediaQueryList>();
+
+/**
+ * Memoised `matchMedia`, and the reason every media query in this package goes
+ * through one function: a module-scope `matchMedia(...)` throws the moment the
+ * package is imported anywhere without a DOM (SSR, prerender, a Node test), and
+ * would contradict the `sideEffects` declaration in package.json.
+ *
+ * Memoising also lets callers attach `change` listeners to the same object the
+ * predicates read, so "honour it live" costs no extra plumbing.
+ */
+export function mediaQuery(query: string): MediaQueryList {
+  let mql = queries.get(query);
+  if (!mql) {
+    mql = matchMedia(query);
+    queries.set(query, mql);
+  }
+  return mql;
+}
+
+export function motionAllowed(): boolean {
+  return !mediaQuery('(prefers-reduced-motion: reduce)').matches;
+}
+
+interface NetworkInformation {
+  saveData?: boolean;
+  effectiveType?: string;
+}
+
+/**
+ * Video is an enhancement over a poster that already stands on its own, so it is
+ * skipped on a metered or very slow connection.
+ *
+ * Absence must mean *allow*. The Network Information API is not Baseline: Safari
+ * and Firefox never expose it, and Brave disables it as a fingerprinting surface.
+ * Reading absence as "block" would fail closed for most of the web, and fail
+ * closed in the one direction nobody would catch: Chrome is the browser that has
+ * the API, so a Chrome-only developer never sees it.
+ */
+export function connectionAllowsMedia(): boolean {
+  const conn = (navigator as Navigator & { connection?: NetworkInformation }).connection;
+  if (!conn) return true;
+  if (conn.saveData) return false;
+  return conn.effectiveType !== 'slow-2g' && conn.effectiveType !== '2g';
+}
+
+/** Drops memoised queries so a test can swap `matchMedia`. Not part of the public API. */
+export function resetEnv(): void {
+  queries.clear();
+}

package/src/events.ts

@@ -0,0 +1,78 @@
+/**
+ * The events both halves dispatch, and the typing that makes them usable.
+ *
+ * Three pieces, because no one of them is sufficient on its own:
+ *
+ * - The **constants**, because a mistyped event name still compiles. lib.dom
+ *   declares a fallback `addEventListener(type: string, ...)` overload, so
+ *   `'polite-video:redy'` type-checks happily however the maps are augmented.
+ * - The **detail**, because these events bubble by design and the useful
+ *   listener sits on a container, which makes `event.target` the wrong element
+ *   or a bare `EventTarget` needing a cast.
+ * - The **augmentation**, so a listener gets `CustomEvent<Detail>` rather than
+ *   `Event`.
+ *
+ * `ElementEventMap` and `DocumentEventMap` are the two that have to be patched,
+ * and not the more obvious `HTMLElementEventMap`. lib.dom declares
+ * `HTMLElementEventMap extends ElementEventMap`, so augmenting the base reaches
+ * `HTMLElement`, `HTMLMediaElement` and `HTMLVideoElement` through inheritance,
+ * while augmenting the derived one reaches none of its ancestors. `document` is
+ * a separate branch entirely -- `DocumentEventMap extends
+ * GlobalEventHandlersEventMap` -- so it needs its own entry.
+ */
+
+/** Dispatched on the video once a frame has genuinely painted. Bubbles. */
+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 image once it has decoded. Bubbles. */
+export const POLITE_IMAGE_READY = 'polite-image:ready';
+
+/**
+ * Dispatched on `document` when the user pauses or resumes everything.
+ *
+ * The odd one out, and deliberately: a user pause is page-wide rather than about
+ * one video, so there is no element to dispatch it at and nothing for it to
+ * bubble through. Only `DocumentEventMap` is augmented for it.
+ *
+ * It exists because the alternative for a host is watching `data-polite-paused`
+ * on `<html>` with a MutationObserver, which is the same unreasonable ask this
+ * library avoids by maintaining `aria-pressed` itself. Without it, the
+ * label-swapping control the README offers as an option cannot be built.
+ */
+export const POLITE_VIDEO_PAUSECHANGE = 'polite-video:pausechange';
+
+export interface PoliteVideoEventDetail {
+  /**
+   * The managed video. Saves casting `event.target`, which is the container
+   * rather than the video whenever the listener is on an ancestor.
+   */
+  video: HTMLVideoElement;
+}
+
+export interface PoliteImageEventDetail {
+  /** The managed image, for the same reason. */
+  image: HTMLImageElement;
+}
+
+export interface PolitePauseEventDetail {
+  /** True once the user has paused everything, false once they resume. */
+  paused: boolean;
+}
+
+declare global {
+  interface ElementEventMap {
+    'polite-video:ready': CustomEvent<PoliteVideoEventDetail>;
+    'polite-video:failed': CustomEvent<PoliteVideoEventDetail>;
+    'polite-image:ready': CustomEvent<PoliteImageEventDetail>;
+  }
+
+  interface DocumentEventMap {
+    'polite-video:ready': CustomEvent<PoliteVideoEventDetail>;
+    'polite-video:failed': CustomEvent<PoliteVideoEventDetail>;
+    'polite-image:ready': CustomEvent<PoliteImageEventDetail>;
+    'polite-video:pausechange': CustomEvent<PolitePauseEventDetail>;
+  }
+}

package/src/image.css

@@ -0,0 +1,74 @@
+/*
+ * polite-media/image.css -- optional stylesheet.
+ *
+ * Timing only, like the video half: no size, no position, no aspect ratio.
+ *
+ * The opt-in is `data-polite-reveal`, ON THE IMAGE, not on its container.
+ * That placement is load-bearing. A container-wide rule hides every image
+ * inside it, including ones the library then declines to manage -- which leaves
+ * them invisible forever rather than merely unfaded. Per image, an image is
+ * hidden only if something is going to reveal it.
+ *
+ * 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.
+ *
+ *   <div class="card" style-hook>          <-- background-color lives here
+ *     <img src="photo.avif" alt="" loading="lazy" data-polite-reveal>
+ *   </div>
+ *
+ * The fade exists because otherwise an image cuts from the backdrop to the photo
+ * on whatever frame the async decode lands, which reads as a flicker rather than
+ * a load. That is also why this keeps a 350ms default where video.css cuts at
+ * 0s: an image has no second moving picture to ghost against. Both read
+ * --polite-fade, so setting it overrides both.
+ *
+ * Unlike the video half, a hidden image degrades to nothing rather than to a
+ * poster, so hiding it is gated on scripting being available. Baseline since
+ * December 2023, and it needs nothing from the host: with scripting off the rule
+ * never applies and the images simply arrive unfaded.
+ *
+ * No media query can see a bundle that fails to load while scripting is on, so
+ * that case is covered by the failsafe below instead.
+ */
+
+@media (scripting: enabled) {
+  img[data-polite-reveal] {
+    opacity: 0;
+    transition: opacity var(--polite-fade, 350ms) ease;
+    /*
+     * Nothing may stay hidden forever. Marking an image and never passing it to
+     * revealImages() used to leave it invisible permanently, and so did a bundle
+     * that never arrived; both now resolve to merely unfaded.
+     *
+     * Deliberately universal rather than cancelled for images the library owns.
+     * An earlier version marked those and set `animation: none`, which reverts
+     * the filled end state: measured in all three engines, an image the failsafe
+     * had already revealed jumped back to opacity 0 the moment it was claimed.
+     * Applying to everything removes that case, and costs nothing, since a
+     * managed image reaches opacity 1 through `data-polite-ready` long before
+     * the delay and the two agree on the value.
+     */
+    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;
+    }
+  }
+}
+
+/*
+ * The image still reveals under reduced motion, it just arrives instead of
+ * fading. Suppressing the reveal entirely would leave a blank card.
+ */
+@media (prefers-reduced-motion: reduce) {
+  img[data-polite-reveal] {
+    transition: none;
+  }
+}

package/src/image.ts

@@ -0,0 +1,160 @@
+/**
+ * @module
+ * Image reveal. Independent of the video module by design: an image needs no
+ * IntersectionObserver, no source negotiation and no playback arbitration, and
+ * it is not skipped on a metered connection the way video is -- you still have
+ * to show the picture.
+ *
+ * The point is the same as the video module's, applied to a different signal:
+ * reveal when pixels are ready, not when bytes arrived. `load` fires *before*
+ * decode, so fading on it can start against an undecoded bitmap and hitch.
+ * `HTMLImageElement.decode()` resolves when the image is actually paintable,
+ * which is the image analogue of requestVideoFrameCallback.
+ *
+ * Reduced motion is handled entirely in image.css: the image still reveals, it
+ * just does so instantly. No JS gate, because "show the picture without
+ * animating" is a pure styling concern.
+ */
+
+import { POLITE_IMAGE_READY, type PoliteImageEventDetail } from './events.js';
+import { resolveTargets, type Target } from './targets.js';
+
+/** Anything that names one or more images. See {@link Target}. */
+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.
+   */
+  allowEager?: boolean;
+}
+
+const READY = 'data-polite-ready';
+
+function markReady(image: HTMLImageElement): void {
+  image.setAttribute(READY, '');
+  image.dispatchEvent(
+    new CustomEvent<PoliteImageEventDetail>(POLITE_IMAGE_READY, {
+      bubbles: true,
+      detail: { 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.
+ */
+const managed = new WeakSet<HTMLImageElement>();
+
+let unmanagedCheck: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * The failsafe in image.css keeps a stray image from vanishing, but silently.
+ * This is the half a developer can act on: it names the element and says which
+ * of the two mistakes was made.
+ *
+ * Debounced rather than run per call, because several `revealImages()` calls
+ * with different selectors are a normal way to set a page up and an image is
+ * only stray once all of them have had their chance. Rescheduling also means a
+ * client-side navigation gets its own check instead of one per page lifetime,
+ * which a once-only flag would have given.
+ */
+function scheduleUnmanagedCheck(): void {
+  clearTimeout(unmanagedCheck);
+  unmanagedCheck = setTimeout(() => {
+    for (const image of document.querySelectorAll<HTMLImageElement>('img[data-polite-reveal]')) {
+      if (managed.has(image)) continue;
+      console.warn(
+        'polite-media: no revealImages() call manages this image, so the failsafe revealed ' +
+          'it late and unfaded. Widen the selector, or drop data-polite-reveal.',
+        image
+      );
+      return;
+    }
+  }, 1000);
+}
+
+/**
+ * Reveals each matching image once it has decoded.
+ *
+ * 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: ImageTarget, options: RevealImagesOptions = {}): () => void {
+  const controller = new AbortController();
+  const { signal } = controller;
+
+  scheduleUnmanagedCheck();
+
+  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.
+    //
+    // 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') {
+      markReady(image);
+      continue;
+    }
+
+    // A cached image is frequently already decoded before this module runs at
+    // all -- these are deferred scripts. Revealing on the next frame rather than
+    // synchronously lets the browser paint the hidden state first, so the
+    // transition still runs instead of snapping.
+    if (image.complete && image.naturalWidth > 0) {
+      requestAnimationFrame(() => {
+        if (!signal.aborted) markReady(image);
+      });
+      continue;
+    }
+
+    image
+      .decode()
+      .then(() => {
+        if (!signal.aborted) markReady(image);
+      })
+      .catch(() => {
+        // decode() rejects with EncodingError when `src` changes mid-flight,
+        // which a responsive `srcset` genuinely does on resize, and on a real
+        // decode failure. Either way the image must not be left hidden: `load`
+        // is the weaker signal, and no reveal at all is worse than an early one.
+        if (signal.aborted) return;
+        if (image.complete) {
+          markReady(image);
+          return;
+        }
+        image.addEventListener('load', () => markReady(image), { once: true, signal });
+        image.addEventListener('error', () => markReady(image), { once: true, signal });
+      });
+  }
+
+  return () => controller.abort();
+}
+
+// Re-exported so `polite-media/image` carries the ElementEventMap and
+// DocumentEventMap augmentation too: it only reaches a consumer whose program
+// includes the module that declares it.
+export { POLITE_IMAGE_READY, type PoliteImageEventDetail } from './events.js';

package/src/layer.css

@@ -0,0 +1,60 @@
+/*
+ * polite-media/layer.css -- optional stylesheet, and the only one that touches
+ * layout.
+ *
+ * video.css owns *when* the swap happens and deliberately owns no geometry, so
+ * that the package drops into any design at any size. That left one thing every
+ * consumer has to write for themselves: stacking the poster and the video in the
+ * same box. Both of this project's first two consumers wrote the same five
+ * declarations, twice each, and both then reimplemented video.css wholesale
+ * rather than import it, because adding `z-index` to those elements felt like
+ * taking ownership of the file.
+ *
+ * So this is the standard stack, opt-in. Import it and write only what is
+ * genuinely yours:
+ *
+ *   import 'polite-media/video.css';
+ *   import 'polite-media/layer.css';
+ *
+ *   .hero__video { z-index: -2; }   <-- yours: this sits behind a scrim
+ *
+ * Skip it and nothing changes: the package still imposes no geometry on anyone
+ * who has their own arrangement, and `object-fit: cover` stays a choice you made
+ * rather than one made for you.
+ *
+ * The box needs a size of its own. This positions the media inside it and says
+ * nothing about how tall it is, which is still the host's decision: an
+ * aspect-ratio, a fixed height, a grid cell.
+ */
+
+[data-polite-media] {
+  position: relative;
+}
+
+/*
+ * The image is positioned, never the `<picture>` around it.
+ *
+ * Two reasons, both learned the hard way against a real page. A `<picture>` is
+ * commonly `display: contents`, which generates no box at all, so positioning it
+ * does nothing and the image's `height: 100%` has no definite containing block
+ * to resolve against: it silently falls back to `auto` and letterboxes. And
+ * forcing `display: contents` here to normalise that would be worse than the
+ * bug, since browsers drop such elements from the accessibility tree, taking the
+ * poster's `alt` with them.
+ *
+ * Positioning the image instead works for both shapes without caring: an
+ * absolutely positioned element resolves against its nearest *positioned*
+ * ancestor, skipping a static or box-less `<picture>` to land on the container
+ * above.
+ *
+ * object-fit needs the image for its own reason: it "Applies to: replaced
+ * elements", and a `<picture>` is a container rather than one.
+ */
+[data-polite-media] > :is(img, video),
+[data-polite-media] > picture > img {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}

package/src/reveal.ts

@@ -0,0 +1,75 @@
+/**
+ * The library's core primitive: fire once a frame has genuinely reached the
+ * compositor.
+ *
+ * The obvious signal, the `playing` event, is wrong -- and measurably wrong in
+ * both directions rather than merely early. On one machine in one run
+ * H.264 presented its first frame 1.6 ms *before* `playing`,
+ * while AV1 presented 0.8 ms *after*. So revealing on `playing` either flashes
+ * (poster removed before anything painted) or lingers (poster held over a frame
+ * that already painted), and which one you get depends on the codec, so no delay
+ * can tune it away.
+ *
+ * `requestVideoFrameCallback` is specified in terms of a frame being sent to the
+ * compositor, making it correct by definition rather than by timing.
+ */
+
+/**
+ * `HTMLMediaElement.HAVE_CURRENT_DATA`. Inlined rather than read off the global
+ * so this module never touches `HTMLMediaElement`, which does not exist in Node.
+ */
+const HAVE_CURRENT_DATA = 2;
+
+/**
+ * Calls `onPainted` once, when a frame is on screen.
+ *
+ * Returns a cancel function. Cancelling matters: a video can be unregistered
+ * (scrolled out of view, a router navigation) before its first frame ever
+ * arrives, and a reveal firing afterwards would un-hide a layer whose element is
+ * already gone.
+ *
+ * Cancellation does two things on the two rungs that can still be pending. The
+ * `done` flag is the correctness guarantee, so `cancel()` means "will not fire"
+ * however the underlying mechanism behaves; the platform call beside it
+ * (`cancelVideoFrameCallback`, `removeEventListener`) is resource release. They
+ * overlap on the `loadeddata` rung, where removing the listener would be enough
+ * on its own -- the price of `cancel()` meaning one thing rather than three
+ * subtly different things. On the `readyState` rung there is nothing to cancel:
+ * it has already fired synchronously by the time the caller holds the function.
+ */
+export function revealWhenPainted(video: HTMLVideoElement, onPainted: () => void): () => void {
+  let done = false;
+  const fire = (): void => {
+    if (done) return;
+    done = true;
+    onPainted();
+  };
+
+  // lib.dom declares requestVideoFrameCallback as always present, but it is only
+  // Baseline as of October 2024, so the types are more optimistic than reality
+  // and the runtime check is doing real work on older browsers.
+  if (typeof video.requestVideoFrameCallback === 'function') {
+    const handle = video.requestVideoFrameCallback(fire);
+    return () => {
+      done = true;
+      video.cancelVideoFrameCallback(handle);
+    };
+  }
+
+  // Both fallbacks are strictly weaker signals. HAVE_CURRENT_DATA means "data
+  // exists for the current playback position", which is a decode-side fact and
+  // says nothing about whether pixels have been presented. Accepted only because
+  // the alternative on these browsers is no reveal at all.
+  if (video.readyState >= HAVE_CURRENT_DATA) {
+    fire();
+    return () => {
+      done = true;
+    };
+  }
+
+  video.addEventListener('loadeddata', fire, { once: true });
+  return () => {
+    done = true;
+    video.removeEventListener('loadeddata', fire);
+  };
+}

package/src/sources.ts

@@ -0,0 +1,164 @@
+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: MediaError | null): boolean {
+  if (!error) return false;
+  return error.code === MEDIA_ERR_DECODE || error.code === MEDIA_ERR_SRC_NOT_SUPPORTED;
+}
+
+export interface SourceManager {
+  /** Loads the best remaining candidate. False when none are left to try. */
+  select(): boolean;
+  /** Discards the current candidate and loads the next. False when exhausted. */
+  advance(): boolean;
+}
+
+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: HTMLVideoElement): { declared: number; playable: string[] } {
+  // `:scope >` so a <source> belonging to some nested media element is never
+  // mistaken for this one's.
+  const sources = [...video.querySelectorAll<HTMLSourceElement>(':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: HTMLVideoElement): void {
+  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: HTMLVideoElement): SourceManager {
+  const { declared, playable: candidates } = candidatesFor(video);
+  let index = -1;
+
+  const load = (): boolean => {
+    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(): boolean {
+      // "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(): boolean {
+      index += 1;
+      return load();
+    },
+  };
+}
+
+/** Internal reset for tests. Not exported from the package entry point. */
+export function resetSourceWarnings(): void {
+  warnedMediaGap = false;
+}