@playcademy/sdk 0.6.1-beta.1 → 0.6.1-beta.3

package/README.md

@@ -240,6 +240,23 @@ client.timeback.startActivity({
 })
 // Auto-derived: activityName "Math Quiz Level 1"
 // Auto-filled by backend: appName, subject, sensorUrl
+// Automatically pauses active time when the tab is hidden, the shell pauses,
+// or the player has no visible keyboard/mouse activity for 10 minutes
+
+// Customize inactivity handling
+client.timeback.startActivity(
+    { activityId: 'math-quiz-level-1' },
+    {
+        inactivityTimeoutMs: 5 * 60 * 1000, // 5 minutes
+        heartbeatIntervalMs: 15_000,
+    },
+)
+
+// Disable keyboard/mouse inactivity tracking
+client.timeback.startActivity(
+    { activityId: 'math-quiz-level-1' },
+    { inactivityTimeoutMs: Infinity },
+)
 
 // ... player completes activity ...
 
@@ -323,12 +340,16 @@ const { token } = await client.realtime.token.get()
 
 - `role`: The user's TimeBack role (`'student'`, `'parent'`, `'teacher'`, or `'administrator'`)
 - `enrollments`: Array of course enrollments with `subject`, `grade`, and `courseId`
-- `startActivity(metadata)`: Start tracking an activity (stores start time and metadata)
+- `startActivity(metadata, options?)`: Start tracking an activity (stores start time and metadata)
     - `metadata.activityId`: Unique activity identifier (required)
     - `metadata.activityName`: Human-readable activity name
     - `metadata.subject`: Subject area (Math, Reading, Science, etc.)
     - `metadata.appName`: Application name
     - `metadata.sensorUrl`: Sensor URL for tracking
+    - Automatically pauses active time when the tab is hidden, the shell pauses the game, or the player is idle while visible
+    - `options.pausedHeartbeatTimeoutMs`: Stop periodic heartbeats after a long automatic pause (`hidden` or `inactivity`); `Infinity` keeps them running
+    - `options.heartbeatIntervalMs`: Flush incremental heartbeats (`Infinity` disables periodic heartbeats)
+    - `options.inactivityTimeoutMs`: Keyboard/mouse idle timeout while visible (defaults to 10 minutes; `Infinity` disables)
 - `endActivity(scoreData)`: End activity and submit results
     - `scoreData.correctQuestions`: Number of correct answers
     - `scoreData.totalQuestions`: Total number of questions

package/dist/index.d.ts

@@ -1681,16 +1681,34 @@ declare abstract class PlaycademyBaseClient {
  */
 interface StartActivityOptions {
     /**
-     * How long the tab can stay hidden before the timing window resets on return.
-     * Defaults to 10 minutes. Set to `Infinity` to disable.
+     * How long heartbeats continue after the activity is automatically paused
+     * because the tab is hidden or the player is inactive while visible.
+     * Defaults to 10 minutes. Set to `Infinity` to keep heartbeats running
+     * indefinitely during automatic pauses. Invalid values fall back to the
+     * 10-minute default.
+     */
+    pausedHeartbeatTimeoutMs?: number;
+    /**
+     * @deprecated Use `pausedHeartbeatTimeoutMs` instead.
+     *
+     * Backward-compatible alias for callers that still use the old option
+     * name from earlier SDK releases.
      */
     hiddenTimeoutMs?: number;
     /**
      * How often to flush periodic heartbeats with accumulated time data.
      * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
-     * final unload/endActivity flushes still run.
+     * final unload/endActivity flushes still run. Values must be greater than
+     * 0 or `Infinity`; invalid values fall back to the 15-second default.
      */
     heartbeatIntervalMs?: number;
+    /**
+     * How long the tab can remain visible without keyboard or mouse activity
+     * before the activity is marked inactive. Defaults to 10 minutes. Set to
+     * `Infinity` to disable keyboard/mouse inactivity tracking. Invalid values
+     * fall back to the 10-minute default.
+     */
+    inactivityTimeoutMs?: number;
     /**
      * Stable identifier for this activity run. When provided, it is used on
      * every heartbeat and on endActivity instead of a freshly-generated UUID.
@@ -1772,7 +1790,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `user.fetch()` - Refresh user context from server
      *
      * Activity tracking:
-     * - `startActivity(metadata)` - Begin tracking an activity
+     * - `startActivity(metadata)` - Begin tracking an activity with automatic
+     *   hidden-tab and visible-tab inactivity handling, plus configurable
+     *   paused-heartbeat timeout behavior
      * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
      * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */

package/dist/index.js

@@ -1451,9 +1451,21 @@ function isValidUUID(value) {
 }
 
 // src/core/activity-tracker.ts
-var DEFAULT_HIDDEN_TIMEOUT_MS = 10 * 60 * 1000;
+var DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
+var DEFAULT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var HEARTBEAT_RETRY_POLICY = { retryableMethods: ["POST"] };
+var USER_ACTIVITY_EVENTS = ["keydown", "pointerdown", "pointermove", "wheel"];
+var USER_ACTIVITY_LISTENER_OPTIONS = { capture: true };
+function normalizeDelayMs(value, defaultValue, allowZero = true) {
+  if (value === Infinity) {
+    return Infinity;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && (allowZero ? value >= 0 : value > 0)) {
+    return value;
+  }
+  return defaultValue;
+}
 function getCurrentPausedTotal(activity, now = Date.now()) {
   if (activity.pauseStartTime === null) {
     return activity.pausedTime;
@@ -1503,9 +1515,40 @@ function stopHeartbeatInterval(activity) {
   clearInterval(activity.heartbeatIntervalId);
   activity.heartbeatIntervalId = null;
 }
+function clearInactivityTimeout(activity) {
+  if (activity.inactivityTimeoutId !== null) {
+    clearTimeout(activity.inactivityTimeoutId);
+    activity.inactivityTimeoutId = null;
+  }
+  activity.inactivityTimerStartedAt = null;
+}
+function clearPausedHeartbeatTimeout(activity) {
+  if (activity.pausedHeartbeatTimeoutId !== null) {
+    clearTimeout(activity.pausedHeartbeatTimeoutId);
+    activity.pausedHeartbeatTimeoutId = null;
+  }
+}
+function hasBlockingPauseReason(activity) {
+  for (const reason of activity.pauseReasons) {
+    if (reason !== "inactivity") {
+      return true;
+    }
+  }
+  return false;
+}
+function isDocumentHidden() {
+  return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+function isAutoPauseReason(reason) {
+  return reason === "hidden" || reason === "inactivity";
+}
+function hasAutoPauseReason(activity) {
+  return activity.pauseReasons.has("hidden") || activity.pauseReasons.has("inactivity");
+}
 function createTimebackActivityTracker(client) {
   let currentActivity = null;
   let boundVisibilityHandler = null;
+  let boundUserInteractionHandler = null;
   let boundShellPauseHandler = null;
   let boundShellResumeHandler = null;
   let boundPageHideHandler = null;
@@ -1517,25 +1560,134 @@ function createTimebackActivityTracker(client) {
       flushHeartbeat();
     }, activity.heartbeatIntervalMs);
   }
+  function resetPausedHeartbeatWindow(activity) {
+    const now = Date.now();
+    const pausedAtReset = getCurrentPausedTotal(activity, now);
+    activity.pausedHeartbeatTimedOut = false;
+    activity.windowStartTime = now;
+    activity.windowPausedAtStart = pausedAtReset;
+    startHeartbeatInterval(activity);
+  }
+  function armPausedHeartbeatTimeout(activity) {
+    if (activity.pausedHeartbeatTimeoutMs === Infinity) {
+      return;
+    }
+    clearPausedHeartbeatTimeout(activity);
+    const trackedActivity = activity;
+    activity.pausedHeartbeatTimeoutId = setTimeout(() => {
+      if (currentActivity !== trackedActivity) {
+        return;
+      }
+      trackedActivity.pausedHeartbeatTimeoutId = null;
+      trackedActivity.pausedHeartbeatTimedOut = true;
+      stopHeartbeatInterval(trackedActivity);
+    }, activity.pausedHeartbeatTimeoutMs);
+  }
   function addPauseReason(reason) {
     if (!currentActivity) {
       return;
     }
     const wasPaused = currentActivity.pauseReasons.size > 0;
+    const wasAutoPaused = hasAutoPauseReason(currentActivity);
+    const alreadyHadReason = currentActivity.pauseReasons.has(reason);
     currentActivity.pauseReasons.add(reason);
     if (!wasPaused && currentActivity.pauseReasons.size > 0) {
       currentActivity.pauseStartTime = Date.now();
     }
+    if (isAutoPauseReason(reason) && !alreadyHadReason && !wasAutoPaused) {
+      armPausedHeartbeatTimeout(currentActivity);
+    }
+    syncInactivityTracking();
   }
   function removePauseReason(reason) {
     if (!currentActivity) {
       return;
     }
+    const hadReason = currentActivity.pauseReasons.has(reason);
+    const wasAutoPaused = hasAutoPauseReason(currentActivity);
     currentActivity.pauseReasons.delete(reason);
     if (currentActivity.pauseReasons.size === 0 && currentActivity.pauseStartTime !== null) {
       currentActivity.pausedTime += Date.now() - currentActivity.pauseStartTime;
       currentActivity.pauseStartTime = null;
     }
+    if (isAutoPauseReason(reason) && hadReason && wasAutoPaused && !hasAutoPauseReason(currentActivity)) {
+      clearPausedHeartbeatTimeout(currentActivity);
+      if (currentActivity.pausedHeartbeatTimedOut) {
+        resetPausedHeartbeatWindow(currentActivity);
+      }
+    }
+    syncInactivityTracking();
+  }
+  function captureRemainingInactivityMs(activity, now = Date.now()) {
+    if (activity.inactivityTimerStartedAt === null) {
+      return;
+    }
+    const elapsedMs = Math.max(0, now - activity.inactivityTimerStartedAt);
+    activity.remainingInactivityMs = Math.max(0, activity.remainingInactivityMs - elapsedMs);
+    clearInactivityTimeout(activity);
+  }
+  function shouldRunInactivityCountdown(activity) {
+    if (activity.inactivityTimeoutMs === Infinity) {
+      return false;
+    }
+    if (isDocumentHidden()) {
+      return false;
+    }
+    if (activity.pauseReasons.has("inactivity")) {
+      return false;
+    }
+    return !hasBlockingPauseReason(activity);
+  }
+  function armInactivityTimeout(activity) {
+    if (!shouldRunInactivityCountdown(activity)) {
+      return;
+    }
+    if (activity.remainingInactivityMs <= 0) {
+      addPauseReason("inactivity");
+      return;
+    }
+    clearInactivityTimeout(activity);
+    const trackedActivity = activity;
+    activity.inactivityTimerStartedAt = Date.now();
+    activity.inactivityTimeoutId = setTimeout(() => {
+      if (currentActivity !== trackedActivity) {
+        return;
+      }
+      trackedActivity.remainingInactivityMs = 0;
+      clearInactivityTimeout(trackedActivity);
+      addPauseReason("inactivity");
+    }, trackedActivity.remainingInactivityMs);
+  }
+  function syncInactivityTracking() {
+    const activity = currentActivity;
+    if (!activity) {
+      return;
+    }
+    if (shouldRunInactivityCountdown(activity)) {
+      if (activity.inactivityTimeoutId === null) {
+        armInactivityTimeout(activity);
+      }
+      return;
+    }
+    if (activity.inactivityTimeoutId !== null) {
+      captureRemainingInactivityMs(activity);
+    }
+  }
+  function resetInactivityTracking(activity) {
+    clearInactivityTimeout(activity);
+    activity.remainingInactivityMs = activity.inactivityTimeoutMs;
+  }
+  function handleUserInteraction() {
+    const activity = currentActivity;
+    if (!activity || activity.inactivityTimeoutMs === Infinity || isDocumentHidden()) {
+      return;
+    }
+    resetInactivityTracking(activity);
+    if (activity.pauseReasons.has("inactivity")) {
+      removePauseReason("inactivity");
+      return;
+    }
+    syncInactivityTracking();
   }
   function handleVisibilityChange() {
     if (!currentActivity) {
@@ -1543,34 +1695,8 @@ function createTimebackActivityTracker(client) {
     }
     if (document.visibilityState === "hidden") {
       addPauseReason("hidden");
-      if (currentActivity.hiddenTimeoutMs !== Infinity) {
-        if (currentActivity.hiddenTimeoutId !== null) {
-          clearTimeout(currentActivity.hiddenTimeoutId);
-        }
-        const activity = currentActivity;
-        currentActivity.hiddenTimeoutId = setTimeout(() => {
-          if (currentActivity === activity) {
-            activity.hiddenTimeoutId = null;
-            activity.hiddenTimedOut = true;
-            stopHeartbeatInterval(activity);
-          }
-        }, activity.hiddenTimeoutMs);
-      }
     } else {
-      const shouldResetWindow = currentActivity.hiddenTimedOut;
-      if (currentActivity.hiddenTimeoutId !== null) {
-        clearTimeout(currentActivity.hiddenTimeoutId);
-        currentActivity.hiddenTimeoutId = null;
-      }
       removePauseReason("hidden");
-      if (shouldResetWindow) {
-        const now = Date.now();
-        const pausedAtReset = getCurrentPausedTotal(currentActivity, now);
-        currentActivity.hiddenTimedOut = false;
-        currentActivity.windowStartTime = now;
-        currentActivity.windowPausedAtStart = pausedAtReset;
-        startHeartbeatInterval(currentActivity);
-      }
     }
   }
   function handleShellPause() {
@@ -1645,6 +1771,12 @@ function createTimebackActivityTracker(client) {
       document.removeEventListener("visibilitychange", boundVisibilityHandler);
       boundVisibilityHandler = null;
     }
+    if (boundUserInteractionHandler && typeof document !== "undefined") {
+      for (const eventName of USER_ACTIVITY_EVENTS) {
+        document.removeEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+      }
+      boundUserInteractionHandler = null;
+    }
     if (boundShellPauseHandler) {
       messaging.unlisten("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
       boundShellPauseHandler = null;
@@ -1657,8 +1789,9 @@ function createTimebackActivityTracker(client) {
       globalThis.window.removeEventListener("pagehide", boundPageHideHandler);
       boundPageHideHandler = null;
     }
-    if (currentActivity?.hiddenTimeoutId != null) {
-      clearTimeout(currentActivity.hiddenTimeoutId);
+    if (currentActivity) {
+      clearInactivityTimeout(currentActivity);
+      clearPausedHeartbeatTimeout(currentActivity);
     }
     if (currentActivity?.heartbeatIntervalId != null) {
       stopHeartbeatInterval(currentActivity);
@@ -1671,7 +1804,9 @@ function createTimebackActivityTracker(client) {
       }
       cleanupListeners();
       const now = Date.now();
-      const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+      const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
+      const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
+      const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
       currentActivity = {
         runId: options?.runId ?? crypto.randomUUID(),
         resumeId: crypto.randomUUID(),
@@ -1680,13 +1815,17 @@ function createTimebackActivityTracker(client) {
         pausedTime: 0,
         pauseStartTime: null,
         pauseReasons: new Set,
-        hiddenTimeoutId: null,
-        hiddenTimedOut: false,
-        hiddenTimeoutMs: options?.hiddenTimeoutMs ?? DEFAULT_HIDDEN_TIMEOUT_MS,
+        pausedHeartbeatTimeoutId: null,
+        pausedHeartbeatTimedOut: false,
+        pausedHeartbeatTimeoutMs,
         windowStartTime: now,
         windowPausedAtStart: 0,
         heartbeatIntervalId: null,
         heartbeatIntervalMs,
+        inactivityTimeoutId: null,
+        inactivityTimeoutMs,
+        inactivityTimerStartedAt: null,
+        remainingInactivityMs: inactivityTimeoutMs,
         flushInFlight: null,
         totalPersistedActiveMs: 0,
         totalPersistedPausedMs: 0
@@ -1694,6 +1833,10 @@ function createTimebackActivityTracker(client) {
       if (typeof document !== "undefined") {
         boundVisibilityHandler = handleVisibilityChange;
         document.addEventListener("visibilitychange", boundVisibilityHandler);
+        boundUserInteractionHandler = handleUserInteraction;
+        for (const eventName of USER_ACTIVITY_EVENTS) {
+          document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+        }
         if (document.visibilityState === "hidden") {
           handleVisibilityChange();
         }
@@ -1707,6 +1850,7 @@ function createTimebackActivityTracker(client) {
       boundShellResumeHandler = handleShellResume;
       messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
       messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
+      syncInactivityTracking();
     },
     pauseActivity() {
       if (!currentActivity) {

package/dist/internal.js

@@ -1451,9 +1451,21 @@ function isValidUUID(value) {
 }
 
 // src/core/activity-tracker.ts
-var DEFAULT_HIDDEN_TIMEOUT_MS = 10 * 60 * 1000;
+var DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
+var DEFAULT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var HEARTBEAT_RETRY_POLICY = { retryableMethods: ["POST"] };
+var USER_ACTIVITY_EVENTS = ["keydown", "pointerdown", "pointermove", "wheel"];
+var USER_ACTIVITY_LISTENER_OPTIONS = { capture: true };
+function normalizeDelayMs(value, defaultValue, allowZero = true) {
+  if (value === Infinity) {
+    return Infinity;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && (allowZero ? value >= 0 : value > 0)) {
+    return value;
+  }
+  return defaultValue;
+}
 function getCurrentPausedTotal(activity, now = Date.now()) {
   if (activity.pauseStartTime === null) {
     return activity.pausedTime;
@@ -1503,9 +1515,40 @@ function stopHeartbeatInterval(activity) {
   clearInterval(activity.heartbeatIntervalId);
   activity.heartbeatIntervalId = null;
 }
+function clearInactivityTimeout(activity) {
+  if (activity.inactivityTimeoutId !== null) {
+    clearTimeout(activity.inactivityTimeoutId);
+    activity.inactivityTimeoutId = null;
+  }
+  activity.inactivityTimerStartedAt = null;
+}
+function clearPausedHeartbeatTimeout(activity) {
+  if (activity.pausedHeartbeatTimeoutId !== null) {
+    clearTimeout(activity.pausedHeartbeatTimeoutId);
+    activity.pausedHeartbeatTimeoutId = null;
+  }
+}
+function hasBlockingPauseReason(activity) {
+  for (const reason of activity.pauseReasons) {
+    if (reason !== "inactivity") {
+      return true;
+    }
+  }
+  return false;
+}
+function isDocumentHidden() {
+  return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+function isAutoPauseReason(reason) {
+  return reason === "hidden" || reason === "inactivity";
+}
+function hasAutoPauseReason(activity) {
+  return activity.pauseReasons.has("hidden") || activity.pauseReasons.has("inactivity");
+}
 function createTimebackActivityTracker(client) {
   let currentActivity = null;
   let boundVisibilityHandler = null;
+  let boundUserInteractionHandler = null;
   let boundShellPauseHandler = null;
   let boundShellResumeHandler = null;
   let boundPageHideHandler = null;
@@ -1517,25 +1560,134 @@ function createTimebackActivityTracker(client) {
       flushHeartbeat();
     }, activity.heartbeatIntervalMs);
   }
+  function resetPausedHeartbeatWindow(activity) {
+    const now = Date.now();
+    const pausedAtReset = getCurrentPausedTotal(activity, now);
+    activity.pausedHeartbeatTimedOut = false;
+    activity.windowStartTime = now;
+    activity.windowPausedAtStart = pausedAtReset;
+    startHeartbeatInterval(activity);
+  }
+  function armPausedHeartbeatTimeout(activity) {
+    if (activity.pausedHeartbeatTimeoutMs === Infinity) {
+      return;
+    }
+    clearPausedHeartbeatTimeout(activity);
+    const trackedActivity = activity;
+    activity.pausedHeartbeatTimeoutId = setTimeout(() => {
+      if (currentActivity !== trackedActivity) {
+        return;
+      }
+      trackedActivity.pausedHeartbeatTimeoutId = null;
+      trackedActivity.pausedHeartbeatTimedOut = true;
+      stopHeartbeatInterval(trackedActivity);
+    }, activity.pausedHeartbeatTimeoutMs);
+  }
   function addPauseReason(reason) {
     if (!currentActivity) {
       return;
     }
     const wasPaused = currentActivity.pauseReasons.size > 0;
+    const wasAutoPaused = hasAutoPauseReason(currentActivity);
+    const alreadyHadReason = currentActivity.pauseReasons.has(reason);
     currentActivity.pauseReasons.add(reason);
     if (!wasPaused && currentActivity.pauseReasons.size > 0) {
       currentActivity.pauseStartTime = Date.now();
     }
+    if (isAutoPauseReason(reason) && !alreadyHadReason && !wasAutoPaused) {
+      armPausedHeartbeatTimeout(currentActivity);
+    }
+    syncInactivityTracking();
   }
   function removePauseReason(reason) {
     if (!currentActivity) {
       return;
     }
+    const hadReason = currentActivity.pauseReasons.has(reason);
+    const wasAutoPaused = hasAutoPauseReason(currentActivity);
     currentActivity.pauseReasons.delete(reason);
     if (currentActivity.pauseReasons.size === 0 && currentActivity.pauseStartTime !== null) {
       currentActivity.pausedTime += Date.now() - currentActivity.pauseStartTime;
       currentActivity.pauseStartTime = null;
     }
+    if (isAutoPauseReason(reason) && hadReason && wasAutoPaused && !hasAutoPauseReason(currentActivity)) {
+      clearPausedHeartbeatTimeout(currentActivity);
+      if (currentActivity.pausedHeartbeatTimedOut) {
+        resetPausedHeartbeatWindow(currentActivity);
+      }
+    }
+    syncInactivityTracking();
+  }
+  function captureRemainingInactivityMs(activity, now = Date.now()) {
+    if (activity.inactivityTimerStartedAt === null) {
+      return;
+    }
+    const elapsedMs = Math.max(0, now - activity.inactivityTimerStartedAt);
+    activity.remainingInactivityMs = Math.max(0, activity.remainingInactivityMs - elapsedMs);
+    clearInactivityTimeout(activity);
+  }
+  function shouldRunInactivityCountdown(activity) {
+    if (activity.inactivityTimeoutMs === Infinity) {
+      return false;
+    }
+    if (isDocumentHidden()) {
+      return false;
+    }
+    if (activity.pauseReasons.has("inactivity")) {
+      return false;
+    }
+    return !hasBlockingPauseReason(activity);
+  }
+  function armInactivityTimeout(activity) {
+    if (!shouldRunInactivityCountdown(activity)) {
+      return;
+    }
+    if (activity.remainingInactivityMs <= 0) {
+      addPauseReason("inactivity");
+      return;
+    }
+    clearInactivityTimeout(activity);
+    const trackedActivity = activity;
+    activity.inactivityTimerStartedAt = Date.now();
+    activity.inactivityTimeoutId = setTimeout(() => {
+      if (currentActivity !== trackedActivity) {
+        return;
+      }
+      trackedActivity.remainingInactivityMs = 0;
+      clearInactivityTimeout(trackedActivity);
+      addPauseReason("inactivity");
+    }, trackedActivity.remainingInactivityMs);
+  }
+  function syncInactivityTracking() {
+    const activity = currentActivity;
+    if (!activity) {
+      return;
+    }
+    if (shouldRunInactivityCountdown(activity)) {
+      if (activity.inactivityTimeoutId === null) {
+        armInactivityTimeout(activity);
+      }
+      return;
+    }
+    if (activity.inactivityTimeoutId !== null) {
+      captureRemainingInactivityMs(activity);
+    }
+  }
+  function resetInactivityTracking(activity) {
+    clearInactivityTimeout(activity);
+    activity.remainingInactivityMs = activity.inactivityTimeoutMs;
+  }
+  function handleUserInteraction() {
+    const activity = currentActivity;
+    if (!activity || activity.inactivityTimeoutMs === Infinity || isDocumentHidden()) {
+      return;
+    }
+    resetInactivityTracking(activity);
+    if (activity.pauseReasons.has("inactivity")) {
+      removePauseReason("inactivity");
+      return;
+    }
+    syncInactivityTracking();
   }
   function handleVisibilityChange() {
     if (!currentActivity) {
@@ -1543,34 +1695,8 @@ function createTimebackActivityTracker(client) {
     }
     if (document.visibilityState === "hidden") {
       addPauseReason("hidden");
-      if (currentActivity.hiddenTimeoutMs !== Infinity) {
-        if (currentActivity.hiddenTimeoutId !== null) {
-          clearTimeout(currentActivity.hiddenTimeoutId);
-        }
-        const activity = currentActivity;
-        currentActivity.hiddenTimeoutId = setTimeout(() => {
-          if (currentActivity === activity) {
-            activity.hiddenTimeoutId = null;
-            activity.hiddenTimedOut = true;
-            stopHeartbeatInterval(activity);
-          }
-        }, activity.hiddenTimeoutMs);
-      }
     } else {
-      const shouldResetWindow = currentActivity.hiddenTimedOut;
-      if (currentActivity.hiddenTimeoutId !== null) {
-        clearTimeout(currentActivity.hiddenTimeoutId);
-        currentActivity.hiddenTimeoutId = null;
-      }
       removePauseReason("hidden");
-      if (shouldResetWindow) {
-        const now = Date.now();
-        const pausedAtReset = getCurrentPausedTotal(currentActivity, now);
-        currentActivity.hiddenTimedOut = false;
-        currentActivity.windowStartTime = now;
-        currentActivity.windowPausedAtStart = pausedAtReset;
-        startHeartbeatInterval(currentActivity);
-      }
     }
   }
   function handleShellPause() {
@@ -1645,6 +1771,12 @@ function createTimebackActivityTracker(client) {
       document.removeEventListener("visibilitychange", boundVisibilityHandler);
       boundVisibilityHandler = null;
     }
+    if (boundUserInteractionHandler && typeof document !== "undefined") {
+      for (const eventName of USER_ACTIVITY_EVENTS) {
+        document.removeEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+      }
+      boundUserInteractionHandler = null;
+    }
     if (boundShellPauseHandler) {
       messaging.unlisten("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
       boundShellPauseHandler = null;
@@ -1657,8 +1789,9 @@ function createTimebackActivityTracker(client) {
       globalThis.window.removeEventListener("pagehide", boundPageHideHandler);
       boundPageHideHandler = null;
     }
-    if (currentActivity?.hiddenTimeoutId != null) {
-      clearTimeout(currentActivity.hiddenTimeoutId);
+    if (currentActivity) {
+      clearInactivityTimeout(currentActivity);
+      clearPausedHeartbeatTimeout(currentActivity);
     }
     if (currentActivity?.heartbeatIntervalId != null) {
       stopHeartbeatInterval(currentActivity);
@@ -1671,7 +1804,9 @@ function createTimebackActivityTracker(client) {
       }
       cleanupListeners();
       const now = Date.now();
-      const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+      const heartbeatIntervalMs = normalizeDelayMs(options?.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS, false);
+      const pausedHeartbeatTimeoutMs = normalizeDelayMs(options?.pausedHeartbeatTimeoutMs ?? options?.hiddenTimeoutMs, DEFAULT_PAUSED_HEARTBEAT_TIMEOUT_MS, false);
+      const inactivityTimeoutMs = normalizeDelayMs(options?.inactivityTimeoutMs, DEFAULT_INACTIVITY_TIMEOUT_MS, false);
       currentActivity = {
         runId: options?.runId ?? crypto.randomUUID(),
         resumeId: crypto.randomUUID(),
@@ -1680,13 +1815,17 @@ function createTimebackActivityTracker(client) {
         pausedTime: 0,
         pauseStartTime: null,
         pauseReasons: new Set,
-        hiddenTimeoutId: null,
-        hiddenTimedOut: false,
-        hiddenTimeoutMs: options?.hiddenTimeoutMs ?? DEFAULT_HIDDEN_TIMEOUT_MS,
+        pausedHeartbeatTimeoutId: null,
+        pausedHeartbeatTimedOut: false,
+        pausedHeartbeatTimeoutMs,
         windowStartTime: now,
         windowPausedAtStart: 0,
         heartbeatIntervalId: null,
         heartbeatIntervalMs,
+        inactivityTimeoutId: null,
+        inactivityTimeoutMs,
+        inactivityTimerStartedAt: null,
+        remainingInactivityMs: inactivityTimeoutMs,
         flushInFlight: null,
         totalPersistedActiveMs: 0,
         totalPersistedPausedMs: 0
@@ -1694,6 +1833,10 @@ function createTimebackActivityTracker(client) {
       if (typeof document !== "undefined") {
         boundVisibilityHandler = handleVisibilityChange;
         document.addEventListener("visibilitychange", boundVisibilityHandler);
+        boundUserInteractionHandler = handleUserInteraction;
+        for (const eventName of USER_ACTIVITY_EVENTS) {
+          document.addEventListener(eventName, boundUserInteractionHandler, USER_ACTIVITY_LISTENER_OPTIONS);
+        }
         if (document.visibilityState === "hidden") {
           handleVisibilityChange();
         }
@@ -1707,6 +1850,7 @@ function createTimebackActivityTracker(client) {
       boundShellResumeHandler = handleShellResume;
       messaging.listen("PLAYCADEMY_PAUSE" /* PAUSE */, boundShellPauseHandler);
       messaging.listen("PLAYCADEMY_RESUME" /* RESUME */, boundShellResumeHandler);
+      syncInactivityTracking();
     },
     pauseActivity() {
       if (!currentActivity) {

package/dist/types.d.ts

@@ -5174,16 +5174,34 @@ declare abstract class PlaycademyBaseClient {
  */
 interface StartActivityOptions {
     /**
-     * How long the tab can stay hidden before the timing window resets on return.
-     * Defaults to 10 minutes. Set to `Infinity` to disable.
+     * How long heartbeats continue after the activity is automatically paused
+     * because the tab is hidden or the player is inactive while visible.
+     * Defaults to 10 minutes. Set to `Infinity` to keep heartbeats running
+     * indefinitely during automatic pauses. Invalid values fall back to the
+     * 10-minute default.
+     */
+    pausedHeartbeatTimeoutMs?: number;
+    /**
+     * @deprecated Use `pausedHeartbeatTimeoutMs` instead.
+     *
+     * Backward-compatible alias for callers that still use the old option
+     * name from earlier SDK releases.
      */
     hiddenTimeoutMs?: number;
     /**
      * How often to flush periodic heartbeats with accumulated time data.
      * Defaults to 15 seconds. Set to `Infinity` to disable the interval;
-     * final unload/endActivity flushes still run.
+     * final unload/endActivity flushes still run. Values must be greater than
+     * 0 or `Infinity`; invalid values fall back to the 15-second default.
      */
     heartbeatIntervalMs?: number;
+    /**
+     * How long the tab can remain visible without keyboard or mouse activity
+     * before the activity is marked inactive. Defaults to 10 minutes. Set to
+     * `Infinity` to disable keyboard/mouse inactivity tracking. Invalid values
+     * fall back to the 10-minute default.
+     */
+    inactivityTimeoutMs?: number;
     /**
      * Stable identifier for this activity run. When provided, it is used on
      * every heartbeat and on endActivity instead of a freshly-generated UUID.
@@ -5265,7 +5283,9 @@ declare class PlaycademyClient extends PlaycademyBaseClient {
      * - `user.fetch()` - Refresh user context from server
      *
      * Activity tracking:
-     * - `startActivity(metadata)` - Begin tracking an activity
+     * - `startActivity(metadata)` - Begin tracking an activity with automatic
+     *   hidden-tab and visible-tab inactivity handling, plus configurable
+     *   paused-heartbeat timeout behavior
      * - `pauseActivity()` / `resumeActivity()` - Pause/resume timer
      * - `endActivity(scoreData)` - Submit activity results to TimeBack
      */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.6.1-beta.1",
+    "version": "0.6.1-beta.3",
     "type": "module",
     "exports": {
         ".": {