npm - @schalkneethling/css-media-pseudo-polyfill - Versions diffs - 1.0.2 - Mend

@schalkneethling/css-media-pseudo-polyfill 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE +21 -0
package/README.md +121 -0
package/dist/fn.d.mts +4 -0
package/dist/fn.mjs +2 -0
package/dist/index.d.mts +1 -0
package/dist/index.mjs +6 -0
package/dist/polyfill-BA69lY_2.mjs +503 -0
package/package.json +59 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Schalk Neethling
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,121 @@
+# css-media-pseudo-polyfill
+A CSS polyfill for the [media pseudo-classes](https://html.spec.whatwg.org/multipage/semantics-other.html#selector-muted): `:playing`, `:paused`, `:seeking`, `:buffering`, `:stalled`, and `:muted`.
+These pseudo-classes allow styling based on the playback, loading, and sound state of `<audio>` and `<video>` elements. Browser support is still incomplete — this polyfill detects which pseudo-classes the browser does not support and provides equivalent behavior via class selectors.
+## How it works
+The polyfill runs in four stages:
+1. **Feature detection** — Each of the 7 media pseudo-classes is tested individually via `CSS.supports('selector(:name)')`. Only unsupported pseudo-classes are polyfilled. This allows partial support (e.g., Safari may support `:playing` but not `:buffering`).
+2. **CSS rewriting** — Inline `<style>` elements are parsed with [css-tree](https://github.com/nicolo-ribaudo/css-tree). For each rule containing a target pseudo-class, a class-based equivalent is injected as a sibling rule immediately after the original in the AST (e.g., `video:playing { ... }` is followed by `video.media-pseudo-polyfill-playing { ... }`). The browser skips the rule it doesn't understand and applies the class-based fallback — a natural progressive enhancement pair.
+3. **`<link>` stylesheet rewriting** — Same-origin `<link rel="stylesheet">` elements are fetched via the Fetch API and rewritten using the same text-based approach as inline `<style>` elements. The rewritten CSS is injected as a sibling `<style>` element and the original `<link>` is disabled. This avoids the CSSOM approach where browsers silently drop rules containing unrecognised pseudo-class selectors before the polyfill can process them. Cross-origin stylesheets are detected via origin comparison and skipped.
+4. **Element observation** — Media elements are discovered via `querySelectorAll` and a `MutationObserver`. Event listeners are attached to each element to track state changes. On every relevant event, the element's state is recomputed and the corresponding polyfill classes are toggled.
+## Entry points
+| Export          | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| `"."` (default) | Auto-applies the polyfill on `DOMContentLoaded`         |
+| `"./fn"`        | Exports the `polyfill()` function for manual invocation |
+The `"./fn"` entry point is useful when you need to run the polyfill earlier (e.g., from a synchronous `<script>` in `<head>`) to minimize the flash of unstyled content (FOUC).
+## Spec references
+The pseudo-class definitions and their DOM conditions come from the [WHATWG HTML spec](https://html.spec.whatwg.org/multipage/semantics-other.html#selector-muted):
+| Pseudo-class     | DOM condition                                                                    |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `:playing`       | `paused === false`                                                               |
+| `:paused`        | `paused === true`                                                                |
+| `:seeking`       | `seeking === true`                                                               |
+| `:buffering`     | `!paused && networkState === NETWORK_LOADING && readyState <= HAVE_CURRENT_DATA` |
+| `:stalled`       | matches `:buffering` AND the internal "is currently stalled" flag is `true`      |
+| `:muted`         | `muted === true`                                                                 |
+| `:volume-locked` | Not polyfillable (no DOM surface)                                                |
+The `NETWORK_LOADING`, `HAVE_CURRENT_DATA`, and other constants are defined on the [HTMLMediaElement interface](https://html.spec.whatwg.org/multipage/media.html#htmlmediaelement) as `const unsigned short` values. They are available as both static and instance properties.
+## Design decisions
+### Per-pseudo-class detection
+Rather than a single feature check, each pseudo-class is tested individually. Safari has partial support — it may implement some pseudo-classes but not others. Per-pseudo-class detection allows the polyfill to skip already-supported pseudo-classes and only rewrite and manage the unsupported ones. If `CSS.supports` is unavailable or throws, the pseudo-class is treated as unsupported.
+### Immediate-sibling injection for cascade preservation
+For each rule containing a target pseudo-class, the polyfill inserts a class-based equivalent as a sibling rule immediately after the original in the AST. The original stylesheet is left untouched. This produces pairs like:
+```css
+video:playing {
+  outline: 0.25rem solid green;
+}
+video.media-pseudo-polyfill-playing {
+  outline: 0.25rem solid green;
+}
+```
+Two alternative approaches were considered and rejected:
+- **Clone-and-disable** (clone the entire AST, disable the original stylesheet): unnecessarily complex. Because the polyfill class is only present when the state is active, the injected rule is inert when the state doesn't apply — it cannot interfere with other rules regardless of source order. This is fundamentally different from attribute-based polyfills (e.g., container queries) where rewritten selectors match unconditionally.
+- **Extract-and-append** (extract only rewritten rules, append to end): incorrect. Moving rules out of their `@layer`, `@media`, or `@supports` context would break the author's cascade intent.
+Immediate-sibling injection keeps each rewritten rule inside the same block as its original, preserving `@layer`, `@media`, and `@supports` nesting with no special logic.
+### Specificity-neutral substitution
+The polyfill replaces `PseudoClassSelector` nodes (specificity 0,1,0) with `ClassSelector` nodes (also 0,1,0). This substitution is specificity-neutral in all contexts — including inside `:is()` (which uses the most specific argument's specificity), `:where()` (which zeroes everything), and `:has()` (which contributes the argument's specificity). No `:where()` wrapping is needed.
+### `:volume-locked` handling
+`:volume-locked` cannot be polyfilled because the "volume locked" flag is a user-agent-level boolean with no DOM surface. The polyfill handles it as follows to prevent broken stylesheets:
+- **Lone selector** (`video:volume-locked { ... }`): the entire rule is removed
+- **In a selector list** (`video:playing, video:volume-locked { ... }`): the `:volume-locked` branch is pruned; the `:playing` branch is rewritten normally
+- **Inside `:is()` / `:where()`**: the `:volume-locked` argument is removed from the list
+- **Inside `:not()`**: rewritten to `.media-pseudo-polyfill-volume-locked` (matches everything, since the class is never set — consistent behavior)
+### Pure state computation with externally managed stalled flag
+The `computeStates()` function is pure — it reads properties from an `HTMLMediaElement` and returns a `Set<string>` of active states. The "is currently stalled" flag is passed in as a parameter rather than being computed internally because this flag is not directly observable from DOM properties. It must be tracked via the formal state machine defined in the [HTML spec](https://html.spec.whatwg.org/multipage/media.html#concept-media-load-resource):
+- Set to `true` when the `stalled` event fires (browser's ~3 second stall timeout expired)
+- Reset to `false` when `progress`, `emptied`, or `loadstart` fires
+This separation keeps `computeStates()` easily testable with plain objects.
+### WeakMap for per-element state
+Per-element state (event handler reference and stalled flag) is stored in a `WeakMap<HTMLMediaElement, ElementState>`. The `MutationObserver` callback explicitly cleans up when elements are removed from the DOM. The `WeakMap` acts as a safety net — if cleanup is missed (e.g., observer disconnected, edge case in DOM reparenting), the garbage collector can still reclaim the element and its associated state. A regular `Map` would hold a strong reference to the element key, preventing collection. On pages with many dynamic video elements (e.g., YouTube feed with preview hovers), this prevents memory leaks.
+### Single event handler per element
+Media events do not bubble, so each element requires direct `addEventListener` calls. Rather than creating 14 separate handler functions per element, a single handler is created and registered for all 14 event types. The handler uses `event.type` in a switch statement to handle special cases (stalled flag transitions) before recomputing state. This means 14 registrations per element (unavoidable) but only 1 function object allocated per element — on a page with 20 videos, that is 20 function objects instead of 280.
+### Bind-once guard
+Before attaching listeners, the polyfill checks whether the element is already tracked in the `WeakMap`. This prevents duplicate bindings from rapid DOM reparenting, where the `MutationObserver` may report the same element in both `removedNodes` and `addedNodes` in a single batch.
+### Fetch-based rewriting for `<link>` stylesheets
+Same-origin `<link rel="stylesheet">` elements are rewritten by fetching the CSS text and running it through the same `rewriteCss()` function used for inline `<style>` elements. The rewritten output is injected as a `<style>` element immediately after the original `<link>`, which is then disabled.
+An earlier approach used the CSSOM API (`sheet.cssRules` + `insertRule()`), which avoids an extra network request. However, this has a fundamental flaw: browsers silently drop rules containing unrecognised pseudo-class selectors during CSS parsing. By the time the polyfill walks the CSSOM, the rules it needs to rewrite have already been discarded. The fetch-based approach accesses the raw CSS text before browser parsing, ensuring all rules are available for rewriting.
+Cross-origin stylesheets are detected via `new URL(href).origin` comparison against `window.location.origin` and skipped. This covers both relative paths (resolved to absolute by the browser) and explicit absolute URLs to external CDNs.
+## Known limitations
+- **`:volume-locked` is not polyfillable.** The "volume locked" flag has no DOM surface. The polyfill removes `:volume-locked` selectors from rewritten stylesheets and never sets the corresponding class.
+- **Class selectors can match non-media elements.** Native `:playing` only matches `<audio>` and `<video>` elements. The polyfilled `.media-pseudo-polyfill-playing` class has no such restriction. In practice this is not an issue because the polyfill only ever toggles these classes on media elements. An author would need to manually add the class to a non-media element to trigger a false positive.
+- **FOUC window.** Stylesheet rewriting runs when the polyfill is invoked (at `DOMContentLoaded` for the default entry point). There is a window between first paint and polyfill initialization where pseudo-class-based styles are not applied. Use the `"./fn"` entry point from a synchronous `<script>` in `<head>` to minimize this gap.
+- **Cross-origin `<link>` stylesheets are not rewritten.** The polyfill only fetches and rewrites same-origin stylesheets. Cross-origin sheets served from external CDNs are skipped.

package/dist/fn.d.mts ADDED Viewed

@@ -0,0 +1,4 @@
+//#region src/polyfill.d.ts
+declare function polyfill(): void;
+//#endregion
+export { polyfill };

package/dist/fn.mjs ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { t as polyfill } from "./polyfill-BA69lY_2.mjs";
2	+ export { polyfill };

package/dist/index.d.mts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export { };

package/dist/index.mjs ADDED Viewed

@@ -0,0 +1,6 @@
+import { t as polyfill } from "./polyfill-BA69lY_2.mjs";
+//#region src/index.ts
+if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", () => polyfill());
+else polyfill();
+//#endregion
+export {};

package/dist/polyfill-BA69lY_2.mjs ADDED Viewed

@@ -0,0 +1,503 @@
+import { clone, generate, parse, walk } from "css-tree";
+//#region src/constants.ts
+const PSEUDO_CLASSES = [
+	"playing",
+	"paused",
+	"seeking",
+	"buffering",
+	"stalled",
+	"muted",
+	"volume-locked"
+];
+const CLASS_PREFIX = "media-pseudo-polyfill-";
+const MEDIA_EVENTS = [
+	"play",
+	"playing",
+	"pause",
+	"ended",
+	"seeking",
+	"seeked",
+	"waiting",
+	"canplay",
+	"canplaythrough",
+	"stalled",
+	"progress",
+	"volumechange",
+	"emptied",
+	"loadstart"
+];
+//#endregion
+//#region src/rewrite.ts
+/**
+* Rewrite CSS text using immediate-sibling injection. For each rule containing
+* an unsupported media pseudo-class selector, a class-based equivalent is
+* inserted as a sibling rule immediately after the original. The original rules
+* are preserved — the browser silently skips rules it does not understand and
+* applies the class-based fallback. Returns null if no rewrites occurred.
+*/
+function rewriteCss(cssText, unsupported) {
+	const ast = parse(cssText);
+	let rewrote = false;
+	injectSiblingRules(ast, unsupported, (didRewrite) => {
+		if (didRewrite) rewrote = true;
+	});
+	if (!rewrote) return null;
+	const output = generate(ast);
+	if (!output.trim()) return null;
+	return output;
+}
+/**
+* Walk the AST looking for Rule nodes that contain target pseudo-classes.
+* For each match, clone the rule, rewrite selectors in the clone, and
+* insert the clone immediately after the original in the parent list.
+*/
+function injectSiblingRules(ast, unsupported, onRewrite) {
+	const rulesToProcess = [];
+	walk(ast, {
+		visit: "Rule",
+		enter(node, item, list) {
+			if (containsTargetPseudoClass(node, unsupported)) rulesToProcess.push({
+				rule: node,
+				item,
+				list
+			});
+		}
+	});
+	for (const { rule, item, list } of rulesToProcess) {
+		const cloned = clone(rule);
+		const prelude = cloned.prelude;
+		if (prelude.type !== "SelectorList") continue;
+		if (!rewriteSelectorList(prelude, unsupported)) continue;
+		if (prelude.children.isEmpty) continue;
+		const newItem = list.createItem(cloned);
+		if (item.next) list.insert(newItem, item.next);
+		else list.appendData(cloned);
+		onRewrite(true);
+	}
+}
+/**
+* Check whether a CSS node contains any target pseudo-class selectors.
+*/
+function containsTargetPseudoClass(node, unsupported) {
+	let found = false;
+	walk(node, {
+		visit: "PseudoClassSelector",
+		enter(pseudoNode) {
+			if (unsupported.has(pseudoNode.name)) {
+				found = true;
+				return this.break;
+			}
+		}
+	});
+	return found;
+}
+/**
+* Rewrite pseudo-class selectors to class selectors in a SelectorList node,
+* mutating it in place. Handles :volume-locked pruning and :not() rewriting.
+* Returns whether any rewrites occurred.
+*
+* Used by both the <style> text rewriting path and the <link> CSSOM path.
+*/
+function rewriteSelectorList(selectorList, unsupported) {
+	let rewrote = false;
+	walk(selectorList, {
+		visit: "PseudoClassSelector",
+		enter(node, pseudoItem, pseudoList) {
+			if (!unsupported.has(node.name)) return;
+			if (node.name === "volume-locked") return;
+			rewrote = true;
+			const replacement = pseudoList.createItem({
+				type: "ClassSelector",
+				name: `${CLASS_PREFIX}${node.name}`,
+				loc: node.loc
+			});
+			pseudoList.replace(pseudoItem, replacement);
+		}
+	});
+	if (unsupported.has("volume-locked")) {
+		if (handleVolumeLocked(selectorList)) rewrote = true;
+	}
+	return rewrote;
+}
+/**
+* Handle :volume-locked pseudo-class in a selector list. Although unpolyfillable,
+* it cannot be left as-is in the sibling rule: in a comma-separated selector
+* list, one invalid selector causes the browser to discard the entire rule —
+* breaking sibling selectors that were successfully rewritten.
+*
+* - In a selector list → prune the :volume-locked branch
+* - Lone selector → list becomes empty (caller skips injection)
+* - Inside :is()/:where() → prune from argument list
+* - Inside :not() → rewrite to class selector (matches everything, consistent)
+*/
+function handleVolumeLocked(selectorList) {
+	let rewrote = false;
+	walk(selectorList, {
+		visit: "PseudoClassSelector",
+		enter(node) {
+			if (node.name !== "not" || !node.children) return;
+			walk(node, {
+				visit: "PseudoClassSelector",
+				enter(inner, innerItem, innerList) {
+					if (inner.name !== "volume-locked") return;
+					rewrote = true;
+					const replacement = innerList.createItem({
+						type: "ClassSelector",
+						name: `${CLASS_PREFIX}volume-locked`,
+						loc: inner.loc
+					});
+					innerList.replace(innerItem, replacement);
+				}
+			});
+		}
+	});
+	walk(selectorList, {
+		visit: "PseudoClassSelector",
+		enter(node) {
+			if (node.name !== "is" && node.name !== "where") return;
+			if (!node.children) return;
+			const nestedSelectorList = node.children.first;
+			if (nestedSelectorList?.type === "SelectorList") {
+				if (pruneSelectorsWithVolumeLocked(nestedSelectorList)) rewrote = true;
+			}
+		}
+	});
+	if (pruneSelectorsWithVolumeLocked(selectorList)) rewrote = true;
+	return rewrote;
+}
+function containsVolumeLocked(node) {
+	let found = false;
+	walk(node, {
+		visit: "PseudoClassSelector",
+		enter(node) {
+			if (node.name === "volume-locked") {
+				found = true;
+				return this.break;
+			}
+		}
+	});
+	return found;
+}
+function pruneSelectorsWithVolumeLocked(selectorList) {
+	const toRemove = [];
+	selectorList.children.forEach((selector, selectorItem) => {
+		if (containsVolumeLocked(selector)) toRemove.push(selectorItem);
+	});
+	for (const selectorItem of toRemove) selectorList.children.remove(selectorItem);
+	return toRemove.length > 0;
+}
+/**
+* Process a single inline <style> element.
+* If it contains target pseudo-classes, replaces its content
+* with the rewritten CSS (originals plus class-based siblings).
+*/
+function rewriteSingleStyleElement(style, unsupported) {
+	const cssText = style.textContent;
+	if (!cssText) return;
+	const rewritten = rewriteCss(cssText, unsupported);
+	if (rewritten === null) return;
+	style.textContent = rewritten;
+	style.setAttribute("data-polyfill-rewritten", "");
+}
+/**
+* Process all inline <style> elements in the document.
+* For each that contains target pseudo-classes, replaces its content
+* with the rewritten CSS (originals plus class-based siblings).
+*/
+function rewriteStyleElements(unsupported) {
+	const styles = document.querySelectorAll("style:not([data-polyfill-rewritten])");
+	for (const style of styles) rewriteSingleStyleElement(style, unsupported);
+}
+//#endregion
+//#region src/rewrite-link.ts
+/**
+* Check whether a stylesheet URL is same-origin. The browser resolves
+* relative hrefs to absolute URLs on the HTMLLinkElement.href property,
+* so comparing the origin portion covers both relative paths and
+* absolute same-origin URLs while filtering out external CDN links.
+*/
+function isSameOrigin(href) {
+	try {
+		return new URL(href).origin === window.location.origin;
+	} catch {
+		return false;
+	}
+}
+/**
+* Fetch CSS text from a linked stylesheet, rewrite unsupported media
+* pseudo-classes to class-based selectors using the same text-based
+* sibling-injection strategy as inline <style> elements, then inject
+* the rewritten CSS as a <style> element and disable the original link.
+*
+* This avoids the CSSOM approach where the browser silently drops rules
+* with unrecognised pseudo-class selectors before the polyfill can
+* process them.
+*/
+async function processLinkSheet(link, unsupported) {
+	if (link.hasAttribute("data-polyfill-rewritten")) return;
+	const href = link.href;
+	if (!href || !isSameOrigin(href)) return;
+	let cssText;
+	try {
+		cssText = await (await fetch(href)).text();
+	} catch {
+		return;
+	}
+	const rewritten = rewriteCss(cssText, unsupported);
+	link.setAttribute("data-polyfill-rewritten", "");
+	if (rewritten === null) return;
+	const style = document.createElement("style");
+	style.textContent = rewritten;
+	style.setAttribute("data-polyfill-rewritten", "");
+	link.after(style);
+	link.disabled = true;
+}
+/**
+* Process all <link rel="stylesheet"> elements in the document.
+* For each same-origin link, fetches the CSS text, rewrites it, and
+* injects the result as a sibling <style> element.
+*
+* @param unsupported - The set of pseudo-class names that need polyfilling.
+*/
+function rewriteLinkStylesheets(unsupported) {
+	const links = document.querySelectorAll("link[rel=\"stylesheet\"]:not([data-polyfill-rewritten])");
+	for (const link of links) processLinkSheet(link, unsupported);
+}
+//#endregion
+//#region src/state.ts
+/**
+* Computes the current set of pseudo-class states for a media element
+* based on its playback, network, and user-interaction properties.
+*
+* @param element - The media element to inspect.
+* @param isStalledFlag - Whether a `stalled` event has fired since the last
+*   `progress` event, indicating the browser has not received new data.
+* @returns A set of pseudo-class name strings (e.g. "paused", "playing",
+*   "buffering", "stalled", "seeking", "muted") derived from the element's
+*   properties at the time of the call.
+*/
+function computeStates(element, isStalledFlag) {
+	const states = /* @__PURE__ */ new Set();
+	if (element.paused) states.add("paused");
+	else {
+		states.add("playing");
+		if (element.networkState === element.NETWORK_LOADING && element.readyState <= element.HAVE_CURRENT_DATA) {
+			states.add("buffering");
+			if (isStalledFlag) states.add("stalled");
+		}
+	}
+	if (element.seeking) states.add("seeking");
+	if (element.muted) states.add("muted");
+	return states;
+}
+//#endregion
+//#region src/observe.ts
+const elementStates = /* @__PURE__ */ new WeakMap();
+function isMediaElement(node) {
+	const tagName = node.tagName;
+	return tagName === "VIDEO" || tagName === "AUDIO";
+}
+function computeAndApply(element, unsupported) {
+	const state = elementStates.get(element);
+	if (!state) return;
+	const activeStates = computeStates(element, state.isCurrentlyStalled);
+	for (const name of PSEUDO_CLASSES) {
+		if (!unsupported.has(name)) continue;
+		const className = `${CLASS_PREFIX}${name}`;
+		element.classList.toggle(className, activeStates.has(name));
+	}
+}
+function attachListeners(element, unsupported) {
+	if (elementStates.has(element)) return;
+	const state = {
+		handler: () => {},
+		isCurrentlyStalled: false
+	};
+	const handler = (event) => {
+		switch (event.type) {
+			case "stalled":
+				state.isCurrentlyStalled = true;
+				break;
+			case "progress":
+			case "emptied":
+			case "loadstart":
+				state.isCurrentlyStalled = false;
+				break;
+		}
+		computeAndApply(element, unsupported);
+	};
+	state.handler = handler;
+	elementStates.set(element, state);
+	for (const eventType of MEDIA_EVENTS) element.addEventListener(eventType, handler);
+	computeAndApply(element, unsupported);
+}
+function detachListeners(element) {
+	const state = elementStates.get(element);
+	if (!state) return;
+	for (const eventType of MEDIA_EVENTS) element.removeEventListener(eventType, state.handler);
+	elementStates.delete(element);
+}
+function discoverMediaElements(node, unsupported) {
+	if (isMediaElement(node)) attachListeners(node, unsupported);
+	if (node.nodeType === 1) {
+		const mediaElements = node.querySelectorAll("audio, video");
+		for (const mediaElement of mediaElements) attachListeners(mediaElement, unsupported);
+	}
+}
+function cleanupMediaElements(node) {
+	if (isMediaElement(node)) detachListeners(node);
+	if (node.nodeType === 1) {
+		const mediaElements = node.querySelectorAll("audio, video");
+		for (const mediaElement of mediaElements) detachListeners(mediaElement);
+	}
+}
+/**
+* Discovers media elements in the DOM, attaches event listeners, and
+* toggles polyfill classes based on computed state. Sets up a
+* MutationObserver to handle dynamically added and removed elements.
+*
+* @param unsupported - The set of pseudo-class names that need polyfilling.
+*/
+function observeMediaElements(unsupported) {
+	const existingElements = document.querySelectorAll("audio, video");
+	for (const element of existingElements) attachListeners(element, unsupported);
+	new MutationObserver((mutations) => {
+		for (const mutation of mutations) {
+			for (const addedNode of mutation.addedNodes) discoverMediaElements(addedNode, unsupported);
+			for (const removedNode of mutation.removedNodes) cleanupMediaElements(removedNode);
+		}
+	}).observe(document.documentElement, {
+		childList: true,
+		subtree: true
+	});
+}
+//#endregion
+//#region src/observe-stylesheets.ts
+/**
+* Tracks <style> elements currently being rewritten by the polyfill.
+* Used to distinguish polyfill-initiated textContent changes from
+* author-initiated ones, preventing infinite mutation loops.
+*/
+const rewritingInProgress = /* @__PURE__ */ new WeakSet();
+/**
+* Check whether a node is an Element (nodeType 1).
+*/
+function isElement(node) {
+	return node.nodeType === 1;
+}
+/**
+* Check whether an element is a <style> element.
+*/
+function isStyleElement(element) {
+	return element.tagName === "STYLE";
+}
+/**
+* Check whether an element is a <link rel="stylesheet">.
+*/
+function isStylesheetLink(element) {
+	return element.tagName === "LINK" && element.getAttribute("rel") === "stylesheet";
+}
+/**
+* Rewrite a <style> element, guarding against mutation loops via the
+* rewritingInProgress WeakSet.
+*/
+function rewriteStyleWithGuard(style, unsupported) {
+	rewritingInProgress.add(style);
+	rewriteSingleStyleElement(style, unsupported);
+}
+/**
+* Process a single added node: if it is (or contains) stylesheet elements,
+* rewrite them.
+*/
+function processAddedNode(node, unsupported) {
+	if (!isElement(node)) return;
+	if (isStyleElement(node) && !node.hasAttribute("data-polyfill-rewritten")) rewriteStyleWithGuard(node, unsupported);
+	else if (isStylesheetLink(node) && !node.hasAttribute("data-polyfill-rewritten")) processLinkElement(node, unsupported);
+	for (const style of node.querySelectorAll("style:not([data-polyfill-rewritten])")) rewriteStyleWithGuard(style, unsupported);
+	for (const link of node.querySelectorAll("link[rel=\"stylesheet\"]:not([data-polyfill-rewritten])")) processLinkElement(link, unsupported);
+}
+/**
+* Handle a childList mutation whose target is a <style> element.
+* This fires when textContent is replaced (old Text child removed, new added).
+*/
+function handleStyleChildListMutation(style, unsupported) {
+	if (rewritingInProgress.has(style)) {
+		rewritingInProgress.delete(style);
+		return;
+	}
+	style.removeAttribute("data-polyfill-rewritten");
+	rewriteStyleWithGuard(style, unsupported);
+}
+/**
+* Handle a characterData mutation on a text node inside a <style> element.
+* This fires when the author modifies the text node directly
+* (e.g., style.firstChild.data = "...").
+*/
+function handleCharacterDataMutation(target, unsupported) {
+	const parent = target.parentElement;
+	if (!parent || !isStyleElement(parent)) return;
+	if (rewritingInProgress.has(parent)) {
+		rewritingInProgress.delete(parent);
+		return;
+	}
+	parent.removeAttribute("data-polyfill-rewritten");
+	rewriteStyleWithGuard(parent, unsupported);
+}
+/**
+* Process a <link rel="stylesheet"> element. processLinkSheet handles
+* fetching the CSS text directly, so no load-event deferral is needed.
+*/
+function processLinkElement(link, unsupported) {
+	processLinkSheet(link, unsupported);
+}
+/**
+* Observe the DOM for dynamically added or mutated stylesheets and
+* rewrite them to polyfill unsupported media pseudo-classes.
+*/
+function observeStylesheets(unsupported) {
+	new MutationObserver((records) => {
+		for (const record of records) if (record.type === "childList") {
+			const target = record.target;
+			if (isElement(target) && isStyleElement(target) && target.hasAttribute("data-polyfill-rewritten")) {
+				handleStyleChildListMutation(target, unsupported);
+				continue;
+			}
+			for (const node of record.addedNodes) processAddedNode(node, unsupported);
+		} else if (record.type === "characterData") handleCharacterDataMutation(record.target, unsupported);
+		else if (record.type === "attributes") {
+			const target = record.target;
+			if (isElement(target) && isStylesheetLink(target)) {
+				target.removeAttribute("data-polyfill-rewritten");
+				processLinkSheet(target, unsupported);
+			}
+		}
+	}).observe(document.documentElement, {
+		childList: true,
+		subtree: true,
+		characterData: true,
+		attributes: true,
+		attributeFilter: ["href"]
+	});
+}
+//#endregion
+//#region src/polyfill.ts
+function detectUnsupported() {
+	const unsupported = /* @__PURE__ */ new Set();
+	if (typeof CSS === "undefined" || typeof CSS.supports !== "function") return new Set(PSEUDO_CLASSES);
+	for (const name of PSEUDO_CLASSES) try {
+		if (!CSS.supports(`selector(:${name})`)) unsupported.add(name);
+	} catch {
+		unsupported.add(name);
+	}
+	return unsupported;
+}
+function polyfill() {
+	const unsupported = detectUnsupported();
+	if (unsupported.size === 0) return;
+	rewriteStyleElements(unsupported);
+	rewriteLinkStylesheets(unsupported);
+	observeMediaElements(unsupported);
+	observeStylesheets(unsupported);
+}
+//#endregion
+export { polyfill as t };

package/package.json ADDED Viewed

@@ -0,0 +1,59 @@
+{
+  "name": "@schalkneethling/css-media-pseudo-polyfill",
+  "version": "1.0.2",
+  "description": "A CSS polyfill for media pseudo-classes (:playing, :paused, :seeking, :buffering, :stalled, :muted)",
+  "keywords": [
+    "audio",
+    "buffering",
+    "css",
+    "media",
+    "muted",
+    "paused",
+    "playing",
+    "polyfill",
+    "pseudo-classes",
+    "seeking",
+    "video"
+  ],
+  "homepage": "https://github.com/schalkneethling/css-media-pseudo-polyfill",
+  "bugs": {
+    "url": "https://github.com/schalkneethling/css-media-pseudo-polyfill/issues"
+  },
+  "license": "MIT",
+  "author": "Schalk Neethling",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/schalkneethling/css-media-pseudo-polyfill"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./fn": "./dist/fn.mjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "css-tree": "^3.1.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "@types/css-tree": "^2.3.10",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260316.1",
+    "bumpp": "^11.0.1",
+    "typescript": "^5.9.3",
+    "vite": "latest",
+    "vite-plus": "latest",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp"
+  }
+}