polite-media 0.3.0

package/dist/coordinator.d.ts

@@ -0,0 +1,231 @@
+import { type Target } from './targets.js';
+/**
+ * @module
+ * The single arbiter of what plays. Nothing outside this module calls `play()`
+ * or `pause()`, so "why is this video running" always has one answer.
+ *
+ * The `@module` tag matters: without it TypeScript attaches this preamble to the
+ * first declaration below, and a consumer hovering that symbol gets a sentence
+ * about internal call discipline instead of its own documentation.
+ */
+/**
+ * Deliberately three cases rather than a number. These are the ones that exist,
+ * the type system does the checking a bare `number` would invite (`0.5`), and it
+ * avoids inventing an answer to which of several incumbents a rival displaces --
+ * the incumbent's hysteresis has clean semantics only for a single slot.
+ */
+export type AtOnce = 0 | 1 | 'all';
+/**
+ * How patient a video is about starting, as a genuine ladder: each value waits
+ * for everything the one before it did, and then something more.
+ *
+ * Buffering is deliberately not a fourth value here. It is a different question
+ * and lives on {@link ConfigureOptions.requireBuffered}, so the two compose.
+ */
+export type StartWhen = 'visible' | 'page-loaded' | 'interaction';
+/**
+ * Options for {@link configure}. Every field is optional; anything left out keeps
+ * its default.
+ *
+ * All-optional deliberately. As a fully required interface this could not be used
+ * for what a consumer naturally reaches for -- `const preset: ConfigureOptions =
+ * { atOnce: 0 }` -- and only the inline `configure({ ... })` form worked, via
+ * contextual typing.
+ */
+export interface ConfigureOptions {
+    /**
+     * How far outside the viewport a video starts buffering, so it is ready by the
+     * time it arrives. `'200px'` on a feed is the difference between a card that
+     * plays as it lands and one that shows its poster first.
+     *
+     * Defaults to `'0px'`: buffering video a visitor may never scroll to is the
+     * opposite of what this package is for, and on a twelve-card grid it would
+     * fetch twelve files.
+     *
+     * This drives a second observer of its own, and deliberately does not touch
+     * the thresholds. `intersectionRatio` is measured against the root *including*
+     * the margin, so a single observer made every threshold mean less than it
+     * said: measured on a 368px card at a 50px margin, 25% on screen reported 0.39
+     * and `pauseBelow: 0.25` actually stopped the video at about 10% visible, with
+     * the error scaling by element height. The observer that decides playback
+     * keeps no margin, so a fraction is always the true visible fraction.
+     */
+    prefetchMargin?: string;
+    /**
+     * Which viewports count as small. Configurable because 767px is one project's
+     * breakpoint, not a fact about phones.
+     */
+    smallViewport?: string;
+    /**
+     * How many videos may run at once.
+     *
+     * - `'all'` lets every visible video play. A bento grid of cards whose content
+     *   *is* the video is meant to move.
+     * - `1` gives one video the screen at a time, the rest holding their posters.
+     *   A feed wants this: the eye has one subject, and the handover happens as
+     *   the next card takes the slot.
+     * - `0` never starts a video, spending nothing on data or battery.
+     *
+     * Pass an object to split the answer by viewport, which is the default:
+     * `{ small: 1, large: 'all' }`. Phones have far less decode headroom than
+     * desktops -- three concurrent H.264 streams while compositing drops frames
+     * badly on real hardware -- so they arbitrate while a desktop does not.
+     * {@link ConfigureOptions.smallViewport} decides which side a viewport is on.
+     *
+     * No standards or platform source recommends any of these; the default is the
+     * one with device testing behind it.
+     */
+    atOnce?: AtOnce | {
+        small: AtOnce;
+        large: AtOnce;
+    };
+    /**
+     * Visible fraction, 0 to 1, at or below which a video stops.
+     *
+     * Defaults to `0.5`: a video runs while it is the thing you are looking at and
+     * stops once it is mostly gone. At `0` it stopped only when entirely off
+     * screen, so one hanging on by a sliver effectively never stopped.
+     *
+     * **This caps how tall a managed video can be.** `intersectionRatio` is a
+     * fraction of the *element*, and with no margin on the playback observer its
+     * ceiling is `viewport / height` -- so anything taller than twice the viewport
+     * can never reach `0.5` and would never play. Measured at a 953px viewport:
+     * 1.5x viewport height peaks at 0.667 and 3x at 0.333. Lower it for a tall
+     * video, or shorten the box.
+     */
+    pauseBelow?: number;
+    /**
+     * How patient a video is about starting. Each rung is strictly more patient
+     * than the last.
+     *
+     * - `'visible'` starts fetching the moment the video is on screen. Module
+     *   scripts are deferred, so on a real page that lands inside the tail of the
+     *   page's own loading and competes with it.
+     * - `'page-loaded'` waits for `window`'s `load` event first, so the video
+     *   competes with nothing the page still needs. The default.
+     * - `'interaction'` additionally waits for the visitor: the first
+     *   `pointerdown`, `keydown` or `scroll`.
+     *
+     * `'page-loaded'` is the default because a video that never plays reads as
+     * broken. It keeps the part that matters most: the fetch happens after `load`,
+     * so those bytes never compete with the page's own.
+     *
+     * **Reach for `'interaction'` when Largest Contentful Paint matters.** The
+     * browser stops updating LCP on "a tap, scroll, or keypress"
+     * (https://web.dev/articles/lcp), so a video revealed after that signal can
+     * never become the LCP element, and a synthetic audit, which never interacts,
+     * never starts it at all. The cost is a visitor who lands and never scrolls,
+     * taps or types: they see a still.
+     *
+     * Below the fold the choice barely matters, since a video down there cannot be
+     * seen without scrolling and scrolling is the interaction. It is a policy for
+     * whatever is on screen at load, which in practice means the hero.
+     *
+     * Two things compose with this rather than replacing it.
+     * {@link ConfigureOptions.requireBuffered} asks for data as well as patience,
+     * and `until` gates one video on your own promise while this is the policy for
+     * all of them. A video waits for every gate that applies to it.
+     */
+    startWhen?: StartWhen;
+    /**
+     * Hold playback until the video can play through without stalling.
+     *
+     * Separate from {@link ConfigureOptions.startWhen} because they answer
+     * different questions: that one is *when may it begin*, this one is *how much
+     * data first*. As a fourth `startWhen` value it competed with `'interaction'`,
+     * so "wait for the user, and also wait for the buffer" could not be said at
+     * all.
+     *
+     * Raises `preload` to `'auto'` when it prepares, which it has to: the markup
+     * contract says `preload="none"`, and a browser buffers nothing until playback
+     * is asked for, so waiting for `canplaythrough` without the promotion would
+     * wait forever.
+     */
+    requireBuffered?: boolean;
+}
+/**
+ * Call before the first `register`.
+ *
+ * `atOnce`, `startWhen` and `requireBuffered` are read on every reconcile, so
+ * they can be changed at any time and take effect on the next pass. The three
+ * keys in {@link CONSTRUCTION_TIME_KEYS} cannot, and throw if patched while
+ * videos are registered. Unregister everything first, or configure earlier.
+ */
+export declare function configure(patch: ConfigureOptions): void;
+export interface RegisterOptions {
+    /**
+     * Hold this video out of the arbiter's reach until the promise settles. A hero
+     * at scroll-top is reported visible in the observer's very first batch, so
+     * without a gate it starts before whatever the page is waiting on (a splash
+     * screen, a consent dialog) has finished.
+     */
+    until?: Promise<unknown>;
+    /**
+     * Element to observe instead of the video, for when the video is absolutely
+     * positioned inside a wrapper that carries the real layout box.
+     */
+    observe?: Element;
+    /**
+     * Override the page's {@link ConfigureOptions.startWhen} for this video.
+     *
+     * A page usually wants one policy, but not always: only a video that can be
+     * the LCP element needs the strictest gate, and holding a below-fold grid to
+     * the same rule buys nothing.
+     */
+    startWhen?: StartWhen;
+}
+export declare function reconcile(): void;
+/**
+ * Starts managing a video: reveals it on its first genuinely painted frame,
+ * plays it only while it is visible, falls through its `<source>` list when one
+ * cannot be decoded, and stops it when a gate closes.
+ *
+ * The video and its poster must already share a box carrying `data-polite-media`
+ * in the authored markup, and the video should be `muted loop playsinline
+ * preload="none"`. Calling this twice on the same element is a no-op.
+ *
+ * @param video the element to manage
+ * @param options see {@link RegisterOptions}
+ */
+export declare function register(video: HTMLVideoElement, options?: RegisterOptions): void;
+/** Anything that names one or more videos. See {@link Target}. */
+export type VideoTarget = Target<HTMLVideoElement>;
+/**
+ * Registers every video a target names, so the common case is one line and
+ * matches `revealImages` on the image side rather than being a second idea.
+ *
+ * `observe` is deliberately not accepted. Each observed element maps to exactly
+ * one entry, so handing the same wrapper to several videos would silently
+ * discard all but the last. Anything needing it, or a different gate per video,
+ * goes through {@link register} one at a time.
+ *
+ * Idempotent, because `register` is: safe to call on every navigation of a
+ * client-side router, where module scripts do not re-run.
+ */
+export declare function registerAll(target: VideoTarget, options?: Omit<RegisterOptions, 'observe'>): void;
+/**
+ * Stops managing a video and releases everything it owned: the observer entry,
+ * any pending pause timer, its listeners, and the page-level listeners once it
+ * was the last one. Safe to call for a video that was never registered.
+ */
+export declare function unregister(video: HTMLVideoElement): void;
+export declare function pauseAll(): void;
+/** Lets playback resume, undoing {@link pauseAll}. */
+export declare function resumeAll(): void;
+/**
+ * Releases every video, for a host tearing down the whole page. Configuration
+ * survives: it describes the page's setup rather than the videos currently on
+ * it, and a client-side router calling this per navigation would otherwise have
+ * its settings quietly reverted on the first swap. The once-per-page warnings do
+ * reset, because the markup they judge is about to be replaced.
+ */
+export declare function unregisterAll(): void;
+/** Internal reset for tests. Not exported from the package entry point. */
+export declare function resetForTests(): void;
+/** Internal view for tests. Not exported from the package entry point. */
+export declare function inspect(): {
+    tracked: number;
+    observing: boolean;
+    lifecycle: boolean;
+};
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/coordinator.d.ts.map

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