# Building a new menu item This is the operational build guide for adding a menu item, the panel it opens, and the controls inside it, so a new one is indistinguishable from the shipped ones and does not need its styles corrected afterward. Read `docs/design-system.md` once for the why (tokens, themes, the modular CSS architecture, the full primitive and utility-class reference). This guide is the how: the steps in order, the reuse-or-rebuild decisions, the pitfalls we keep correcting, and the gate. When this guide and `design-system.md` overlap they agree; `design-system.md` is the reference, this is the checklist. "Add a menu item" has two senses, kept separate here: - A new top-level feature reached from the app menu: a `MenuItem` plus the `SlideOver` panel it opens. This is most of the guide. - A clickable row inside a popover menu: the `.menu-item` utility class. See the row-class table in section 5. --- ## 0. The gate (run in this order, every change) During edits, the fast per-file loop: 1. `npx @biomejs/biome check --write ` (format, lint, and organize imports, with autofix) 2. `npm run check` (svelte-check plus the tsgo TypeScript passes) 3. `npx @biomejs/biome ci ` (no-write verify, the same engine the commit hook runs) Then run `npm run verify:commit` before committing. The pre-push hook runs `npm run verify:browser`, including type checks, coverage, a production build, bundle budgets, and Chromium E2E without a duplicate build. CI runs `npm run verify:ci` for Chromium, WebKit, package, and runtime dependency coverage. Tooling traps, each of which has bitten us: 1. All tools are development dependencies. Use the npm scripts or a package-qualified local binary through `npx`. Never depend on a globally installed formatter or linter. 2. Biome `lineWidth` is 100. Wrap to 100. 3. dependency-cruiser `no-cross-feature`: a feature may import another feature ONLY through that feature's `index.ts` public barrel, never a deep path. The same holds for shared and entities slices, and the layer direction is enforced: `app -> views -> widgets -> features -> entities -> shared`, with shared importing nothing above it. Cross-feature data flows through an `entities` store, never feature to feature. 4. `noGlobalAssign` fires when a local variable shadows a JS global. We have hit this with `open` (window.open), `name` (window.name), and other `window.*` names. The fix is to rename the local, never to disable the rule. The Disclosure prop is `expanded`, not `open`, for exactly this reason. 5. svelte-check warns `state_referenced_locally` for `let x = $state(prop)`. When the one-time seed is intentional (a freshly mounted form takes a snapshot of a default), silence it with `untrack(() => prop)`, as `NameEntry` does. Do not ignore the warning. 6. zsh does NOT word-split an unquoted variable, so a file list in `$FILES` reaches the command as a single argument. Pass file lists as explicit arguments or a shell array, never a bare `$FILES`. 7. No `prepare` or `prepack` lifecycle script in `package.json`: it corrupts the App Store install-simulation step. Git hooks are opt-in through the non-lifecycle `hooks` script. --- ## 1. Wire the menu item in `app/App.svelte` (all four steps, together) The menu and bottom bar are data-driven, so these four steps are the whole integration. Doing one or two leaves a tile that opens nothing, or a panel with no way in. 1. Add a `MenuItem` to the `menuItems` array, in the right intent group. The groups today are Chart, Navigate, Safety, Weather, Instruments, and Settings. Groups derive from contiguous item order, so a group move means relocating the literal, not only editing its `group` string. Safety stays before Weather and Instruments; Settings (Profiles) MUST stay last. Set `id`, `label`, `icon` (a lucide component), `group`, `pressed: activePanel === ''`, and `onSelect: () => togglePanel('')`. Add `shortLabel` when the label is long (the bottom-bar pill renders `shortLabel ?? label`). Add `disabled` plus `disabledLabel` for a transient block, such as a chart still loading. When a user-relevant optional provider is absent, keep the item visible with `available: false` plus an actionable `unavailableHint`; do not hide it with a conditional spread. Offline charts is the canonical example: one entry is always present, and its hint explains how to install, start, or sign in to Signal K as an administrator. Radar, Playback, and Instrument dashboard (KIP) follow the same availability rule. When discovery has multiple failure states, derive the hint from current state so absence, an access refusal, malformed provider data, and a transport failure do not collapse into the same message. Chart Locker management requests use the browser's Signal K administrator session. Do not attach Binnacle's device bearer token to its administrator-gated `/api` routes. Classify 401 and 403 responses against `/skServer/loginStatus` instead of assuming the browser is signed out. 2. Add the panel id to the `LeftPanel` union type. 3. Add the mount block: `{#if activePanel === '' && }` wrapping `
`. The guards mirror the menu gating. 4. Construct the feature's controller and services in `App.svelte` and pass them down as props. Services are never global singletons; they are built here so they are swappable in tests. Large optional panels should expose a cached dynamic-import loader from the slice's `index.ts` and mount through an `{#await}` block with loading, failure, and Retry states. Keep the import behind the public API. Use the shared `LazyPanelState` for a docked panel's loading and failure branches so Back, Close, Escape, and Retry remain available before its module mounts. Use `createRetryableLazyUiLoader` to bound a stalled import and clear rejected or timed-out promises so Retry performs a new import. Reserve the unbounded `createRetryableLazyLoader` for one-shot registration paths without a recovery action, where a slow import must be allowed to finish instead of permanently rolling back the feature. Wrap the resolved component in the shared `ErrorBoundary`. Its fallback must preserve the same contextual Back, Close, Exit, or Done controls as the import-failure state, plus Retry, so a render or effect failure cannot trap the workflow. Apply the same boundary to nested lazy charts and dialogs. Core chart and safety chrome stays eagerly loaded. If a chart marker opens a small lazy panel, warm that panel while the marker is tappable so its first tap does not start the chunk request. When a menu destination depends on a matching chart layer, opening the destination must establish the visible state it needs. Use `togglePanel('', () => setLayerVisible('', true))`, as Find places does for the Places layer. The panel must still render explicit hidden, loading, empty, offline, and error states reported by the provider path. Do not infer them all from an empty list. --- ## 2. Build the panel (canonical structure, top to bottom) A panel is a feature component that renders exactly one `` and nothing else at the top level. Inside, in this order: 1. The `SlideOver` open tag: `title`, then a specific `closeLabel` (see the copy rules: never the bare default), then `{onClose}` and `{onBack}`, then `bodyFlex` when the body is a stack of controls and readouts (the common case). Omit `bodyFlex` only for a continuous accordion list that owns its own spacing (LayersPanel), and say why in a comment. Optional: `subtitle`, `footer`, `minimize` (the phone collapse, as one `{ collapsed, onToggle }` object), `dock`, `ariaLabel`. When a phone workflow needs a chart gesture, pass `minimize`, collapse the panel before enabling the gesture, and restore it when the gesture finishes or is canceled. Offline area drawing is the canonical example. When `focusTrap` changes at a responsive breakpoint, update the prop on the one stable `SlideOver`. Do not branch into duplicate panel shells because that discards scroll, focus, and child-local state. 2. Top-of-body notes, before any section: a transient error as ``, and and a write-gate teach note through the shared `WriteAccessNote` when `auth.writeBlocked`, whose message names what is blocked in the panel's own words. The vocabulary is fixed: read and write access, approved by the boat's Signal K admin, never "token". 3. A one-line teach intro in plain helm voice: `

...

`. 4. One or more `
` blocks, each led by an `

` heading, then its control primitives and readouts. A sub-heading is `

`. 5. A list of saved records uses `` with a next-step `empty` message. A destructive action on a card arms an `` first. When a card needs more than one primary and two secondary actions, keep the primary visible and put the rest in `OverflowActions` with plain text labels. Its shared anchored surface follows panel scrolling, flips above or below, and clamps to the viewport. Do not replace that behavior with card-relative positioning. 6. Live status carries a role: `role="progressbar"` with aria-valuemin/max/now for a determinate bar, `role="status"` for a soft advisory, `role="alert"` for a hard error. A determinate bar also shows a visible percentage, byte count, or item count and supplies matching `aria-valuetext`. Never make a thin, unlabeled track the only progress readout. 7. A server-backed list distinguishes initial loading, refresh with retained rows, true empty, and failure. Confirmed writes update local state before a follow-up refresh, late refreshes cannot overwrite newer results, and conflicting mutations disable until completion. Tracks and Waypoints are the canonical saved-resource examples. A failed modal write must preserve the dialog and its entered values. 8. An action that starts navigation or turns incomplete sensor history into guidance requires an explicit confirmation and states what data it will use. Retrace track and Navigate to waypoint are the canonical examples. 9. A background recorder must explain where unsaved and saved data live, what survives reload, and what a destructive action removes. If persistence degrades to memory, surface that state before the user leaves the panel. The Tracks guide documents the complete lifecycle pattern. 10. A chart-tap tool uses a visible mode affordance, gives the next gesture in its live strip, validates and bounds collected points, and restores chart chrome on exit. Selection must not implicitly begin a destructive drag. A nested manipulation mode cancels before the parent tool on Escape, chart hit areas meet the 44 px target, and the strip supplies a keyboard-equivalent path. Selecting an already-active menu item must not silently erase work. Measure is the canonical example. 11. Sensor-derived actions must reject stale inputs at the action boundary, not only gray the button. Center, Follow, and Anchor watch are the canonical GPS examples. Readouts derived from stale own position must become unavailable instead of keeping frozen range or bearing values. 12. A provider load with automatic cooldown must also offer an explicit retry that bypasses that cooldown. Keep already accepted data visible during refresh and after failure. Chart sources, Forecast, Tides and currents, Data trends, and Playback are the canonical examples. 13. Bound every externally supplied collection, string, coordinate, and numeric range before it reaches reactive state or rendering. This includes server resources, plugin discovery, imported files, local persistence, IndexedDB replay, and history-provider rows. 14. Every setting must declare whether it belongs to a portable profile, this device, a Signal K resource, safety state, credentials, or disposable cache and draft state. Profiles is the canonical example. Active profile settings save automatically, so do not add a separate dirty, save, or discard workflow. A button labeled Now changes the current view to the newest loaded data; it must not hide a network refresh behind navigation wording. 15. Every `PersistedValue` carrying production state must receive a bounded validator or codec. A codec owns legacy migration and lets invalid JSON repair to a safe fallback. Record codecs should rebuild a clean literal when unknown fields must not survive. Do not cast parsed browser storage directly into reactive state. 16. Device-data deletion must register exact Binnacle storage owners. Never call `localStorage.clear()`, delete every origin database or cache, or unregister another Signal K webapp's service worker. Block erasure while safety or unsaved navigation state is active, and explain that local deletion does not revoke server access or delete server resources. 17. Add every production localStorage key to `src/shared/persistence/storage-keys.ts`. Portable settings also need a profile type, bounded validation, a binding-table entry, merge metadata, and tests. Device, safety, credential, server-resource, and cache values must not enter the profile capture path. Skeleton: ```svelte {#if error !== null} {/if}

One plain sentence telling the helm what this panel does.

Section name

My records

r.id}> {#snippet card(record)} {/snippet}
``` --- ## 3. Pick the panel shape Three established shapes. Pick by what the second screen IS, not by size. 1. Single flat panel (alarms, installed charts, profiles). The whole feature is one screen of stacked sections. Constant `title`, no sub-view state. This is the default; reach for it first. 2. Landing plus sibling sub-views (RegionsPanel). One feature with several peer destinations that each deserve a titled screen (home, build, automatic caching, storage). One `subView` state in the parent, a `$derived` `subViewTitle` fed to `SlideOver`, and a cleanup-aware `backToOfflineHome` callback that returns to the landing first and clears any active map drawing. Installed charts can open as a sibling panel, whose back action returns to this landing. Landing rows are a `.subview-link row-interactive` button with a label, a current value, and a trailing chevron. Keep orchestration and navigation in the parent, and extract substantial sibling screens into focused view components, as RegionsPanel does for storage and automatic caching. 3. Detail drill-in (LayersPanel opening SourceDetail). Selecting one record from a list opens that record's detail or editor in the SAME SlideOver. The detail renders ``, and the parent suppresses its own panel-level back while the detail is open (`onBack={detailOpen ? undefined : onBack}`). There must never be two stacked back controls. Whoever owns the in-body back (the title switch in shape 2, the SubViewHeader in shape 3) requires the panel-level back to be suppressed for that state. Sanctioned exception: a full-screen map panel (the weather map) hosts its own header chrome instead of a SlideOver, because it is a docked mini-map with a layers menu and a conditions sheet rather than a scrolling body of controls. It still carries a specific back control and close control and follows the copy, token, and accessibility rules. A new panel uses a SlideOver unless it is a full-screen map of this kind. Second sanctioned exception: the instrument dock is a true SPLIT, not an overlay. The shell is a two-column grid; the dock takes the second column beside a live, narrowed chart, with a 1px `--border` seam (night-red has no shadows) and an instant toggle (animating the grid track would resize the map every frame). Under its 900px breakpoint the same panel goes full-screen at `--z-panel`, below the safety strips, with its own close chrome ("Close instruments, return to chart"). A full-screen instrument panel and a chart-owned panel never stack: the existing chart panel keeps ownership when the viewport crosses the breakpoint, while deliberately opening Instruments closes the other surface. Route a dirty editor, such as a Radar area draft, through its discard guard before transferring that ownership. Its tile grid fills the dock: rows share the full height, dense flow backfills holes, and an empty tile is never full width (the layout rules live in the design system's instruments module entry). Selecting a tile opens an in-dock detail view, and Customize groups available instruments by category with a Rescan action for dynamic Signal K instances. That scan unions live instances with concrete paths from the preceding year of registered history providers within a bounded scan. Validate those context-free catalog paths with a `vessels.self` values query before displaying them. Previously seen readings remain selectable, visibly marked in Available and Shown, and identified in detail until live data arrives. Provider absence or failure must preserve live discovery and explain the reduced catalog. Dynamic labels lead with the reading and then name the source. Customize must also disambiguate any repeated catalog label so visible text, checkbox names, and reorder announcements remain unique without deduplicating legitimate readings. Never copy a stored sample into a current instrument tile. Do not add further split panels without a matching product case; overlays stay the default. Data trends is a normal SlideOver, not another split. Its overview selection is profile-owned and independent from the instrument dock. It renders zero to eight explicit trend descriptors in saved order and uses `CustomizeToggle` plus `createReorder` for touch and keyboard editing. Preserve unavailable saved IDs until the navigator removes them. Opening Data trends must trigger live and historical discovery without depending on the instrument dock having opened. Retain the eight saved stream demands and recorder buffers plus one optional focused slot, and release removed demands. Opening a focused chart from an eligible instrument detail adds that transient slot without changing the overview. Back restores the same detail and focus, while Close clears the transient context and returns to the chart. History loading for Data trends is chart-specific. Batch deduplicated `path:aggregate` requests within the Signal K History API limit, query each registered provider once per batch, and resolve by candidate priority followed by provider order. Never merge providers or fallback paths inside one series. Attribute the chosen provider, path, and reference. Keep accepted data during retry, and distinguish provider checking, partial failure, total failure, true empty history, session fallback, and no samples. A stock server gets only the bounded, in-memory session window, and the copy must say so. Edit-mode entry (the customize rule): render the `CustomizeToggle` primitive from `$shared/ui`, one per surface, trailing in the header row, and open the mode with one `.muted-note` line stating what a tap now does. The visual and aria recipe lives in the design system's Edit modes entry. The app menu's toolbar editor also shows the current pinned bar order. Use the shared `createReorder` controller for pointer and ArrowUp or ArrowDown movement, keep the stored `pinnedActionIds` order as the source of truth, and include a reset action that restores `DEFAULT_PINNED`. The menu tile grid still controls membership by tapping tiles in edit mode. --- ## 4. Reuse a primitive, never re-implement Everything below is exported from `$shared/ui`. The standing rule is to hoist a shape into `$shared/ui` at the SECOND copy; a third copy is a review failure. | Need | Reach for | Never | | --- | --- | --- | | Top-level slide-in panel | `SlideOver` | a bespoke `