cmux-next: liquid glass lens primitive and Glass setting

Packages/macOS/CmuxNext/Sources/CmuxNextActions/ActionCatalog.xcstrings

@@ -8647,6 +8647,137 @@
         }
       }
     },
+    "action.appearance.glass.lens.toggle": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Toggle Liquid Glass Lens"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "リキッドグラスのレンズを切り替え"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "تبديل عدسة الزجاج السائل"
+          }
+        },
+        "bs": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Uključi/isključi sočivo tečnog stakla"
+          }
+        },
+        "da": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Slå flydende glas-linse til/fra"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Liquid-Glass-Linse umschalten"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Activar o desactivar la lente de cristal líquido"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Activer/désactiver la lentille de verre liquide"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Attiva/disattiva lente in vetro liquido"
+          }
+        },
+        "km": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "បិទ/បើកកញ្ចក់កែវរាវ"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "리퀴드 글래스 렌즈 켜기/끄기"
+          }
+        },
+        "nb": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Slå flytende glass-linse av/på"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Przełącz soczewkę płynnego szkła"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Alternar Lente de Vidro Líquido"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Переключить линзу жидкого стекла"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "สลับเลนส์กระจกเหลว"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Sıvı Cam Merceğini Aç/Kapat"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Перемкнути лінзу рідкого скла"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "Bật/tắt thấu kính kính lỏng"
+          }
+        },
+        "zh-Hans": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "切换液态玻璃透镜"
+          }
+        },
+        "zh-Hant": {
+          "stringUnit": {
+            "state": "needs_review",
+            "value": "切換液態玻璃透鏡"
+          }
+        }
+      }
+    },
     "action.attachTextBoxFile": {
       "extractionState": "manual",
       "localizations": {

Packages/macOS/CmuxNext/Sources/CmuxNextActions/Catalog/SettingsActionCatalog.swift

@@ -440,6 +440,16 @@ nonisolated enum SettingsActionCatalog: ActionCatalogGroup {
                 keywords: ["titlebar", "title bar", "window", "workspace name", "show", "appearance"], category: .settings,
                 symbol: "macwindow.badge.plus", surfaces: [.palette], cliName: "settings use-standard-titlebar"
             ),
+            // Leo 2026-10-21: the lens is a toggle to see and feel before it is the default. Flips the
+            // Debug choice `glass.lens` between Plain Glass (the default) and Lens, live, from the
+            // palette or the Debug menu (DEV and NIGHTLY).
+            ActionDescriptor(
+                id: "appearance.glass.lens.toggle",
+                title: String(localized: "action.appearance.glass.lens.toggle", defaultValue: "Toggle Liquid Glass Lens", bundle: .module),
+                keywords: ["glass", "liquid glass", "lens", "refraction", "wallpaper", "plain glass", "appearance"],
+                category: .settings, symbol: "drop", surfaces: [.palette, .menu], mainMenu: .debug, isDebugOnly: true,
+                surfacePlan: ActionSurfacePlan(cli: .exempt(.devOnly), contextMenuExemption: .noObject)
+            ),
             ActionDescriptor(
                 id: "appearance.customize",
                 title: String(localized: "action.appearance.customize", defaultValue: "Customize Appearance…", bundle: .module),

Packages/macOS/CmuxNext/Sources/CmuxNextAgentActivity/AgentActivityHostView.swift

@@ -14,6 +14,12 @@ public final class AgentActivityHostView: NSView {
     /// Activity events can arrive as a batch, and serializing the full projection for every
     /// element makes the main actor and WebKit do redundant work while the page is catching up.
     private var statePushScheduled = false
+    /// The wallpaper still the page's glass lenses (`cmuxTheme.backdrop`), pushed after each theme.
+    private lazy var glassFeed = GlassBackdropFeed(host: webView, zoom: { [webView] in webView.pageZoom * webView.magnification }) { [weak self] in
+        self?.webView.evaluateJavaScript($0, completionHandler: nil)
+    }
+    /// Pushes the theme again on every repaint of this view's scope (the glass mode included).
+    private lazy var themeFollower = ThemeFollower(self) { [weak self] in self?.applyTheme() }
 
     /// Makes an Activity web view for a model and its native data source.
     public init(model: AgentActivityModel, source: any AgentActivitySource) {
@@ -75,11 +81,15 @@ public final class AgentActivityHostView: NSView {
     /// Gives the page this view's scope colors when they changed; `reload` after a navigation,
     /// whose new document has only the document-start colors.
     fileprivate func applyTheme(reload: Bool = false) {
+        themeFollower.rebind()
         if reload { appliedTheme = nil }
         let theme = Self.theme(themeScope)
-        guard theme.payloadJSON != appliedTheme else { return }
-        appliedTheme = theme.payloadJSON
-        webView.evaluateJavaScript(theme.applyScript, completionHandler: nil)
+        if theme.payloadJSON != appliedTheme {
+            appliedTheme = theme.payloadJSON
+            webView.evaluateJavaScript(theme.applyScript, completionHandler: nil)
+        }
+        // After the theme, which sets `data-glass`; a reload is a new document with no still yet.
+        glassFeed.refresh(newDocument: reload)
     }
 
     private static func theme(_ scope: ThemeScope) -> WebTheme {

Packages/macOS/CmuxNext/Sources/CmuxNextAgentPane/AgentPaneView.swift

@@ -72,6 +72,10 @@ public final class AgentPaneView: NSView {
     /// Pushes every color change of this view's scope to the page, shown or hidden, so a page
     /// shown after a change paints its first frame in the new colors (cx-8w027.12).
     private lazy var themeFollower = ThemeFollower(self) { [weak self] in self?.applyTheme() }
+    /// The wallpaper still the old host's page lenses (the page host's ``PageWebView`` has its own).
+    private lazy var glassFeed = GlassBackdropFeed(host: webView, zoom: { [webView] in webView.pageZoom * webView.magnification }) { [weak self] in
+        self?.evaluateScript($0)
+    }
     private var uiScaleObservation: Task<Void, Never>?
     public var zoom: Double = 1 {
         didSet { guard zoom != oldValue else { return }; applyZoom() }
@@ -280,6 +284,7 @@ public final class AgentPaneView: NSView {
             return
         }
         webView.pageZoom = Double(DesignSettings.shared.uiScale) * zoom
+        glassFeed.refresh() // the zoom moves the art's rect in CSS px
         webView.evaluateJavaScript(DesignSettings.shared.interfaceScaleScript, completionHandler: nil)
     }
 
@@ -427,9 +432,12 @@ public final class AgentPaneView: NSView {
             deliveredThemeEvent = event
             pageEvents.publish(event)
         } else {
-            guard let script = AgentPaneTheme.script(tokens, surface: surface), force || script != deliveredThemeScript else { return }
-            deliveredThemeScript = script
-            evaluateScript(script)
+            if let script = AgentPaneTheme.script(tokens, surface: surface), force || script != deliveredThemeScript {
+                deliveredThemeScript = script
+                evaluateScript(script)
+            }
+            // After the theme, which sets `data-glass`; a forced push is a new document or its handshake.
+            glassFeed.refresh(newDocument: force)
         }
     }
 

Packages/macOS/CmuxNext/Sources/CmuxNextApp/AppDelegate.swift

@@ -203,6 +203,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         // After two quick unexpected ends in a row, Chromium starts only
         // when the user reloads a browser tab.
         services.observeBorders()
+        services.observeGlass()
         services.updateFeedObservation = UpdateFeedPosting.follow(services)
         // The runtime pack check wires the engine reason at once; its download waits until asked.
         services.startChromiumRuntime()

Packages/macOS/CmuxNext/Sources/CmuxNextApp/AppServices+Glass.swift

@@ -0,0 +1,10 @@
+import CmuxNextDesign
+
+extension AppServices {
+    /// Repaints every window when the glass mode pages draw changes (the Debug choice `glass.lens`, Reduce
+    /// Transparency, Low Power Mode): every web view pushes its theme (`data-glass`) and its
+    /// wallpaper still again (plans/cmux-next/glass-lens-DESIGN.md).
+    func observeGlass() {
+        glassWatch = GlassModeWatch { ThemeStore.shared.repaintAll() }
+    }
+}

Packages/macOS/CmuxNext/Sources/CmuxNextApp/AppServices.swift

@@ -283,6 +283,8 @@ final class AppServices {
     var chromiumLikelyObservations: [Task<Void, Never>] = []
     /// Repaints on `appearance.borders` changes (`observeBorders`).
     var borderObservation: Task<Void, Never>?
+    /// Repaints when the glass mode pages draw changes (`observeGlass`).
+    var glassWatch: GlassModeWatch?
     /// Posts this launch's installed-update Feed card once (`UpdateFeedPosting.follow`).
     var updateFeedObservation: Task<Void, Never>?
     /// Page menus and the open-menu diagnostic shared by browser hosts.

Packages/macOS/CmuxNext/Sources/CmuxNextApp/GlassModeWatch.swift

@@ -0,0 +1,44 @@
+import AppKit
+import CmuxNextCompat
+import CmuxNextDesign
+
+/// Calls back when the glass mode pages draw (`GlassLensMode.current`) changes: the Debug choice `glass.lens`,
+/// Reduce Transparency (system or Debug override) or Low Power Mode. Events only, nothing polls.
+final class GlassModeWatch {
+    private var shown: GlassLensMode
+    private let onChange: @MainActor () -> Void
+    private var settings: Task<Void, Never>?
+    private var lowPower: LowPowerModeObservation?
+    private var display: (any NSObjectProtocol)?
+
+    init(onChange: @escaping @MainActor () -> Void) {
+        shown = .current
+        self.onChange = onChange
+        settings = Task { [weak self] in
+            for await _ in ObservationStream({ GlassLensMode.tunable.value }) { self?.check() }
+        }
+        lowPower = LowPowerMode.system.observe { [weak self] _ in self?.check() }
+        display = NSWorkspace.shared.notificationCenter.addObserver(
+            forName: NSWorkspace.accessibilityDisplayOptionsDidChangeNotification, object: nil, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated { self?.check() } // main-proof: observer on queue: .main
+        }
+    }
+
+    // cx-t7hu: not an isolated deinit; its runtime hop traps when released inside an action's task-local scope.
+    nonisolated deinit {
+        guard Thread.isMainThread else { return } // main-proof: returns off the main thread
+        MainActor.assumeIsolated {
+            settings?.cancel()
+            lowPower?.cancel()
+            if let display { NSWorkspace.shared.notificationCenter.removeObserver(display) }
+        }
+    }
+
+    /// Calls back when the mode is not the one last seen.
+    func check() {
+        let now = GlassLensMode.current
+        guard now != shown else { return }
+        shown = now
+        onChange()
+    }
+}

Packages/macOS/CmuxNext/Sources/CmuxNextApp/Handlers/AppearanceHandlers.swift

@@ -62,6 +62,7 @@ enum AppearanceHandlers {
         for style in TitlebarStyle.allCases {
             registry.bind(ActionID(rawValue: "appearance.titlebar.\(style.rawValue)"), run: { _ in try setTitlebar(style, context) })
         }
+        registry.bind("appearance.glass.lens.toggle", run: { _ in GlassLensMode.choose(GlassLensMode.tunable.value.lensToggled) })
         registry.bind("appearance.interfaceSize.reset", run: { _ in
             let path = context.design.interfaceSizePath; try requireUnmanaged(path, context); context.design.resetInterfaceSize()
             context.writeSetting("reset interface size", path, nil, reloadOnFailure: true)