Module routines 

Guided break routines + the routine engine (#152, #153).

A routine is an ordered list of RoutineSteps — each a short instruction shown for a number of seconds — that the break overlay walks through instead of rotating flat hint text. Each routine is tagged with a RoutineCategory and a RoutineDifficulty.

Per break kind the user picks, in the Breaks tab, one of three modes (persisted in Settings as micro_routine / long_routine):

• "" — off; the overlay falls back to plain hint rotation.
• a routine id — always run that specific routine.
• "random" — the engine: pick a routine at break time from the bundled set, filtered by the profile’s chosen categories (*_routine_categories) and a maximum difficulty (*_routine_max_difficulty).

The selection core (routines_matching + resolve_routine) is pure and deterministic — the only impurity is random_index, which chooses which of the matching routines to run.

Structs

ResolvedRoutine

Steps + pacing metadata resolved for a single break, produced by a single random_index call so all three fields always come from the same routine draw.

Routine

A curated, ordered sequence of guided break steps with a stable id (persisted in settings), a human label, and engine metadata (category / difficulty). Deserialize so user routines can arrive from imported content packs (#155) and persist in Settings.

Enums

RoutineCategory

The theme a routine belongs to, used to filter the randomized pool.

RoutineDifficulty

How demanding a routine is. Ordered Gentle < Moderate < Active; the per-kind *_routine_max_difficulty filter includes everything up to and including the chosen level. Default is Active (the most permissive filter) so a stale/unknown value can fall back through the shared deserialize_with_fallback helper, matching the other tolerant settings enums.

RoutineKind

Which break kind a routine is offered for. Sleep has no routines.

Functions

all_routines

Every routine available to a profile: the bundled starters plus any the user has imported from a content pack (custom_routines). A custom routine whose id collides with a starter is dropped so the built-in always wins (import already rejects such ids, but resolve stays defensive).

get_routines

List every routine (starter + imported) for the Breaks-tab picker.

random_index 🔒

A random index in [0, n), or 0 when n is 0 or entropy is unavailable. The lone impurity in the routine engine; kept tiny so the pure selection core stays fully testable. Uniform enough for picking a routine (the modulo bias across a handful of routines is negligible).

resolve_routine

Resolve the guided routine for a break of kind from the user’s per-kind settings: "" → none, a routine id → that routine, "random" → the engine picks one from the filtered pool. Unknown ids and the Sleep kind resolve to an empty routine. A single random_index call is made so steps and pacing always come from the same pick.

routine 🔒

routines_matching

The routines that match a break kind and the engine filters: the kind’s pool, intersected with categories (empty means “all categories”) and capped at max_difficulty. Pure so every filter combination is unit-testable. Sleep matches nothing.

starter_routines

The bundled starter routines, ordered as they appear in the picker (micro first, then long). Pure and allocation-only so it can be returned straight from the get_routines command and unit-tested without state.

step 🔒