🖥️ Chapter 54: The Fullscreen API

Exiting Fullscreen & State Recovery

Master `document.exitFullscreen()`, the Escape key security interceptor, nested fullscreen stack unwinding, and layout state recovery.

LEARNING OBJECTIVES ⌵

Understand why exitFullscreen() is invoked on the Document object rather than individual elements.
Handle Promise resolution and capture TypeError exceptions when exiting fullscreen.
Explain how browsers handle the user's Escape key and why e.preventDefault() cannot trap or block it.
Unwind multi-level nested fullscreen element stacks cleanly.
Restore component layout states, scroll positions, and canvas aspect ratios upon exiting.

🎬 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 stepping into a high-security submarine airlock chamber. To enter the chamber (diving into fullscreen), you activate the hatch mechanism on a specific submarine compartment (compartment.requestFullscreen()).

However, once you are inside the submerged airlock, there isn't a separate hatch control for every single wall or gadget. The central command station controls the overall atmosphere and pressure of the vessel (document.exitFullscreen()). Furthermore, the airlock has a bright red manual emergency override lever (Escape key) that immediately vents the water and reopens the chamber door—no software or electronic lock can ever override that mechanical safety lever.

THE FULLSCREEN CONTROL ASYMMETRY
+-------------------------------------------------------------------------------+
| ENTRY (Specific Element Level)                                                |
|                                                                               |
|   myVideoElement.requestFullscreen()     <-- Called on specific DOM ELEMENT   |
|   myCanvasElement.requestFullscreen()    <-- Promotes that targeted element   |
+-------------------------------------------------------------------------------+
                                       |
                                       v
+-------------------------------------------------------------------------------+
| EXIT (Document Master Level)                                                  |
|                                                                               |
|   document.exitFullscreen()             <-- Called on DOCUMENT object        |
|   [ESC Key Pressed by User]             <-- Browser OS-Level Master Override |
+-------------------------------------------------------------------------------+

This asymmetry is one of the most common stumbling blocks for web developers: You request fullscreen on an Element, but you exit fullscreen from the Document.

Technical Deep Dive & Specifications

The `document.exitFullscreen()` Method Signature

document.exitFullscreen(): Promise<void>

Under the WHATWG specification:

exitFullscreen() is defined on the DocumentOrShadowRoot interface.
It returns a Promise that resolves with undefined once the browser has vacated the Top Layer and resized the viewport back to standard windowed mode.
If the document is not currently in fullscreen mode (i.e., document.fullscreenElement === null), invoking document.exitFullscreen() immediately rejects the Promise with a TypeError.

// ❌ WRONG: Attempting to call exit on an element
myElement.exitFullscreen(); // Uncaught TypeError: myElement.exitFullscreen is not a function

// ❌ RISKY: Calling exit when no element is fullscreen
await document.exitFullscreen(); // Rejects if already in normal window mode!

// ✅ SAFE PATTERN: Check document.fullscreenElement first
async function toggleFullscreen(targetElement) {
  if (!document.fullscreenElement) {
    await targetElement.requestFullscreen();
  } else {
    await document.exitFullscreen();
  }
}

The Browser Escape Key Interceptor

To prevent malicious websites from trapping users in full-screen phishing environments, browser engines implement a hardcoded, non-suppressible Escape Key Interceptor:

[User Presses ESC Key]
          |
          v (Hardware / OS Level)
[Browser Engine Intercepts ESC]
          |
          +---> 1. Instantly triggers exitFullscreen() workflow
          |
          +---> 2. Dispatches 'keydown' / 'keyup' event to DOM
                   (Note: e.preventDefault() is IGNORED by the browser)
          |
          v
[Top Layer Collapsed & 'fullscreenchange' Dispatched]

[!WARNING] Escape Cannot Be Blocked: Calling event.preventDefault() or event.stopPropagation() inside a keydown listener for the Escape key will not prevent the browser from exiting fullscreen mode. This is a fundamental web security invariant.

Nested Fullscreen Element Stacks

Modern browsers support nested fullscreen transitions. If an element Container A is currently in fullscreen mode, and a child element Video B calls requestFullscreen(), the browser pushes Video B to the top of the fullscreen stack.

INITIAL ENTRY:
[ Top Layer Stack: Container A ] -> document.fullscreenElement === Container A

NESTED ENTRY:
[ Top Layer Stack: Video B (Active), Container A (Previous) ] -> document.fullscreenElement === Video B

FIRST document.exitFullscreen():
[ Top Layer Stack: Container A (Active) ] -> document.fullscreenElement === Container A

SECOND document.exitFullscreen():
[ Top Layer Stack: EMPTY ] -> document.fullscreenElement === null

When document.exitFullscreen() is called:

The browser removes the topmost element (Video B).
If another element was previously fullscreen (Container A), it becomes the active document.fullscreenElement.
Only when the stack is completely empty does the document return to normal windowed mode.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 132–136 (incrementBtn): Modifies in-memory state (count). This proves that entering or exiting the Top Layer does not reload the page or reset JavaScript runtime state.
Line 139–151 (toggleBtn): Implements the canonical idempotent toggle pattern: checking document.fullscreenElement to decide whether to call element.requestFullscreen() or document.exitFullscreen().
Line 154–163 (exitBtn): Demonstrates safe invocation of document.exitFullscreen() guarded by a document.fullscreenElement existence check.
Line 166–181 (document.addEventListener('fullscreenchange')): Listens to the browser's global lifecycle event. Crucially, this event fires regardless of whether the user clicked our custom exit button or pressed the physical keyboard Escape key!

Expected Browser Render Output

The user clicks "Increment Ticker" several times (counter reads 5).
The user clicks "Toggle Fullscreen". The dashboard fills the entire monitor, and the button label switches to "Exit Fullscreen".
The user hits the physical Escape key on their keyboard. The dashboard immediately shrinks back to normal layout.
The counter still displays 5—proving 100% DOM and JavaScript memory state retention.

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.3 - Exiting Fullscreen & State Recovery</title>
  <style>
    * {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
      font-family: system-ui, -apple-system, sans-serif;
    }

body {
      background: #0f172a;
      color: #f8fafc;
      padding: 40px 20px;
      display: flex;
      flex-direction: column;
      align-items: center;
      min-height: 100vh;
    }

.dashboard-container {
      background: #1e293b;
      border: 1px solid #334155;
      border-radius: 12px;
      padding: 24px;
      max-width: 800px;
      width: 100%;
      box-shadow: 0 10px 25px rgba(0, 0, 0, 0.4);
    }

.header-bar {
      display: flex;
      justify-content: space-between;
      align-items: center;
      margin-bottom: 20px;
      padding-bottom: 12px;
      border-bottom: 1px solid #334155;
    }

.counter-display {
      font-size: 2.5rem;
      font-weight: 800;
      color: #38bdf8;
      text-align: center;
      margin: 30px 0;
    }

.btn-toolbar {
      display: flex;
      gap: 12px;
      justify-content: center;
      margin-bottom: 20px;
    }

button {
      padding: 10px 18px;
      border-radius: 6px;
      border: none;
      font-weight: 600;
      font-size: 0.9rem;
      cursor: pointer;
      transition: all 0.2s;
    }

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

.btn-increment { background: #10b981; color: white; }
    .btn-increment:hover { background: #059669; }

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

.btn-exit:disabled {
      background: #475569;
      cursor: not-allowed;
      opacity: 0.5;
    }

.log-box {
      background: #020617;
      border-radius: 6px;
      padding: 12px;
      font-family: monospace;
      font-size: 0.85rem;
      color: #a5f3fc;
      min-height: 80px;
    }

/* Fullscreen UI Overrides */
    .dashboard-container:fullscreen {
      width: 100vw;
      height: 100vh;
      max-width: 100vw;
      border-radius: 0;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
    }
  </style>
</head>
<body>

<div class="dashboard-container" id="dashboard">
    <div class="header-bar">
      <h2>🚀 Live Telemetry Hub</h2>
      <span id="screenStateBadge">Mode: Windowed</span>
    </div>

<div class="btn-toolbar">
      <button class="btn-increment" id="incrementBtn">Increment Ticker (+1)</button>
      <button class="btn-toggle" id="toggleFullscreenBtn">Toggle Fullscreen</button>
      <button class="btn-exit" id="explicitExitBtn" disabled>Explicit Exit</button>
    </div>

<div class="log-box" id="eventLog">> System ready. State preserved across mode changes.</div>
  </div>

let count = 0;

function log(msg) {
      logBox.innerHTML = `[${new Date().toLocaleTimeString()}] ${msg}<br>` + logBox.innerHTML;
    }

// 1. Increment state (verifies state is preserved upon exit)
    incrementBtn.addEventListener('click', () => {
      count++;
      counterDisplay.textContent = count;
      log(`Counter updated to ${count}`);
    });

// 2. Safe Toggle Handler
    toggleBtn.addEventListener('click', async () => {
      try {
        if (!document.fullscreenElement) {
          log('Requesting fullscreen on #dashboard...');
          await dashboard.requestFullscreen();
        } else {
          log('Calling document.exitFullscreen()...');
          await document.exitFullscreen();
        }
      } catch (err) {
        log(`Error: ${err.message}`);
      }
    });

// 3. Explicit Exit Button Handler
    exitBtn.addEventListener('click', async () => {
      if (document.fullscreenElement) {
        try {
          await document.exitFullscreen();
          log('Exited via explicit button.');
        } catch (err) {
          log(`Exit error: ${err.message}`);
        }
      }
    });

// 4. Synchronize UI with Fullscreen Changes (handles both button & ESC key)
    document.addEventListener('fullscreenchange', () => {
      const isFullscreen = Boolean(document.fullscreenElement);
      
      if (isFullscreen) {
        badge.textContent = 'Mode: FULLSCREEN';
        badge.style.color = '#34d399';
        toggleBtn.textContent = 'Exit Fullscreen';
        exitBtn.disabled = false;
        log('DOM Event: entered fullscreen mode.');
      } else {
        badge.textContent = 'Mode: Windowed';
        badge.style.color = '#f8fafc';
        toggleBtn.textContent = 'Enter Fullscreen';
        exitBtn.disabled = true;
        log('DOM Event: exited fullscreen mode (state perfectly preserved).');
      }
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Construct a Multi-Level Fullscreen Dashboard with Graceful Exit

Instructions:

Create a parent container (#presentationDeck) containing two nested child slides (#slideA and #slideB).
Provide a button to promote #presentationDeck to fullscreen.
Inside Slide A, provide a second button that promotes #slideA into nested fullscreen mode.
Implement an Exit Controller that displays how many levels are in the fullscreen stack and exits one level at a time.
Record every exit action in a real-time event log.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Challenge: Nested Fullscreen Unwinder</title>
  <style>
    body { font-family: sans-serif; padding: 20px; background: #0f172a; color: white; }
    .deck { padding: 20px; background: #1e293b; border: 2px solid #3b82f6; }
    .slide { margin: 15px 0; padding: 15px; background: #334155; border-radius: 6px; }
    button { padding: 8px 14px; margin-right: 8px; cursor: pointer; }
  </style>
</head>
<body>
  <h1>Nested Fullscreen Stack Challenge</h1>

<div class="deck" id="presentationDeck">
    <h2>Main Presentation Deck (Parent)</h2>
    <button id="deckFullscreenBtn">Fullscreen Entire Deck</button>

<div class="slide" id="slideA">
      <h3>Slide A: Nested Deep Dive</h3>
      <button id="slideAFullscreenBtn">Fullscreen Slide A Only</button>
    </div>
  </div>

<div style="margin-top: 15px;">
    <button id="exitBtn">Exit Fullscreen Step</button>
  </div>

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: Nested Fullscreen Unwinder</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      padding: 30px;
      background: #090d16;
      color: #f1f5f9;
      max-width: 800px;
      margin: 0 auto;
    }
    .deck {
      padding: 24px;
      background: #1e293b;
      border: 2px solid #3b82f6;
      border-radius: 8px;
      margin-bottom: 20px;
    }
    .slide {
      margin-top: 16px;
      padding: 20px;
      background: #0f172a;
      border: 1px dashed #64748b;
      border-radius: 6px;
    }
    button {
      padding: 10px 16px;
      margin: 8px 8px 8px 0;
      border: none;
      border-radius: 6px;
      font-weight: 600;
      cursor: pointer;
      background: #3b82f6;
      color: white;
    }
    button:hover { background: #2563eb; }
    .btn-exit { background: #ef4444; }
    .btn-exit:hover { background: #dc2626; }
    #outputLog {
      background: #020617;
      border: 1px solid #1e293b;
      padding: 16px;
      border-radius: 6px;
      font-family: monospace;
      font-size: 0.85rem;
      color: #38bdf8;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>
  <h1>Nested Fullscreen Stack Challenge</h1>

  <div class="deck" id="presentationDeck">
    <h2>📊 Main Presentation Deck (Parent)</h2>
    <p style="color: #94a3b8; font-size: 0.9rem;">Parent container holding multiple slide modules.</p>
    <button id="deckFullscreenBtn">1. Fullscreen Entire Deck</button>

    <div class="slide" id="slideA">
      <h3>🔍 Slide A: Sub-Component</h3>
      <p style="color: #94a3b8; font-size: 0.85rem;">Nested child element capable of independent fullscreen promotion.</p>
      <button id="slideAFullscreenBtn">2. Fullscreen Slide A (Nested)</button>
    </div>
  </div>

  <button class="btn-exit" id="exitBtn">Unwind / Exit Fullscreen</button>

  <div id="outputLog">> Ready. Request a fullscreen element to test stack unwinding.</div>

  <script>
    const deck = document.getElementById('presentationDeck');
    const slideA = document.getElementById('slideA');
    const deckBtn = document.getElementById('deckFullscreenBtn');
    const slideBtn = document.getElementById('slideAFullscreenBtn');
    const exitBtn = document.getElementById('exitBtn');
    const logBox = document.getElementById('outputLog');

    function log(msg) {
      logBox.textContent += `\n[${new Date().toLocaleTimeString()}] ${msg}`;
    }

    // 1. Promote Parent Deck
    deckBtn.addEventListener('click', async () => {
      try {
        await deck.requestFullscreen();
        log('Action: Deck requested fullscreen.');
      } catch (err) {
        log(`Error: ${err.message}`);
      }
    });

    // 2. Promote Child Slide (Creates nested stack)
    slideBtn.addEventListener('click', async () => {
      try {
        await slideA.requestFullscreen();
        log('Action: Slide A requested nested fullscreen.');
      } catch (err) {
        log(`Error: ${err.message}`);
      }
    });

    // 3. Unwind Stack Step by Step
    exitBtn.addEventListener('click', async () => {
      if (!document.fullscreenElement) {
        log('Notice: Not currently in fullscreen mode.');
        return;
      }
      try {
        log(`Unwinding from active element: <${document.fullscreenElement.tagName.toLowerCase()} id="${document.fullscreenElement.id}">`);
        await document.exitFullscreen();
      } catch (err) {
        log(`Exit error: ${err.message}`);
      }
    });

    // 4. Track Stack Lifecycle
    document.addEventListener('fullscreenchange', () => {
      const activeEl = document.fullscreenElement;
      if (activeEl) {
        log(`State Change: Active fullscreen element is now #${activeEl.id}`);
      } else {
        log('State Change: Fullscreen stack is completely EMPTY. Returned to windowed mode.');
      }
    });
  </script>
</body>
</html>

Why this works:

When the parent Deck is fullscreen, document.fullscreenElement points to #presentationDeck.
When Slide A is then requested, the browser pushes #slideA into the Top Layer stack.
Calling document.exitFullscreen() once pops #slideA off the stack, seamlessly returning focus to #presentationDeck.
A second call to document.exitFullscreen() returns the document to normal windowed view.

⚠️ Common Pitfalls

Calling element.exitFullscreen(): There is no exitFullscreen() method on DOM elements. It exists exclusively on the document object.
Uncaught Rejections on Duplicate Exit: Calling document.exitFullscreen() when no element is currently fullscreen causes a Promise rejection. Always check if (document.fullscreenElement) prior to calling.
Attempting to Trap the User: Trying to re-enter fullscreen immediately inside an Escape key event listener will be blocked by the browser because the Escape key is not classified as an activation gesture.

💡 Pro Tips

Idempotent Fullscreen Helper: Write a lightweight helper utility:

export const toggleFullscreen = async (el = document.documentElement) => {
  if (document.fullscreenElement) {
    await document.exitFullscreen();
  } else {
    await el.requestFullscreen();
  }
};

Track Scroll Restoration: When exiting fullscreen on a complex document, verify that window.scrollTo() is not unintentionally shifted by layout resizing. Conforming browsers preserve scroll offsets automatically.

📌 Key Takeaways

document.exitFullscreen() exits fullscreen mode and returns a Promise.
Fullscreen requests are initiated on individual Elements, but exit calls are executed globally on the Document.
The physical keyboard Escape key is hardwired to exit fullscreen mode and cannot be intercepted or suppressed by application JavaScript.
Browsers maintain an internal fullscreen element stack, allowing nested components to unwind layer by layer.
DOM state, event listeners, input values, and media playback remain completely uninterrupted when exiting fullscreen.
--

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

? Question 1 / 3

Why does calling `myVideo.exitFullscreen()` throw a TypeError in JavaScript?

Topic: HTML Fundamentals

? Question 2 / 3

What happens if a developer attempts to call `e.preventDefault()` inside a `keydown` handler for the `Escape` key while in fullscreen?

Topic: HTML Fundamentals

? Question 3 / 3

If Element B is requested fullscreen while Element A is already fullscreen, what happens on the first call to `document.exitFullscreen()`?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The document.exitFullscreen() Method Signature

The Browser Escape Key Interceptor

Nested Fullscreen Element Stacks

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Construct a Multi-Level Fullscreen Dashboard with Graceful Exit

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why does calling myVideo.exitFullscreen() throw a TypeError in JavaScript?

What happens if a developer attempts to call e.preventDefault() inside a keydown handler for the Escape key while in fullscreen?

If Element B is requested fullscreen while Element A is already fullscreen, what happens on the first call to document.exitFullscreen()?

The `document.exitFullscreen()` Method Signature

Why does calling `myVideo.exitFullscreen()` throw a TypeError in JavaScript?

What happens if a developer attempts to call `e.preventDefault()` inside a `keydown` handler for the `Escape` key while in fullscreen?

If Element B is requested fullscreen while Element A is already fullscreen, what happens on the first call to `document.exitFullscreen()`?