Features: shift-swipe thirds, ctrl+A lock screen, Help menu label

- GestureAction.thirdWidth (fixture-compatible decode); recognizer snapshots
  Shift; left/right swipes with Shift tile to thirds, combining with Cmd
  (TDD: 6 new tests incl. decode compatibility)
- TilingCommand left/rightThird + geometry (live integration test) and
  lockScreen via SACLockScreenImmediate with CGSession fallback
- HotkeyController: ctrl+A -> lock screen (conflict with beginning-of-line
  flagged to and accepted by owner)
- Menu: Help label; guide cheat sheet gains ctrl+A and shift-third rows;
  README screenshot regenerated. 103 tests green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: alexnskcody

Sources/Tiler/AppDelegate.swift

@@ -219,9 +219,16 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
         NSLog("Tiler: gesture %@ nextDisplay=%d", action.direction.rawValue, action.nextDisplay ? 1 : 0)
         let command: TilingCommand
         switch action.direction {
-        case .left: command = .leftHalf(nextDisplay: action.nextDisplay)
-        case .right: command = .rightHalf(nextDisplay: action.nextDisplay)
-        case .up: command = .maximize
+        case .left:
+            command = action.thirdWidth
+                ? .leftThird(nextDisplay: action.nextDisplay)
+                : .leftHalf(nextDisplay: action.nextDisplay)
+        case .right:
+            command = action.thirdWidth
+                ? .rightThird(nextDisplay: action.nextDisplay)
+                : .rightHalf(nextDisplay: action.nextDisplay)
+        case .up:
+            command = .maximize
         }
         execute(command)
     }
@@ -254,7 +261,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
         item.button?.imagePosition = .imageLeft
 
         let menu = NSMenu()
-        menu.addItem(makeItem("Tiler", #selector(showGuideAction)))
+        menu.addItem(makeItem("Help", #selector(showGuideAction)))
         let settingsItem = makeItem("Settings", #selector(showSettingsAction))
         settingsItem.keyEquivalent = ","
         menu.addItem(settingsItem)

Sources/Tiler/GuideWindow.swift

@@ -42,6 +42,7 @@ enum GuideContent {
         let id = UUID()
         let direction: GestureDirection
         let cmd: Bool
+        var shift: Bool = false
         let action: String
     }
 
@@ -74,18 +75,21 @@ enum GuideContent {
         HotkeyRow(keys: ["⌃", "⇧", "↓"], action: "Restore the window's previous frame"),
         HotkeyRow(keys: ["⌘", "⌃", "⇧", "←"], action: "Left half on the next display"),
         HotkeyRow(keys: ["⌘", "⌃", "⇧", "→"], action: "Right half on the next display"),
+        HotkeyRow(keys: ["⌃", "A"], action: "Lock the screen"),
     ]
 
     static let gestures: [GestureRow] = [
         GestureRow(direction: .left, cmd: false, action: "Left half"),
         GestureRow(direction: .right, cmd: false, action: "Right half"),
         GestureRow(direction: .up, cmd: false, action: "Maximize"),
+        GestureRow(direction: .left, cmd: false, shift: true, action: "Left third"),
+        GestureRow(direction: .right, cmd: false, shift: true, action: "Right third"),
         GestureRow(direction: .left, cmd: true, action: "Left half on the next display"),
         GestureRow(direction: .right, cmd: true, action: "Right half on the next display"),
     ]
 
     static let gestureFootnote =
-        "Exactly three fingers, one confident stroke. Two- and four-finger movements and swipe-down do nothing — by design."
+        "Exactly three fingers, one confident stroke. ⇧ and ⌘ combine (⇧⌘ = third on the next display). Two- and four-finger movements and swipe-down do nothing — by design."
 
     /// Honesty marker: the only configuration this build was actually verified on.
     static let verifiedOn = "verified on macOS 26.5 only"
@@ -146,7 +150,9 @@ struct GuideView: View {
                             ForEach(GuideContent.gestures) { row in
                                 GridRow {
                                     HStack(spacing: 6) {
-                                        if row.cmd { keycaps(["⌘"]) }
+                                        if row.cmd || row.shift {
+                                            keycaps((row.cmd ? ["⌘"] : []) + (row.shift ? ["⇧"] : []))
+                                        }
                                         HoverDemo(direction: row.direction)
                                     }
                                     .gridColumnAlignment(.trailing)

Sources/TilerCore/GestureRecognizer.swift

@@ -60,9 +60,10 @@ public final class GestureRecognizer {
         pendingTunables = nil
     }
 
-    /// Process one frame. `cmdHeld` is the Cmd-modifier snapshot at frame time.
+    /// Process one frame. `cmdHeld`/`shiftHeld` are modifier snapshots at frame time.
     /// Returns an action only at the exact moment a gesture is confirmed.
-    public func process(_ frame: TouchFrame, cmdHeld: Bool = false) -> GestureAction? {
+    public func process(_ frame: TouchFrame, cmdHeld: Bool = false,
+                        shiftHeld: Bool = false) -> GestureAction? {
         let t = frame.timestamp
 
         // Stream silence implies zero contacts for the whole gap: if the gap covers
@@ -96,7 +97,8 @@ public final class GestureRecognizer {
             processIdle(active: active, palmPresent: palmPresent, at: t)
             return nil
         case .tracking:
-            return processTracking(active: active, palmPresent: palmPresent, at: t, cmdHeld: cmdHeld)
+            return processTracking(active: active, palmPresent: palmPresent, at: t,
+                                   cmdHeld: cmdHeld, shiftHeld: shiftHeld)
         }
     }
 
@@ -153,7 +155,7 @@ public final class GestureRecognizer {
     }
 
     private func processTracking(active: [Contact], palmPresent: Bool,
-                                 at t: Double, cmdHeld: Bool) -> GestureAction? {
+                                 at t: Double, cmdHeld: Bool, shiftHeld: Bool) -> GestureAction? {
         let keys = Set(active.map { FingerKey(device: $0.deviceID, finger: $0.fingerID) })
         guard !palmPresent, active.count == 3, keys == trackedFingers else {
             lockoutNow()
@@ -215,11 +217,12 @@ public final class GestureRecognizer {
         case .down:
             return nil // deliberately not implemented
         case .up:
+            // ⇧ is meaningless for maximize and is ignored (spec).
             return cmdHeld ? nil : GestureAction(direction: .up, nextDisplay: false)
         case .left:
-            return GestureAction(direction: .left, nextDisplay: cmdHeld)
+            return GestureAction(direction: .left, nextDisplay: cmdHeld, thirdWidth: shiftHeld)
         case .right:
-            return GestureAction(direction: .right, nextDisplay: cmdHeld)
+            return GestureAction(direction: .right, nextDisplay: cmdHeld, thirdWidth: shiftHeld)
         }
     }
 

Sources/TilerCore/Models.swift

@@ -50,12 +50,24 @@ public enum GestureDirection: String, Codable, Sendable, Equatable {
 }
 
 /// The single output of a confirmed gesture. Swipe-down and Cmd+up produce no action.
+/// `thirdWidth` = ⇧ held at confirmation: left/right tile to thirds instead of halves.
 public struct GestureAction: Codable, Sendable, Equatable {
     public var direction: GestureDirection
     public var nextDisplay: Bool
+    public var thirdWidth: Bool
 
-    public init(direction: GestureDirection, nextDisplay: Bool) {
+    public init(direction: GestureDirection, nextDisplay: Bool, thirdWidth: Bool = false) {
         self.direction = direction
         self.nextDisplay = nextDisplay
+        self.thirdWidth = thirdWidth
+    }
+
+    // Custom decode: golden fixtures recorded before thirdWidth existed must keep
+    // decoding (missing key defaults to false).
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        direction = try container.decode(GestureDirection.self, forKey: .direction)
+        nextDisplay = try container.decode(Bool.self, forKey: .nextDisplay)
+        thirdWidth = try container.decodeIfPresent(Bool.self, forKey: .thirdWidth) ?? false
     }
 }

Sources/TilerSystem/GestureEngine.swift

@@ -52,8 +52,10 @@ public final class GestureEngine: @unchecked Sendable {
         tap?(frame)
 
         recorder?.append(frame)
-        let cmdHeld = CGEventSource.flagsState(.hidSystemState).contains(.maskCommand)
-        if let action = recognizer.process(frame, cmdHeld: cmdHeld) {
+        let flags = CGEventSource.flagsState(.hidSystemState)
+        if let action = recognizer.process(frame,
+                                           cmdHeld: flags.contains(.maskCommand),
+                                           shiftHeld: flags.contains(.maskShift)) {
             onAction(action)
         }
     }

Sources/TilerSystem/HotkeyController.swift

@@ -11,21 +11,23 @@ public final class HotkeyController {
     public var handler: ((TilingCommand) -> Void)?
 
     private enum Key: UInt32, CaseIterable {
-        case left = 1, right, up, down, cmdLeft, cmdRight
+        case left = 1, right, up, down, cmdLeft, cmdRight, lockScreen
 
         var keyCode: UInt32 {
             switch self {
             case .left, .cmdLeft: UInt32(kVK_LeftArrow)
             case .right, .cmdRight: UInt32(kVK_RightArrow)
             case .up: UInt32(kVK_UpArrow)
             case .down: UInt32(kVK_DownArrow)
+            case .lockScreen: UInt32(kVK_ANSI_A)
             }
         }
 
         var modifiers: UInt32 {
             switch self {
             case .left, .right, .up, .down: UInt32(controlKey | shiftKey)
             case .cmdLeft, .cmdRight: UInt32(cmdKey | controlKey | shiftKey)
+            case .lockScreen: UInt32(controlKey)
             }
         }
     }
@@ -108,6 +110,8 @@ public final class HotkeyController {
             emit(.leftHalf(nextDisplay: true))
         case .cmdRight:
             emit(.rightHalf(nextDisplay: true))
+        case .lockScreen:
+            emit(.lockScreen)
         case .up:
             let now = ProcessInfo.processInfo.systemUptime
             if let decision = resolver.registerPress(at: now) {

Sources/TilerSystem/WindowActions.swift

@@ -6,9 +6,12 @@ import TilerCore
 public enum TilingCommand: Equatable, Sendable {
     case leftHalf(nextDisplay: Bool)
     case rightHalf(nextDisplay: Bool)
+    case leftThird(nextDisplay: Bool)
+    case rightThird(nextDisplay: Bool)
     case maximize
     case centerThird
     case restore
+    case lockScreen
 }
 
 /// AX window manipulation layer (specs/window-actions/spec.md).
@@ -34,6 +37,10 @@ public final class WindowActions {
     /// can feed PermissionMonitor.noteActionFailed().
     @discardableResult
     public func perform(_ command: TilingCommand) -> Bool {
+        if command == .lockScreen {
+            lockScreen()
+            return true
+        }
         guard let (app, window) = frontmostFocusedWindow() else {
             NSLog("Tiler: no focused window for \(command) — ignoring")
             return false
@@ -45,6 +52,10 @@ public final class WindowActions {
     /// the window by pid instead of relying on frontmost focus).
     @discardableResult
     public func perform(_ command: TilingCommand, app: AXUIElement, window: AXUIElement) -> Bool {
+        if command == .lockScreen {
+            lockScreen()
+            return true
+        }
         trimStoresIfNeeded()
         guard let currentAX = frame(of: window) else {
             NSLog("Tiler: cannot read window frame — ignoring \(command)")
@@ -93,6 +104,12 @@ public final class WindowActions {
                           width: vf.width / 2, height: vf.height)
         }
 
+        func third(of screen: NSScreen, left: Bool) -> CGRect {
+            let vf = screen.visibleFrame
+            return CGRect(x: left ? vf.minX : vf.minX + vf.width * 2 / 3, y: vf.minY,
+                          width: vf.width / 3, height: vf.height)
+        }
+
         switch command {
         case .maximize:
             return current.visibleFrame
@@ -103,7 +120,11 @@ public final class WindowActions {
             return half(of: nextDisplay ? next(after: current, in: screens) : current, left: true)
         case .rightHalf(let nextDisplay):
             return half(of: nextDisplay ? next(after: current, in: screens) : current, left: false)
-        case .restore:
+        case .leftThird(let nextDisplay):
+            return third(of: nextDisplay ? next(after: current, in: screens) : current, left: true)
+        case .rightThird(let nextDisplay):
+            return third(of: nextDisplay ? next(after: current, in: screens) : current, left: false)
+        case .restore, .lockScreen:
             return nil
         }
     }
@@ -234,6 +255,28 @@ public final class WindowActions {
         AXUIElementSetAttributeValue(element, attribute as CFString, value ? kCFBooleanTrue : kCFBooleanFalse)
     }
 
+    /// System screen lock (⌃A hotkey): private login framework, same effect as
+    /// the system Lock Screen; CGSession suspend as fallback. No AX involved.
+    private func lockScreen() {
+        typealias LockFn = @convention(c) () -> Int32
+        if let handle = dlopen("/System/Library/PrivateFrameworks/login.framework/login", RTLD_NOW),
+           let sym = dlsym(handle, "SACLockScreenImmediate") {
+            _ = unsafeBitCast(sym, to: LockFn.self)()
+            NSLog("Tiler: screen locked (SACLockScreenImmediate)")
+            return
+        }
+        let task = Process()
+        task.executableURL = URL(fileURLWithPath:
+            "/System/Library/CoreServices/Menu Extras/User.menu/Contents/Resources/CGSession")
+        task.arguments = ["-suspend"]
+        do {
+            try task.run()
+            NSLog("Tiler: screen locked (CGSession fallback)")
+        } catch {
+            NSLog("Tiler: lock screen failed: \(error)")
+        }
+    }
+
     /// Drop entries for windows that no longer answer AX queries (closed windows).
     private func trimStoresIfNeeded() {
         guard originalFrames.count > 64 else { return }

Tests/TilerCoreTests/GestureSim.swift

@@ -14,28 +14,29 @@ struct Sim {
         t = startTime
     }
 
-    mutating func feed(_ contacts: [Contact], cmd: Bool = false) {
-        if let a = recognizer.process(TouchFrame(timestamp: t, contacts: contacts), cmdHeld: cmd) {
+    mutating func feed(_ contacts: [Contact], cmd: Bool = false, shift: Bool = false) {
+        if let a = recognizer.process(TouchFrame(timestamp: t, contacts: contacts),
+                                      cmdHeld: cmd, shiftHeld: shift) {
             actions.append(a)
         }
         t += dt
     }
 
-    mutating func hold(_ contacts: [Contact], frames: Int, cmd: Bool = false) {
-        for _ in 0..<frames { feed(contacts, cmd: cmd) }
+    mutating func hold(_ contacts: [Contact], frames: Int, cmd: Bool = false, shift: Bool = false) {
+        for _ in 0..<frames { feed(contacts, cmd: cmd, shift: shift) }
     }
 
     /// Move `n` fingers' centroid from `start` by `delta` over `frames` frames.
     /// `extra` contacts (palm, stale…) are appended to every frame.
     mutating func move(_ n: Int, from start: (x: Double, y: Double),
                        by delta: (dx: Double, dy: Double), frames: Int,
-                       cmd: Bool = false, size: Double = 0.5,
+                       cmd: Bool = false, shift: Bool = false, size: Double = 0.5,
                        idBase: Int32 = 1, extra: [Contact] = []) {
         for i in 1...frames {
             let f = Double(i) / Double(frames)
             let contacts = fingers(n, at: start.x + delta.dx * f, start.y + delta.dy * f,
                                    size: size, idBase: idBase)
-            feed(contacts + extra, cmd: cmd)
+            feed(contacts + extra, cmd: cmd, shift: shift)
         }
     }
 
@@ -47,9 +48,10 @@ struct Sim {
 
     /// Canonical valid 3-finger swipe: arm stationary, move, lift.
     /// delta of ±0.15 with 18 move frames comfortably exceeds all confirm thresholds.
-    mutating func performValidSwipe(_ delta: (dx: Double, dy: Double), cmd: Bool = false) {
-        hold(fingers(3, at: 0.5, 0.5), frames: 5, cmd: cmd)
-        move(3, from: (0.5, 0.5), by: delta, frames: 18, cmd: cmd)
+    mutating func performValidSwipe(_ delta: (dx: Double, dy: Double),
+                                    cmd: Bool = false, shift: Bool = false) {
+        hold(fingers(3, at: 0.5, 0.5), frames: 5, cmd: cmd, shift: shift)
+        move(3, from: (0.5, 0.5), by: delta, frames: 18, cmd: cmd, shift: shift)
         liftAll()
     }
 }

Tests/TilerCoreTests/ShiftModifierTests.swift

@@ -0,0 +1,45 @@
+import Foundation
+import Testing
+@testable import TilerCore
+
+// Shift modifier (add-thirds-lock-help): ⇧ at confirmation turns left/right into
+// third-width actions; combines with ⌘; ignored for up.
+@Suite("Shift modifier") struct ShiftModifierTests {
+
+    @Test func shiftLeftSwipeEmitsThirdWidth() {
+        var sim = Sim()
+        sim.performValidSwipe((dx: -0.15, dy: 0), shift: true)
+        #expect(sim.actions == [GestureAction(direction: .left, nextDisplay: false, thirdWidth: true)])
+    }
+
+    @Test func shiftRightSwipeEmitsThirdWidth() {
+        var sim = Sim()
+        sim.performValidSwipe((dx: 0.15, dy: 0), shift: true)
+        #expect(sim.actions == [GestureAction(direction: .right, nextDisplay: false, thirdWidth: true)])
+    }
+
+    @Test func shiftAndCmdCombine() {
+        var sim = Sim()
+        sim.performValidSwipe((dx: -0.15, dy: 0), cmd: true, shift: true)
+        #expect(sim.actions == [GestureAction(direction: .left, nextDisplay: true, thirdWidth: true)])
+    }
+
+    @Test func plainSwipesStayHalfWidth() {
+        var sim = Sim()
+        sim.performValidSwipe((dx: 0.15, dy: 0))
+        #expect(sim.actions == [GestureAction(direction: .right, nextDisplay: false, thirdWidth: false)])
+    }
+
+    @Test func shiftWithUpIsIgnoredPlainMaximize() {
+        var sim = Sim()
+        sim.performValidSwipe((dx: 0, dy: 0.15), shift: true)
+        #expect(sim.actions == [GestureAction(direction: .up, nextDisplay: false, thirdWidth: false)])
+    }
+
+    // Old golden fixtures predate thirdWidth: decoding must default it to false.
+    @Test func decodingWithoutThirdWidthDefaultsFalse() throws {
+        let json = Data(#"{"direction":"left","nextDisplay":false}"#.utf8)
+        let action = try JSONDecoder().decode(GestureAction.self, from: json)
+        #expect(action == GestureAction(direction: .left, nextDisplay: false, thirdWidth: false))
+    }
+}