Chapter 55: Screen Orientation & Device APIs

Locking Screen Orientation

Control viewport rotation programmatically with `screen.orientation.lock()`, understand fullscreen prerequisites, and handle cross-browser security constraints.

LEARNING OBJECTIVES ⌵

Programmatically lock the display orientation using screen.orientation.lock() with specific lock types (landscape, portrait, any, natural).
Understand why calling lock() requires a Fullscreen API state or standalone PWA context.
Handle DOMException error types (NotSupportedError, SecurityError, AbortError) with asynchronous try...catch blocks.
Programmatically unlock orientation using screen.orientation.unlock() during cleanup routines.

🎬 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 a passenger sitting on a high-speed train playing a flight simulator on their tablet. As the train sways around sharp mountain curves, the tablet's physical accelerometer thinks the device is rotating and continuously flips the game viewport upside down and sideways, breaking the flight controls.

                      +----------------------------------+
                      |       USER ENTERS FULLSCREEN     |
                      |  document.documentElement        |
                      |    .requestFullscreen()          |
                      +----------------------------------+
                                       │
                                       ▼
                      +----------------------------------+
                      |     REQUEST ORIENTATION LOCK     |
                      |  screen.orientation.lock(        |
                      |    'landscape-primary'           |
                      |  )                               |
                      +----------------------------------+
                                       │
                   ┌───────────────────┴───────────────────┐
                   ▼                                       ▼
        [ PROMISE RESOLVES ✅ ]                  [ PROMISE REJECTS ❌ ]
        - Hardware display is                   - Not in Fullscreen
          pinned to landscape                   - User denied permission
        - OS ignores physical tilts             - OS/Browser unsupported (iOS)

To prevent unwanted display rotation in games, video players, and VR experiences, browsers provide screen.orientation.lock(). However, because locking the entire screen orientation takes control away from the user, browsers enforce strict security boundaries: your web app can only lock the orientation if it has received user interaction and entered Fullscreen mode or is installed as a Progressive Web App (PWA).

Technical Deep Dive & Specifications

The `lock()` Method Signature & Parameters

The lock() method returns a standard JavaScript Promise that resolves with undefined when the lock is active or rejects with a DOMException if the lock fails:

screen.orientation.lock(orientationLockType: OrientationLockType): Promise<void>;
screen.orientation.unlock(): void;

type OrientationLockType = 
  | "any"                  // Unlocks any orientation (both portrait and landscape)
  | "natural"              // Natural hardware baseline (portrait on phones, landscape on PCs)
  | "landscape"            // Either landscape-primary or landscape-secondary
  | "portrait"             // Either portrait-primary or portrait-secondary
  | "portrait-primary"     // Upright portrait only
  | "portrait-secondary"   // Inverted portrait only
  | "landscape-primary"    // Sideways landscape only
  | "landscape-secondary"; // Inverted sideways landscape only

The Orientation Lock Type Hierarchy

                                  [ ANY ]
                    (Allows all 4 physical rotations)
                                     │
                 ┌───────────────────┴───────────────────┐
                 ▼                                       ▼
           [ PORTRAIT ]                            [ LANDSCAPE ]
        (0° or 180° only)                       (90° or 270° only)
           │          │                            │          │
     ┌─────┘          └─────┐                ┌─────┘          └─────┐
     ▼                      ▼                ▼                      ▼
[ portrait-primary ]  [ portrait-secondary ] [ landscape-primary ]  [ landscape-secondary ]
    (Upright)            (Inverted)              (Rotated 90°)          (Rotated 270°)

Security & Prerequisite Requirements Matrix

Why does screen.orientation.lock() fail? Browsers enforce three strict prerequisites:

Requirement	Why It Is Mandated	Result if Missing
Secure Context (HTTPS)	Prevents man-in-the-middle scripts from hijacking display controls.	Throws `SecurityError`
Fullscreen Mode or Installed PWA	A standard web tab cannot hijack the entire OS screen unless the user agreed to full immersion.	Throws `NotSupportedError` / `SecurityError`
Transient User Activation	Must be triggered inside a click, tap, or touch event handler.	Throws `SecurityError`

`DOMException` Error Handling Reference

try {
  await screen.orientation.lock('landscape');
} catch (error) {
  switch (error.name) {
    case 'NotSupportedError':
      console.warn('Orientation locking not supported on this device/browser.');
      break;
    case 'SecurityError':
      console.warn('Locked out: Must enter Fullscreen or run as installed PWA.');
      break;
    case 'AbortError':
      console.warn('Lock request was aborted by another concurrent orientation change.');
      break;
    default:
      console.error('Orientation lock failed:', error);
  }
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Lines 134–146: Manages entering and exiting Fullscreen mode via document.documentElement.requestFullscreen(), fulfilling the mandatory browser prerequisite.
Lines 149–153: Evaluates feature detection for screen.orientation.lock to prevent fatal runtime errors on iOS Safari or legacy browsers.
Lines 155–158: Executes await screen.orientation.lock(lockMode) inside an asynchronous try...catch wrapper.
Lines 159–165: Catches specific DOMException types (SecurityError, NotSupportedError) and gives actionable diagnostic feedback.
Lines 174–180: Calls screen.orientation.unlock() to release hardware display constraints, restoring natural OS sensor responsiveness.

Expected Browser Render Output

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 55.2 - Orientation Lock Controller</title>
  <style>
    :root {
      --bg: #090d16;
      --card: #131c2e;
      --accent: #38bdf8;
      --text: #f1f5f9;
      --muted: #94a3b8;
      --border: #1e293b;
      --success: #10b981;
      --danger: #ef4444;
    }
    * { box-sizing: border-box; margin: 0; padding: 0; }
    body {
      font-family: system-ui, -apple-system, sans-serif;
      background: var(--bg);
      color: var(--text);
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      padding: 1.5rem;
    }
    .container {
      background: var(--card);
      border: 1px solid var(--border);
      border-radius: 16px;
      padding: 2rem;
      max-width: 560px;
      width: 100%;
      box-shadow: 0 20px 40px rgba(0,0,0,0.4);
    }
    h1 {
      font-size: 1.4rem;
      color: var(--accent);
      margin-bottom: 0.5rem;
    }
    p.desc {
      color: var(--muted);
      font-size: 0.85rem;
      margin-bottom: 1.5rem;
    }
    .status-badge {
      display: inline-flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.4rem 0.8rem;
      border-radius: 9999px;
      font-size: 0.8rem;
      font-weight: 600;
      background: rgba(56, 189, 248, 0.1);
      color: var(--accent);
      border: 1px solid rgba(56, 189, 248, 0.3);
      margin-bottom: 1.5rem;
    }
    .button-grid {
      display: grid;
      grid-template-columns: repeat(2, 1fr);
      gap: 0.75rem;
      margin-bottom: 1.5rem;
    }
    button {
      background: #1e293b;
      color: var(--text);
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 0.75rem 1rem;
      font-size: 0.85rem;
      font-weight: 600;
      cursor: pointer;
      transition: all 0.2s;
    }
    button:hover:not(:disabled) {
      background: var(--accent);
      color: #090d16;
      border-color: var(--accent);
    }
    button.primary {
      background: var(--accent);
      color: #090d16;
      border: none;
      grid-column: span 2;
    }
    button.unlock {
      background: rgba(239, 68, 68, 0.15);
      color: #fca5a5;
      border: 1px solid rgba(239, 68, 68, 0.4);
      grid-column: span 2;
    }
    button.unlock:hover:not(:disabled) {
      background: var(--danger);
      color: #fff;
    }
    .console-log {
      background: #050811;
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 0.8rem;
      font-family: ui-monospace, monospace;
      font-size: 0.8rem;
      color: #cbd5e1;
      height: 120px;
      overflow-y: auto;
    }
  </style>
</head>
<body>

<main class="container" id="app-root">
    <h1>🔒 Screen Orientation Lock</h1>
    <p class="desc">Locking screen orientation requires Fullscreen mode on mobile web browsers.</p>

<div class="status-badge" id="current-state">
      <span>Current:</span> <strong id="state-text">portrait-primary (0°)</strong>
    </div>

<div class="button-grid">
      <button class="primary" id="btn-fullscreen">1️⃣ Enter Fullscreen Mode</button>
      <button id="btn-lock-landscape">🔒 Lock Landscape</button>
      <button id="btn-lock-portrait">🔒 Lock Portrait</button>
      <button id="btn-lock-land-pri">🔒 Lock Landscape-Primary</button>
      <button id="btn-lock-natural">🔒 Lock Natural</button>
      <button class="unlock" id="btn-unlock">🔓 Unlock Orientation</button>
    </div>

<div class="console-log" id="console-output">System ready. Enter fullscreen before locking.</div>
  </main>

function updateState() {
      if (window.screen && window.screen.orientation) {
        stateText.textContent = `${screen.orientation.type} (${screen.orientation.angle}°)`;
      }
    }

// Toggle Fullscreen
    btnFullscreen.addEventListener('click', async () => {
      try {
        if (!document.fullscreenElement) {
          await document.documentElement.requestFullscreen();
          btnFullscreen.textContent = '🚪 Exit Fullscreen Mode';
          log('Entered Fullscreen mode.', 'success');
        } else {
          await document.exitFullscreen();
          btnFullscreen.textContent = '1️⃣ Enter Fullscreen Mode';
          log('Exited Fullscreen mode.', 'info');
        }
      } catch (err) {
        log(`Fullscreen Error: ${err.message}`, 'error');
      }
    });

// Orientation Lock Helper
    async function applyOrientationLock(lockMode) {
      if (!('orientation' in screen && 'lock' in screen.orientation)) {
        log('screen.orientation.lock() is not supported on this browser/platform (e.g. iOS Safari).', 'error');
        return;
      }

try {
        log(`Requesting lock("${lockMode}")...`);
        await screen.orientation.lock(lockMode);
        log(`Successfully locked to "${lockMode}".`, 'success');
        updateState();
      } catch (error) {
        if (error.name === 'SecurityError' || error.name === 'NotSupportedError') {
          log(`${error.name}: Must enter Fullscreen mode before locking orientation.`, 'error');
        } else {
          log(`${error.name}: ${error.message}`, 'error');
        }
      }
    }

// Bind Button Handlers
    document.getElementById('btn-lock-landscape').addEventListener('click', () => applyOrientationLock('landscape'));
    document.getElementById('btn-lock-portrait').addEventListener('click', () => applyOrientationLock('portrait'));
    document.getElementById('btn-lock-land-pri').addEventListener('click', () => applyOrientationLock('landscape-primary'));
    document.getElementById('btn-lock-natural').addEventListener('click', () => applyOrientationLock('natural'));

// Unlock
    btnUnlock.addEventListener('click', () => {
      if ('orientation' in screen && 'unlock' in screen.orientation) {
        screen.orientation.unlock();
        log('Orientation unlocked. Free device rotation restored.', 'info');
        updateState();
      }
    });

if (window.screen && window.screen.orientation) {
      screen.orientation.addEventListener('change', updateState);
      updateState();
    }
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🔒 Screen Orientation Lock
Locking screen orientation requires Fullscreen mode on mobile web browsers.

[ Current: portrait-primary (0°) ]

[ 1️⃣ Enter Fullscreen Mode                                      ]
[ 🔒 Lock Landscape       ] [ 🔒 Lock Portrait                 ]
[ 🔒 Lock Landscape-Primary] [ 🔒 Lock Natural                  ]
[ 🔓 Unlock Orientation                                        ]

System ready. Enter fullscreen before locking.
[10:20:10 AM] ℹ️ Requesting lock("landscape")...
[10:20:10 AM] ❌ SecurityError: Must enter Fullscreen mode before locking orientation.

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Auto-Locking Arcade Game Launcher

Instructions:

Build an HTML page with a "Launch Arcade Mode" button.
When the user clicks the button:
- Request Fullscreen on the game canvas container.
- Attempt to lock the orientation to 'landscape-primary'.
- If lock() fails (e.g. on desktop or iOS), fall back gracefully by rendering an in-game UI notification asking the player to turn their device.
When the user exits fullscreen (listens to fullscreenchange), automatically unlock the orientation via screen.orientation.unlock().

🏁 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>Arcade Game Launcher</title>
  <style>
    :root {
      --bg: #030712;
      --accent: #f59e0b;
      --text: #f9fafb;
    }
    * { box-sizing: border-box; margin: 0; padding: 0; }
    body {
      font-family: system-ui, -apple-system, sans-serif;
      background: var(--bg);
      color: var(--text);
      height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
    }
    #game-stage {
      background: #111827;
      border: 2px solid #374151;
      border-radius: 16px;
      padding: 3rem;
      text-align: center;
      max-width: 480px;
      width: 90%;
    }
    h1 { font-size: 2rem; color: var(--accent); margin-bottom: 1rem; }
    p { color: #9ca3af; margin-bottom: 2rem; }
    button {
      background: var(--accent);
      color: #030712;
      border: none;
      padding: 1rem 2rem;
      border-radius: 8px;
      font-size: 1.1rem;
      font-weight: 700;
      cursor: pointer;
    }
    #game-canvas {
      display: none;
      background: #000;
      width: 100vw;
      height: 100vh;
      justify-content: center;
      align-items: center;
      flex-direction: column;
    }
    #game-canvas.active {
      display: flex;
    }
    .hud {
      color: #10b981;
      font-family: monospace;
      font-size: 1.5rem;
      margin-top: 1rem;
    }
  </style>
</head>
<body>

  <div id="game-stage">
    <h1>🚀 Retro Asteroids</h1>
    <p>Landscape orientation locked during high-intensity arcade battles.</p>
    <button id="launch-btn">🎮 Launch Arcade Mode</button>
  </div>

  <div id="game-canvas">
    <h2 style="color: #38bdf8;">👾 GAME IN PROGRESS (LANDSCAPE)</h2>
    <div class="hud">SCORE: 9940 | LIVES: 3</div>
    <button id="exit-btn" style="margin-top: 2rem; background: #ef4444; color: #fff;">Exit Game</button>
  </div>

  <script>
    const stage = document.getElementById('game-stage');
    const canvas = document.getElementById('game-canvas');
    const launchBtn = document.getElementById('launch-btn');
    const exitBtn = document.getElementById('exit-btn');

    async function launchArcade() {
      try {
        // Step 1: Request Fullscreen
        if (canvas.requestFullscreen) {
          await canvas.requestFullscreen();
        }

        // Step 2: Show game canvas
        stage.style.display = 'none';
        canvas.classList.add('active');

        // Step 3: Lock Screen Orientation
        if ('orientation' in screen && 'lock' in screen.orientation) {
          await screen.orientation.lock('landscape-primary');
          console.log('✅ Display locked to landscape-primary');
        } else {
          console.warn('⚠️ Orientation lock API unsupported on this device.');
        }
      } catch (err) {
        console.error('Launch Error:', err);
      }
    }

    function cleanupGame() {
      // Step 1: Unlock Orientation
      if ('orientation' in screen && 'unlock' in screen.orientation) {
        screen.orientation.unlock();
        console.log('🔓 Orientation unlocked.');
      }
      // Step 2: Restore UI
      canvas.classList.remove('active');
      stage.style.display = 'block';
    }

    launchBtn.addEventListener('click', launchArcade);

    exitBtn.addEventListener('click', () => {
      if (document.fullscreenElement) {
        document.exitFullscreen();
      }
    });

    // Cleanup whenever Fullscreen is dismissed
    document.addEventListener('fullscreenchange', () => {
      if (!document.fullscreenElement) {
        cleanupGame();
      }
    });
  </script>
</body>
</html>

Why this works:

Bundling requestFullscreen() directly prior to screen.orientation.lock('landscape-primary') satisfies browser security prerequisites.
Hooking the global fullscreenchange event guarantees that if the user hits Escape, pulls down the notification tray, or taps the exit button, screen.orientation.unlock() is unconditionally executed.

⚠️ Common Pitfalls

Invoking lock() Outside Fullscreen or PWA Mode: Calling screen.orientation.lock() on a standard un-fullscreened web page will trigger an unhandled Promise rejection with SecurityError or NotSupportedError.
Forgetting iOS Safari Incompatibility: As of modern iOS versions, Apple WebKit does not implement screen.orientation.lock(). Never assume the promise exists without checking 'lock' in screen.orientation.
Failing to Unlock on Exit: If you lock the screen inside an experience and forget to call unlock(), the user may remain trapped in landscape orientation even after closing your modal dialog.

💡 Pro Tips

Declare Orientation in Web App Manifest: For Progressive Web Apps, you can declaratively enforce orientation without writing JavaScript by adding "orientation": "landscape" or "orientation": "portrait" inside your manifest.json.
Handle Transient Abort Rejections: If a user violently flips their phone while lock() is executing, the browser may reject with an AbortError. Always wrap your lock() call in a resilient try...catch block.

📌 Key Takeaways

screen.orientation.lock() locks the browser display to a chosen orientation subtype (e.g. 'landscape', 'portrait-primary').
Programmatic locking strictly requires a Fullscreen state or an Installed PWA context.
screen.orientation.unlock() releases hardware display locking and restores normal accelerometer orientation tracking.
Always handle NotSupportedError, SecurityError, and AbortError DOMException rejections.
Always tie orientation unlocking to the fullscreenchange event.
--

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

? Question 1 / 3

What is the required prerequisite for a regular mobile browser tab before calling `screen.orientation.lock()`?

Topic: HTML Fundamentals

? Question 2 / 3

Which lock parameter value locks the screen into landscape mode while allowing the user to rotate between $90^\circ$ and $270^\circ$ sideways?

Topic: HTML Fundamentals

? Question 3 / 3

What method should be called to restore the device to its normal free-rotating behavior?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The lock() Method Signature & Parameters

The Orientation Lock Type Hierarchy

Security & Prerequisite Requirements Matrix

DOMException Error Handling Reference

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Auto-Locking Arcade Game Launcher

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the required prerequisite for a regular mobile browser tab before calling screen.orientation.lock()?

Which lock parameter value locks the screen into landscape mode while allowing the user to rotate between $90^\circ$ and $270^\circ$ sideways?

What method should be called to restore the device to its normal free-rotating behavior?

The `lock()` Method Signature & Parameters

`DOMException` Error Handling Reference

What is the required prerequisite for a regular mobile browser tab before calling `screen.orientation.lock()`?