🖥️ Chapter 54: The Fullscreen API

Cross-Browser Prefixes & Polyfills

Master legacy vendor implementations (WebKit, Gecko, MS), iOS Safari video exceptions, and write an enterprise-grade compatibility adapter.

LEARNING OBJECTIVES ⌵

Understand the historical evolution and capitalization nuances across vendor prefixes (webkit, moz, ms).
Handle iOS Safari limitations where fullscreen is restricted exclusively to <video> elements via webkitEnterFullscreen().
Normalize cross-browser event names (webkitfullscreenchange, mozfullscreenchange, MSFullscreenChange).
Build a zero-dependency, production-grade TypeScript/JavaScript Fullscreen adapter wrapper.

🎬 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 traveling across Europe in an electric car before universal charging standards were established.

In Germany, the charging stations used a 7-pin connector with a blue plug. In France, they used a 5-pin connector with a red lever. In Italy, they used a 3-pin connector with an inverted latch. If you didn't carry a universal adapter kit in your trunk, your car would be stranded at the border.

THE VENDOR PREFIX ADAPTER MATRIX
+-------------------------------------------------------------------------------+
| UNIFIED API CALL: `fullscreenAdapter.request(element)`                        |
+-------------------------------------------------------------------------------+
                                       |
       +-------------------------------+-------------------------------+
       |                               |                               |
       v                               v                               v
[Modern Standard]              [Legacy WebKit/Blink]           [Legacy Mozilla Gecko]
element.requestFullscreen()    element.webkitRequestFullscreen() element.mozRequestFullScreen()
       |                               |                               |
       +-------------------------------+-------------------------------+
                                       |
       +-------------------------------+-------------------------------+
       |                               |                               |
       v                               v                               v
[Legacy Microsoft / IE]        [iOS Safari <video>]            [Fallback Mode]
element.msRequestFullscreen()  video.webkitEnterFullscreen()   CSS Pseudo-Fullscreen

The Fullscreen API underwent significant evolution before being standardized by the WHATWG. Older Safari releases, legacy Android WebViews, older Firefox builds, and Internet Explorer 11 all implemented their own proprietary method names and capitalization quirks (such as Mozilla's capital 'S' in mozRequestFullScreen).

A robust web application must implement an adapter layer that unifies these variants into a single, reliable API interface.

Technical Deep Dive & Specifications

The Vendor Prefix Taxonomy

The following matrix documents the complete historical taxonomy of Fullscreen methods, properties, and events:

+--------------------------------------------------------------------------------------------------------+
|                                    CROSS-BROWSER VENDOR MATRIX                                         |
+---------------------+-------------------------+------------------------+-------------------------------+
| Specification       | Request Method          | Exit Method            | Active Element Property       |
+---------------------+-------------------------+------------------------+-------------------------------+
| **WHATWG Standard** | `requestFullscreen()`   | `exitFullscreen()`     | `document.fullscreenElement`  |
| **WebKit (Safari)** | `webkitRequestFullscreen()`| `webkitExitFullscreen()`| `document.webkitFullscreenElement`|
| **Gecko (Firefox)** | `mozRequestFullScreen()`| `mozCancelFullScreen()`| `document.mozFullScreenElement`|
| **Trident (IE/Edge)**| `msRequestFullscreen()`| `msExitFullscreen()`   | `document.msFullscreenElement`|
+---------------------+-------------------------+------------------------+-------------------------------+

[!CAUTION] Notice the Capitalization Quirk in Mozilla:
Standard: requestFullscreen (lowercase 's')
WebKit: webkitRequestFullscreen (lowercase 's')
Gecko: mozRequestFullScreen (Uppercase 'S' in Screen!)
Gecko Exit: mozCancelFullScreen (Cancel instead of Exit!)

The iOS Safari Special Case

On Apple iOS (iPhones), Apple restricts arbitrary DOM elements (such as <div> or <canvas>) from entering native OS fullscreen mode to protect the mobile Safari navigation gesture model.

However, HTML5 <video> elements on iOS support a proprietary WebKit media method:

const video = document.querySelector('video');

if (video.webkitEnterFullscreen) {
  // Native iOS full-screen video player overlay
  video.webkitEnterFullscreen();
}

+-------------------------------------------------------------------------------+
|                            SAFARI PLATFORM BEHAVIOR                           |
+-----------------------+-------------------------------------------------------+
| Platform              | Fullscreen Capabilities                               |
+-----------------------+-------------------------------------------------------+
| **macOS Safari 16.4+**| Full standard WHATWG Fullscreen API on any DOM element|
| **iPadOS Safari 13+** | Supports standard `requestFullscreen()` on `<div>`    |
| **iOS iPhone Safari** | ❌ Blocked on `<div>` / `<canvas>`                    |
|                       | ✅ Supported on `<video>` via `webkitEnterFullscreen`  |
+-----------------------+-------------------------------------------------------+

Normalizing Fullscreen Lifecycle Events

To ensure event handlers fire reliably across all legacy rendering engines, your application should bind all vendor-prefixed event strings:

const FULLSCREEN_EVENTS = [
  'fullscreenchange',
  'webkitfullscreenchange',
  'mozfullscreenchange',
  'MSFullscreenChange'
];

FULLSCREEN_EVENTS.forEach(eventName => {
  document.addEventListener(eventName, onFullscreenStateChange, false);
});

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 124–182 (class FullscreenAdapter): Implements an enterprise helper encapsulating standard and vendor-prefixed methods (requestFullscreen, webkitRequestFullscreen, mozRequestFullScreen, msRequestFullscreen).
Line 137–146 (getActiveElement): Normalizes the active element property check across document.fullscreenElement, document.webkitFullscreenElement, document.mozFullScreenElement, and document.msFullscreenElement.
Line 160–168 (exit): Normalizes document-level exit methods, correctly accounting for Gecko's historical mozCancelFullScreen().
Line 170–178 (bindChange): Binds all legacy and standard change events to guarantee execution across older browsers.

Expected Browser Render Output

The table generates a live audit of your browser engine: modern Chrome and Edge show standard requestFullscreen and webkitRequestFullscreen as available.
Clicking "Toggle Fullscreen via Adapter" smoothly promotes the card using the highest-priority supported API.
The adapter log streams all transition timestamps seamlessly.

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

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

.container {
      max-width: 800px;
      width: 100%;
    }

.card {
      background: #1e293b;
      border: 1px solid #334155;
      border-radius: 12px;
      padding: 24px;
      margin-bottom: 24px;
    }

.card:fullscreen {
      background: #020617;
    }

.table-container {
      overflow-x: auto;
      margin-top: 16px;
    }

table {
      width: 100%;
      border-collapse: collapse;
      font-size: 0.85rem;
      font-family: monospace;
    }

th, td {
      padding: 10px;
      text-align: left;
      border-bottom: 1px solid #334155;
    }

th {
      background: #0f172a;
      color: #38bdf8;
    }

.status-ok { color: #34d399; font-weight: bold; }
    .status-no { color: #f87171; }

button {
      padding: 12px 20px;
      background: #3b82f6;
      border: none;
      border-radius: 6px;
      color: white;
      font-weight: 700;
      cursor: pointer;
      margin-top: 16px;
    }

button:hover { background: #2563eb; }

.log-box {
      background: #020617;
      border: 1px solid #1e293b;
      border-radius: 8px;
      padding: 16px;
      font-family: monospace;
      font-size: 0.85rem;
      color: #a5f3fc;
      max-height: 150px;
      overflow-y: auto;
    }
  </style>
</head>
<body>

<div class="container">
    <h1>Cross-Browser Fullscreen Adapter</h1>
    <p style="color: #94a3b8; margin: 8px 0 20px;">
      Automatic detection of standard vs vendor-prefixed Fullscreen capabilities.
    </p>

<div class="card" id="targetCard">
      <h2>🖥️ Target Presentation Surface</h2>
      <p style="color: #94a3b8; font-size: 0.9rem; margin-top: 8px;">
        Clicking below executes through our unified adapter wrapper.
      </p>

<div class="table-container">
        <table>
          <thead>
            <tr>
              <th>Method / Property Key</th>
              <th>Vendor Origin</th>
              <th>Detected on this Browser</th>
            </tr>
          </thead>
          <tbody id="vendorDetectionBody">
            
          </tbody>
        </table>
      </div>

<button id="adapterToggleBtn">Toggle Fullscreen via Adapter</button>
    </div>

<div class="log-box" id="adapterLog">> Initializing adapter engine...</div>
  </div>

static getActiveElement() {
        const doc = document;
        return (
          doc.fullscreenElement ||
          doc.webkitFullscreenElement ||
          doc.mozFullScreenElement ||
          doc.msFullscreenElement ||
          null
        );
      }

static async request(element) {
        if (element.requestFullscreen) {
          return element.requestFullscreen();
        } else if (element.webkitRequestFullscreen) {
          return element.webkitRequestFullscreen();
        } else if (element.mozRequestFullScreen) {
          return element.mozRequestFullScreen();
        } else if (element.msRequestFullscreen) {
          return element.msRequestFullscreen();
        } else if (element.webkitEnterFullscreen) {
          // iOS Safari Video Element Fallback
          return element.webkitEnterFullscreen();
        } else {
          throw new Error('Fullscreen API is not supported on this browser/element.');
        }
      }

static async exit() {
        const doc = document;
        if (doc.exitFullscreen) {
          return doc.exitFullscreen();
        } else if (doc.webkitExitFullscreen) {
          return doc.webkitExitFullscreen();
        } else if (doc.mozCancelFullScreen) {
          return doc.mozCancelFullScreen();
        } else if (doc.msExitFullscreen) {
          return doc.msExitFullscreen();
        } else {
          throw new Error('Exit fullscreen is not supported.');
        }
      }

static bindChange(callback) {
        const events = [
          'fullscreenchange',
          'webkitfullscreenchange',
          'mozfullscreenchange',
          'MSFullscreenChange'
        ];
        events.forEach(evt => document.addEventListener(evt, callback));
      }
    }

// =========================================================================
    // UI TEST HARNESS
    // =========================================================================
    const tableBody = document.getElementById('vendorDetectionBody');
    const logBox = document.getElementById('adapterLog');
    const toggleBtn = document.getElementById('adapterToggleBtn');
    const targetCard = document.getElementById('targetCard');

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

// Feature probe list
    const probes = [
      { key: 'requestFullscreen', origin: 'WHATWG Standard', obj: document.documentElement },
      { key: 'webkitRequestFullscreen', origin: 'WebKit / Blink', obj: document.documentElement },
      { key: 'mozRequestFullScreen', origin: 'Mozilla Gecko', obj: document.documentElement },
      { key: 'msRequestFullscreen', origin: 'Microsoft Trident', obj: document.documentElement },
      { key: 'fullscreenElement', origin: 'WHATWG Standard', obj: document },
      { key: 'webkitFullscreenElement', origin: 'WebKit', obj: document },
      { key: 'mozFullScreenElement', origin: 'Gecko', obj: document }
    ];

probes.forEach(probe => {
      const exists = probe.key in probe.obj;
      const row = document.createElement('tr');
      row.innerHTML = `
        <td>${probe.key}</td>
        <td>${probe.origin}</td>
        <td class="${exists ? 'status-ok' : 'status-no'}">${exists ? 'AVAILABLE (YES)' : 'UNDEFINED (NO)'}</td>
      `;
      tableBody.appendChild(row);
    });

log(`Fullscreen Supported: ${FullscreenAdapter.isSupported()}`);

// Wire up button via Adapter
    toggleBtn.addEventListener('click', async () => {
      try {
        if (!FullscreenAdapter.getActiveElement()) {
          log('Invoking FullscreenAdapter.request(targetCard)...');
          await FullscreenAdapter.request(targetCard);
        } else {
          log('Invoking FullscreenAdapter.exit()...');
          await FullscreenAdapter.exit();
        }
      } catch (err) {
        log(`Adapter Error: ${err.message}`);
      }
    });

// Unified Event listener via Adapter
    FullscreenAdapter.bindChange(() => {
      const active = FullscreenAdapter.getActiveElement();
      if (active) {
        log(`Active element detected: <${active.tagName.toLowerCase()} id="${active.id}">`);
        toggleBtn.textContent = 'Exit Fullscreen';
      } else {
        log('Adapter: Exited fullscreen mode.');
        toggleBtn.textContent = 'Toggle Fullscreen via Adapter';
      }
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Author an Enterprise-Grade Cross-Browser Fullscreen Adapter

Instructions:

Write a standalone utility function toggleElementFullscreen(targetEl) that:
- Evaluates standard and prefixed APIs.
- Gracefully handles iOS Safari video elements via .webkitEnterFullscreen().
- Returns a Promise resolving to a boolean indicating whether the element is now fullscreen (true) or windowed (false).
Attach this utility to a simulated video player container.
Add a fallback notification if the client platform is iOS and the target is a non-video element.

🏁 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: Standalone Fullscreen Adapter</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      padding: 30px;
      background: #0f172a;
      color: #f8fafc;
      display: flex;
      flex-direction: column;
      align-items: center;
    }
    .box {
      width: 360px;
      height: 220px;
      background: #1e293b;
      border: 2px solid #3b82f6;
      border-radius: 8px;
      padding: 24px;
      text-align: center;
      display: flex;
      flex-direction: column;
      justify-content: space-between;
    }
    .box:fullscreen { background: #020617; }
    button {
      padding: 10px 16px;
      background: #3b82f6;
      border: none;
      border-radius: 6px;
      color: white;
      font-weight: bold;
      cursor: pointer;
    }
    #statusOutput {
      margin-top: 20px;
      font-family: monospace;
      color: #38bdf8;
    }
  </style>
</head>
<body>

  <div class="box" id="testBox">
    <h3>Universal Adapter Target</h3>
    <p style="color: #94a3b8; font-size: 0.85rem;">Compatible across Blink, WebKit, Gecko, and Trident.</p>
    <button id="actionBtn">Launch Toggle</button>
  </div>

  <div id="statusOutput">State: Ready</div>

  <script>
    /**
     * Enterprise Cross-Browser Fullscreen Toggle
     * @param {HTMLElement} el 
     * @returns {Promise<boolean>} Resolves with true if entered, false if exited
     */
    async function toggleElementFullscreen(el) {
      const doc = document;
      const active = (
        doc.fullscreenElement ||
        doc.webkitFullscreenElement ||
        doc.mozFullScreenElement ||
        doc.msFullscreenElement
      );

      // 1. If currently fullscreen, exit
      if (active) {
        if (doc.exitFullscreen) await doc.exitFullscreen();
        else if (doc.webkitExitFullscreen) await doc.webkitExitFullscreen();
        else if (doc.mozCancelFullScreen) await doc.mozCancelFullScreen();
        else if (doc.msExitFullscreen) await doc.msExitFullscreen();
        return false;
      }

      // 2. iOS iPhone Video Check
      const isIPhone = /iPhone|iPod/.test(navigator.userAgent);
      if (isIPhone && !(el instanceof HTMLVideoElement)) {
        throw new Error('iOS Safari restricts Fullscreen to <video> elements only.');
      }

      // 3. Request Fullscreen with vendor fallback
      if (el.requestFullscreen) {
        await el.requestFullscreen();
      } else if (el.webkitRequestFullscreen) {
        await el.webkitRequestFullscreen();
      } else if (el.mozRequestFullScreen) {
        await el.mozRequestFullScreen();
      } else if (el.msRequestFullscreen) {
        await el.msRequestFullscreen();
      } else if (el.webkitEnterFullscreen) {
        el.webkitEnterFullscreen();
      } else {
        throw new Error('Fullscreen API is not supported on this platform.');
      }

      return true;
    }

    const testBox = document.getElementById('testBox');
    const actionBtn = document.getElementById('actionBtn');
    const statusOutput = document.getElementById('statusOutput');

    actionBtn.addEventListener('click', async () => {
      try {
        const isNowFs = await toggleElementFullscreen(testBox);
        statusOutput.textContent = `State: ${isNowFs ? 'FULLSCREEN' : 'WINDOWED'}`;
        actionBtn.textContent = isNowFs ? 'Exit Fullscreen' : 'Launch Toggle';
      } catch (err) {
        alert(err.message);
      }
    });
  </script>
</body>
</html>

Why this works:

The helper provides an asynchronous Promise-based contract that returns a clean boolean state (true on entry, false on exit).
It handles iOS device detection and gracefully executes the exact vendor-prefixed entry and exit functions required by the host environment.

⚠️ Common Pitfalls

Misspelling Gecko's mozRequestFullScreen: Note the capital 'S' in Screen for Mozilla. Writing mozRequestFullscreen will fail silently as undefined.
Assuming iOS Safari Supports Fullscreen <div>s: Testing only on desktop Chrome will hide the fact that iPhones reject <div>.requestFullscreen(). Always design a graceful CSS modal fallback for iPhone users.
Using Legacy MS Events Without Vendor Prefix: Internet Explorer 11 requires MSFullscreenChange with an uppercase MS.

💡 Pro Tips

Implement Fallback CSS Pseudo-Fullscreen: When FullscreenAdapter.isSupported() returns false (e.g. iPhone Safari), apply a CSS class .pseudo-fullscreen { position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; z-index: 999999; } to simulate fullscreen within the browser tab.
Adopt Modern Standards First: Always check standard requestFullscreen as the first branch in your conditional chain, falling back to prefixes only if the standard method is undefined.

📌 Key Takeaways

Older browsers required vendor prefixes: WebKit (webkit), Mozilla (moz), and Microsoft (ms).
Mozilla Gecko used mozRequestFullScreen (capital 'S') and mozCancelFullScreen (Cancel instead of Exit).
iOS Safari on iPhones only supports fullscreen on <video> elements via webkitEnterFullscreen().
Normalizing event listeners requires binding fullscreenchange, webkitfullscreenchange, mozfullscreenchange, and MSFullscreenChange.
Wrapping API calls in a unified TypeScript/ES6 adapter ensures bulletproof cross-device execution.
--

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

? Question 1 / 3

What is the unique capitalization difference in Mozilla Gecko's legacy fullscreen request method?

Topic: HTML Fundamentals

? Question 2 / 3

What restriction exists when using the Fullscreen API on iPhone Safari?

Topic: HTML Fundamentals

? Question 3 / 3

What was the legacy exit method name in Mozilla Gecko?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Vendor Prefix Taxonomy

The iOS Safari Special Case

Normalizing Fullscreen Lifecycle Events

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Author an Enterprise-Grade Cross-Browser Fullscreen Adapter

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the unique capitalization difference in Mozilla Gecko's legacy fullscreen request method?

What restriction exists when using the Fullscreen API on iPhone Safari?

What was the legacy exit method name in Mozilla Gecko?