JavaScript Window Management Table

window.screen is a single-screen snapshot: it describes whichever display your window happens to be on - its dimensions, its availHeight, its devicePixelRatio - and stays silent about everything else. getScreenDetails() returns the whole ensemble. ScreenDetails carries: screens, an array of ScreenDetailed objects - one per connected display, each with its own label, left/top/width/height bounds in desktop coordinates, devicePixelRatio, color depth, and the isPrimary and isInternal flags (primary display versus the screen your OS designates, internal laptop panel versus external monitor); currentScreen, the ScreenDetailed your window occupies right now; and the two change events. Two practical consequences. First, layout math becomes real: knowing each screen is at left 0 and 1920 versus left 1920 means you can reason about a two-display desktop as one coordinate space instead of guessing. Second, identity becomes real: labels let a presenter console remember that the HDMI monitor shows slides while the laptop shows notes - preferences pinned to a physical screen instead of to the window you dragged last. And the boundary to respect: the API reports the desktop as the OS sees it (including workarea exclusions on some platforms), but it gives you no power to open, move or size windows beyond what window.open and the browser already allow - it is situational awareness, not a window manager.

The call sits behind the window-management permission: first getScreenDetails() surfaces a prompt (browsers typically want a user gesture in the call chain), and denying it makes the promise reject - your code should catch and run a single-screen layout, not surface an exception. The reason browsers gate this hard is that screen topology is a superb fingerprint: two external monitors at specific resolutions and positions narrows a user to one desk in the world, so the same information that makes kiosk dashboards possible makes drive-by tracking possible. The settlement has three tiers. Tier one, free: window.screen basics and the synchronous screen.isExtended boolean - enough to adapt UI coarsely with no prompt at all. Tier two, prompt: getScreenDetails() grants the full per-screen inventory; grant it once per origin and it persists until the user revokes it in site settings. Tier three, never: no events, no enumeration without the grant - backgrounded tabs do not keep monitoring hardware changes silently. Engineering-wise this maps to a clean pattern: build your layout on tier-one signals, request tier two only when the user activates an explicitly multi-screen feature, and treat a denial as a normal product state - a user on a locked-down corporate browser may never grant it, and those users still deserve a working single-screen experience.

They track two different kinds of change. screenschange fires on the ScreenDetails object when the physical or logical display set changes: a monitor plugged in or unplugged, a display sleeping or waking, a virtual display appearing - the screens array after the event is the new truth, so the handler pattern is rebuild-from-scratch (re-read d.screens, re-render your layout) rather than trying to diff the old array; the event carries no payload of what changed precisely because the reliable source is the array itself. currentscreenchange fires when the screen your window is on changes identity - most commonly because the user dragged your window across displays, but also when a screen your window occupied disappears and the window relocates. Both matter to real products and both fail differently: skip screenschange and your trading dashboard shows phantom screens after the projector disconnects mid-meeting; skip currentscreenchange and your presenter console keeps highlighting speaker-notes controls after the user drags it to the projector screen. Two hygiene rules: attach both listeners at the same moment you receive ScreenDetails (they live on that object, not on window), and debounce rebuilds - a docking station waking up can fire a burst of screenschange events, and rebuilding a complex layout five times in half a second shows.

Four boundary cases, each with its own exit. If you need to move or size windows, not just know about screens: the API is read-only by design - your tools remain window.open with feature strings, fullscreen placement, and the browser UI; apps that truly script window layout (trading floors) often end up as installed PWAs where the OS window management is richer. If you need content on a second screen without your window going there: the Presentation API casts a receiver page to a cast device or second display deliberately - different transport, better fit for slides-to-TV. If you need to capture what is on a screen: that is the Screen Capture API (getDisplayMedia) - pixels, not topology, with its own consent surface. And if you just want to show a fullscreen dashboard on whatever screen the user put you on: fullscreen plus a responsive layout solves it with zero new permissions - the honest first question before reaching for getScreenDetails() is whether you actually need to know about the other screens, or just to look good on this one. The genuine sweet spots for Window Management are the products that span displays by design: presenter consoles, multi-panel trading or monitoring walls, POS with a customer-facing display, kiosk clusters - apps where a screen is part of the configuration, not an accident of where the window landed.