fw/shell: halt the app idle timeout while a finger is on the screen

A motionless hold in the launcher (or any app under the idle timeout)
emits no touch events after Touchdown -- the touch service only publishes
PositionUpdate when the coordinates change -- so nothing could refresh the
30 s watchface timeout and it fired mid-touch, yanking the user back to
the watchface while their finger was still down.

Track the physical finger in app_idle_timeout as its own inhibitor,
driven from the kernel touch-event handler: Touchdown halts the timer,
Liftoff restarts it from a full interval. A separate flag (rather than
reusing pause/resume) keeps the hold composed correctly with the
focus-driven pause, so a modal push/pop mid-touch can neither resurrect
nor permanently kill the timeout. The disable/withdraw paths already
synthesize a Liftoff for a finger that is still down, so the hold cannot
leak.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Joshua Jun <lets@throw.rocks>

Author: jplexer

src/fw/kernel/event_loop.c

@@ -335,9 +335,13 @@ static NOINLINE void prv_minimal_event_handler(PebbleEvent* e) {
           PBL_ANALYTICS_ADD(touch_gated_touchdown_count, 1);
         }
         touch_session_extend();
+        // A finger on the screen is ongoing interaction: halt the app idle timeout until liftoff.
+        // A motionless hold emits no further touch events, so a timer refresh alone can't cover it.
+        app_idle_timeout_touch_down();
       } else if (e->touch.event.type == TouchEvent_Liftoff) {
         light_touch_up();
         touch_session_extend();
+        app_idle_timeout_touch_up();
       }
       if (compositor_is_animating() || is_modal_focused) {
         // Mask the app task while the compositor animates or a modal is focused. Otherwise a

src/fw/shell/normal/app_idle_timeout.c

@@ -15,6 +15,9 @@
 TimerID s_timer;
 bool s_app_paused = false;
 bool s_app_started = false;
+// Tracks the physical finger, independent of the app lifecycle: a finger on the screen halts the
+// timeout even across focus pause/resume, and liftoff restarts it only if nothing else pauses it.
+bool s_touch_held = false;
 
 #ifndef CONFIG_NO_WATCH_TIMEOUT
 static const int WATCHFACE_TIMEOUT_MS = 30000;
@@ -33,7 +36,7 @@ static void prv_start_timer(bool create) {
     s_timer = new_timer_create();
   }
 
-  if (s_timer != TIMER_INVALID_ID && !s_app_paused && s_app_started) {
+  if (s_timer != TIMER_INVALID_ID && !s_app_paused && !s_touch_held && s_app_started) {
     bool success = new_timer_start(s_timer, WATCHFACE_TIMEOUT_MS, prv_timeout_expired,
         NULL, 0 /* flags */);
     PBL_ASSERTN(success);
@@ -77,3 +80,17 @@ void app_idle_timeout_refresh(void) {
   prv_start_timer(false /* do not create a timer */);
 #endif
 }
+
+void app_idle_timeout_touch_down(void) {
+  s_touch_held = true;
+  if (s_timer != TIMER_INVALID_ID) {
+    new_timer_stop(s_timer);
+  }
+}
+
+void app_idle_timeout_touch_up(void) {
+  s_touch_held = false;
+#ifndef CONFIG_NO_WATCH_TIMEOUT
+  prv_start_timer(false /* do not create a timer */);
+#endif
+}

src/fw/shell/normal/app_idle_timeout.h

@@ -21,3 +21,11 @@ void app_idle_timeout_resume(void);
 //! is safe to call even if the idle timeout wasn't running previously.
 void app_idle_timeout_refresh(void);
 
+//! Halt the idle timeout while a finger is on the touchscreen. Unlike pause/resume, this state
+//! composes with the focus-driven pause. Safe to call even if the idle timeout isn't running.
+void app_idle_timeout_touch_down(void);
+
+//! Restart the idle timeout when the finger lifts off. Safe to call even if the idle timeout
+//! isn't running or no touch-down was observed.
+void app_idle_timeout_touch_up(void);
+

src/fw/shell/prf/stubs.c

@@ -52,6 +52,12 @@ void watchface_handle_button_event(PebbleEvent *e) {
 void app_idle_timeout_refresh(void) {
 }
 
+void app_idle_timeout_touch_down(void) {
+}
+
+void app_idle_timeout_touch_up(void) {
+}
+
 PebblePhoneCaller* phone_call_util_create_caller(const char *number, const char *name) {
   return NULL;
 }

src/fw/shell/sdk/stubs.c

@@ -21,6 +21,12 @@ void app_idle_timeout_refresh(void) {
 void app_idle_timeout_stop(void) {
 }
 
+void app_idle_timeout_touch_down(void) {
+}
+
+void app_idle_timeout_touch_up(void) {
+}
+
 void watchface_start_low_power(bool enable) {
 }
 

tests/fw/shell/normal/test_app_idle_timeout.c

@@ -0,0 +1,123 @@
+/* SPDX-FileCopyrightText: 2026 Core Devices LLC */
+/* SPDX-License-Identifier: Apache-2.0 */
+
+#include "clar.h"
+
+#include "shell/normal/app_idle_timeout.h"
+
+#include "kernel/event_loop.h"
+#include "shell/normal/watchface.h"
+#include "shell/shell.h"
+
+// Stubs
+/////////////////////////////////////////////////////////////////////////
+#include "stubs_logging.h"
+#include "stubs_passert.h"
+
+#include "fake_new_timer.h"
+
+static int s_watchface_launch_count;
+
+void launcher_task_add_callback(CallbackEventCallback callback, void *data) {
+  callback(data);
+}
+
+const CompositorTransition *shell_get_watchface_compositor_animation(bool watchface_is_destination) {
+  return NULL;
+}
+
+void watchface_launch_default(const CompositorTransition *animation) {
+  s_watchface_launch_count++;
+}
+
+// Module state under test
+/////////////////////////////////////////////////////////////////////////
+extern TimerID s_timer;
+extern bool s_app_paused;
+extern bool s_touch_held;
+
+static bool prv_is_scheduled(void) {
+  return stub_new_timer_is_scheduled(s_timer);
+}
+
+// Tests
+/////////////////////////////////////////////////////////////////////////
+
+void test_app_idle_timeout__initialize(void) {
+  s_watchface_launch_count = 0;
+  app_idle_timeout_stop();
+  s_app_paused = false;
+  s_touch_held = false;
+}
+
+void test_app_idle_timeout__cleanup(void) {
+  app_idle_timeout_stop();
+  stub_new_timer_cleanup();
+}
+
+void test_app_idle_timeout__start_schedules(void) {
+  app_idle_timeout_start();
+  cl_assert(prv_is_scheduled());
+}
+
+void test_app_idle_timeout__touch_hold_halts_until_liftoff(void) {
+  app_idle_timeout_start();
+
+  app_idle_timeout_touch_down();
+  cl_assert(!prv_is_scheduled());
+
+  app_idle_timeout_touch_up();
+  cl_assert(prv_is_scheduled());
+}
+
+void test_app_idle_timeout__refresh_during_hold_stays_halted(void) {
+  app_idle_timeout_start();
+  app_idle_timeout_touch_down();
+
+  app_idle_timeout_refresh();
+  cl_assert(!prv_is_scheduled());
+
+  app_idle_timeout_touch_up();
+  cl_assert(prv_is_scheduled());
+}
+
+void test_app_idle_timeout__hold_composes_with_focus_pause(void) {
+  app_idle_timeout_start();
+
+  // Focus lost mid-hold: liftoff must not restart the timer while paused.
+  app_idle_timeout_touch_down();
+  app_idle_timeout_pause();
+  app_idle_timeout_touch_up();
+  cl_assert(!prv_is_scheduled());
+  app_idle_timeout_resume();
+  cl_assert(prv_is_scheduled());
+
+  // Focus regained mid-hold: resume must not restart the timer while held.
+  app_idle_timeout_pause();
+  app_idle_timeout_touch_down();
+  app_idle_timeout_resume();
+  cl_assert(!prv_is_scheduled());
+  app_idle_timeout_touch_up();
+  cl_assert(prv_is_scheduled());
+}
+
+void test_app_idle_timeout__liftoff_without_touchdown_is_harmless(void) {
+  app_idle_timeout_start();
+  app_idle_timeout_touch_up();
+  cl_assert(prv_is_scheduled());
+}
+
+void test_app_idle_timeout__start_during_hold_waits_for_liftoff(void) {
+  app_idle_timeout_touch_down();
+  app_idle_timeout_start();
+  cl_assert(!prv_is_scheduled());
+
+  app_idle_timeout_touch_up();
+  cl_assert(prv_is_scheduled());
+}
+
+void test_app_idle_timeout__expiry_launches_watchface(void) {
+  app_idle_timeout_start();
+  cl_assert(stub_new_timer_fire(s_timer));
+  cl_assert_equal_i(s_watchface_launch_count, 1);
+}

tests/fw/shell/normal/wscript_build

@@ -4,6 +4,10 @@ clar(ctx,
     sources_ant_glob = " src/fw/shell/normal/system_app_state_machine.c",
     test_sources_ant_glob = "test_normal_system_app_state_machine.c")
 
+clar(ctx,
+    sources_ant_glob = " src/fw/shell/normal/app_idle_timeout.c",
+    test_sources_ant_glob = "test_app_idle_timeout.c")
+
 clar(ctx,
     sources_ant_glob = " src/fw/shell/normal/battery_ui_fsm.c"
                        " src/fw/services/battery/voltage/battery_curve.c",