DebugScreen.tsx

Purpose

This module renders a developer-facing debug tab that surfaces log entries written to the debug_logs SQLite table. It is only accessible when EXPO_PUBLIC_DEBUG=true and is intended for post-hoc inspection of background pipeline activity without requiring a cable or Xcode.

Its responsibilities include:

• Loading all persisted log entries from the database when the tab gains focus
• Rendering log entries in a filterable, color-coded list
• Providing a foreground simulation control to invoke the background fetch task directly in the JS thread
• Providing a real background task trigger for iOS BGTaskScheduler testing in debug builds
• Allowing all log entries to be cleared from the database
• Filtering the visible log list by level without re-querying the database

Invariants

Focus-Triggered Reload

Log entries are reloaded from the database each time the tab receives focus.

No polling interval is used; data is only refreshed on navigation focus or after a simulation run completes.

Build-Gated Visibility

This screen is registered in the tab navigator only when EXPO_PUBLIC_DEBUG === 'true'.

The component itself has no internal guard; exclusion is enforced entirely at the navigator level.

Real Background Trigger Availability

The “Trigger Real BG” button is enabled only when isIOSBackgroundFetchAvailable() returns true.

When unavailable (e.g. on Android or in a non-debug build), the button is rendered in a disabled state with a label indicating unavailability.

Log Entry Shape

Each displayed row exposes exactly three fields: timestamp (formatted as HH:MM:SS), level, and message.

Messages are capped at 4 lines of display to prevent overflow in dense log views.

Variants

Simulation vs Real Background Trigger

Two separate controls exist with distinct semantics:

• Simulate BG — Calls runBgFetchTask() directly in the foreground JS thread. Confirms pipeline logic is correct but does not test actual OS background wakeup.
• Trigger Real BG — Calls triggerIOSBackgroundFetchForTesting(), which asks iOS to schedule and fire the BGTaskScheduler task. Requires backgrounding the app after tapping; logs appear on next foreground.

Level Filtering

Filtering is applied client-side to the already-loaded entries array.

Available filter levels: ALL, INFO, WARN, ERROR, DEBUG.

Empty State

When no log entries match the active filter, a single centered hint text is displayed in place of the list.

Exports

DebugScreen (default)

export default function DebugScreen(): JSX.Element

Renders the debug log viewer with simulation controls and level filter buttons.

Has no props. Only intended for debug builds; not suitable for production use.