connect.idle

Read the system's idle state and react to transitions between active, idle, and locked.

• Capability: idle
• Namespace: connect.idle

Walkthrough

Back off work while the user is away.

1. Declare idle:

   { "capabilities": ["idle"] }

2. Subscribe to transitions:

   connect.idle.onStateChanged((s) => s === 'active' ? resume() : pause());

3. Or poll the current state with queryState when you need a one-off check.

Methods

idle.queryState(detectionInterval?)

Get the current state.

How to use it

1. Optionally pass a detectionInterval (seconds of inactivity → 'idle').
2. await 'active' / 'idle' / 'locked'.

Signature — connect.idle.queryState(detectionInterval = 60)

Parameters

Returns — Promise<'active' | 'idle' | 'locked'>.

if (await connect.idle.queryState(120) === 'active') poll();

idle.setDetectionInterval(seconds)

Set the threshold used for the 'idle' classification.

How to use it

1. Pass the number of idle seconds you want to count as 'idle'.

Signature — connect.idle.setDetectionInterval(seconds) · Returns Promise<void>.

Events

idle.onStateChanged(cb)

Fires on a state transition (inactivity crossing the threshold, or lock/unlock).

How to use it

1. Subscribe once.
2. Pause heavy work on 'idle' / 'locked', resume on 'active'.

Payload — 'active' | 'idle' | 'locked'.

connect.idle.onStateChanged((state) => {
  if (state === 'locked') pauseWork();
});

Notes

• Use idle to back off polling / heavy work while the user is away, and resume on 'active'.