Technical reference. For task-based help, see the corresponding user guide.

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: family members; assigned coaches for in-app timers

Surfaces: mobile web app, native wrapper and platform API

Active timers let care continue while the user navigates the app, reloads the WebView or briefly loses connectivity. Stopping a timer creates a durable review draft rather than immediately inventing a final activity. Idempotent activity creation, a persistent offline outbox and server reconciliation prevent lost or duplicate logs.

Timers are available for Breastfeeding, Sleep and Pumping only.

1. Choose a timer quick action from the relevant tracker; Breastfeeding and Pumping also preselect left/right.
2. The app creates a UUID-backed timer locally immediately, recording family subject, baby, activity type, start time, timezone, editable details and note.
3. It then upserts the same timer to the platform. If the network request cannot complete, the pending upsert remains locally recoverable and retries.
4. Navigating away does not stop it. Up to three running timers appear as draggable floating bubbles; selecting a bubble returns to the correct family, baby, tracker and timer.
5. Reload/login summary and realtime updates reconcile the local list with the authoritative server list.

There is one canonical active timer for a given family/baby/activity-type scope. Different timer types and different babies may run concurrently. Reconciliation prefers the authoritative/latest timer for a duplicated scope while protecting a newer unsynced local start.

Selecting Stop removes the running timer from the active UI immediately and records a six-hour local tombstone so an older summary cannot resurrect it. The app retains a stopped draft locally and sends POST /active-timers/:id/stop.

The platform atomically removes the active timer and stores a stopped draft containing the authoritative start/stop values, details, note and timezone. If the stop request is offline, the client retries it when connectivity returns. On reload, local and server stopped drafts are merged by timer ID.

The user then reviews the normal activity form:

1. Save creates the final activity with both activeTimerId and a UUID clientMutationId;
2. Discard deletes the unresolved timer/draft without creating an activity;
3. leaving the page keeps the stopped draft available to resume later.

The platform handles final activity creation and timer closure as one idempotent operation. Repeating a timed-out save with the same mutation ID returns the existing result instead of producing a duplicate. Once confirmed, the app clears the stopped draft and refreshes Home/history.

If offline, the create moves into the activity outbox. The outbox suppresses the matching timer draft while it is pending so one care event is not displayed as both an unresolved timer and a queued activity.

The persistent outbox applies to new activity creates, including timer completions and manual/quick creates.

1. Each entry is scoped to the API base, authenticated user and family subject, and retains its UUID mutation ID.
2. A background sweep runs every 15 seconds and when the browser reports that it is online.
3. Retryable network, timeout, rate-limit and server failures use a future retry time rather than busy-looping.
4. Pending and failed entries are visible in the matching tracker history.
5. The user can retry one item, discard one, discard all current-scope items or clear corrupt stored entries.
6. Authorization/subject changes fail safely; an entry is never replayed into a different family context.

Existing activity edits and deletes do not use this outbox. They require a successful online platform response.

For a family actor in self-mode, the Sleep tracker can mirror a running timer to supported native surfaces. Current wrapper code includes an iOS Widget/Live Activity path (Live Activities require iOS 16.1+) and Android widget/live-notification support. Availability still depends on the installed native wrapper and operating-system capabilities; the in-app timer remains usable when native synchronization fails.

The secure handoff works as follows:

1. The WebView upserts the Sleep timer with requestNativeActionToken: true.
2. The platform returns a narrow, expiring action token for that timer; it does not expose a Supabase access token to native storage.
3. The wrapper displays baby/timer state and a deep link back to the correct Sleep route.
4. A native completion calls POST /native/sleep-timers/:id/complete with the action token and completion time.
5. The platform validates and consumes the token, creates the Sleep activity and closes the timer atomically. A realtime refresh then removes it from the WebView.

Coach view-as does not request a native action token. Coach timers remain in the authenticated WebView because a device widget must not become a reusable proxy for coach access to a family.

All ordinary timer endpoints resolve actor, family subject, baby ownership and coach permissions through the API. The native completion endpoint is public only in the HTTP-auth sense: possession, validity, expiry and one-time use of the narrowly scoped action token are mandatory.

1. The platform, not localStorage, is the cross-device source of truth.
2. Local timer, draft and outbox records are identity/subject scoped and are reconciled on auth changes.
3. Native storage receives timer display data and a narrow action token, never the family's Supabase bearer token.
4. Deleting a baby/account removes its timer state with the dependent subject data.
5. Coach timer writes require the live assignment and canWriteActivities; native family-self completion is deliberately excluded.

1. A running timer survives navigation/reload and reopens the correct baby/type.
2. Multiple babies/types can run concurrently while duplicate scope timers reconcile to one canonical timer.
3. Stop immediately removes the active bubble and produces a restorable review draft.
4. Offline stop/create retries do not lose the draft or create duplicate activities.
5. Users can understand and recover pending, failed and corrupt outbox states.
6. Native Sleep completion consumes a narrow action token and atomically produces one activity.
7. Coach view-as never provisions a family-self native action token.

• mobile-web/src/timers/ActiveTimersContext.tsx
• mobile-web/src/timers/stoppedTimerDrafts.ts
• mobile-web/src/timers/serverActiveTimers.ts
• mobile-web/src/components/FloatingTimerBubbles.tsx
• mobile-web/src/offline/ActivityCreateOutboxContext.tsx
• mobile-web/src/offline/activity-create-outbox-runner.ts
• mobile-web/src/routes/ActivityTrackingScreen.tsx
• mobile-wrapper/src/native/sleepTimerWidget.ts
• mobile-wrapper/ios/SleepTimerWidget/SleepTimerWidget.swift
• mobile-wrapper/android/app/src/main/java/com/dreamsforlittles/SleepTimerWidgetProvider.kt
• platform/apps/api/src/routes/family-routes.ts
• platform/packages/shared/src/family.ts

• 05 — Family home
• 07 — Activity tracking
• 09 — Analysis and trends
• 33 — Offline cache and app updates