From 6df52021c8e6c8fd843bc8d5652851e8c0fc6ab8 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Wed, 4 Nov 2026 03:04:43 -0800 Subject: [PATCH] Apple Watch: Sound-effects and vibrate settings, build scripts --- app/g2/wear-remote.ts | 4 ++ app/ui/dashboard-settings.ts | 21 ++++++++ app/ui/dashboard/settings-menus.ts | 9 +++- apple-watch/Faceclaw/FaceclawWatchApp.swift | 2 +- apple-watch/Faceclaw/PadController.swift | 4 +- apple-watch/Faceclaw/Protocol.swift | 8 +-- apple-watch/Faceclaw/Screens.swift | 9 ++-- apple-watch/Faceclaw/WatchPrefs.swift | 57 ++++++++++++++++----- apple-watch/README.md | 10 +++- package.json | 1 + tests/ios-watch-remote.test.cjs | 7 +++ tests/native/apple-watch/main.swift | 5 +- wear/PROTOCOL.md | 9 +++- 13 files changed, 117 insertions(+), 29 deletions(-) diff --git a/app/g2/wear-remote.ts b/app/g2/wear-remote.ts index 56c1dd63..c2e2b597 100644 --- a/app/g2/wear-remote.ts +++ b/app/g2/wear-remote.ts @@ -37,6 +37,8 @@ import { watchCrownClockwiseNextSetting, watchMirrorAssistantSetting, watchRemoteEnabledSetting, + watchSoundEffectsSetting, + watchVibrateOnInputSetting, } from "../ui/dashboard-settings"; import { shell, type AssistantActivityEvent } from "../ui/shell/shell"; import { voiceActivity } from "../ui/shell/voice-activity"; @@ -308,6 +310,8 @@ export class WearRemote { apps: this.listApps(), remoteEnabled: watchRemoteEnabledSetting.get(), crownClockwiseNext: watchCrownClockwiseNextSetting.get(), + vibrateOnInput: watchVibrateOnInputSetting.get(), + soundEffects: watchSoundEffectsSetting.get(), canUnlock: watchCanUnlockSetting.get(), mirrorAssistant: watchMirrorAssistantSetting.get(), assistantAvailable: shell.isAssistantAvailable(), diff --git a/app/ui/dashboard-settings.ts b/app/ui/dashboard-settings.ts index d745145f..6bed4672 100644 --- a/app/ui/dashboard-settings.ts +++ b/app/ui/dashboard-settings.ts @@ -699,6 +699,7 @@ export const watchCanUnlockSetting = new ConfigSettingBoolean({ "Let the watch unlock the glasses' lock screen (which otherwise waits for the phone to be unlocked). Your watch is on your wrist; turn this off if you would rather it stay a phone-only unlock.", }); +// Wear OS only: the Apple Watch's crown doesn't reach the app, so iOS doesn't offer this. export const watchCrownClockwiseNextSetting = new ConfigSettingBoolean({ id: "watch-crown-clockwise-next", label: "Clockwise crown = next", @@ -708,6 +709,26 @@ export const watchCrownClockwiseNextSetting = new ConfigSettingBoolean({ "Choose which crown direction moves to the next item. Off: clockwise moves to the previous item. On: clockwise moves to the next item.", }); +// Apple Watch only: Wear OS has no sounds, and keeps its vibration setting on the watch. +// The watch reads these from the mirrored state (apple-watch/Faceclaw/WatchPrefs.swift). +export const watchVibrateOnInputSetting = new ConfigSettingBoolean({ + id: "watch-vibrate-on-input", + label: "Vibrate on input", + storageKey: "watch.vibrateOnInput", + defaultValue: true, + description: + "Adds a slight vibration with each watch input", +}); + +export const watchSoundEffectsSetting = new ConfigSettingBoolean({ + id: "watch-sound-effects", + label: "Sound effects", + storageKey: "watch.soundEffects", + defaultValue: false, + description: + "On: each input gets its own watchOS feedback, a sound with a vibration (watchOS can't play one alone, so this vibrates even with Vibrate on input off). Off: a light tap for every input. Only Silent Mode on the watch guarantees no sound.", +}); + export const watchMirrorAssistantSetting = new ConfigSettingBoolean({ id: "watch-mirror-assistant", label: "Mirror assistant to watch", diff --git a/app/ui/dashboard/settings-menus.ts b/app/ui/dashboard/settings-menus.ts index e96544f1..f974bb8f 100644 --- a/app/ui/dashboard/settings-menus.ts +++ b/app/ui/dashboard/settings-menus.ts @@ -94,6 +94,8 @@ import { watchCrownClockwiseNextSetting, watchMirrorAssistantSetting, watchRemoteEnabledSetting, + watchSoundEffectsSetting, + watchVibrateOnInputSetting, } from "../dashboard-settings"; import { wearBridge } from "../../native/wear-bridge"; import { openSettingsSubMenu, SettingsPanelLayer, type SettingsSection } from "./settings-panel"; @@ -213,7 +215,12 @@ function settingsSections(): SettingsSection[] { // whether a watch running the companion app is currently reachable. items: [ toggleSettingMenuItem(watchRemoteEnabledSetting), - toggleSettingMenuItem(watchCrownClockwiseNextSetting), + ...(global.isIOS ? [ + toggleSettingMenuItem(watchVibrateOnInputSetting), + toggleSettingMenuItem(watchSoundEffectsSetting), + ] : [ + toggleSettingMenuItem(watchCrownClockwiseNextSetting), + ]), toggleSettingMenuItem(watchCanUnlockSetting), toggleSettingMenuItem(watchMirrorAssistantSetting), ], diff --git a/apple-watch/Faceclaw/FaceclawWatchApp.swift b/apple-watch/Faceclaw/FaceclawWatchApp.swift index 9e4e7e51..becf911a 100644 --- a/apple-watch/Faceclaw/FaceclawWatchApp.swift +++ b/apple-watch/Faceclaw/FaceclawWatchApp.swift @@ -7,7 +7,7 @@ struct FaceclawWatchApp: App { init() { link = PhoneLink() - prefs = WatchPrefs() + prefs = WatchPrefs(link: link) // Here rather than in a view: a background launch never builds one. link.start() } diff --git a/apple-watch/Faceclaw/PadController.swift b/apple-watch/Faceclaw/PadController.swift index 43f086a8..6c57401d 100644 --- a/apple-watch/Faceclaw/PadController.swift +++ b/apple-watch/Faceclaw/PadController.swift @@ -171,8 +171,8 @@ final class PadController { let steps = Int(crownRemainder.rounded(.towardZero)) guard steps != 0 else { return } crownRemainder -= Double(steps) - let clockwiseNext = link.state?.crownClockwiseNext == true - let gesture: RingGesture = (steps > 0) == clockwiseNext ? .scrollDown : .scrollUp + // Clockwise moves to the previous item. + let gesture: RingGesture = steps > 0 ? .scrollUp : .scrollDown guard gestureAllowed(gesture) else { return } // Capped low: a fast twirl otherwise outruns the display. The crown's // own detent haptics are the feedback, so there's no buzz here. diff --git a/apple-watch/Faceclaw/Protocol.swift b/apple-watch/Faceclaw/Protocol.swift index 17efb871..b7574d69 100644 --- a/apple-watch/Faceclaw/Protocol.swift +++ b/apple-watch/Faceclaw/Protocol.swift @@ -115,8 +115,9 @@ struct PhoneState: Equatable { var windows: [WindowEntry] = [] var apps: [AppEntry] = [] var remoteEnabled = true - /** False by default: clockwise moves to the previous item. */ - var crownClockwiseNext = false + /** Settings > Watch on the glasses; WatchPrefs and Haptics say what they do. */ + var vibrateOnInput = true + var soundEffects = false var canUnlock = true var mirrorAssistant = true var assistantAvailable = false @@ -155,7 +156,8 @@ struct PhoneState: Equatable { } state.apps = (o["apps"] as? [[String: Any]] ?? []).map(appEntry) state.remoteEnabled = o["remoteEnabled"] as? Bool ?? true - state.crownClockwiseNext = o["crownClockwiseNext"] as? Bool ?? false + state.vibrateOnInput = o["vibrateOnInput"] as? Bool ?? true + state.soundEffects = o["soundEffects"] as? Bool ?? false state.canUnlock = o["canUnlock"] as? Bool ?? true state.mirrorAssistant = o["mirrorAssistant"] as? Bool ?? true state.assistantAvailable = o["assistantAvailable"] as? Bool ?? false diff --git a/apple-watch/Faceclaw/Screens.swift b/apple-watch/Faceclaw/Screens.swift index 6ce94c7f..bfd7a903 100644 --- a/apple-watch/Faceclaw/Screens.swift +++ b/apple-watch/Faceclaw/Screens.swift @@ -340,20 +340,23 @@ struct StatusScreen: View { // MARK: - Settings -/** Watch-local preferences: feel of the pad and crown. */ +/** Watch-local preferences: feel of the crown. */ struct SettingsScreen: View { @Environment(WatchPrefs.self) private var prefs var body: some View { - @Bindable var prefs = prefs ScrollView { VStack(spacing: 4) { - Toggle("Vibrate on input", isOn: $prefs.haptics) Button { prefs.crownSensitivity = prefs.crownSensitivity.next } label: { RowLabel(title: "Crown sensitivity", detail: prefs.crownSensitivity.rawValue) } + Text("Vibration and sound effects are in Settings > Watch on the glasses.") + .font(.caption2) + .foregroundStyle(.secondary) + .multilineTextAlignment(.center) + .padding(.top, 6) Text("To keep the remote open between glances, set Settings > General > Return to Clock > Faceclaw on the watch.") .font(.caption2) .foregroundStyle(.secondary) diff --git a/apple-watch/Faceclaw/WatchPrefs.swift b/apple-watch/Faceclaw/WatchPrefs.swift index 4bfb33bb..e35c02d0 100644 --- a/apple-watch/Faceclaw/WatchPrefs.swift +++ b/apple-watch/Faceclaw/WatchPrefs.swift @@ -22,33 +22,44 @@ enum CrownSensitivity: String, CaseIterable { } } -/** Watch-local preferences (nothing here is synced to the phone). */ +/** + Crown sensitivity is the watch's own. Vibration and sound follow Settings > Watch on + the glasses, through the mirrored state, which the application context keeps for + when the phone is out of reach. + */ @MainActor @Observable final class WatchPrefs { - /** Buzz on every gesture sent, and tick on crown detents. */ - var haptics: Bool { - didSet { store.set(haptics, forKey: Keys.haptics) } - } + /** Confirm each gesture sent, and tick on crown detents. */ + var haptics: Bool { link.state?.vibrateOnInput ?? true } + + /** Give each gesture its own cue, sound included; see Haptics. */ + var soundEffects: Bool { link.state?.soundEffects ?? false } var crownSensitivity: CrownSensitivity { didSet { store.set(crownSensitivity.rawValue, forKey: Keys.crown) } } + @ObservationIgnored private let link: PhoneLink @ObservationIgnored private let store = UserDefaults.standard private enum Keys { - static let haptics = "haptics" static let crown = "crownSensitivity" } - init() { - haptics = store.object(forKey: Keys.haptics) as? Bool ?? true + init(link: PhoneLink) { + self.link = link crownSensitivity = store.string(forKey: Keys.crown).flatMap(CrownSensitivity.init(rawValue:)) ?? .normal } } -/** The wrist's confirmation of what was sent. */ +/** + The wrist's confirmation of what was sent. watchOS has no call that plays only a + vibration or only a sound: every WKHapticType is both, and only the watch's own Silent + Mode mutes the sound. So sound effects on means the full set of cues, which vibrate + whatever the vibrate setting says, and off means `.click` for everything. Whether + `.click` is truly silent is unconfirmed; see notes/apple-watch-followups.md. + */ @MainActor struct Haptics { let prefs: WatchPrefs @@ -62,10 +73,28 @@ struct Haptics { /** A reply finished arriving. */ func done() { play(.success) } - /** The phone refused or did not answer; always plays. */ - func error() { WKInterfaceDevice.current().play(.failure) } - - private func play(_ type: WKHapticType) { - if prefs.haptics { WKInterfaceDevice.current().play(type) } + /** The phone refused or did not answer; always plays, and never feels like a sent gesture. */ + func error() { + let device = WKInterfaceDevice.current() + if prefs.soundEffects { + device.play(.failure) + return + } + device.play(.click) + Task { + try? await Task.sleep(nanoseconds: Self.errorTapGapNanos) + device.play(.click) + } } + + private func play(_ cue: WKHapticType) { + if prefs.soundEffects { + WKInterfaceDevice.current().play(cue) + } else if prefs.haptics { + WKInterfaceDevice.current().play(.click) + } + } + + /** Apple's documentation asks for at least 100 ms between haptics. */ + private static let errorTapGapNanos: UInt64 = 150_000_000 } diff --git a/apple-watch/README.md b/apple-watch/README.md index 76a3ae3e..ca107eab 100644 --- a/apple-watch/README.md +++ b/apple-watch/README.md @@ -17,7 +17,7 @@ standalone app: without Faceclaw on the iPhone it only tells you to install it. | press and hold | the system menu: Focus app switcher, Voice input, Close window (held until you lift your finger; games that use a long press as a move get it instead) | | tap, then press and hold | the app's context menu | | swipe ↑ ↓ ← → | **spatial navigation**: the launcher moves one app by a row or a column, the settings panel moves between its columns and down its lists, the sidebar moves up and down, Music skips tracks. Right goes *into* things and left comes back *out*. Anywhere without a spatial meaning, up/down scroll, right selects and left goes back. One step per swipe. | -| turn the crown | previous / next. Clockwise is previous by default; reverse it in the on-glasses Settings > Watch section. Sensitivity is in the watch's own settings. | +| turn the crown | previous / next; clockwise is previous. Don't count on it: on a real watch the crown has triggered watchOS's own actions instead of reaching the app. Sensitivity is in the watch's own settings. | | the Double Tap hand gesture (Series 9, Ultra 2, SE 3 and later, watchOS 11) | select | Swipe up from the bottom edge to reveal the buttons, and down from them to hide them: @@ -32,7 +32,8 @@ Swipe up from the bottom edge to reveal the buttons, and down from them to hide - **Status** — connection, display on/off, lock/unlock, whether Faceclaw is answering on the iPhone, and the watch's settings. -Phone-side switches live in Faceclaw's Settings > Watch. While the glasses display +Phone-side switches live in Faceclaw's Settings > Watch, including vibration and +sound effects. While the glasses display is off, a double-tap wakes it and a tap or hold shows the Glanceboard; other gestures do nothing. The watch buzzes differently when the phone refuses or doesn't answer a gesture, and the pill at the bottom says why. @@ -46,6 +47,10 @@ These come from what watchOS allows apps to do: - **No two-finger gestures.** SwiftUI on watchOS only reports one finger. - **No side buttons.** The crown press and side button belong to the system. +- **Vibration and sound come as a pair.** watchOS has no call that plays only one, and + only the watch's own Silent Mode mutes the sound. With sound effects off, every input + gets a light tap rather than its own cue; with them on, inputs vibrate even if + Vibrate on input is off. - **The display can't be kept on.** To keep the remote open between glances, set Settings > General > Return to Clock > Faceclaw on the watch to a longer time. - **The tap that wakes the display does nothing.** The system consumes it, and an @@ -69,6 +74,7 @@ The watch app is its own Xcode project, so it can be opened and previewed alone: ./build_apple_watch.sh # simulator build, no signing ./build_apple_watch.sh --device # signed build for a real watch ./build_apple_watch.sh --install # as --device, then installs on the paired watch +npm run install:apple-watch # the same as --install ``` **It only works with a phone app that embeds it.** The system links the two apps diff --git a/package.json b/package.json index bea34dac..75bc1f7e 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,7 @@ "run:ios": "scripts/ios.sh run ios", "prepare:ios": "scripts/ios.sh prepare ios", "doctor:ios": "scripts/ios.sh doctor ios", + "install:apple-watch": "./build_apple_watch.sh --install", "build": "./build.sh", "lint": "./lint.sh", "run": "./build_and_run.sh", diff --git a/tests/ios-watch-remote.test.cjs b/tests/ios-watch-remote.test.cjs index 21a0ba43..316b854b 100644 --- a/tests/ios-watch-remote.test.cjs +++ b/tests/ios-watch-remote.test.cjs @@ -127,6 +127,7 @@ function loadRemote({ phase = 'disconnected', preview = false, now = 1_800_000_0 '../ui/dashboard-settings': { onAnySettingChanged() {}, watchCanUnlockSetting: setting(true), watchCrownClockwiseNextSetting: setting(false), watchMirrorAssistantSetting: setting(true), watchRemoteEnabledSetting: setting(true), + watchVibrateOnInputSetting: setting(true), watchSoundEffectsSetting: setting(false), }, '../ui/shell/shell': { shell }, '../ui/shell/voice-activity': { voiceActivity: { subscribe() {}, isActive: () => false } }, @@ -207,6 +208,12 @@ test('a watch that does not know its battery shows no level, not an empty one', assert.equal(levels.watch, null); }); +test('the mirrored state carries the Apple Watch feedback settings', () => { + const state = loadRemote({ preview: true }).remote.buildState(); + assert.equal(state.vibrateOnInput, true); + assert.equal(state.soundEffects, false); +}); + test('the mirrored state says when gestures are landing on the preview', () => { const state = loadRemote({ preview: true }).remote.buildState(); assert.equal(state.preview, true); diff --git a/tests/native/apple-watch/main.swift b/tests/native/apple-watch/main.swift index 9c2e6bfe..f9121be1 100644 --- a/tests/native/apple-watch/main.swift +++ b/tests/native/apple-watch/main.swift @@ -123,7 +123,7 @@ do { "screenOn":true,"locked":false,"worn":null,"listening":false,"battery":78,"charging":false,"silentMode":false, "caseBattery":64,"caseCharging":null,"foreground":{"appId":"music","title":"Music"}, "windows":[{"windowId":"w1","title":"Music","appId":"music","focused":true,"closeable":false,"acceptsText":true}], - "apps":[{"appId":"timer","title":"Timer"}],"remoteEnabled":true,"crownClockwiseNext":true,"canUnlock":false, + "apps":[{"appId":"timer","title":"Timer"}],"remoteEnabled":true,"vibrateOnInput":false,"soundEffects":true,"canUnlock":false, "mirrorAssistant":true,"assistantAvailable":true} """ let state = PhoneState.parse(json, updatedAt: 42) @@ -134,7 +134,7 @@ do { check(state?.foreground == AppEntry(appId: "music", title: "Music"), "foreground") check(state?.windows.first?.acceptsText == true && state?.windows.first?.closeable == false, "window flags") check(state?.apps.map(\.appId) == ["timer"], "apps") - check(state?.crownClockwiseNext == true && state?.canUnlock == false, "settings") + check(state?.vibrateOnInput == false && state?.soundEffects == true && state?.canUnlock == false, "settings") check(state?.updatedAt == 42, "updatedAt") } @@ -143,6 +143,7 @@ do { let state = PhoneState.parse("{\"battery\":140,\"unknownField\":[1,2]}", updatedAt: 0) check(state?.battery == nil, "out-of-range percentage is unknown") check(state?.remoteEnabled == true && state?.canUnlock == true, "permissive defaults") + check(state?.vibrateOnInput == true && state?.soundEffects == false, "feedback defaults") check(state?.phase == "disconnected" && state?.takesInput == false, "disconnected default") check(PhoneState.parse("not json", updatedAt: 0) == nil, "garbage is rejected") check(PhoneState.parse("[1]", updatedAt: 0) == nil, "a non-object is rejected") diff --git a/wear/PROTOCOL.md b/wear/PROTOCOL.md index 5c399fc5..02316c92 100644 --- a/wear/PROTOCOL.md +++ b/wear/PROTOCOL.md @@ -68,6 +68,7 @@ dashboard state, re-sent whenever it changes (and at least every 30 s): "windows": [{"windowId": "…", "title": "…", "appId": "…", "focused": true, "closeable": true, "acceptsText": false}], "apps": [{"appId": "timer", "title": "Timer"}], "remoteEnabled": true, "crownClockwiseNext": false, + "vibrateOnInput": true, "soundEffects": false, "canUnlock": true, "mirrorAssistant": true, "assistantAvailable": true } @@ -86,7 +87,13 @@ The watch shows the case level under the charging line. `protocol` is reserved for incompatible revisions of this format (nothing checks it yet). `crownClockwiseNext` mirrors the on-glasses Settings > Watch toggle; when false (the default), clockwise crown -rotation sends previous/up, and when true it sends next/down. +rotation sends previous/up, and when true it sends next/down. Only Wear OS reads +it, and the toggle only appears on Android; on Apple Watch, clockwise is always +previous/up. + +`vibrateOnInput` and `soundEffects` mirror the Settings > Watch toggles that appear +on iOS, and only the Apple Watch app reads them. Wear OS keeps its vibration setting +on the watch and has no sounds. `apps` is the launcher grid plus installed EvenHub packages, i.e. exactly what the assistant's `apps.launch` tool accepts.