\`` template in `renderSidebar` is
the fastest way in. The existing metrics (`Alt`, `Spd`, `Hdg`,
`Dist`) live in a `.meta` grid at the bottom of each row.
Each metric looks like:
```html
Alt
${uconv('alt', a.altitude)}${tAlt.arrow}
```
Two things to get right:
1. **Escape user-sourced strings** — anything that came from a
BEAST payload (`callsign`, `registration`, `type_icao`,
`operator*`, `emergency`, …) goes through `escapeHtml()`
before being concatenated into the HTML string. Numeric
fields that go through `fmt()` / `uconv()` are safe — those
helpers only emit digits and unit suffixes. See
`app/static/format.js` for the `escapeHtml` helper and the
Frontend section in CLAUDE.md for the rule.
2. **Update the fingerprint** — find the `const fp = [ … ].join('|')`
block and append every field that affects your new
markup. Miss one and the row will stop re-rendering when
that field changes (the cached element gets reused because
the fingerprint matches) — this is the most common way to
accidentally break the sidebar. If you rely on a derived
value like `trendInfo(entry, 'spd').cls`, include the derived
class/arrow strings in the fingerprint, not the raw inputs.
Sketch of a new "Fuel %" metric that reads `a.fuel_percent`:
```js
// in sidebar.js, inside renderSidebar's per-row block:
const fp = [
// ...existing entries...
tAlt.cls, tAlt.arrow, tSpd.cls, tSpd.arrow, tDst.cls, tDst.arrow,
route,
a.fuel_percent, // new — stringifies to '' for null so stable
].join('|');
// ...inside the `const html = ...` template, within the .meta div:
`
Fuel
` +
`
${fmt(a.fuel_percent, '%')}
`
```
Label text must stay ≤ 4 chars — the metric tiles are narrow
and overflow wraps into two lines (`Alt`, `Spd`, `Hdg`, `Dist`
are the existing ceiling). Long labels belong in a tooltip on a
chip-style element, not the metric grid.
If the new field's data doesn't exist yet in the snapshot, add
it to `SnapshotAircraft` in
`dotnet/src/FlightJar.Core/State/RegistrySnapshot.cs` — the
global snake_case policy means a `FuelPercent` property surfaces
as `fuel_percent` on the wire with no attributes.
### Header / status element
Above the row list, the sidebar has a header row with site name,
status text, msg rate, and a unit switch. To add a new element:
1. **`app/static/index.html`** — add the DOM inside
`#header` or `#header-row2`. Give it a unique id, keep the
markup minimal (usually a `
` and maybe a dot).
2. **`app/static/sidebar.js`** — add a module-level
`let lastYourThing = null;` and inside `renderSidebar`
compute the new value, compare, and set `textContent` only
if it changed:
```js
let lastTrafficClass = '';
// …
const trafficClass = classifyTraffic(snap.count);
if (trafficClass !== lastTrafficClass) {
document.getElementById('traffic-class').textContent = trafficClass;
lastTrafficClass = trafficClass;
}
```
Header elements use `textContent` almost exclusively — user
data displayed here (site_name, status text) has never been
concatenated into `innerHTML`, and new elements should
follow suit. `textContent` is XSS-safe by construction.
## Step — Verify
```bash
node --check app/static/sidebar.js # fast syntax check before the full suite
node --test tests/js/
npx playwright test
```
The Playwright sidebar smoke in `tests/e2e/smoke.spec.js`
renders against a fake snapshot — if your new field is
load-bearing for a test, extend `FAKE_SNAPSHOT` rather than
adding a brand-new spec file.
## Do not
- Do not forget the fingerprint. A new field that isn't in
`fp` will render correctly the first time, then appear to
"stick" at its initial value. This is the #1 sidebar
regression and it's easy to miss because steady-cruise
tests all pass.
- Do not attach event listeners to rows inside the
per-row template. The sidebar builds row Elements via
`buildRowElement` which uses a detached `div` as a parse
host; listeners on a freshly parsed node survive the
`insertBefore` into `#ac-list`, but you'd leak one listener
per icao per cache miss. The existing pattern is a single
delegated `click` / `mouseover` / `mouseout` listener on
`#ac-list`, bound once in `initSidebar`. Add your new row
interactions there.
- Do not interpolate `a.callsign` / `a.registration` /
`a.operator` / `a.emergency` / `a.type_icao` / any
upstream-sourced string into an HTML template without
`escapeHtml(…)`. CodeQL flags these on every PR that
touches the sidebar. Numeric fields via `fmt` / `uconv` are
safe.
- Do not add a new row-level filter without putting its key in
`FILTER_KEYS`. The localStorage reader filters unknown keys
out — a chip whose key isn't registered will visibly toggle
but not persist across reloads, which users read as a bug.
- Do not re-sort by re-rendering everything. Sort chip clicks
set `state.sortDir` / `state.sortKey` and call
`renderSidebar(state.lastSnap)` — the sort happens inside
`renderSidebar` against the cached snapshot. Don't build a
parallel `sortRows()` function; the render path already
does it.
- Do not add a new `` / `` block inside
`#sidebar` without first asking — the list view is
deliberately one-flat-list and the layout has no affordance
for collapsed sub-sections. If you need grouping, that's a
design conversation, not a quick extension.