navigation_safety

Safety-focused navigation session state machine and always-on-top alert overlay for driver-assisting navigation applications.

navigation_safety is an ASIL-QM, advisory-only navigation package. It displays safety-relevant information to help the driver decide. It does not control steering, braking, throttle, or any vehicle actuation path.

When to use this package

Use navigation_safety when you need navigation session state and a safety overlay that stays visually subordinate to the driver, not the vehicle.

Features

• NavigationBloc for navigation session lifecycle: idle, navigating, deviated, arrived.
• SafetyOverlay widget that stays at the top of the UI stack when alerts are active.
• Pure Dart _core exports for SafetyScore, AlertSeverity, and NavigationSafetyConfig.
• Configurable severity thresholds for score-based safety alerts.
• Reusable README/example posture for edge developers.

Install

dependencies:
  navigation_safety: ^0.1.1

Quick Start

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:navigation_safety/navigation_safety.dart';
import 'package:routing_engine/routing_engine.dart';

class MyNavScreen extends StatelessWidget {
  const MyNavScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => NavigationBloc(),
      child: Scaffold(
        body: Stack(
          children: const [
            Placeholder(),
            SafetyOverlay(),
          ],
        ),
      ),
    );
  }
}

API Overview

API	Purpose
NavigationBloc	Navigation session lifecycle and alert state
NavigationState	Session state, maneuver progress, active alert
NavigationEvent	Navigation start/stop, maneuver advance, alert input
SafetyOverlay	Safety alert presentation layer
SafetyScore	Pure Dart score model for grip, visibility, fleet confidence
NavigationSafetyConfig	Pure Dart threshold configuration
AlertSeverity	info, warning, critical

OODA Latency Budget

Phase	Budget	Owner
Observe	< 200 ms	Sensor streams
Orient	< 500 ms	NavigationBloc
Display	< 300 ms	SafetyOverlay
Total to display	< 1 second	SNGNav domain

SafetyOverlay Rules

Rule	Requirement
1	Always rendered - never removed from the widget tree
2	Always on top - Z=5 (topmost)
3	Passthrough when inactive - no input blocking
4	Modal when active - blocks interaction until acknowledged
5	Independent state - not reset by unrelated navigation transitions

Threshold Configuration

import 'package:navigation_safety/navigation_safety_core.dart';

final config = NavigationSafetyConfig(
  safeScoreFloor: 0.80,
  infoScoreFloor: 0.50,
  warningScoreFloor: 0.30,
  criticalTemperatureCelsius: -5,
  warningVisibilityMeters: 200,
);

final score = SafetyScore(
  overall: 0.42,
  gripScore: 0.35,
  visibilityScore: 0.40,
  fleetConfidenceScore: 0.75,
);

final severity = score.toAlertSeverity(config);

Safety Boundary

This package is display-only. It exists to help the driver understand road conditions and navigation risk quickly. It must not be used to issue vehicle control commands or to imply ADAS certification.

See Also

• kalman_dr — Dead reckoning through GPS loss (tunnels, urban canyons)
• routing_engine — Engine-agnostic routing (OSRM + Valhalla)
• driving_weather — Weather condition model for driving (snow, ice, visibility)
• driving_consent — Privacy consent with Jidoka semantics (UNKNOWN = DENIED)
• fleet_hazard — Fleet telemetry hazard model and geographic clustering
• driving_conditions — Pure Dart computation models for road surface, visibility, and safety score simulation
• map_viewport_bloc — Flutter viewport and layer composition state machine
• routing_bloc — Flutter route lifecycle state machine and progress UI
• offline_tiles — Flutter offline tile manager with MBTiles fallback

Part of SNGNav

navigation_safety is one of the 10 packages in SNGNav, an offline-first, driver-assisting navigation reference product for embedded Linux.

License

BSD-3-Clause — see LICENSE.