app-flutter/lib/README.md

---
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 and `hudFont` |
| `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`).
- **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.