Feature/transparent browser background by Li-Hongmin · Pull Request #547 · gnachman/iTerm2

Li-Hongmin · 2025-12-03T14:53:22Z

Adds transparent background support to iTerm2's built-in browser, allowing
users to adjust the browser background opacity through a menu interface.

Motivation

Enhance browser integration with terminal by allowing overlay of browser
content while maintaining visibility of underlying content.

Changes

Added transparency control submenu to browser menu (≡)
Implemented 5 preset transparency levels (Opaque, 25%, 50%, 75%,
Transparent)
Added custom slider for precise transparency control (0-100%)
Fixed JavaScript compatibility issues with SVG and special DOM elements
Optimized performance with debouncing and Set-based element tracking

Implementation Details

iTermBrowserManager.swift: Added setTransparency(_:) method with
inline JavaScript injection
iTermBrowserToolbar.swift: Added transparency submenu with presets and
custom slider
iTermBrowserViewController.swift: Connected toolbar delegate to
browser manager

Testing

✅ Tested on complex websites (YouTube, GitHub, Google)
✅ No JavaScript console errors
✅ Real-time transparency updates work correctly
✅ Media elements (images, videos) remain visible

Screenshots

Enable see-through backgrounds in the browser view, similar to terminal transparency. Changes: - Set WKWebView drawsBackground to false for transparent rendering - Make NSVisualEffectView background fully transparent (alphaValue = 0) - Set iTermBrowserView layer background to clear - Inject CSS with universal selector (*, *::before, *::after) to make all webpage backgrounds transparent - Preserve visibility for images, videos, thumbnails, avatars, icons - Add subtle translucent background for buttons 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Enable browser-only development mode with full transparency for all web content. Changes: 1. Browser-only auto-launch: - Use openSingleUserBrowserWindowWithURL API to create browser sessions - Disable window restoration to prevent terminal windows - Disable untitled window state machine - Auto-launch YouTube on startup for development 2. Complete UI transparency: - Set URL bar visualEffectView alphaValue to 0.0 - Remove URL bar border - Make toolbar and indicators view transparent - Clear layer backgrounds for all browser UI components 3. Aggressive CSS transparency injection: - Force ALL elements to transparent background (not just inline styles) - Continuous monitoring with MutationObserver - Periodic re-application every 500ms for dynamic sites like YouTube - Preserve media elements (img, video, canvas, etc.) - Add debug logging to track element modifications Result: Browser launches automatically with see-through backgrounds on all websites including YouTube. No terminal windows created. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Fix click responsiveness issues caused by aggressive transparency monitoring. Optimizations: - Add WeakSet cache to track processed elements (avoid reprocessing) - Add re-entry guard to prevent recursive calls - Only monitor childList changes (not attributes) to avoid mutation loops - Check for actual new nodes before applying transparency - Increase debounce delay to 200ms for better responsiveness - Remove setInterval periodic refresh (MutationObserver is sufficient) Result: Smooth click interactions while maintaining full transparency on dynamic sites like YouTube. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Restore terminal functionality while keeping transparent browser features. Changes: - Remove browser-only auto-launch code - Restore window restoration system - Restore untitled window creation logic - Restore autolaunch scripts and preferences handling - Keep all transparency features for browser sessions Transparency features remain active: - WebView transparent background (drawsBackground = false) - All UI components transparent (toolbar, URLBar, indicators) - Aggressive CSS injection with debounced MutationObserver - WeakSet caching to prevent UI blocking Result: iTerm2 launches normally with terminal, but when browser sessions are opened (via menu or URL), they have full transparency. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Move transparency control from toolbar to menu with preset values and custom slider. Features: - Add transparency submenu to browser menu - 5 preset values (Opaque, 25%, 50%, 75%, Transparent) - Custom slider for precise control - Real-time transparency updates - Fix JavaScript compatibility with SVG elements Technical improvements: - Check el.style.setProperty existence before calling - Optimize performance with Set-based element tracking - Add debouncing to prevent UI blocking

gnachman · 2025-12-05T19:24:09Z

            forMainFrameOnly: false,
            worlds: [.page, .defaultClient],
            identifier: UserScripts.consoleLog.rawValue))
+


Please put javascript in its own .js file and use iTermBrowserTemplateLoader to load it.

gnachman · 2025-12-05T19:27:17Z

+                if (isProcessing) return;  // Prevent re-entry
+                isProcessing = true;
+
+                const transparency = window.iTermTransparencyLevel || 1.0;


0 is falsey so it'll be treated as 1

gnachman · 2025-12-05T19:27:50Z

+            window.iTermTransparencyLevel = 1.0;
+
+            // Make processedElements and applyTransparency global for external control
+            window.processedElements = new Set();  // Use Set instead of WeakSet for clearing


This will leak elements, won't it? Also this comment doesn't make sense.

gnachman · 2025-12-05T19:28:59Z

+                    if (window.processedElements.has(el)) return;  // Skip already processed
+
+                    // Skip media elements
+                    const isMedia = el.tagName.match(/^(IMG|VIDEO|PICTURE|CANVAS|SVG|IFRAME)$/i) ||


On SVG and some special nodes, className is not a string (e.g. SVGAnimatedString) and this can throw.

const className = String(el.className || ''); const id = String(el.id || ''); const isMedia = el.tagName.match(/^(IMG|VIDEO|PICTURE|CANVAS|SVG|IFRAME)$/i) || className.match(/(thumbnail|avatar|icon|img|video|player|yt-image)/i) || id.match(/(thumbnail|avatar|icon|img|video|player)/i);

gnachman · 2025-12-05T19:30:33Z

+                if (styleElement) {
+                    styleElement.textContent = `
+                        /* Universal transparent background - opacity controlled by slider */
+                        *, *::before, *::after {


This will will:
• Kill contrast-preserving backgrounds, overlays, etc.
• Break sites that rely on background gradients for visibility.
• Nuke background images that aren’t “wallpaper” (e.g. buttons, logos, flags).

Something like this would make more sense:

html, body, main, [role="main"], article, section, .content, .container, .page, .layout, .wrapper { background-color: ${bgColor} !important; background-image: none !important; }

gnachman · 2025-12-05T19:37:20Z

+    @objc private func setTransparency(_ sender: NSMenuItem) {
+        let value = Double(sender.tag) / 100.0
+        currentTransparency = value
+        NSLog("Transparency preset selected: %f", value)


Change to DLog

gnachman · 2025-12-05T19:37:27Z

+
+    @objc private func transparencySliderChanged(_ sender: NSSlider) {
+        currentTransparency = sender.doubleValue
+        NSLog("Transparency slider changed to: %f", sender.doubleValue)


Change to DLog

gnachman · 2025-12-05T19:38:35Z

                                            username:nil];
    }

+    // Auto-launch browser for transparent browser development


gnachman · 2025-12-05T19:38:48Z

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>


gnachman · 2025-12-05T19:38:53Z

@@ -0,0 +1,85 @@
+# WebKit Media Playback Entitlements


Li-Hongmin and others added 5 commits December 2, 2025 20:42

gnachman requested changes Dec 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feature/transparent browser background#547

Feature/transparent browser background#547
Li-Hongmin wants to merge 5 commits into
gnachman:masterfrom
Li-Hongmin:feature/transparent-browser-background

Li-Hongmin commented Dec 3, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

gnachman Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Li-Hongmin commented Dec 3, 2025

Motivation

Changes

Implementation Details

Testing

Screenshots

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants