A Custom Monitor Rest Mode

-- Screensaver dimming mode:
-- after entering the screensaver, wait delayBeforeDim minutes before lowering brightness;
-- dimDuration controls how long it takes to dim to 0.
-- When leaving the screensaver, for example by pressing Enter to wake, restore the original brightness.

local brightness = require("hs.brightness")
local caffeinate = require("hs.caffeinate")
local timer = require("hs.timer")

-- Configuration
local delayBeforeDim = 1 * 60      -- Wait 1 minute after entering the screensaver before dimming (seconds)
local dimDuration    = 5           -- Total time to dim from the current brightness to 0 (seconds)
local steps          = 2           -- Number of dimming steps; higher values are smoother
local originalBrightness = nil
local dimTimer = nil
local delayTimer = nil

-- Stop all timers and restore brightness
local function restoreBrightness()
    if delayTimer then
        delayTimer:stop()
        delayTimer = nil
    end
    if dimTimer then
        dimTimer:stop()
        dimTimer = nil
    end
    if originalBrightness then
        brightness.set(originalBrightness)
        originalBrightness = nil
    end
end

-- Start dimming
local function startDimming()
    -- Avoid starting another dimming timer if one is already running
    if dimTimer ~= nil then return end

    originalBrightness = brightness.get()
    if not originalBrightness or originalBrightness <= 0 then
        return
    end

    local currentStep = 0
    local stepInterval = dimDuration / steps
    local stepDelta = originalBrightness / steps

    dimTimer = timer.doEvery(stepInterval, function()
        currentStep = currentStep + 1
        local newValue = originalBrightness - stepDelta * currentStep
        if newValue < 0 then newValue = 0 end
        brightness.set(math.floor(newValue + 0.5))

        if currentStep >= steps then
            dimTimer:stop()
            dimTimer = nil
        end
    end)
end

-- When the screensaver starts: wait delayBeforeDim minutes, then start dimming
local function onScreensaverStart()
    -- Prevent duplicate timers
    restoreBrightness()

    delayTimer = timer.doAfter(delayBeforeDim, function()
        startDimming()
    end)
end

-- When the screensaver stops: restore brightness immediately
local function onScreensaverStop()
    restoreBrightness()
end

local watcher = caffeinate.watcher.new(function(event)
    if event == caffeinate.watcher.screensaverDidStart then
        -- Entered screensaver
        onScreensaverStart()

    elseif event == caffeinate.watcher.screensaverDidStop then
        -- Left screensaver, usually triggered by a key press or mouse movement
        onScreensaverStop()

    elseif event == caffeinate.watcher.screensDidLock then
        -- Screen locked, either manually or automatically
        onScreensaverStart()

    elseif event == caffeinate.watcher.screensDidUnlock then
        -- Successfully unlocked, after password or Touch ID
        onScreensaverStop()

    elseif event == caffeinate.watcher.systemDidWake then
        -- The Mac woke from sleep
        restoreBrightness()

    elseif event == caffeinate.watcher.screensDidWake then
        -- The screen woke from sleep
        restoreBrightness()
    end
end)

watcher:start()