Phase 5: lock-screen shell + trigger

[tirthfx]

What changed

Kicks off Surface B, the fullscreen lock screen (PRD §3.2) after the dual-surface pivot. This is Phase 5 — the shell + trigger only.

• PseudoLockScreenController — a borderless, fullscreen NSWindow on the built-in display at .screenSaver level, joining all Spaces. Draws a lock-screen backdrop: the current desktop wallpaper (NSWorkspace.desktopImageURL, dark-gradient fallback) with a large SF Pro rounded clock + date updating each second (reference image 1). Esc / the hotkey / (later) click-away dismiss it.
• GlobalHotKey — a permission-free process-global ⌃⌘L via Carbon RegisterEventHotKey (an NSEvent global monitor would need Accessibility/Input Monitoring and can't consume the event). Toggles the lock screen from anywhere.
• Menu bar gains a "Toggle Lock Screen (⌃⌘L)" item.

No now-playing widget yet — that's Phase 6.

Why

The reference screenshots showed the lock-screen flow (idle → click-expand → swipe-lyrics) was always the real hero; main was reset and the docs rewritten to make it a co-equal core surface alongside the notch. This is the first build step of that surface.

Base

Branches off the freshly-reset main (clean 3-commit history: scaffold → notch baseline → dual-surface docs). The old stacked PRs #3/#4 were closed; the notch code is preserved on main and in the backup/notch-phases-1-4 tag.

Notes for review — needs your eyes in Xcode

• I could not verify the visuals headlessly — synthesized keystrokes and screenshots are both blocked without Accessibility/Screen Recording permission. Confirmed only that the app launches cleanly with the hotkey registered (no crash) and the notch still works. Please run it and press ⌃⌘L (or menu → Toggle Lock Screen): expect fullscreen wallpaper + big clock/date, Esc to dismiss.
• .screenSaver window level makes it cover the menu bar for a true "takeover" feel. If you'd rather it sit below the menu bar, that's a one-line change.
• The global hotkey uses Carbon (no permission prompt). If ⌃⌘L clashes with something on your machine, easy to rebind.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a pseudo lock-screen feature (Surface B) for NotchBeat, adding a fullscreen borderless window that displays the desktop wallpaper and a clock, toggled via a global hotkey (⌃⌘L) or a menu bar item. The review feedback highlights several critical improvements: resolving a retain cycle in GlobalHotKey by using weak references in the registry, loading the wallpaper image asynchronously to avoid blocking the main thread, and passing the specific NSScreen instance to properly support multi-monitor setups. Additionally, it is recommended to use SwiftUI's native .keyboardShortcut modifier for the menu item and to remove redundant key-down handling in LockScreenWindow.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The registry dictionary holds a strong reference to GlobalHotKey instances. Since each instance registers itself in init, this creates a retain cycle where the registry keeps the instance alive indefinitely, preventing deinit from ever being called. This leaks the hotkey and its callback. Use a weak wrapper to store weak references in the registry.

    private struct WeakBox {
        weak var value: GlobalHotKey?
    }

    // Carbon dispatches to a C function pointer with no captured context, so we
    // route hotkey presses back to instances through a shared id → instance map.
    // We use weak references to avoid a retain cycle, as the registry would otherwise
    // keep the hotkey instances alive indefinitely.
    private static var registry: [UInt32: WeakBox] = [:]
    private static var nextID: UInt32 = 1
    private static var handlerInstalled = false
    private static let signature: OSType = 0x4E_54_42_54 // 'NTBT'

    init(_ combo: Combo, callback: @escaping () -> Void) {
        self.callback = callback
        self.id = GlobalHotKey.nextID
        GlobalHotKey.nextID += 1
        GlobalHotKey.registry[id] = WeakBox(value: self)

[gemini-code-assist]

Update deinit to remove the entry from the registry safely on the main thread.

    deinit {
        if let ref { UnregisterEventHotKey(ref) }
        let targetID = id
        DispatchQueue.main.async {
            GlobalHotKey.registry.removeValue(forKey: targetID)
        }
    }

[gemini-code-assist]

Update the event handler dispatch to access the weak reference's value.

Suggested change

	DispatchQueue.main.async {
	GlobalHotKey.registry[targetID]?.callback()
	}
	DispatchQueue.main.async {
	GlobalHotKey.registry[targetID]?.value?.callback()
	}

[gemini-code-assist]

NSImage(contentsOf:) performs synchronous disk I/O to load and decode the wallpaper image. Running this on the main thread (which is the default context for SwiftUI .task blocks) can cause noticeable UI stuttering or freezes when presenting the lock screen. Load the image asynchronously on a background queue.

    private func loadWallpaper() {
        guard let url = NSWorkspace.shared.desktopImageURL(for: screen) else { return }
        
        // Load the image asynchronously on a background queue to avoid blocking the main thread
        DispatchQueue.global(qos: .userInitiated).async {
            if let loadedImage = NSImage(contentsOf: url) {
                DispatchQueue.main.async {
                    self.image = loadedImage
                }
            }
        }
    }

[gemini-code-assist]

Check the return status of RegisterEventHotKey to detect and log registration failures (e.g., if another application has already registered the shortcut).

Suggested change

	RegisterEventHotKey(
	combo.keyCode,
	combo.modifiers,
	hotKeyID,
	GetApplicationEventTarget(),
	0,
	&ref
	)
	let status = RegisterEventHotKey(
	combo.keyCode,
	combo.modifiers,
	hotKeyID,
	GetApplicationEventTarget(),
	0,
	&ref
	)
	if status != noErr {
	print("Failed to register global hotkey: \(status)")
	}

[gemini-code-assist]

Update LockScreenBackdropView to accept and pass the target NSScreen to WallpaperView.

Suggested change

	struct LockScreenBackdropView: View {
	var body: some View {
	ZStack(alignment: .top) {
	WallpaperView()
	ClockView()
	.padding(.top, 64)
	}
	.frame(maxWidth: .infinity, maxHeight: .infinity)
	.ignoresSafeArea()
	}
	}
	struct LockScreenBackdropView: View {
	let screen: NSScreen
	var body: some View {
	ZStack(alignment: .top) {
	WallpaperView(screen: screen)
	ClockView()
	.padding(.top, 64)
	}
	.frame(maxWidth: .infinity, maxHeight: .infinity)
	.ignoresSafeArea()
	}
	}

[gemini-code-assist]

Pass the specific NSScreen instance to WallpaperView instead of relying on NSScreen.main. This ensures the correct wallpaper is loaded on multi-monitor setups where the lock screen window might be shown on a different screen than the active key window.

private struct WallpaperView: View {
    let screen: NSScreen
    @State private var image: NSImage?

    var body: some View {

[gemini-code-assist]

Pass the target screen to LockScreenBackdropView when initializing the hosting view.

Suggested change

	window.contentView = NSHostingView(rootView: LockScreenBackdropView())
	window.contentView = NSHostingView(rootView: LockScreenBackdropView(screen: screen))

[gemini-code-assist]

The keyDown override is redundant because cancelOperation(_:) is already overridden and is the standard, system-provided way AppKit handles the Escape key. Bypassing or duplicating this with a hardcoded key code 53 is unnecessary and can be removed.

    // Rely on cancelOperation(_:) to handle the Escape key idiomatic to AppKit.

[gemini-code-assist]

Instead of hardcoding the shortcut string (⌃⌘L) in the button's title, use SwiftUI's .keyboardShortcut modifier. This allows macOS to automatically render the shortcut beautifully on the right side of the menu item and ensures it works natively when the menu is open.

Suggested change

	Button("Toggle Lock Screen (⌃⌘L)") {
	onToggleLockScreen()
	}
	Button("Toggle Lock Screen") {
	onToggleLockScreen()
	}
	.keyboardShortcut("l", modifiers: [.control, .command])