app-flutter/lib/README.md

type

type
reference

The app's code: a catalogue

Laid out like smart-serow's HUD (pi/ui/lib/), which several pieces come from; the menu follows pirate-station-aide's (main views, then the rarely used ones grouped as Tools).

Folders

Where	Holds
main.dart	Startup: the link to the Orin, the theme, then the shell
shell.dart	The shell: a menu that swipes in from the left; Dash, Signals, Captures, then Tools (Camera, Link test, Orin power options), then Settings. Dash, Signals and Captures stay alive while hidden
shell_scope.dart	What a page needs from the shell: MenuButton, ShellView, the landing view (--dart-define=YUKART_HOME=dash|signals, signals for now)
pages/	One file per view: dash, signals (values and raw traffic), checklist (Captures), camera, link_test, settings
actions/	Things done from anywhere, as dialogs and sheets: marks (free-form mark), orin_power (power off / reboot), server_url (gateway address)
link/	Talking to the Orin: boundary (the protocol client), net (binding to the USB link), reading (one signal's state as a display needs it)
theme/	palette.dart: the palette roles, hudFont, and Themes (which variant shows: auto or held, kept across restarts)
widgets/	Reusable display widgets, one per file, each fed values, never the boundary (link_status takes it whole: it shows the link)

Widgets

Widget	File	Shows	From
StatBox, StatBoxMain	widgets/stat_box.dart	A value, its unit and label, sized from its box's height; alarm on warning, subdued when dim	smart-serow
Telltale	widgets/telltale.dart	An on/off lamp: a label or an icon, lit or dark, "—" when missing	Yukart
WhiskeyMark	widgets/whiskey_mark.dart	Attitude: a horizon tilting with roll, ladder moving with pitch	smart-serow
AccelGraph	widgets/accel_graph.dart	G-meter: a dot for lateral/longitudinal g, a trace and a peak marker over a window	smart-serow
GpsCompass	widgets/gps_compass.dart	Heading arrow and bearing; "ACQ" while acquiring, "N/A" without	smart-serow, from gps-speedo
LinkChip, LinkDetails	widgets/link_status.dart	The link's state in good / caution / alarm; address, last-message age, clock offset, USB link	Yukart
MockBanner	widgets/mock_banner.dart	"MOCK DATA — NOT FROM THE CAR" in caution, over every page while the gateway is mocking	Yukart

Conventions

• The boxed pattern. A widget takes its share of a row and sizes its type from its own height, so a layout is a grid of boxes and a value gaining a digit never moves anything. Labels shrink to fit, never wrap.
• Colours by meaning. AppTheme.of(context) gives seven roles: background, foreground, subdued (muted, missing, stale), accent (emphasis without danger: buttons, links, the current item), and the state gradient good → caution → alarm; plus the derived surface (raised bars) and onFill(colour) (text on a fill). No widget names a colour. Themes are JSON in assets/themes/, rei by default; smart-serow's four-key files still load (their highlight is alarm).
• Dark or bright. Themes.mode is auto (Android's dark theme, schedule included), dark or bright, chosen in Settings and kept across restarts. The Dash's quick button holds the other variant; a long press there is auto again.
• Cosmetic fonts are opt-in. A widget that wants the HUD face names fontFamily: hudFont in its own TextStyle; everything else keeps the basic font, which covers CJK where DIN 1451 does not.
• Missing is a state (app guideline 2): a widget given no value draws "—" or subdued, never an error.