Wake the host display for active streams

[acalatrava]

A sleeping display wakes for a device

While the Mac's display is asleep, macOS draws nothing new, so a device that connects streams black windows, thumbnails too (#134).

With this change Sill for Mac tells macOS that someone is using the Mac, the way a key press does, when a device connects and while a person uses the Mac from it. A sleeping display wakes and stays on while the device is used. Once nobody uses it, it sleeps again by the Mac's own setting.

Host only: no wire change, nothing on the device, no setting. Devices and Macs from before this change work as before.

What it does

The call. IOPMAssertionDeclareUserActivity with kIOPMUserActiveLocal, the declaration caffeinate -u makes (the workaround in #134). DisplayActivity makes it on a queue of its own, because it is an IPC to powerd. Nothing is held: the display sleeps again by the Mac's own setting (System Settings › Lock Screen), counted from the last declaration.

What counts (a connect every time, the rest at most once every 5 s):

• a device's session connecting (every connection)
• an app opened (kind 7)
• input (kind 8): touches, keys, text, scrolls, pointer moves
• a window's button (15), a menu item chosen (25), a trackpad gesture (28)

What never counts, because the device sends it by itself or it acts on nothing:

• A pick (6). The device asks for the Desktop on its own when a connection starts, when the Mac stopped the Desktop and when a watched window closed, and it picks again what it watched after a move. A person's pick is followed by their input.
• The viewport (9), settings (17), "show your pairing code" (21), menu fetches (27), the clipboard (32), any other kind, and input that does not decode.
• A bare pointer move within 2 s after the host's own stream restart or new frame size: the device moves its own pointer to the middle of a new frame by itself (StreamClient.pointerFrameChanged).

So a device left connected and untouched lets the display sleep, and nothing it sends by itself wakes it. DisplayWake (pure) is the whole rule; the coordinator forwards every message to it once, and the connect from the client-connected path.

A black picture. A tap on it is a click, posted at a spot nobody can see. A pointer move on the trackpad, a scroll, or ⌘, ⌥ or ⌃ pressed alone on a keyboard attached to the device wakes the display without clicking. Shift alone does not: the device's text system takes it, so nothing reaches the Mac.

Sill.log.

• "Woke the display for iPad (iPad14,1), which connected." only when the main display read asleep just before a declaration and on 0.5 s after it, once per wake (two devices connecting together share it).
• Any other declaration says "Declared activity for …" at most once a minute, with ", but the display read asleep 0.5 s later." when it did (a closed lid, a display slow to wake).
• The stats line counts each declaration as disp.wake; pmset -g assertions lists it as UserIsActive named: "Sill: a device is using this Mac".

Test hosts (--synthetic, the CLI's and the app's test-pattern mode) never touch the display. They count disp.wakeDry instead.

TEST ONLY. SILL_TEST_USER_ACTIVE=remote (every real host, Sill.app included, with a "TEST:" line at start) declares kIOPMUserActiveRemote instead of Local, to learn on a real Mac whether Remote also wakes the panel, or keeps the picture live with the panel dark (#133).

Changed from the PR as opened

• The PreventUserIdleDisplaySleep assertion held for every session is gone. It kept the panel lit the whole session, against Feature Request: Privacy Mode (blank physical display during remote sessions) #133's privacy mode, and kept a Mac at home from idle sleep.
• The single kIOPMUserActiveRemote declaration at the first device became kIOPMUserActiveLocal, at every connect and on a person's activity.
• Nothing runs on test hosts, and the log goes through the host's log, not NSLog.
• The device's idle-timer change (auto-lock off while the stream screen shows) is out. With two Sill windows, one window's stream screen leaving turned auto-lock back on while the other still streamed, and a device kept lit beside a Mac whose display now sleeps by itself would show black. It belongs in a PR of its own.

Docs

• site/support.html, "The picture is black": what is true for Sill for Mac 0.5.1 (the display is asleep, so wake it at the Mac; keep it on longer in Lock Screen; keep the Mac awake in Energy or Battery). The paragraph on Sill waking the display sits between <!-- Display wake markers until the release that ships it.
• docs/release-checklist.md part 1 §3: the perl line that cuts those markers for a republish before that release, and a grep that must then print nothing.
• docs/DEVELOPMENT.md, "A sleeping display" and a troubleshooting bullet; CLAUDE.md; Tests/checks/README.md.

Verified

No device was used, and the real IOKit call never ran here.

• Build: swift build -c release on the tree merged with main at 4d990e9 (iPad: Shift+Return and Shift+Tab reach the Mac with the shift #110, VirtualDisplay: the BOOL return's encoding follows the architecture #87, Sill.app: one universal build for Apple silicon and Intel Macs (#62) #88), no warning. iOSClient is main's, so no iOS build.
• The check, Tests/checks/display-wake: 190 checks and 60 of 60 mutants, in CI's mutants matrix (re-run on this head until a pause stopped it: 54 of 60 caught, none missed; the rule, its check and the two wire files are byte for byte those of the full run). Every message kind decided, every input event, the 2 s window, the 5 s interval, the lines and their 0.5 s second look, the TEST ONLY switch, and two random models of 20,000 sessions each.
• Every check: Tests/checks/run-all.sh, all 47 pass.
• Loopback runs, SillHost --synthetic on 127.0.0.1 with the software encoder, no router and a scripted pointer:
  • Two stand-in devices that ask for the Desktop by themselves and move their own pointer to the middle as a new stream's parameter sets arrive. disp.wakeDry in exactly six seconds: both connects (2 s apart), a tap, a person's move 3.3 s after a restart, a gesture, and ⌘ alone. Nothing for the other device's tap 2 s after the first, a pick of nothing, the Desktop picked again, the device's own re-centre (after the Desktop was picked, and after the other device's settings change restarted the stream, 8.2 s and 7.6 s after the last declaration), the viewport, a settings change, the clipboard, a menu fetch, or input that does not decode.
  • The earlier review's timeline with two sillclient.py devices: 3 counts (both connects and a move 4.5 s after a restart), where the rule before counted the Desktop picks too.
  • The Desktop picked again with the device's re-centre on the restarted stream's first parameter sets, twice: not counted (5.8 and 6.2 s after the last declaration), and a person's move 2.3 s after: counted.
  • Never a disp.wake key, a "Woke" or "Declared" line, or an assertion of the host's in pmset -g assertions; the test host printed "SILL_TEST_USER_ACTIVE ignored: a test host declares no user activity (it counts disp.wakeDry)."
• Previews: Sill.app's 140 preview files identical to main's (9a8e30c) and the branch's earlier renders from one path.
• CI: not yet run on this head: a fork's pull request needs approval for Actions.

For Noah to try

Use Sill.app from this branch, release-signed with the embedded profile, and the iPad.

1. pmset displaysleepnow, then connect at home and through Tailscale. Expect the picture, not black windows, and Sill.log "Woke the display for …, which connected.". pmset -g assertions should list UserIsActive named: "Sill: a device is using this Mac", its timeout the display-sleep setting.
2. Leave the iPad connected and untouched. The display should sleep by its own setting and stay asleep: no "Woke" line without a touch, also after any "Capture stopped: …". Then move the pointer on the trackpad, or press ⌘ alone on the Magic Keyboard: it should wake. Shift alone and the key row's modifiers send nothing, so they don't.
3. A locked Mac (⌃⌘Q, the display asleep) should show its lock screen on the iPad.
4. Remote instead of Local: quit Sill, run open --env SILL_TEST_USER_ACTIVE=remote /Applications/Sill.app, run pmset displaysleepnow, then connect. Does the panel light, or does the picture come back with the panel dark?
5. Virtual Display on, with a window streaming from Sill's own display while the panel is asleep: does that picture need the panel woken at all?
6. A laptop with its lid closed, on power: expect "…, but the display read asleep 0.5 s later." and no "Woke" line. With an external display, that display should wake.

Towards #134

🤖 Generated with Claude Code

[Saffsanity]

Thanks for the fix, @acalatrava. Following Noah's direction on #134 (user activity when a device connects, rather than keeping the display on for the whole session), commits were added on top of yours on this branch. Your commit is unchanged.

Host: user activity instead of a hold.

• The host declares user activity the way a key press does: IOPMAssertionDeclareUserActivity with kIOPMUserActiveLocal, the declaration caffeinate -u makes (the workaround in Sill doesn’t wake display (Black windows) #134).
• It declares when a device's session connects (every connection), and when a person uses the Mac from the device: an app opened, input, a window's button, a menu item, a trackpad gesture, at most once every 5 s. A sleeping display wakes, and it sleeps again by the Mac's own setting once nobody uses it.
• What the device sends by itself never counts, so an untouched device does not keep the display awake: no pick (the device asks for the Desktop on its own, at a connection's start and after the Mac's capture stops), and no bare pointer move within 2 s after the host restarts its stream (the device re-centres its own pointer then).
• The PreventUserIdleDisplaySleep assertion is gone. Held for every session, it kept the panel lit the whole time (the opposite of Feature Request: Privacy Mode (blank physical display during remote sessions) #133's privacy mode) and kept a Mac at home from idle sleep. The single kIOPMUserActiveRemote declaration became the local one, which is what the workaround uses; a TEST ONLY switch, SILL_TEST_USER_ACTIVE=remote, keeps Remote available to compare on a real Mac.
• DisplayWake (pure) is the whole rule, checked in Tests/checks/display-wake (190 checks, 60 of 60 mutants, in CI's mutants matrix). DisplayActivity, your file rewritten, makes the call on a queue of its own and logs through the host's log instead of NSLog: "Woke the display for ‹device›, which connected." only when the display read asleep before and on half a second after.
• --synthetic test hosts never touch the display; they count disp.wakeDry instead.

Device: the idle-timer change is out of this PR. Turning auto-lock off while the stream screen shows is a separate decision: with two Sill windows, one window's stream screen leaving turned auto-lock back on while the other was still streaming, and now that the Mac's display sleeps by its own setting, an idle device kept awake would sit on a black picture. It would make a good PR of its own if it is safe across windows and says what it does to battery life.

Docs: the support page has "The picture is black" (the part about Sill waking the display is marked for the release that ships it), docs/DEVELOPMENT.md has "A sleeping display", and CLAUDE.md the details. The support page now names the Command key for waking the display from an attached keyboard: Shift alone never leaves the device, since its text system takes it.

Main was merged in three times (most recently at 4d990e9); only lists in the docs and CI's mutants matrix conflicted. The description now says "Towards #134" rather than "Fixes": a test on a real Mac with a sleeping display comes before the issue closes.