Introducing a new way to review your PRs.

Read the announcement

fingerprintjs / fingerprintjs

The most advanced free and open-source browser fingerprinting library

View on GitHub

13 documents · Updated Nov 16, 2026

docs / display-and-media-preference-sources

Display and Media Preference Sources

Overview

This source group reports display geometry, color capability, HDR, and accessibility/media preferences from browser APIs. Each file exports a small entropy source under src/sources/, with tests beside it that either assert native-browser return shapes or mock matchMedia/screen to cover normalization and fallback behavior.

src/…/screen_resolution.ts reads screen.width and screen.height, parses them with toInt, replaces NaN with null, sorts the two dimensions descending, and returns [larger, smaller]. This makes portrait/landscape orientation differences less noisy and tolerates plugins/browsers that expose numeric screen dimensions as strings or invalid values. The stabilized default export returns undefined on Safari WebKit 616+ (isWebKit() && isWebKit616OrNewer() && isSafariWebKit()), because Safari 17 private mode reports window/document-sized values. getUnstableScreenResolution() bypasses that browser suppression. src/…/screen_resolution.test.ts checks positive native dimensions when not suppressed, undefined on Safari 17+, and repeat-call stability.

src/…/screen_frame.ts measures the unavailable screen area as a CSS-side-ordered tuple [top, right, bottom, left]. getCurrentScreenFrame() reads screen.availTop, screen.width, screen.availWidth, screen.availLeft, screen.height, and screen.availHeight; values are parsed with toFloat, invalid side values become null, and missing availLeft/availTop are treated as 0 when computing right/bottom so IE and Edge <=18 can still contribute availWidth/availHeight entropy. getUnstableScreenFrame() returns an async getter and starts watchScreenFrame(), which polls every screenFrameCheckInterval (2500 ms) until a non-zero frame is observed and stores it in screenFrameBackup. If a later measurement is all zero/null, the getter returns the remembered non-zero frame; if there is no backup but fullscreen is active, it calls exitFullscreen() and measures again because some browsers zero the frame in programmatic fullscreen. The stabilized default export rounds non-null sides to the nearest 10 via round and returns undefined on Safari WebKit 616+/Safari 17+ and Gecko 143+/Firefox 143+ because those modes spoof or zero screen frame values. src/…/screen_frame.test.ts covers non-zero frames, all-zero frames, missing position properties, the polling/backup behavior with fake timers, rounding, browser suppression, and repeat-call stability.

src/…/color_depth.ts is the only non-matchMedia color source: it returns window.screen.colorDepth directly with no normalization or fallback sentinel. src/…/color_depth.test.ts checks that the native value is one of the expected browser depths [48, 36, 32, 30, 24, 18, 16, 15, 12, 8, 0].

src/…/color_gamut.ts uses the CSS color-gamut media feature. It probes (color-gamut: rec2020), then p3, then srgb, returning the widest matching gamut because rec2020 includes p3 and p3 includes srgb; if none match, including missing browser support, it returns undefined. src/…/color_gamut.test.ts verifies native values, unsupported media feature fallback, and that overlapping supported gamuts resolve to the widest string.

src/…/hdr.ts uses Media Queries Level 5 dynamic-range. It returns true for (dynamic-range: high), false for (dynamic-range: standard), and undefined if neither matches or the browser lacks support. src/…/hdr.test.ts covers native return shape, missing support, high, and standard.

src/…/monochrome.ts uses the CSS monochrome media feature to return the display's monochrome bits per pixel. It first checks (min-monochrome: 0); if that fails, browser support is treated as missing and the source returns undefined. Otherwise it linearly checks (max-monochrome: 0) through (max-monochrome: 100) and returns the first matching integer. Non-monochrome displays return 0, monochrome displays return their depth, and values above 100 throw Error('Too high value'). src/…/monochrome.test.ts covers native type, unsupported fallback, 0, 8, 10, and repeat-call stability.

src/…/contrast.ts maps prefers-contrast media queries into numeric ContrastPreference values: no-preference -> 0, high or more -> 1, low or less -> -1, and forced -> 10. It returns undefined when no queried value matches. The implementation intentionally accepts both high/low and more/less because referenced specs and MDN disagree on historical keywords. src/…/contrast.test.ts verifies native return shape plus unsupported, no-preference, both more/high spellings, both less/low spellings, and forced colors.

src/…/inverted_colors.ts maps inverted-colors to booleans: inverted -> true, none -> false, and undefined for missing support/no match. src/…/inverted_colors.test.ts covers native return shape and the unsupported, none, and inverted cases.

src/…/forced_colors.ts maps forced-colors to booleans: active -> true, none -> false, and undefined for missing support/no match. src/…/forced_colors.test.ts covers native return shape and the unsupported, none, and active cases.

src/…/reduced_motion.ts maps prefers-reduced-motion to booleans: reduce -> true, no-preference -> false, and undefined otherwise. src/…/reduced_motion.test.ts covers native return shape, unsupported fallback, no-preference, and reduce.

src/…/reduced_transparency.ts maps prefers-reduced-transparency to booleans with the same convention as reduced motion: reduce -> true, no-preference -> false, and undefined when unsupported or unmatched. src/…/reduced_transparency.test.ts covers native return shape, unsupported fallback, no-preference, and reduce.

Coupling

  • If browser-engine/version detection changes in src/…/browser.ts, re-check src/…/screen_resolution.ts and src/…/screen_frame.ts: their stabilized exports depend on isWebKit, isWebKit616OrNewer, isSafariWebKit, isGecko, and isGecko143OrNewer to suppress noisy Safari 17+ and Firefox 143+ screen values, while their tests mirror that logic using test browser helpers.
  • If numeric parsing or rounding changes in src/…/data.ts, verify screen normalization in src/…/screen_resolution.ts and src/…/screen_frame.ts: replaceNaN, toInt, toFloat, and round define the null sentinels and rounded frame output asserted by the tests.
  • If adding or renaming CSS media preference sources, keep the return sentinels consistent with the existing matchMedia sources: booleans use true/false/undefined, enumerated values use string or numeric enums plus undefined, and unsupported media features are represented by undefined rather than false.

Risks

  • src/…/screen_frame.ts keeps module-level state (screenFrameBackup and screenFrameSizeTimeoutId). If a consumer or test changes the polling lifecycle without calling resetScreenFrameWatch() in tests, stale backup values can leak into later reads and make an all-zero frame look non-zero.
  • src/…/screen_frame.ts may call exitFullscreen() when the frame is null and getFullscreenElement() is set. If fullscreen API compatibility helpers in src/…/browser.ts stop binding the document method correctly, this source can reject instead of returning a frame.
  • src/…/monochrome.ts throws when the first matching (max-monochrome: N) is above 100. If future browsers expose larger monochrome depths, the source will fail hard instead of returning undefined or a capped value.