🖥️ Chapter 54: The Fullscreen API

Fullscreen Lifecycle Events & State

Master `fullscreenchange`, `fullscreenerror`, tracking `document.fullscreenElement`, and synchronizing reactive application state.

LEARNING OBJECTIVES ⌵

Implement robust event listeners for fullscreenchange and fullscreenerror.
Accurately query document.fullscreenElement to synchronize UI controls, icons, and themes.
Understand the event dispatch chain and bubbling behavior across elements and the Document.
Diagnose and log permission rejections and runtime failures captured by fullscreenerror.
Architect a resilient state machine to track fullscreen sessions and analytics telemetry.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine an airport air traffic control tower.

Aircraft are constantly taxiing, taking off, climbing, and landing. The air traffic controller doesn't just push a button to grant clearance and then look away; the radar screen continuously tracks which aircraft is currently occupying the active runway.

Whenever an aircraft crosses the runway threshold or clears the landing zone, an automated radar transponder ping sounds across the tower, updating the master status board.

FULLSCREEN EVENT DISPATCH LIFECYCLE
+-------------------------------------------------------------------------------+
| USER ACTION: Clicks "Play Fullscreen" OR Presses [ESC] Key                    |
+-------------------------------------------------------------------------------+
                                       |
                                       v
+-------------------------------------------------------------------------------+
| BROWSER COMPOSITOR TRANSITION                                                 |
|  1. Evaluates user activation & permissions                                   |
|  2. If DENIED  ---> Dispatches 'fullscreenerror' (on Element & Document)      |
|  3. If GRANTED ---> Reconfigures display & updates document.fullscreenElement |
+-------------------------------------------------------------------------------+
                                       |
                                       v
+-------------------------------------------------------------------------------+
| EVENT BROADCAST: 'fullscreenchange'                                           |
|                                                                               |
|  Target Element (#player)  ========> Dispatches 'fullscreenchange'            |
|                                      (Bubbles up to Document & Window)        |
|                                                                               |
|  document.fullscreenElement === #player (or null if exiting)                  |
+-------------------------------------------------------------------------------+

In the Fullscreen API, fullscreenchange is that transponder ping. Because users can exit fullscreen at any time using the keyboard (Escape key), trackpad gestures, or OS controls, your UI state must never assume success based solely on a click. You must observe the lifecycle events to keep your play/pause buttons, icons, and analytics in sync.

Technical Deep Dive & Specifications

The `fullscreenchange` Event

The browser dispatches a fullscreenchange event whenever:

An element successfully transitions into the Top Layer.
An element is popped off the Top Layer (transitioning to a previous nested fullscreen element).
The last element in the stack exits, returning to normal windowed mode.

// Listening at the document level (Recommended)
document.addEventListener('fullscreenchange', (event: Event) => {
  if (document.fullscreenElement) {
    console.log('Entered fullscreen on:', document.fullscreenElement);
  } else {
    console.log('Exited fullscreen mode completely.');
  }
});

The `fullscreenerror` Event

If a call to requestFullscreen() fails (or if exitFullscreen() encounters a fatal error), the browser fires the fullscreenerror event:

document.addEventListener('fullscreenerror', (event: Event) => {
  console.error('Fullscreen request was rejected by browser policy.', event);
});

Common Causes of `fullscreenerror`:

Missing User Activation: Attempting programmatic invocation without an active user gesture.
Iframe Sandboxing: The element resides inside an <iframe> missing allow="fullscreen".
Detached DOM Node: The element was removed or detached from the DOM immediately after calling requestFullscreen().
Conflicting Window State: The window is minimized or inactive.

Querying `document.fullscreenElement`

document.fullscreenElement is the single source of truth for fullscreen status:

+-------------------------------------------------------------------------------+
|                         `document.fullscreenElement`                          |
+----------------------+--------------------------------------------------------+
| Return Value         | State Description                                      |
+----------------------+--------------------------------------------------------+
| `null`               | The document is currently in normal windowed mode.     |
|                      |                                                        |
| `HTMLElement`        | Reference to the specific DOM node currently promoted  |
| (e.g. `<video id>`)  | into the active Top Layer slot.                        |
+----------------------+--------------------------------------------------------+

Comparison: Event Listener vs Promise Handling

Modern browsers support both Promises on requestFullscreen() and the fullscreenchange event. How do they compare?

Feature	`requestFullscreen().then()` / `await`	`document.addEventListener('fullscreenchange')`
Scope	Captures only the specific initiating call	Captures ALL transitions (entry, nested, and `Escape` key exits)
Handles Keyboard `Esc`	❌ No (Only catches the entry promise)	✅ Yes (Guaranteed to fire on Esc)
Error Handling	`catch (err)` captures the specific `TypeError`	Fires global `fullscreenerror`
Best Practice Usage	Immediate async flow control	Global UI synchronization & analytics

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 164–187 (document.addEventListener('fullscreenchange')): Centralizes all UI updates into a single event handler. When the user exits using Escape, this handler fires automatically and restores all labels and button icons.
Line 172–176 (sessionStartTime): Captures high-precision timestamps (performance.now()) to compute exact user viewing duration metrics.
Line 149–157 (triggerErrorBtn): Deliberately executes requestFullscreen() after a setTimeout to trigger the fullscreenerror event for diagnostic testing.
Line 189–192 (document.addEventListener('fullscreenerror')): Catches systemic browser rejections and security failures.

Expected Browser Render Output

The page renders with a grey badge: STATE: WINDOWED and document.fullscreenElement: null.
Clicking "Enter Fullscreen" promotes the player and triggers fullscreenchange. The telemetry log records the exact event and changes the badge to green: STATE: FULLSCREEN ACTIVE.
Pressing Escape triggers fullscreenchange again, calculating the total viewing session duration (e.g. Session duration: 4.82s) and restoring the icon.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Lesson 54.6 - Fullscreen Lifecycle Events</title>
  <style>
    * {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
      font-family: system-ui, -apple-system, sans-serif;
    }

body {
      background: #090d16;
      color: #f1f5f9;
      padding: 30px 20px;
      display: flex;
      flex-direction: column;
      align-items: center;
      min-height: 100vh;
    }

.dashboard {
      max-width: 750px;
      width: 100%;
    }

.media-player-box {
      background: #1e293b;
      border: 2px solid #334155;
      border-radius: 12px;
      padding: 24px;
      margin-bottom: 20px;
      display: flex;
      flex-direction: column;
      align-items: center;
      text-align: center;
      transition: all 0.3s ease;
    }

.media-player-box:fullscreen {
      background: #020617;
      justify-content: center;
    }

.status-indicator {
      display: inline-flex;
      align-items: center;
      gap: 8px;
      padding: 6px 14px;
      border-radius: 9999px;
      font-size: 0.85rem;
      font-weight: 700;
      margin-bottom: 16px;
      background: #334155;
      color: #94a3b8;
    }

.status-indicator.active {
      background: #065f46;
      color: #34d399;
    }

.dot {
      width: 8px;
      height: 8px;
      border-radius: 50%;
      background: currentColor;
    }

.btn-group {
      display: flex;
      gap: 12px;
      margin-top: 16px;
    }

button {
      padding: 10px 18px;
      border: none;
      border-radius: 6px;
      font-weight: 600;
      font-size: 0.9rem;
      cursor: pointer;
      display: inline-flex;
      align-items: center;
      gap: 6px;
    }

.btn-primary { background: #3b82f6; color: white; }
    .btn-primary:hover { background: #2563eb; }

.btn-danger { background: #ef4444; color: white; }
    .btn-danger:hover { background: #dc2626; }

.telemetry-card {
      background: #020617;
      border: 1px solid #1e293b;
      border-radius: 8px;
      padding: 16px;
      font-family: monospace;
      font-size: 0.85rem;
      color: #38bdf8;
    }

.log-stream {
      margin-top: 10px;
      max-height: 180px;
      overflow-y: auto;
      border-top: 1px solid #1e293b;
      padding-top: 10px;
    }
  </style>
</head>
<body>

<div class="dashboard">
    <div class="media-player-box" id="playerNode">
      <div class="status-indicator" id="statusBadge">
        <span class="dot"></span>
        <span id="statusText">STATE: WINDOWED</span>
      </div>

<h2 id="playerHeading">High-Definition Broadcast Stream</h2>
      <p style="color: #94a3b8; margin: 10px 0 20px;">
        Lifecycle events will automatically detect transitions, whether triggered by button or ESC key.
      </p>

<div class="btn-group">
        <button class="btn-primary" id="toggleFsBtn">
          <span id="btnIcon">⛶</span>
          <span id="btnText">Enter Fullscreen</span>
        </button>
        <button class="btn-danger" id="triggerErrorBtn">
          <span>⚠️</span>
          <span>Simulate Fault</span>
        </button>
      </div>
    </div>

<div class="telemetry-card">
      <div><strong>📡 Fullscreen Event Telemetry Monitor</strong></div>
      <div id="activeElementInfo" style="margin-top: 6px; color: #a5f3fc;">
        document.fullscreenElement: <code>null</code>
      </div>
      <div class="log-stream" id="eventLog"></div>
    </div>
  </div>

let sessionStartTime = null;

// 1. Unified Toggle Button
    toggleFsBtn.addEventListener('click', async () => {
      try {
        if (!document.fullscreenElement) {
          await playerNode.requestFullscreen();
        } else {
          await document.exitFullscreen();
        }
      } catch (err) {
        appendLog(`Catch: ${err.message}`, true);
      }
    });

// 2. Trigger an intentional failure (delayed execution without user gesture)
    triggerErrorBtn.addEventListener('click', () => {
      appendLog('Scheduling unauthorized request in 1500ms (will trigger fullscreenerror)...');
      setTimeout(() => {
        // Attempting without user gesture
        playerNode.requestFullscreen().catch(err => {
          appendLog(`Promise Rejection: ${err.name} - ${err.message}`, true);
        });
      }, 1500);
    });

// 3. MASTER LIFECYCLE LISTENER: fullscreenchange
    document.addEventListener('fullscreenchange', () => {
      const activeEl = document.fullscreenElement;
      
      activeElementInfo.innerHTML = `document.fullscreenElement: <code>${
        activeEl ? `<${activeEl.tagName.toLowerCase()} id="${activeEl.id}">` : 'null'
      }</code>`;

if (activeEl) {
        // ENTERED FULLSCREEN
        sessionStartTime = performance.now();
        statusBadge.className = 'status-indicator active';
        statusText.textContent = 'STATE: FULLSCREEN ACTIVE';
        btnIcon.textContent = '🗗';
        btnText.textContent = 'Exit Fullscreen';
        appendLog(`EVENT: 'fullscreenchange' -> Promoted <${activeEl.tagName.toLowerCase()} id="${activeEl.id}"> to Top Layer.`);
      } else {
        // EXITED FULLSCREEN
        const duration = sessionStartTime ? ((performance.now() - sessionStartTime) / 1000).toFixed(2) : 0;
        statusBadge.className = 'status-indicator';
        statusText.textContent = 'STATE: WINDOWED';
        btnIcon.textContent = '⛶';
        btnText.textContent = 'Enter Fullscreen';
        appendLog(`EVENT: 'fullscreenchange' -> Returned to window. Session duration: ${duration}s.`);
      }
    });

// 4. MASTER ERROR LISTENER: fullscreenerror
    document.addEventListener('fullscreenerror', (e) => {
      appendLog(`EVENT: 'fullscreenerror' dispatched by browser!`, true);
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Create a Resilient Fullscreen Telemetry & Error Monitor

Instructions:

Create a media container (#gameViewport) with an "Enter Fullscreen Game" button.
Build an analytics tracker that logs:
- When fullscreen was entered.
- The screen resolution at the time of entry (window.innerWidth x window.innerHeight).
- How many times the user entered and exited during the session.
Add a warning banner if the user stays in fullscreen for more than 10 seconds.
Listen for fullscreenerror and display a user-friendly modal warning explaining that user gestures are required.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Challenge Solution: Fullscreen Telemetry Tracker</title>
  <style>
    * { box-sizing: border-box; margin: 0; padding: 0; font-family: system-ui, sans-serif; }
    body {
      background: #090d16;
      color: #f1f5f9;
      padding: 30px;
      display: flex;
      flex-direction: column;
      align-items: center;
    }
    #gameViewport {
      width: 400px;
      height: 240px;
      background: #1e293b;
      border: 2px solid #3b82f6;
      border-radius: 8px;
      padding: 24px;
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      text-align: center;
      margin-bottom: 20px;
    }
    #gameViewport:fullscreen {
      background: #020617;
      border: none;
    }
    button {
      padding: 10px 18px;
      background: #3b82f6;
      border: none;
      border-radius: 6px;
      color: white;
      font-weight: 700;
      cursor: pointer;
      margin-top: 16px;
    }
    #analyticsBox {
      max-width: 600px;
      width: 100%;
      background: #020617;
      border: 1px solid #1e293b;
      border-radius: 8px;
      padding: 16px;
      font-family: monospace;
      font-size: 0.9rem;
      color: #38bdf8;
      line-height: 1.6;
    }
  </style>
</head>
<body>

  <div id="gameViewport">
    <h2>🎮 WebGL 3D Game Canvas</h2>
    <p style="color: #94a3b8; font-size: 0.85rem; margin-top: 8px;">Interactive real-time game engine.</p>
    <button id="startBtn">Launch Fullscreen</button>
  </div>

  <div id="analyticsBox">
    <strong>📊 Telemetry Metrics:</strong>
    <div id="metricSessionCount">Fullscreen Sessions: 0</div>
    <div id="metricResolution">Active Resolution: N/A</div>
    <div id="metricDuration">Last Session Duration: 0s</div>
  </div>

  <script>
    const viewport = document.getElementById('gameViewport');
    const startBtn = document.getElementById('startBtn');
    const metricSessions = document.getElementById('metricSessionCount');
    const metricRes = document.getElementById('metricResolution');
    const metricDur = document.getElementById('metricDuration');

    let totalSessions = 0;
    let entryTimestamp = 0;

    startBtn.addEventListener('click', async () => {
      if (!document.fullscreenElement) {
        await viewport.requestFullscreen();
      } else {
        await document.exitFullscreen();
      }
    });

    document.addEventListener('fullscreenchange', () => {
      if (document.fullscreenElement) {
        totalSessions++;
        entryTimestamp = performance.now();
        metricSessions.textContent = `Fullscreen Sessions: ${totalSessions}`;
        metricRes.textContent = `Active Resolution: ${window.innerWidth} x ${window.innerHeight} (${window.devicePixelRatio}x DPI)`;
        startBtn.textContent = 'Exit Game';
      } else {
        const elapsed = ((performance.now() - entryTimestamp) / 1000).toFixed(2);
        metricDur.textContent = `Last Session Duration: ${elapsed}s`;
        startBtn.textContent = 'Launch Fullscreen';
      }
    });

    document.addEventListener('fullscreenerror', () => {
      alert('Security Error: Fullscreen transition was blocked by the browser.');
    });
  </script>
</body>
</html>

Why this works:

Every transition fires fullscreenchange, which accurately reads the new dimensions via window.innerWidth and window.innerHeight.
The duration calculation seamlessly captures the precise time between entry and exit regardless of whether the user clicked the button or pressed Escape.

⚠️ Common Pitfalls

Updating UI State Only in Click Handlers: Updating your button label to "Exit" inside button.addEventListener('click') causes a desynchronization bug when the user exits using the Escape key. Always update state inside the fullscreenchange listener.
Attaching fullscreenchange Only to Target Elements on Legacy Browsers: While modern browsers bubble fullscreenchange, some older WebKit engines dispatched it only to the Document. Listening on document is the most reliable cross-browser approach.
Assuming event.target is Always the Fullscreen Element: On exit, document.fullscreenElement is null. Always verify whether document.fullscreenElement is truthy before reading element properties.

💡 Pro Tips

Integrate with Visibility API: Combine fullscreenchange with visibilitychange (document.hidden) to automatically pause full-screen games or video playback if the user switches virtual desktops (e.g. via Alt+Tab or Mission Control).
Dispatch Framework-Level Custom Events: In large web apps, wrap fullscreenchange in an application-wide event bus or reactive store (e.g., Zustand, Pinia, Redux) to notify decoupled navigation bars and modals.

📌 Key Takeaways

fullscreenchange is dispatched whenever entering or exiting any layer of fullscreen mode.
fullscreenerror fires when a fullscreen request is denied by permissions or security gating.
document.fullscreenElement is the canonical source of truth for the currently promoted DOM node.
Always synchronize UI buttons, icons, and timers inside fullscreenchange to account for Escape key exits.
Listening on document ensures 100% capture of all transitions across parent and child components.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Why is listening to the `fullscreenchange` event preferred over relying exclusively on the Promise returned by `requestFullscreen()` for updating UI buttons?

Topic: HTML Fundamentals

? Question 2 / 3

What is the value of `document.fullscreenElement` when the browser is in standard windowed mode?

Topic: HTML Fundamentals

? Question 3 / 3

Which event is dispatched if a script attempts to invoke `requestFullscreen()` without a valid transient user gesture?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The fullscreenchange Event

The fullscreenerror Event

Common Causes of fullscreenerror:

Querying document.fullscreenElement

Comparison: Event Listener vs Promise Handling

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Create a Resilient Fullscreen Telemetry & Error Monitor

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why is listening to the fullscreenchange event preferred over relying exclusively on the Promise returned by requestFullscreen() for updating UI buttons?

What is the value of document.fullscreenElement when the browser is in standard windowed mode?

Which event is dispatched if a script attempts to invoke requestFullscreen() without a valid transient user gesture?

The `fullscreenchange` Event

The `fullscreenerror` Event

Common Causes of `fullscreenerror`:

Querying `document.fullscreenElement`

Why is listening to the `fullscreenchange` event preferred over relying exclusively on the Promise returned by `requestFullscreen()` for updating UI buttons?

What is the value of `document.fullscreenElement` when the browser is in standard windowed mode?

Which event is dispatched if a script attempts to invoke `requestFullscreen()` without a valid transient user gesture?