Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions src/main/appkit-scene-mutation.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { deferAppKitSceneMutation } from './appkit-scene-mutation'

beforeEach(() => {
vi.useFakeTimers()
})

afterEach(() => {
vi.useRealTimers()
})

describe('deferAppKitSceneMutation', () => {
it('runs the mutation on a later turn, never inside the caller stack', () => {
const mutate = vi.fn()

deferAppKitSceneMutation(mutate)
expect(mutate).not.toHaveBeenCalled()

vi.advanceTimersByTime(0)
expect(mutate).toHaveBeenCalledOnce()
})

it('keeps scheduled mutations in call order', () => {
const order: string[] = []

deferAppKitSceneMutation(() => order.push('first'))
deferAppKitSceneMutation(() => order.push('second'))
vi.advanceTimersByTime(0)

expect(order).toEqual(['first', 'second'])
})
})
6 changes: 6 additions & 0 deletions src/main/appkit-scene-mutation.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
// Why: macOS 26 backs AppKit objects (windows, NSStatusItem) with scenes, and a scene
// update sent re-entrantly from inside AppKit's own dispatch self-deadlocks the main
// thread in FrontBoardServices; a fresh event-loop turn vacates that callout frame.
export function deferAppKitSceneMutation(mutate: () => void): void {
setTimeout(mutate, 0)
}
86 changes: 85 additions & 1 deletion src/main/tray/system-tray.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,14 @@ function builtMenuItems(): MenuItem[] {
return menuFromTemplateMock.mock.calls.at(-1)?.[0] as MenuItem[]
}

// Why: tray image/tooltip writes are deferred off the caller's stack to keep the
// NSStatusItem scene update out of AppKit's dispatch; run the pending turn.
function flushTraySceneMutation(): void {
vi.advanceTimersByTime(0)
}

beforeEach(() => {
vi.useFakeTimers()
trayInstances.length = 0
menuFromTemplateMock.mockClear()
composeAttentionMock.mockClear()
Expand Down Expand Up @@ -180,6 +187,7 @@ beforeEach(() => {

afterEach(() => {
setPlatform(originalPlatform)
vi.useRealTimers()
vi.restoreAllMocks()
})

Expand Down Expand Up @@ -296,6 +304,7 @@ describe('dev instance indicator', () => {
createSystemTray(createOptions({ isDevInstance: true, devInstanceLabel: 'my-branch' }))

setTrayAttention(true)
flushTraySceneMutation()

expect(tintTemplateMock).toHaveBeenCalledWith(devBadgeImage, false)
})
Expand Down Expand Up @@ -334,8 +343,10 @@ describe('dev instance indicator', () => {
created.setToolTip.mockClear()

setTrayAttention(true)
flushTraySceneMutation()
expect(created.setToolTip).toHaveBeenCalledWith('Orca DEV (my-branch) - activity waiting')
setTrayAttention(false)
flushTraySceneMutation()
expect(created.setToolTip).toHaveBeenLastCalledWith('Orca DEV (my-branch)')
})

Expand Down Expand Up @@ -388,9 +399,11 @@ describe('setTrayAttention', () => {
created.setImage.mockClear()

setTrayAttention(true)
flushTraySceneMutation()
expect(composeAttentionMock).toHaveBeenCalledWith(resizedImage)
expect(created.setImage).toHaveBeenCalledWith(attentionImage)
setTrayAttention(false)
flushTraySceneMutation()
expect(created.setImage).toHaveBeenLastCalledWith(resizedImage)
})

Expand All @@ -403,6 +416,7 @@ describe('setTrayAttention', () => {
created.setToolTip.mockClear()

setTrayAttention(true)
flushTraySceneMutation()
expect(tintTemplateMock).toHaveBeenCalledWith(baseMacImage, false)
expect(composeAttentionMock).toHaveBeenCalledWith(tintedMacImage)
// Why: the attention image is rebuilt from 1x pixels, so the @2x
Expand All @@ -417,6 +431,7 @@ describe('setTrayAttention', () => {
expect(created.setToolTip).toHaveBeenCalledWith('Orca - activity waiting')

setTrayAttention(false)
flushTraySceneMutation()
expect(baseMacImage.setTemplateImage).toHaveBeenLastCalledWith(true)
expect(created.setImage).toHaveBeenLastCalledWith(baseMacImage)
expect(created.setToolTip).toHaveBeenLastCalledWith('Orca')
Expand All @@ -427,11 +442,15 @@ describe('setTrayAttention', () => {
const { createSystemTray, setTrayAttention } = await loadModule()
createSystemTray(createOptions())
setTrayAttention(true)
flushTraySceneMutation()
tintTemplateMock.mockClear()
nativeThemeMock.shouldUseDarkColors = true

themeState.updatedListener?.()
// Why: appearance changes arrive on an AppKit dispatch too, so the recompose defers.
expect(tintTemplateMock).not.toHaveBeenCalled()

flushTraySceneMutation()
expect(tintTemplateMock).toHaveBeenCalledWith(baseMacImage, true)
})

Expand All @@ -453,10 +472,74 @@ describe('setTrayAttention', () => {

setTrayAttention(true)
setTrayAttention(true)
flushTraySceneMutation()

expect(created.setImage).toHaveBeenCalledTimes(1)
})

it('never touches the NSStatusItem scene inside the caller stack', async () => {
setPlatform('darwin')
const { createSystemTray, setTrayAttention } = await loadModule()
createSystemTray(createOptions())
const created = trayInstances[0]
created.setImage.mockClear()
created.setToolTip.mockClear()

// Why: show/restore call this from AppKit's window-state dispatch; a scene
// update sent there self-deadlocks the main thread on macOS 26.
setTrayAttention(true)
expect(created.setImage).not.toHaveBeenCalled()
expect(created.setToolTip).not.toHaveBeenCalled()

flushTraySceneMutation()
expect(created.setImage).toHaveBeenCalledWith(attentionImage)
})

it('collapses a burst of toggles into one deferred repaint', async () => {
setPlatform('darwin')
const { createSystemTray, setTrayAttention } = await loadModule()
createSystemTray(createOptions())
const created = trayInstances[0]
created.setImage.mockClear()

setTrayAttention(true)
setTrayAttention(false)
setTrayAttention(true)
flushTraySceneMutation()

expect(created.setImage).toHaveBeenCalledTimes(1)
expect(created.setImage).toHaveBeenCalledWith(attentionImage)
})

it('still dedupes after the deferred repaint has run', async () => {
setPlatform('darwin')
const { createSystemTray, setTrayAttention } = await loadModule()
createSystemTray(createOptions())
const created = trayInstances[0]
created.setImage.mockClear()

setTrayAttention(true)
flushTraySceneMutation()
setTrayAttention(true)
flushTraySceneMutation()

expect(created.setImage).toHaveBeenCalledTimes(1)
})

it('does not throw when the tray is destroyed before the deferred repaint runs', async () => {
setPlatform('darwin')
const { createSystemTray, destroySystemTray, setTrayAttention } = await loadModule()
createSystemTray(createOptions())
const created = trayInstances[0]
created.setImage.mockClear()

setTrayAttention(true)
destroySystemTray()

expect(() => flushTraySceneMutation()).not.toThrow()
expect(created.setImage).not.toHaveBeenCalled()
})

it('keeps a pending attention dot across a macOS hide/show toggle', async () => {
setPlatform('darwin')
const { setMacMenuBarIconVisible, setTrayAttention } = await loadModule()
Expand Down Expand Up @@ -514,7 +597,8 @@ describe('macOS hardening', () => {
throw new Error('native image failure')
})

expect(() => setTrayAttention(true)).not.toThrow()
setTrayAttention(true)
expect(() => flushTraySceneMutation()).not.toThrow()
expect(created.setImage).toHaveBeenLastCalledWith(baseMacImage)
expect(created.setToolTip).toHaveBeenLastCalledWith('Orca')
expect(warn).toHaveBeenCalledWith(
Expand Down
25 changes: 23 additions & 2 deletions src/main/tray/system-tray.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { Menu, Tray, nativeImage, nativeTheme, type NativeImage } from 'electron'
import menuBarIconPath from '../../../resources/tray/orca-menu-barTemplate.png?asset&asarUnpack'
import menuBarIconRetinaPath from '../../../resources/tray/orca-menu-barTemplate@2x.png?asset&asarUnpack'
import { deferAppKitSceneMutation } from '../appkit-scene-mutation'
import { createAppIconImage } from '../app-icon'
import { translateMain } from '../i18n/main-i18n'
import { composeTrayAttentionIcon, tintTrayTemplateForAttention } from './tray-attention-icon'
Expand Down Expand Up @@ -107,6 +108,23 @@ function applyTrayImage(): void {
tray.setImage(attentionActive ? composeTrayAttentionIcon(baseTrayImage) : baseTrayImage)
}

// Why: collapse bursts (rapid show/hide) into one repaint; the deferred pass reads
// current module state, so a dropped schedule can never land a stale icon.
let trayImageRepaintPending = false

// Why: tray.setImage/setToolTip drive an NSStatusItem scene update, which deadlocks
// the main thread when sent from inside an AppKit callout; run it on a fresh turn.
function scheduleTrayImage(): void {
if (trayImageRepaintPending) {
return
}
trayImageRepaintPending = true
deferAppKitSceneMutation(() => {
trayImageRepaintPending = false
applyTrayImage()
})
}

function createMacMenuBarImage(): NativeImage | null {
const image = nativeImage.createFromPath(menuBarIconPath)
const { width, height } = image.getSize()
Expand Down Expand Up @@ -172,7 +190,8 @@ function watchMacAppearance(): void {
}
nativeThemeUpdatedListener = () => {
if (attentionActive) {
applyTrayImage()
// Why: 'updated' fires from AppKit's appearance-change dispatch.
scheduleTrayImage()
}
}
nativeTheme.on('updated', nativeThemeUpdatedListener)
Expand Down Expand Up @@ -299,8 +318,10 @@ export function setTrayAttention(active: boolean): void {
if (attentionActive === active) {
return
}
// Why: the dedup latch must settle synchronously or rapid show/hide mis-dedupes;
// only the native scene mutation moves off the caller's (AppKit) stack.
attentionActive = active
applyTrayImage()
scheduleTrayImage()
}

/** Destroys the tray icon if present. Safe to call repeatedly or with no tray. */
Expand Down
Loading
Loading