Chapter 55: Screen Orientation & Device APIs

The Battery Status API

Monitor device power telemetry, charging states, and energy depletion rates with `navigator.getBattery()` to engineer adaptive power-saving web experiences.

LEARNING OBJECTIVES ⌵

Query hardware battery status asynchronously using navigator.getBattery().
Inspect and interpret charging, level, chargingTime, and dischargingTime properties on the BatteryManager interface.
Listen to real-time power state transitions using levelchange and chargingchange events.
Implement an adaptive energy-saving UI mode that automatically downgrades CPU/GPU load when the device is low on battery.
Understand why Firefox and Safari removed the Battery Status API due to hardware fingerprinting concerns.

🎬 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 driving an electric vehicle on a long cross-country road trip. When the battery drops below $15%$, the car's dashboard automatically enters "Eco-Mode": it dims the cabin displays, throttles air conditioning, and reroutes navigation to the nearest fast charger.

                    [ DEVICE HARDWARE BATTERY GAUGE ]
                                   │
                                   ▼
                    +─────────────────────────────+
                    │    navigator.getBattery()   │
                    │   (Resolves BatteryManager) │
                    +─────────────────────────────+
                                   │
                ┌──────────────────┴──────────────────┐
                ▼                                     ▼
      [ POWER TELEMETRY ]                    [ LIFECYCLE EVENTS ]
      - .charging (true/false)               - 'chargingchange'
      - .level (0.0 to 1.0)                  - 'levelchange'
      - .chargingTime (seconds)              - 'chargingtimechange'
      - .dischargingTime (seconds)           - 'dischargingtimechange'
                │                                     │
                └──────────────────┬──────────────────┘
                                   │
                                   ▼
                +─────────────────────────────────────+
                │      ADAPTIVE WEB ARCHITECTURE      │
                │ • Low Power (<20% & Discharging):   │
                │   - Throttle 60fps canvas to 30fps  │
                │   - Disable heavy CSS blur filters  │
                │   - Pause background polling        │
                │ • High Power (Charging / 100%):     │
                │   - Full 120fps animations & WebGL  │
                +─────────────────────────────────────+

The W3C Battery Status API exposes this same power intelligence to client-side web applications. Instead of blindly running intensive animations, WebGL shaders, or heavy background network polling, your app can gracefully adapt to the user's real-world power constraints.

Technical Deep Dive & Specifications

The `BatteryManager` Interface

Invoking navigator.getBattery() returns a Promise that resolves with a BatteryManager instance:

interface Navigator {
  getBattery?(): Promise<BatteryManager>;
}

interface BatteryManager extends EventTarget {
  readonly attribute boolean charging;
  readonly attribute double chargingTime;    // Seconds until 100% (or 0 / Infinity)
  readonly attribute double dischargingTime; // Seconds until 0% (or Infinity)
  readonly attribute double level;           // 0.0 (0%) to 1.0 (100%)

  attribute EventHandler onchargingchange;
  attribute EventHandler onchargingtimechange;
  attribute EventHandler ondischargingtimechange;
  attribute EventHandler onlevelchange;
}

Telemetry Properties Matrix

Property	Type	Range / Format	Behavior & Edge Cases
`level`	`number`	`0.0` to `1.0`	`1.0` represents $100%$, `0.5` represents $50%$. Updated in discrete steps by the OS.
`charging`	`boolean`	`true` or `false`	`true` if connected to AC/USB power, `false` if running on battery.
`chargingTime`	`number`	Seconds or `Infinity`	Seconds until battery is full. If fully charged, returns `0`. If discharging or unable to calculate, returns `Infinity`.
`dischargingTime`	`number`	Seconds or `Infinity`	Seconds until battery is empty. If charging or unable to estimate, returns `Infinity`.

The Four Reactive Event Listeners

+---------------------------------------------------------------------------------------------------+
|                                BATTERYMANAGER EVENT DISPATCH PIPELINE                             |
+---------------------------------------------------------------------------------------------------+
|                                                                                                   |
|  [ User Plugs In Charger ] ──────────────► 'chargingchange' (battery.charging = true)            |
|                                                                                                   |
|  [ Charge Percentage Drops ] ────────────► 'levelchange' (battery.level: 0.85 -> 0.84)            |
|                                                                                                   |
|  [ OS Recalculates Charge Time ] ────────► 'chargingtimechange' (battery.chargingTime updated)    |
|                                                                                                   |
|  [ OS Recalculates Drain Time ] ─────────► 'dischargingtimechange' (battery.dischargingTime)     |
|                                                                                                   |
+---------------------------------------------------------------------------------------------------+

The Privacy & Fingerprinting Controversy

[!WARNING] Browser Support Status: In 2016, security researchers demonstrated that the combination of high-precision level (e.g. 0.562341) and dischargingTime created a unique short-term tracking fingerprint across incognito sessions. As a result:

Mozilla Firefox: Removed the API in Firefox 52.

Apple Safari / WebKit: Never implemented the API.

Chromium (Chrome, Edge, Brave, Opera, Samsung Internet): Retained support, but rounds values (e.g., level quantized to 2 decimal places) and restricts access in cross-origin iframes.

Always test if ('getBattery' in navigator) before calling!

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Lines 131–137: Formats raw seconds into human-readable hours and minutes strings (e.g. 2h 15m), safely guarding against Infinity.
Lines 139–153: Converts the fractional battery.level ($0.0 \dots 1.0$) into an integer percentage and dynamically changes the battery bar color (Green $\to$ Amber $\to$ Red).
Lines 156–164: Checks battery.charging and toggles the charging lightning bolt icon.
Lines 169–178: Implements the Eco-Mode trigger: when the battery is $\le 20%$ and not charging, the application enters an energy-saving state.
Lines 181–188: Evaluates 'getBattery' in navigator to gracefully fail on unsupported browsers (Firefox, Safari).
Lines 195–198: Binds listeners to all four core battery lifecycle events (chargingchange, levelchange, chargingtimechange, dischargingtimechange).

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.6 - Battery Power Monitor & Eco-Engine</title>
  <style>
    :root {
      --bg: #090d16;
      --card: #131c2e;
      --accent: #38bdf8;
      --text: #f1f5f9;
      --muted: #94a3b8;
      --border: #1e293b;
      --bat-full: #10b981;
      --bat-mid: #f59e0b;
      --bat-low: #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;
    }
    .panel {
      background: var(--card);
      border: 1px solid var(--border);
      border-radius: 16px;
      padding: 2rem;
      max-width: 520px;
      width: 100%;
      box-shadow: 0 20px 40px rgba(0,0,0,0.5);
    }
    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; }

/* Animated Battery Pill Graphic */
    .battery-container {
      display: flex;
      align-items: center;
      justify-content: center;
      margin-bottom: 1.5rem;
    }
    .battery-shell {
      width: 160px;
      height: 70px;
      border: 4px solid #475569;
      border-radius: 12px;
      padding: 4px;
      position: relative;
      background: #0b1120;
    }
    .battery-terminal {
      width: 8px;
      height: 28px;
      background: #475569;
      border-radius: 0 4px 4px 0;
      margin-left: 2px;
    }
    .battery-fill {
      height: 100%;
      width: 50%;
      background: var(--bat-full);
      border-radius: 6px;
      transition: width 0.4s ease, background 0.4s ease;
      display: flex;
      align-items: center;
      justify-content: center;
      font-weight: 800;
      font-size: 1.1rem;
      color: #090d16;
    }
    .charging-bolt {
      position: absolute;
      right: -25px;
      top: 15px;
      font-size: 1.8rem;
      display: none;
    }
    .charging-bolt.active { display: block; }

.metrics-grid {
      display: grid;
      grid-template-columns: repeat(2, 1fr);
      gap: 0.75rem;
      margin-bottom: 1.5rem;
    }
    .metric-box {
      background: #080c16;
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 0.8rem;
    }
    .metric-label { font-size: 0.75rem; color: var(--muted); margin-bottom: 0.2rem; }
    .metric-val { font-size: 1.1rem; font-weight: 700; font-family: ui-monospace, monospace; color: var(--accent); }

.eco-banner {
      background: rgba(245, 158, 11, 0.1);
      border: 1px solid rgba(245, 158, 11, 0.3);
      color: #fde68a;
      border-radius: 8px;
      padding: 0.8rem 1rem;
      font-size: 0.85rem;
      display: flex;
      align-items: center;
      gap: 0.5rem;
    }
  </style>
</head>
<body>

<main class="panel">
    <h1>🔋 Battery Status & Eco Engine</h1>
    <p class="desc">Real-time hardware power diagnostics and adaptive workload throttling.</p>

<div class="metrics-grid">
      <div class="metric-box">
        <div class="metric-label">Power Source</div>
        <div id="val-charging" class="metric-val">Checking...</div>
      </div>
      <div class="metric-box">
        <div class="metric-label">Battery Level</div>
        <div id="val-level" class="metric-val">--%</div>
      </div>
      <div class="metric-box">
        <div class="metric-label">Time to Full</div>
        <div id="val-charge-time" class="metric-val">--</div>
      </div>
      <div class="metric-box">
        <div class="metric-label">Time Remaining</div>
        <div id="val-discharge-time" class="metric-val">--</div>
      </div>
    </div>

<div id="eco-status" class="eco-banner">
      <span>🌱 Eco-Mode: Standby (High-Performance Animation Active)</span>
    </div>
  </main>

// Set battery color depending on level
      if (pct > 50) {
        batFill.style.background = 'var(--bat-full)';
      } else if (pct > 20) {
        batFill.style.background = 'var(--bat-mid)';
      } else {
        batFill.style.background = 'var(--bat-low)';
      }

// Charging status
      if (battery.charging) {
        valCharging.textContent = 'Plugged In (AC)';
        valCharging.style.color = '#10b981';
        boltIcon.classList.add('active');
      } else {
        valCharging.textContent = 'On Battery';
        valCharging.style.color = '#f59e0b';
        boltIcon.classList.remove('active');
      }

valChargeTime.textContent = formatTime(battery.chargingTime);
      valDischargeTime.textContent = formatTime(battery.dischargingTime);

// Adaptive Power-Saving Logic
      if (pct <= 20 && !battery.charging) {
        ecoStatus.style.background = 'rgba(239, 68, 68, 0.15)';
        ecoStatus.style.borderColor = '#ef4444';
        ecoStatus.style.color = '#fca5a5';
        ecoStatus.innerHTML = '⚠️ <strong>ECO-MODE ACTIVE:</strong> Animations throttled to save power.';
      } else {
        ecoStatus.style.background = 'rgba(16, 185, 129, 0.1)';
        ecoStatus.style.borderColor = '#10b981';
        ecoStatus.style.color = '#86efac';
        ecoStatus.innerHTML = '⚡ <strong>PERFORMANCE MODE:</strong> Normal operation.';
      }
    }

async function initBattery() {
      if (!('getBattery' in navigator)) {
        valCharging.textContent = 'Unsupported';
        valCharging.style.color = '#ef4444';
        ecoStatus.innerHTML = 'ℹ️ Battery Status API not supported (e.g. Safari / Firefox for privacy).';
        return;
      }

try {
        const battery = await navigator.getBattery();
        updateBatteryUI(battery);

// Attach live listeners
        battery.addEventListener('chargingchange', () => updateBatteryUI(battery));
        battery.addEventListener('levelchange', () => updateBatteryUI(battery));
        battery.addEventListener('chargingtimechange', () => updateBatteryUI(battery));
        battery.addEventListener('dischargingtimechange', () => updateBatteryUI(battery));
      } catch (err) {
        console.error('Battery API Error:', err);
      }
    }

initBattery();
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🔋 Battery Status & Eco Engine
Real-time hardware power diagnostics and adaptive workload throttling.

             ┌───────────────────────┐
             │ [████████████]   85%  │ ▌ ⚡
             └───────────────────────┘

POWER SOURCE                     BATTERY LEVEL
Plugged In (AC)                  85%

TIME TO FULL                     TIME REMAINING
25 mins                          N/A

⚡ PERFORMANCE MODE: Normal operation.

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Adaptive WebGL / Canvas Frame Rate Governor

Instructions:

Create a dynamic Canvas animation loop driven by requestAnimationFrame.
Inspect the device battery state via navigator.getBattery().
If battery.level <= 0.20 && !battery.charging:
- Throttle the Canvas frame rate to 15 FPS.
- Display a "Power Saver: 15 FPS" indicator.
If battery.charging or battery.level > 0.20:
- Run at full 60 FPS.

🏁 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>Adaptive Frame Governor</title>
  <style>
    body {
      background: #090d16;
      color: #f1f5f9;
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      min-height: 100vh;
      margin: 0;
      font-family: system-ui, sans-serif;
    }
    canvas {
      background: #0f172a;
      border: 2px solid #334155;
      border-radius: 12px;
      margin-top: 1rem;
    }
    .badge {
      padding: 0.4rem 1rem;
      border-radius: 9999px;
      font-weight: 700;
      font-size: 0.9rem;
      margin-top: 0.5rem;
    }
    .full { background: rgba(16, 185, 129, 0.2); color: #10b981; border: 1px solid #10b981; }
    .eco { background: rgba(239, 68, 68, 0.2); color: #ef4444; border: 1px solid #ef4444; }
  </style>
</head>
<body>

  <h1>🎮 Battery-Adaptive Canvas Engine</h1>
  <div id="fps-badge" class="badge full">Target FPS: 60 (Normal)</div>
  <canvas id="game-canvas" width="400" height="200"></canvas>

  <script>
    const canvas = document.getElementById('game-canvas');
    const ctx = canvas.getContext('2d');
    const badge = document.getElementById('fps-badge');

    let targetFps = 60;
    let lastFrameTime = 0;
    let ballX = 50;
    let ballSpeed = 3;

    async function setupBatteryGovernor() {
      if (!('getBattery' in navigator)) return;

      const battery = await navigator.getBattery();

      function evaluatePower() {
        if (battery.level <= 0.20 && !battery.charging) {
          targetFps = 15;
          badge.textContent = 'Target FPS: 15 (Eco-Mode Active)';
          badge.className = 'badge eco';
        } else {
          targetFps = 60;
          badge.textContent = 'Target FPS: 60 (Normal)';
          badge.className = 'badge full';
        }
      }

      battery.addEventListener('levelchange', evaluatePower);
      battery.addEventListener('chargingchange', evaluatePower);
      evaluatePower();
    }

    function renderLoop(timestamp) {
      requestAnimationFrame(renderLoop);

      const frameInterval = 1000 / targetFps;
      const elapsed = timestamp - lastFrameTime;

      if (elapsed < frameInterval) return;
      lastFrameTime = timestamp - (elapsed % frameInterval);

      // Render simple bouncing ball animation
      ctx.clearRect(0, 0, canvas.width, canvas.height);
      ctx.fillStyle = targetFps === 60 ? '#38bdf8' : '#f59e0b';
      ctx.beginPath();
      ctx.arc(ballX, 100, 20, 0, Math.PI * 2);
      ctx.fill();

      ballX += ballSpeed;
      if (ballX > canvas.width - 20 || ballX < 20) {
        ballSpeed = -ballSpeed;
      }
    }

    setupBatteryGovernor();
    requestAnimationFrame(renderLoop);
  </script>
</body>
</html>

Why this works:

By measuring timestamp deltas against 1000 / targetFps, the animation loop cleanly skips redundant redraw cycles when in Eco-Mode, reducing CPU and GPU battery drain by up to $70%$.

⚠️ Common Pitfalls

Assuming dischargingTime is Always a Number: When plugged into power or when the battery management microcontroller is calibrating, dischargingTime returns Infinity. Never divide by it without checking Number.isFinite().
Neglecting Privacy Deprecation: Writing web apps that crash if navigator.getBattery is undefined will break completely for all Apple Safari and Mozilla Firefox users. Always check 'getBattery' in navigator.
Over-Polling Battery Status: Never poll getBattery() inside a setInterval(). It returns a singleton BatteryManager that pushes updates via event listeners (levelchange, chargingchange).

💡 Pro Tips

Quantized Privacy Levels: Modern Chromium browsers intentionally round battery.level to the nearest $0.01$ (1%) or $0.05$ (5%) to prevent micro-entropy fingerprinting.
Combine Battery with Network Awareness: When both battery is $< 20%$ AND network is on metered connection (navigator.connection.saveData === true), suspend all non-critical background fetch requests.

📌 Key Takeaways

navigator.getBattery() returns a Promise resolving to the BatteryManager interface.
level provides battery percentage from 0.0 to 1.0.
charging provides a boolean indicating whether the device is receiving external power.
The four key events are chargingchange, levelchange, chargingtimechange, and dischargingtimechange.
Firefox and Safari disabled this API to protect user privacy against persistent device fingerprinting.
--

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

? Question 1 / 3

What value does `battery.dischargingTime` return when a laptop is plugged into an AC wall charger?

Topic: HTML Fundamentals

? Question 2 / 3

Why did Mozilla Firefox and Apple Safari remove or refuse to implement the Battery Status API?

Topic: HTML Fundamentals

? Question 3 / 3

Which event fires on the `BatteryManager` object when the user disconnects their phone from the charging cable?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The BatteryManager Interface

Telemetry Properties Matrix

The Four Reactive Event Listeners

The Privacy & Fingerprinting Controversy

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build an Adaptive WebGL / Canvas Frame Rate Governor

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What value does battery.dischargingTime return when a laptop is plugged into an AC wall charger?

Why did Mozilla Firefox and Apple Safari remove or refuse to implement the Battery Status API?

Which event fires on the BatteryManager object when the user disconnects their phone from the charging cable?

The `BatteryManager` Interface

What value does `battery.dischargingTime` return when a laptop is plugged into an AC wall charger?

Which event fires on the `BatteryManager` object when the user disconnects their phone from the charging cable?