Locus

https://pub.dev/packages/locus
Admin
Locus is a reliable background geolocation SDK for Flutter apps, providing native tracking,...
Tokens:20,453
Snippets:98
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### List available executables

Source: https://pub.dev/packages/locus/install

The package provides these specific executable commands after installation.

```text
$ doctor
$ locus
$ migrate
$ setup
```

--------------------------------

### Initialize and Start Tracking

Source: https://pub.dev/packages/locus

Initialize the Locus service and listen to location updates.

```dart
import 'package:locus/locus.dart';

void main() async {
  // 1. Initialize (url is optional - omit for local-only testing)
  await Locus.ready(ConfigPresets.balanced);

  // 2. Start tracking
  await Locus.start();

  // 3. Listen to updates
  Locus.location.stream.listen((location) {
    print('Location: ${location.coords.latitude}, ${location.coords.longitude}');
  });
}
```

--------------------------------

### Initialize Locus tracking

Source: https://pub.dev/packages/locus

Example of initializing the Locus service and adding a geofence with specific imports to support tree shaking.

```dart
import 'package:locus/locus.dart' show Locus, Config, Geofence, GeoPoint;

Future<void> initTracking() async {
  await Locus.ready(const Config());
  await Locus.start();
  await Locus.geofencing.add(Geofence(
    identifier: 'office',
    latitude: 37.7749,
    longitude: -122.4194,
    radius: 100,
  ));
}
```

--------------------------------

### Activate Locus globally

Source: https://pub.dev/packages/locus/install

Use this command to install the package as a global executable from the command line.

```bash
dart pub global activate locus
```

--------------------------------

### Run Locus CLI commands

Source: https://pub.dev/packages/locus

Use these commands for project setup, environment diagnostics, and migration tasks.

```bash
# Automate native permission setup
dart run locus:setup

# Run environment diagnostics
dart run locus:doctor

# Migration helper (v1.x to v2.0)
dart run locus:migrate --dry-run
```

--------------------------------

### Install Locus Dependency

Source: https://pub.dev/packages/locus

Add the Locus package to your pubspec.yaml file.

```yaml
dependencies:
  locus: ^2.3.1
```

--------------------------------

### Build Sync Policy Card Widget

Source: https://pub.dev/packages/locus/example

Initializes the sync policy card widget structure.

```dart
Widget _buildSyncPolicyCard() {
    final label = _syncPolicyLabel(_syncPolicy);
```

--------------------------------

### Control Trips

Source: https://pub.dev/packages/locus/example

Starts and stops tracking trips using the Locus SDK trip configuration.

```dart
  Future<void> _startTrip() async {
    await Locus.trips.start(const TripConfig(startOnMoving: true));
    _showSnackbar('Trip started');
    _recordEvent('trip', 'Trip started');
  }

  Future<void> _stopTrip() async {
    final summary = await Locus.trips.stop();
    // setState(() => _lastTripSummary = summary);
    if (summary != null) {
      _showSnackbar('Trip: ${summary.distanceMeters.toStringAsFixed(0)}m');
    } else {
      _showSnackbar('Trip stopped');
    }
    _recordEvent('trip', 'Trip stopped');
  }
```

--------------------------------

### Initialize Locus SDK

Source: https://pub.dev/packages/locus/example

Configures the Locus SDK with tracking parameters, sync policies, and notification settings. Requires location permissions to be granted before calling Locus.ready.

```dart
Future<void> _configure() async {
    final isGranted = await Locus.requestPermission();
    if (!isGranted) {
      _showSnackbar('Location permission required', isSuccess: false);
      return;
    }

    final config = Config(
      stationaryRadius: 25,
      motionTriggerDelay: 15000,
      activityRecognitionInterval: 10000,
      startOnBoot: true,
      stopOnTerminate: false,
      enableHeadless: true,
      autoSync: true,
      batchSync: true,
      maxBatchSize: 5,
      autoSyncThreshold: 1,
      queueMaxDays: 7,
      queueMaxRecords: 500,
      persistMode: PersistMode.location,
      maxDaysToPersist: 7,
      maxRecordsToPersist: 200,
      maxMonitoredGeofences: 20,
      url: 'https://example.com/locations',
      extras: _syncContext,
      adaptiveTracking: AdaptiveTrackingConfig.balanced,
      logLevel: LogLevel.info,
      notification: const NotificationConfig(
        title: 'Locus Example',
        text: 'Tracking location in background',
      ),
    );

    await Locus.ready(config);
    await _configureProfiles();
    _setupListeners();
    await _refreshState();
    await Locus.dataSync.setPolicy(_syncPolicy);
    await Locus.battery.setAdaptiveTracking(AdaptiveTrackingConfig.balanced);
```

--------------------------------

### Build Settings UI

Source: https://pub.dev/packages/locus/example

Constructs the main settings view using a ListView containing various configuration cards and status information.

```dart
Widget _buildSettings() {
    return ListView(
      padding: const EdgeInsets.all(16),
      children: [
        Card(
          child: Padding(
            padding: const EdgeInsets.all(20),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                _SectionHeader(
                  icon: Icons.battery_charging_full_rounded,
                  title: 'Battery',
                  trailing: _powerState != null
                      ? Text(
                          '${_powerState!.batteryLevel}%',
                          style: const TextStyle(fontWeight: FontWeight.w600),
                        )
                      : null,
                ),
                const SizedBox(height: 16),
                if (_batteryStats != null) ...[
                  _InfoRow(
                    icon: Icons.gps_fixed,
                    label: 'GPS On Time',
                    value:
                        '${(_batteryStats!.gpsOnTimePercent * 100).toStringAsFixed(1)}%',
                  ),
                  const SizedBox(height: 8),
                ],
                if (_powerState != null)
                  _InfoRow(
                    icon: Icons.power,
                    label: 'Charging',
                    value: _powerState!.isCharging ? 'Yes' : 'No',
                  ),
                if (_lastPowerEvent != null)
                  _InfoRow(
                    icon: Icons.power_settings_new,
                    label: 'Last Power Change',
                    value: _lastPowerEvent!.changeType.name,
                  ),
                Row(
                  children: [
                    Expanded(
                      child: _ActionButton(
                        onPressed: _refreshBattery,
                        icon: Icons.refresh_rounded,
                        label: 'Refresh',
                        filled: true,
                      ),
                    ),
                    const SizedBox(width: 12),
                    Expanded(
                      child: _ActionButton(
                        onPressed: _toggleBenchmark,
                        icon: _benchmarkStatus != null
                            ? Icons.stop_rounded
                            : Icons.speed_rounded,
                        label: _benchmarkStatus ?? 'Benchmark',
                        color: _benchmarkStatus != null ? Colors.red : null,
                      ),
                    ),
                  ],
                ),
              ],
            ),
          ),
        ),
        const SizedBox(height: 16),
        _buildAdaptiveTrackingCard(),
        const SizedBox(height: 16),
        _buildSyncPolicyCard(),
        const SizedBox(height: 16),
        _buildSyncContextCard(),
        const SizedBox(height: 16),
        _buildMonitoringCard(),
        const SizedBox(height: 16),
        _buildDiagnosticsCard(),
        const SizedBox(height: 16),
        const Card(
          child: Padding(
            padding: EdgeInsets.all(20),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                _SectionHeader(
                  icon: Icons.info_outline_rounded,
                  title: 'About',
                ),
                SizedBox(height: 16),
                Text(
                  'Locus Example App showcases tracking profiles, sync queues, adaptive tracking, polygon geofences, workflows, diagnostics, and quality monitoring.',
                  style: TextStyle(color: Colors.grey, height: 1.5),
                ),
              ],
            ),
          ),
        ),
      ],
    );
  }
}
```

--------------------------------

### Configure MaterialApp with Locus Theme

Source: https://pub.dev/packages/locus/example

Sets up the root MaterialApp with a custom theme, Google Fonts, and a tabbed scaffold structure.

```dart
@override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Locus Example',
      scaffoldMessengerKey: _scaffoldMessengerKey,
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(
          seedColor: const Color(0xFF2E5D4B),
          brightness: Brightness.light,
        ),
        textTheme: GoogleFonts.interTextTheme(),
        cardTheme: CardThemeData(
          elevation: 0,
          shape: RoundedRectangleBorder(
            borderRadius: BorderRadius.circular(16),
          ),
          color: Colors.white,
        ),
        appBarTheme: const AppBarTheme(
          centerTitle: false,
          elevation: 0,
          scrolledUnderElevation: 1,
        ),
      ),
      home: DefaultTabController(
        length: 4,
        child: Scaffold(
          backgroundColor: const Color(0xFFF5F5F5),
          appBar: AppBar(
            title: Row(
              children: [
                SvgPicture.asset(
                  'assets/locus_logo.svg',
                  width: 32,
                  height: 32,
                ),
                const SizedBox(width: 10),
                const Text(
                  'Locus',
                  style: TextStyle(fontWeight: FontWeight.bold),
                ),
              ],
            ),
            actions: [
              IconButton(
                onPressed: _refreshState,
                icon: const Icon(Icons.refresh_rounded),
                tooltip: 'Refresh',
              ),
            ],
            bottom: const TabBar(
              tabs: [
                Tab(icon: Icon(Icons.dashboard_rounded), text: 'Dashboard'),
                Tab(icon: Icon(Icons.list_alt_rounded), text: 'Events'),
                Tab(icon: Icon(Icons.storage_rounded), text: 'Storage'),
                Tab(icon: Icon(Icons.settings_rounded), text: 'Settings'),
              ],
            ),
          ),
          body: TabBarView(
            children: [
              _buildDashboard(),
              _buildEvents(),
              _buildStorage(),
              _buildSettings(),
            ],
          ),
        ),
      ),
    );
  }
```

--------------------------------

### Build Quick Actions Widget

Source: https://pub.dev/packages/locus/example

Constructs a card containing a grid of quick action tiles for geofencing and trip management.

```dart
  Widget _buildQuickActions() {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const _SectionHeader(
              icon: Icons.bolt_rounded,
              title: 'Quick Actions',
            ),
            const SizedBox(height: 16),
            GridView.count(
              shrinkWrap: true,
              physics: const NeverScrollableScrollPhysics(),
              crossAxisCount: 3,
              mainAxisSpacing: 10,
              crossAxisSpacing: 10,
              childAspectRatio: 1.1,
              children: [
                _QuickActionTile(
                  icon: Icons.add_location_alt_rounded,
                  label: 'Geofence',
                  onTap: _addGeofence,
                ),
                _QuickActionTile(
                  icon: Icons.delete_outline_rounded,
                  label: 'Clear Geo',
                  onTap: _clearGeofences,
                ),
                _QuickActionTile(
                  icon: Icons.privacy_tip_outlined,
                  label: 'Privacy',
                  onTap: _addPrivacyZone,
                ),
                _QuickActionTile(
                  icon: Icons.trip_origin_rounded,
                  label: 'Start Trip',
                  onTap: _startTrip,
                ),
                _QuickActionTile(
                  icon: Icons.stop_circle_outlined,
                  label: 'Stop Trip',
                  onTap: _stopTrip,
                ),
                _QuickActionTile(
                  icon: _isSyncPaused
                      ? Icons.play_arrow_rounded
                      : Icons.pause_rounded,
                  label: _isSyncPaused ? 'Resume Sync' : 'Pause Sync',
                  onTap: _toggleSyncPause,
                ),
                _QuickActionTile(
                  icon: Icons.sync_rounded,
                  label: 'Sync Now',
                  onTap: _syncNow,
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Build Sync Context Card Widget

Source: https://pub.dev/packages/locus/example

Constructs a card displaying sync context details with action buttons to apply specific shift configurations.

```dart
Widget _buildSyncContextCard() {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const _SectionHeader(
              icon: Icons.badge_outlined,
              title: 'Sync Context',
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _applySyncContext(const {
                      'shift_id': 'shift-001',
                      'driver_id': 'driver-42',
                      'route_id': 'route-7',
                    }),
                    icon: Icons.route,
                    label: 'Shift A',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _applySyncContext(const {
                      'shift_id': 'shift-002',
                      'driver_id': 'driver-55',
                      'route_id': 'route-12',
                      'priority': 'rush',
                    }),
                    icon: Icons.route,
                    label: 'Shift B',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            _InfoRow(
              icon: Icons.work_outline,
              label: 'Shift',
              value: _syncContext['shift_id']?.toString() ?? '-',
            ),
            _InfoRow(
              icon: Icons.person_outline,
              label: 'Driver',
              value: _syncContext['driver_id']?.toString() ?? '-',
            ),
            _InfoRow(
              icon: Icons.route,
              label: 'Route',
              value: _syncContext['route_id']?.toString() ?? '-',
            ),
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Format Configuration Labels

Source: https://pub.dev/packages/locus/example

Maps configuration objects and policies to human-readable labels.

```dart
  String _adaptiveTrackingLabel(AdaptiveTrackingConfig? config) {
    if (config == null) return 'Unknown';
    if (!config.enabled) return 'Disabled';
    if (identical(config, AdaptiveTrackingConfig.aggressive)) {
      return 'Aggressive';
    }
    if (identical(config, AdaptiveTrackingConfig.balanced)) {
      return 'Balanced';
    }
    return 'Custom';
  }
```

```dart
  String _syncPolicyLabel(SyncPolicy policy) {
    if (identical(policy, SyncPolicy.aggressive)) return 'Aggressive';
    if (identical(policy, SyncPolicy.conservative)) return 'Conservative';
    if (identical(policy, SyncPolicy.minimal)) return 'Minimal';
    return 'Balanced';
  }
```

--------------------------------

### Build Monitoring Card Widget

Source: https://pub.dev/packages/locus/example

Creates a Card widget containing multiple SwitchListTile controls for toggling monitoring features and displaying real-time quality metrics.

```dart
Widget _buildMonitoringCard() {
    return Card(
      child: Column(
        children: [
          Padding(
            padding: const EdgeInsets.fromLTRB(20, 20, 20, 0),
            child: Row(
              children: [
                Icon(
                  Icons.tune,
                  size: 20,
                  color: Theme.of(context).colorScheme.primary,
                ),
                const SizedBox(width: 10),
                const Text(
                  'Monitoring & Automation',
                  style: TextStyle(fontSize: 16, fontWeight: FontWeight.w600),
                ),
              ],
            ),
          ),
          SwitchListTile(
            secondary: const Icon(Icons.smart_toy_outlined),
            title: const Text('Tracking Automation'),
            subtitle: const Text('Auto-switch profiles based on rules'),
            value: _automationEnabled,
            onChanged: (_) => _toggleAutomation(),
          ),
          const Divider(height: 1),
          SwitchListTile(
            secondary: const Icon(Icons.high_quality),
            title: const Text('Quality Monitoring'),
            subtitle: const Text('Assess signal quality'),
            value: _qualityMonitoringEnabled,
            onChanged: (_) => _toggleQualityMonitoring(),
          ),
          const Divider(height: 1),
          SwitchListTile(
            secondary: const Icon(Icons.report_problem_outlined),
            title: const Text('Anomaly Detection'),
            subtitle: const Text('Detect implausible jumps'),
            value: _anomalyMonitoringEnabled,
            onChanged: (_) => _toggleAnomalyMonitoring(),
          ),
          const Divider(height: 1),
          SwitchListTile(
            secondary: const Icon(Icons.security_rounded),
            title: const Text('Spoof Detection'),
            subtitle: const Text('Detect mock locations'),
            value: _spoofDetectionEnabled,
            onChanged: (_) => _toggleSpoof(),
          ),
          const Divider(height: 1),
          SwitchListTile(
            secondary: const Icon(Icons.compare_arrows_rounded),
            title: const Text('Significant Changes'),
            subtitle: const Text('Ultra-low power monitoring'),
            value: _significantChangesEnabled,
            onChanged: (_) => _toggleSignificant(),
          ),
          if (_lastQuality != null) ...[
            const Divider(height: 1),
            Padding(
              padding: const EdgeInsets.fromLTRB(20, 8, 20, 8),
              child: Column(
                children: [
                  _InfoRow(
                    icon: Icons.insights_rounded,
                    label: 'Quality Score',
                    value:
                        '${(_lastQuality!.overallScore * 100).toStringAsFixed(0)}%',
                  ),
                  _InfoRow(
                    icon: Icons.speed_rounded,
                    label: 'Jitter',
                    value:
                        '${(_lastQuality!.jitterScore * 100).toStringAsFixed(0)}%',
                  ),
                  _InfoRow(
                    icon: Icons.shield_outlined,
                    label: 'Spoof Suspect',
                    value: _lastQuality!.isSpoofSuspected ? 'Yes' : 'No',
                  ),
                ],
              ),
            ),
          ],
          if (_lastAnomaly != null) ...[
            const Divider(height: 1),
            Padding(
              padding: const EdgeInsets.fromLTRB(20, 8, 20, 8),
              child: _InfoRow(
                icon: Icons.warning_rounded,
                label: 'Last Anomaly',
                value: '${_lastAnomaly!.speedKph.toStringAsFixed(0)} kph',
              ),
            ),
          ],
          const Divider(height: 1),
          Padding(
            padding: const EdgeInsets.fromLTRB(20, 12, 20, 20),
            child: Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _setPace(true),
                    icon: Icons.directions_walk_rounded,
                    label: 'Set Moving',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _setPace(false),
                    icon: Icons.do_not_disturb_on_outlined,
                    label: 'Set Stationary',
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _resetOdometer,
                    icon: Icons.restore_rounded,
                    label: 'Reset Odo',
                  ),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
```

--------------------------------

### Build Diagnostics Card Widget

Source: https://pub.dev/packages/locus/example

Initializes the diagnostics card widget by accessing the current diagnostic snapshot.

```dart
Widget _buildDiagnosticsCard() {
    final snapshot = _diagnostics;
```

--------------------------------

### Build Storage Management Widget

Source: https://pub.dev/packages/locus/example

Displays a card with storage statistics and action buttons for loading or clearing stored locations.

```dart
Widget _buildStorage() {
    return ListView(
      padding: const EdgeInsets.all(16),
      children: [
        Card(
          child: Padding(
            padding: const EdgeInsets.all(20),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                _SectionHeader(
                  icon: Icons.storage_rounded,
                  title: 'Stored Locations',
                  trailing: Container(
                    padding: const EdgeInsets.symmetric(
                      horizontal: 10,
                      vertical: 4,
                    ),
                    decoration: BoxDecoration(
                      color: const Color(0xFFF0F0F0),
                      borderRadius: BorderRadius.circular(20),
                    ),
                    child: Text(
                      '${_storedLocations.length}',
                      style: const TextStyle(
                        fontSize: 12,
                        fontWeight: FontWeight.w600,
                      ),
                    ),
                  ),
                ),
                const SizedBox(height: 16),
                Row(
                  children: [
                    Expanded(
                      child: _ActionButton(
                        onPressed: _loadLocations,
                        icon: Icons.download_rounded,
                        label: 'Load',
                        filled: true,
                      ),
                    ),
                    const SizedBox(width: 12),
                    Expanded(
                      child: _ActionButton(
                        onPressed: _clearLocations,
                        icon: Icons.delete_outline_rounded,
                        label: 'Clear',
                      ),
                    ),
                  ],
                ),
              ],
            ),
          ),
        ),
        if (_storedLocations.isNotEmpty) ...[
          const SizedBox(height: 16),
          Card(
            child: ListView.separated(
              shrinkWrap: true,
              physics: const NeverScrollableScrollPhysics(),
              itemCount: _storedLocations.length.clamp(0, 20),
              separatorBuilder: (_, __) => const Divider(height: 1),
              itemBuilder: (_, i) {
                final loc = _storedLocations[i];
                return ListTile(
                  leading: CircleAvatar(

```

--------------------------------

### Build Use Cases Widget

Source: https://pub.dev/packages/locus/example

Constructs a card displaying active scenarios, action buttons for operations, and contextual information rows.

```dart
Widget _buildUseCases() {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const _SectionHeader(
              icon: Icons.workspaces_filled,
              title: 'Use Cases',
            ),
            const SizedBox(height: 12),
            Text(
              'Active: $_activeScenario',
              style: const TextStyle(fontWeight: FontWeight.w600),
            ),
            const SizedBox(height: 12),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: _activateDeliveryOps,
                    icon: Icons.local_shipping_outlined,
                    label: 'Delivery Ops',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _activatePrivacyMode,
                    icon: Icons.shield_outlined,
                    label: 'Privacy Mode',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            _InfoRow(
              icon: Icons.badge_outlined,
              label: 'Shift',
              value: _syncContext['shift_id']?.toString() ?? '-',
            ),
            _InfoRow(
              icon: Icons.person_outline,
              label: 'Driver',
              value: _syncContext['driver_id']?.toString() ?? '-',
            ),
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Implement Sync Queue Card UI

Source: https://pub.dev/packages/locus/example

Displays a card containing sync queue statistics, action buttons for queue management, and a list of queued items.

```dart
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            _SectionHeader(
              icon: Icons.sync_rounded,
              title: 'Sync Queue',
              trailing: Text(
                '${_syncQueue.length} items',
                style: const TextStyle(fontSize: 12, color: Colors.grey),
              ),
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: _enqueueCheckIn,
                    icon: Icons.add_rounded,
                    label: 'Enqueue',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _loadSyncQueue,
                    icon: Icons.refresh_rounded,
                    label: 'Load',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: _syncQueueNow,
                    icon: Icons.cloud_upload_outlined,
                    label: 'Sync Queue',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _clearSyncQueue,
                    icon: Icons.delete_outline_rounded,
                    label: 'Clear',
                  ),
                ),
              ],
            ),
            if (_lastQueueId != null) ...[
              const SizedBox(height: 12),
              Text(
                'Last queued: $_lastQueueId',
                style: const TextStyle(fontSize: 12, color: Colors.grey),
              ),
            ],
            if (_syncQueue.isNotEmpty) ...[
              const SizedBox(height: 16),
              ListView.separated(
                shrinkWrap: true,
                physics: const NeverScrollableScrollPhysics(),
                itemCount: itemCount,
                separatorBuilder: (_, __) => const Divider(height: 1),
                itemBuilder: (_, i) {
                  final item = _syncQueue[i];
                  final shortIdLength = item.id.length > 6 ? 6 : item.id.length;
                  return ListTile(
                    dense: true,
                    title: Text(
                      item.type ?? 'payload',
                      style: const TextStyle(fontSize: 13),
                    ),
                    subtitle: Text(
                      '${item.createdAt.toLocal().toString().substring(0, 19)} · retries ${item.retryCount}',
                      style: const TextStyle(fontSize: 11),
                    ),
                    trailing: Text(
                      item.id.substring(0, shortIdLength),
                      style: const TextStyle(
                        fontSize: 11,
                        color: Colors.grey,
                      ),
                    ),
                  );
                },
              ),
            ],
          ],
        ),
      ),
    );
  }

  Widget _buildHistorySummaryCard() {
    final summary = _locationSummary;
```

--------------------------------

### Configure Battery and Tracking

Source: https://pub.dev/packages/locus/example

Methods to adjust adaptive tracking configurations, calculate settings, and estimate battery runway.

```dart
  Future<void> _setAdaptiveTracking(
    AdaptiveTrackingConfig config,
    String label,
  ) async {
    await Locus.battery.setAdaptiveTracking(config);
    setState(() => _adaptiveTrackingConfig = config);
    _showSnackbar('Adaptive: $label');
    _recordEvent('battery', 'Adaptive tracking: $label');
  }
```

```dart
  Future<void> _calculateAdaptiveSettings() async {
    final settings = await Locus.battery.calculateAdaptiveSettings();
    setState(() => _adaptiveSettings = settings);
    _showSnackbar('Adaptive settings updated');
  }
```

```dart
  Future<void> _estimateRunway() async {
    final runway = await Locus.battery.estimateRunway();
    setState(() => _batteryRunway = runway);
    _showSnackbar(runway.recommendation);
  }
```

--------------------------------

### Build a Profile Chip Widget

Source: https://pub.dev/packages/locus/example

Creates a selectable chip component with an icon and label, using theme-based colors for the selected state.

```dart
class _ProfileChip extends StatelessWidget {
  const _ProfileChip({
    required this.label,
    required this.icon,
    required this.selected,
    required this.onTap,
  });

  final String label;
  final IconData icon;
  final bool selected;
  final VoidCallback onTap;

  @override
  Widget build(BuildContext context) {
    return Expanded(
      child: GestureDetector(
        onTap: onTap,
        child: Container(
          padding: const EdgeInsets.symmetric(vertical: 12),
          margin: const EdgeInsets.symmetric(horizontal: 4),
          decoration: BoxDecoration(
            color: selected
                ? Theme.of(context).colorScheme.primaryContainer
                : const Color(0xFFF5F5F5),
            borderRadius: BorderRadius.circular(12),
            border: selected
                ? Border.all(
                    color: Theme.of(context).colorScheme.primary.withAlpha(100),
                  )
                : null,
          ),
          child: Column(
            children: [
              Icon(
                icon,
                size: 20,
                color: selected
                    ? Theme.of(context).colorScheme.primary
                    : Colors.grey,
              ),
              const SizedBox(height: 4),
              Text(
                label,
                style: TextStyle(
                  fontSize: 10,
                  fontWeight: selected ? FontWeight.w600 : FontWeight.normal,
                  color: selected
                      ? Theme.of(context).colorScheme.primary
                      : Colors.grey,
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}
```

--------------------------------

### Build Profile Selector Widget

Source: https://pub.dev/packages/locus/example

Constructs a card for selecting tracking profiles like Off Duty, Standby, En Route, or Arrived.

```dart
  Widget _buildProfileSelector() {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            _SectionHeader(
              icon: Icons.tune_rounded,
              title: 'Profile',
              trailing: _currentProfile != null
                  ? Container(
                      padding: const EdgeInsets.symmetric(
                        horizontal: 10,
                        vertical: 4,
                      ),
                      decoration: BoxDecoration(
                        color: Theme.of(context).colorScheme.primaryContainer,
                        borderRadius: BorderRadius.circular(20),
                      ),
                      child: Text(
                        _currentProfile!.name,
                        style: TextStyle(
                          fontSize: 12,
                          fontWeight: FontWeight.w600,
                          color: Theme.of(context).colorScheme.primary,
                        ),
                      ),
                    )
                  : null,
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                _ProfileChip(
                  label: 'Off Duty',
                  icon: Icons.bedtime_outlined,
                  selected: _currentProfile == TrackingProfile.offDuty,
                  onTap: () => _setProfile(TrackingProfile.offDuty),
                ),
                _ProfileChip(
                  label: 'Standby',
                  icon: Icons.pause_circle_outline,
                  selected: _currentProfile == TrackingProfile.standby,
                  onTap: () => _setProfile(TrackingProfile.standby),
                ),
                _ProfileChip(
                  label: 'En Route',
                  icon: Icons.navigation_outlined,
                  selected: _currentProfile == TrackingProfile.enRoute,
                  onTap: () => _setProfile(TrackingProfile.enRoute),
                ),
                _ProfileChip(
                  label: 'Arrived',
                  icon: Icons.flag_outlined,
                  selected: _currentProfile == TrackingProfile.arrived,
                  onTap: () => _setProfile(TrackingProfile.arrived),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Build Tracking Controls Widget

Source: https://pub.dev/packages/locus/example

Constructs a card containing buttons for starting/stopping tracking, fetching positions, and updating notifications.

```dart
  Widget _buildTrackingControls() {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const _SectionHeader(
              icon: Icons.play_circle_outline,
              title: 'Tracking',
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: _toggleTracking,
                    icon: _isRunning
                        ? Icons.stop_rounded
                        : Icons.play_arrow_rounded,
                    label: _isRunning ? 'Stop' : 'Start',
                    color: _isRunning ? Colors.red : Colors.green,
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _getPosition,
                    icon: Icons.my_location_rounded,
                    label: 'Get Position',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            _ActionButton(
              onPressed: _isRunning ? _updateNotification : null,
              icon: Icons.notifications_active_rounded,
              label: 'Update Notification',
            ),
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Sync Policy Selection UI

Source: https://pub.dev/packages/locus/example

A Card widget containing action buttons for applying various sync policies and displaying the resulting decision metadata.

```dart
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            _SectionHeader(
              icon: Icons.sync_rounded,
              title: 'Sync Policy',
              trailing: Text(
                label,
                style: const TextStyle(fontSize: 12, color: Colors.grey),
              ),
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: () =>
                        _applySyncPolicy(SyncPolicy.balanced, 'Balanced'),
                    icon: Icons.tune,
                    label: 'Balanced',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: () =>
                        _applySyncPolicy(SyncPolicy.aggressive, 'Aggressive'),
                    icon: Icons.flash_on,
                    label: 'Aggressive',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _applySyncPolicy(
                        SyncPolicy.conservative, 'Conservative'),
                    icon: Icons.slow_motion_video,
                    label: 'Conservative',
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: () =>
                        _applySyncPolicy(SyncPolicy.minimal, 'Minimal'),
                    icon: Icons.savings_outlined,
                    label: 'Minimal',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            _ActionButton(
              onPressed: _evaluateSyncPolicy,
              icon: Icons.insights_rounded,
              label: 'Evaluate Policy',
              filled: true,
            ),
            if (_syncDecision != null) ...[
              const SizedBox(height: 12),
              Text(
                _syncDecision!.reason,
                style: const TextStyle(color: Colors.grey),
              ),
              if (_syncDecision!.batchLimit != null)
                _InfoRow(
                  icon: Icons.layers_outlined,
                  label: 'Batch Size',
                  value: '${_syncDecision!.batchLimit}',
                ),
              if (_syncDecision!.delay != null)
                _InfoRow(
                  icon: Icons.timer_outlined,
                  label: 'Delay',
                  value: _formatDuration(_syncDecision!.delay!),
                ),
            ],
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Configure Device Monitoring

Source: https://pub.dev/packages/locus/example

Toggles spoof detection, significant change monitoring, and automation profiles.

```dart
  Future<void> _toggleSpoof() async {
    final enabled = !_spoofDetectionEnabled;
    await Locus.setSpoofDetection(
      enabled ? SpoofDetectionConfig.high : SpoofDetectionConfig.disabled,
    );
    setState(() => _spoofDetectionEnabled = enabled);
    _showSnackbar('Spoof detection: ${enabled ? "ON" : "OFF"}');
  }

  Future<void> _toggleSignificant() async {
    final enabled = !_significantChangesEnabled;
    if (enabled) {
      await Locus.startSignificantChangeMonitoring(
        SignificantChangeConfig.defaults,
      );
    } else {
      await Locus.stopSignificantChangeMonitoring();
    }
    setState(() => _significantChangesEnabled = enabled);
    _showSnackbar('Significant changes: ${enabled ? "ON" : "OFF"}');
  }

  Future<void> _toggleAutomation() async {
    final enabled = !_automationEnabled;
    await _configureProfiles(enableAutomation: enabled);
    _showSnackbar('Automation: ${enabled ? "ON" : "OFF"}');
    _recordEvent('profile', 'Automation ${enabled ? "enabled" : "disabled"}');
  }
```

--------------------------------

### Build Adaptive Tracking Card Widget

Source: https://pub.dev/packages/locus/example

Constructs a card UI for managing adaptive tracking configurations, including action buttons and status information.

```dart
Widget _buildAdaptiveTrackingCard() {
    final label = _adaptiveTrackingLabel(_adaptiveTrackingConfig);

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            _SectionHeader(
              icon: Icons.battery_charging_full_rounded,
              title: 'Adaptive Tracking',
              trailing: Text(
                label,
                style: const TextStyle(fontSize: 12, color: Colors.grey),
              ),
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _setAdaptiveTracking(
                        AdaptiveTrackingConfig.balanced, 'Balanced'),
                    icon: Icons.tune,
                    label: 'Balanced',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _setAdaptiveTracking(
                        AdaptiveTrackingConfig.aggressive, 'Aggressive'),
                    icon: Icons.flash_on,
                    label: 'Aggressive',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: () => _setAdaptiveTracking(
                        AdaptiveTrackingConfig.disabled, 'Disabled'),
                    icon: Icons.power_settings_new,
                    label: 'Disable',
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _calculateAdaptiveSettings,
                    icon: Icons.tune,
                    label: 'Calc Settings',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            _ActionButton(
              onPressed: _estimateRunway,
              icon: Icons.timelapse,
              label: 'Estimate Runway',
              filled: true,
            ),
            if (_adaptiveSettings != null) ...[
              const SizedBox(height: 16),
              _InfoRow(
                icon: Icons.my_location_outlined,
                label: 'Accuracy',
                value: _adaptiveSettings!.desiredAccuracy.name,
              ),
              _InfoRow(
                icon: Icons.linear_scale,
                label: 'Distance Filter',
                value:
                    '${_adaptiveSettings!.distanceFilter.toStringAsFixed(0)} m',
              ),
              _InfoRow(
                icon: Icons.favorite_border,
                label: 'Heartbeat',
                value: '${_adaptiveSettings!.heartbeatInterval}s',
              ),
            ],
            if (_batteryRunway != null) ...[
              const SizedBox(height: 12),
              _InfoRow(
                icon: Icons.battery_full_rounded,
                label: 'Runway',
                value: _batteryRunway!.formattedDuration,
              ),
              _InfoRow(
                icon: Icons.battery_2_bar_rounded,
                label: 'Low Power',
                value: _batteryRunway!.formattedLowPowerDuration,
              ),
            ],
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Define Quick Action Tile Widget

Source: https://pub.dev/packages/locus/example

Defines the structure for a quick action tile component.

```dart
class _QuickActionTile extends StatelessWidget {
  const _QuickActionTile({
    required this.icon,
    required this.label,
    required this.onTap,
  });

  final IconData icon;
  final String label;
  final VoidCallback onTap;
```

--------------------------------

### Activate Scenarios

Source: https://pub.dev/packages/locus/example

Complex workflows for initializing delivery operations or privacy-focused tracking modes.

```dart
  Future<void> _activateDeliveryOps() async {
    if (!_ensureReady()) return;
    await _applySyncContext({
      'shift_id': 'shift-204',
      'driver_id': 'driver-17',
      'route_id': 'route-5',
      'tenant': 'west-coast',
    });
    await _applySyncPolicy(SyncPolicy.balanced, 'Balanced');
    await _setAdaptiveTracking(AdaptiveTrackingConfig.balanced, 'Balanced');
    await _registerDeliveryWorkflow();
    await _configureProfiles(enableAutomation: true);
    if (Locus.trips.getState() == null) {
      await Locus.trips.start(
        const TripConfig(
          tripId: 'delivery-204',
          startOnMoving: true,
          destination: RoutePoint(
            latitude: 37.4187,
            longitude: -122.0816,
          ),
          waypoints: [
            RoutePoint(latitude: 37.4215, longitude: -122.0834),
          ],
        ),
      );
    }
    if (!_isRunning) {
      await Locus.start();
    }
    setState(() => _activeScenario = 'Delivery Ops');
    _showSnackbar('Delivery ops ready');
    _recordEvent('scenario', 'Delivery ops activated');
  }
```

```dart
  Future<void> _activatePrivacyMode() async {
    if (!_ensureReady()) return;
    await _addPrivacyZone();
    if (!_spoofDetectionEnabled) {
      await _toggleSpoof();
    }
    setState(() => _activeScenario = 'Privacy Mode');
    _showSnackbar('Privacy mode enabled');
    _recordEvent('scenario', 'Privacy mode enabled');
  }
```

--------------------------------

### Build an Info Row Widget

Source: https://pub.dev/packages/locus/example

Displays a label and value pair with an icon, suitable for list-style information display.

```dart
class _InfoRow extends StatelessWidget {
  const _InfoRow({
    required this.icon,
    required this.label,
    required this.value,
  });

  final IconData icon;
  final String label;
  final String value;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.symmetric(vertical: 4),
      child: Row(
        children: [
          Icon(icon, size: 16, color: Colors.grey),
          const SizedBox(width: 8),
          Text(label, style: const TextStyle(color: Colors.grey, fontSize: 13)),
          const Spacer(),
          Text(
            value,
            style: const TextStyle(fontWeight: FontWeight.w500, fontSize: 13),
          ),
        ],
      ),
    );
  }
}
```

--------------------------------

### Define Sync Queue Card Widget

Source: https://pub.dev/packages/locus/example

Initializes the sync queue card widget logic.

```dart
  Widget _buildSyncQueueCard() {
    final itemCount = _syncQueue.length > 5 ? 5 : _syncQueue.length;
```

--------------------------------

### Manage Sync Context and Policies

Source: https://pub.dev/packages/locus/example

Methods for updating the Locus configuration context, setting sync policies, and evaluating those policies against current settings.

```dart
Future<void> _applySyncContext(Map<String, dynamic> context) async {
    await Locus.setConfig(Config(extras: context));
    await Locus.dataSync.refreshHeaders();
    setState(() => _syncContext = Map<String, dynamic>.from(context));
    _showSnackbar('Context: ${context['shift_id'] ?? 'updated'}');
    _recordEvent('config', 'Context updated');
  }

  Future<void> _applySyncPolicy(SyncPolicy policy, String label) async {
    await Locus.dataSync.setPolicy(policy);
    setState(() => _syncPolicy = policy);
    _showSnackbar('Sync policy: $label');
    _recordEvent('sync', 'Policy set: $label');
  }

  Future<void> _evaluateSyncPolicy() async {
    final decision = await Locus.dataSync.evaluatePolicy(policy: _syncPolicy);
    setState(() => _syncDecision = decision);
    _showSnackbar(decision.reason);
    _recordEvent('sync', 'Policy decision: ${decision.reason}');
  }
```

--------------------------------

### Build Geofencing Tools Widget

Source: https://pub.dev/packages/locus/example

Constructs a card displaying geofencing status indicators and action buttons for polygon and workflow management.

```dart
  Widget _buildGeofencingTools() {
    final workflowStatus = _lastWorkflowEvent?.status.name ?? 'idle';

    return Card(
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const _SectionHeader(
              icon: Icons.map_outlined,
              title: 'Geofencing',
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                _StatusIndicator(
                  active: _polygonGeofences.isNotEmpty,
                  label: 'Polygons ${_polygonGeofences.length}',
                ),
                const SizedBox(width: 12),
                _StatusIndicator(
                  active: _workflowRegistered,
                  label:
                      _workflowRegistered ? 'Workflow $workflowStatus' : 'No',
                ),
              ],
            ),
            const SizedBox(height: 16),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: _addPolygonGeofence,
                    icon: Icons.crop_square_rounded,
                    label: 'Add Polygon',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _clearPolygonGeofences,
                    icon: Icons.layers_clear_rounded,
                    label: 'Clear Polygons',
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            Row(
              children: [
                Expanded(
                  child: _ActionButton(
                    onPressed: _registerDeliveryWorkflow,
                    icon: Icons.route,
                    label: 'Register Flow',
                    filled: true,
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: _ActionButton(
                    onPressed: _stopWorkflows,
                    icon: Icons.stop_circle_outlined,
                    label: 'Clear Flow',
                  ),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
```

--------------------------------

### Build Dashboard Tab Layout

Source: https://pub.dev/packages/locus/example

Constructs the dashboard view using a ListView containing various tracking and status widgets.

```dart
Widget _buildDashboard() {
    return ListView(
      padding: const EdgeInsets.all(16),
      children: [
        _buildStatusCard(),
        const SizedBox(height: 16),
        _buildTrackingControls(),
        const SizedBox(height: 16),
        _buildProfileSelector(),
        const SizedBox(height: 16),
        _buildQuickActions(),
        const SizedBox(height: 16),
        _buildGeofencingTools(),
        const SizedBox(height: 16),
        _buildUseCases(),
        const SizedBox(height: 16),
        _buildEventStats(),
      ],
    );
  }
```

--------------------------------

### Configure Locus Sync and State

Source: https://pub.dev/packages/locus/example

Sets up custom body builders, headers, and pre-sync validation for data synchronization, followed by updating the application state.

```dart
// Demo: Custom sync body builder
    await Locus.setSyncBodyBuilder((locations, extras) async {
      return {
        'app': 'locus_example',
        'timestamp': DateTime.now().toIso8601String(),
        'locations': locations.map((l) => l.toMap()).toList(),
        ...extras,
      };
    });
    await Locus.dataSync.setHeadersCallback(() async {
      return {
        'X-Client': 'locus_example',
        'X-Shift-Id': _syncContext['shift_id']?.toString() ?? 'unknown',
      };
    });
    Locus.dataSync.setPreSyncValidator((locations, extras) async {
      final hasShift = extras['shift_id'] != null;
      if (!hasShift) {
        _recordEvent('sync', 'Sync skipped (missing shift_id)');
      }
      return hasShift;
    });

    setState(() {
      _isReady = true;
      _adaptiveTrackingConfig = AdaptiveTrackingConfig.balanced;
    });
  }
```

--------------------------------

### Validate SDK Readiness

Source: https://pub.dev/packages/locus/example

Checks if the SDK is ready and displays a snackbar error if not.

```dart
  bool _ensureReady() {
    if (!_isReady) {
      _showSnackbar('SDK not ready', isSuccess: false);
      return false;
    }
    return true;
  }
```
Tokens:
Raw