Remote-Terminal-for-MeshCore/frontend/AGENTS.md

Frontend AGENTS.md

This document is the frontend working guide for agents and developers. Keep it aligned with frontend/src source code.

Stack

• React 18 + TypeScript
• Vite
• Vitest + Testing Library
• shadcn/ui primitives
• Tailwind utility classes + local CSS (index.css, styles.css)
• Sonner (toasts)
• Leaflet / react-leaflet (map)
• Vendored @michaelhart/meshcore-decoder in frontend/lib/meshcore-decoder (local file dependency for multibyte-support build)
• meshcore-hashtag-cracker + nosleep.js (channel cracker)

Frontend Map

frontend/src/
├── main.tsx                # React entry point (StrictMode, root render)
├── App.tsx                 # App shell and orchestration
├── api.ts                  # Typed REST client
├── types.ts                # Shared TS contracts
├── useWebSocket.ts         # WS lifecycle + event dispatch
├── messageCache.ts         # Conversation-scoped cache
├── prefetch.ts             # Consumes prefetched API promises started in index.html
├── index.css               # Global styles/utilities
├── styles.css              # Additional global app styles
├── themes.css              # Color theme definitions
├── lib/
│   └── utils.ts            # cn() — clsx + tailwind-merge helper
├── hooks/
│   ├── index.ts            # Central re-export of all hooks
│   ├── useConversationMessages.ts  # Fetch, pagination, dedup, ACK buffering
│   ├── useUnreadCounts.ts          # Unread counters, mentions, recent-sort timestamps
│   ├── useRepeaterDashboard.ts      # Repeater dashboard state (login, panes, console, retries)
│   ├── useRadioControl.ts          # Radio health/config state, reconnection
│   ├── useAppSettings.ts           # Settings, favorites, preferences migration
│   ├── useConversationRouter.ts    # URL hash → active conversation routing
│   └── useContactsAndChannels.ts   # Contact/channel loading, creation, deletion
├── utils/
│   ├── urlHash.ts              # Hash parsing and encoding
│   ├── conversationState.ts    # State keys, in-memory + localStorage helpers
│   ├── favorites.ts            # LocalStorage migration for favorites
│   ├── messageParser.ts        # Message text → rendered segments
│   ├── pathUtils.ts            # Distance/validation helpers for paths + map
│   ├── pubkey.ts               # getContactDisplayName (12-char prefix fallback)
│   ├── contactAvatar.ts        # Avatar color derivation from public key
│   ├── rawPacketIdentity.ts    # observation_id vs id dedup helpers
│   ├── visualizerUtils.ts      # 3D visualizer node types, colors, particles
│   ├── visualizerSettings.ts   # LocalStorage persistence for visualizer options
│   ├── a11y.ts                 # Keyboard accessibility helper
│   ├── lastViewedConversation.ts   # localStorage for last-viewed conversation
│   ├── contactMerge.ts            # Merge WS contact updates into list
│   ├── localLabel.ts              # Local label (text + color) in localStorage
│   ├── radioPresets.ts            # LoRa radio preset configurations
│   └── theme.ts                   # Theme switching helpers
├── components/
│   ├── StatusBar.tsx
│   ├── Sidebar.tsx
│   ├── ChatHeader.tsx          # Conversation header (trace, favorite, delete)
│   ├── MessageList.tsx
│   ├── MessageInput.tsx
│   ├── NewMessageModal.tsx
│   ├── SearchView.tsx          # Full-text message search pane
│   ├── SettingsModal.tsx       # Layout shell — delegates to settings/ sections
│   ├── RawPacketList.tsx
│   ├── MapView.tsx
│   ├── VisualizerView.tsx
│   ├── PacketVisualizer3D.tsx
│   ├── PathModal.tsx
│   ├── PathRouteMap.tsx
│   ├── CrackerPanel.tsx
│   ├── BotCodeEditor.tsx
│   ├── ContactAvatar.tsx
│   ├── ContactInfoPane.tsx     # Contact detail sheet (stats, name history, paths)
│   ├── ContactStatusInfo.tsx   # Contact status info component
│   ├── RepeaterDashboard.tsx   # Layout shell — delegates to repeater/ panes
│   ├── RepeaterLogin.tsx       # Repeater login form (password + guest)
│   ├── ChannelInfoPane.tsx     # Channel detail sheet (stats, top senders)
│   ├── NeighborsMiniMap.tsx    # Leaflet mini-map for repeater neighbor locations
│   ├── settings/
│   │   ├── settingsConstants.ts          # Settings section type, ordering, labels
│   │   ├── SettingsRadioSection.tsx      # Name, keys, advert interval, max contacts, radio preset, freq/bw/sf/cr, txPower, lat/lon, reboot
│   │   ├── SettingsLocalSection.tsx      # Browser-local settings: theme, local label, reopen last conversation
│   │   ├── SettingsFanoutSection.tsx     # Fanout integrations: MQTT, bots, config CRUD
│   │   ├── SettingsDatabaseSection.tsx   # DB size, cleanup, auto-decrypt, local label
│   │   ├── SettingsStatisticsSection.tsx # Read-only mesh network stats
│   │   ├── SettingsAboutSection.tsx     # Version, author, license, links
│   │   └── ThemeSelector.tsx           # Color theme picker
│   ├── repeater/
│   │   ├── repeaterPaneShared.tsx        # Shared: RepeaterPane, KvRow, format helpers
│   │   ├── RepeaterTelemetryPane.tsx    # Battery, airtime, packet counts
│   │   ├── RepeaterNeighborsPane.tsx    # Neighbor table + lazy mini-map
│   │   ├── RepeaterAclPane.tsx          # Permission table
│   │   ├── RepeaterRadioSettingsPane.tsx # Radio settings + advert intervals
│   │   ├── RepeaterLppTelemetryPane.tsx # CayenneLPP sensor data
│   │   ├── RepeaterOwnerInfoPane.tsx    # Owner info + guest password
│   │   ├── RepeaterActionsPane.tsx      # Send Advert, Sync Clock, Reboot
│   │   └── RepeaterConsolePane.tsx      # CLI console with history
│   └── ui/                     # shadcn/ui primitives
├── types/
│   ├── d3-force-3d.d.ts       # Type declarations for d3-force-3d
│   └── globals.d.ts           # Global type declarations (__APP_VERSION__, __COMMIT_HASH__)
└── test/
    ├── setup.ts
    ├── fixtures/websocket_events.json
    ├── api.test.ts
    ├── appFavorites.test.tsx
    ├── appStartupHash.test.tsx
    ├── contactAvatar.test.ts
    ├── integration.test.ts
    ├── messageCache.test.ts
    ├── messageParser.test.ts
    ├── pathUtils.test.ts
    ├── prefetch.test.ts
    ├── radioPresets.test.ts
    ├── rawPacketIdentity.test.ts
    ├── repeaterDashboard.test.tsx
    ├── repeaterFormatters.test.ts
    ├── repeaterLogin.test.tsx
    ├── repeaterMessageParsing.test.ts
    ├── localLabel.test.ts
    ├── messageInput.test.tsx
    ├── newMessageModal.test.tsx
    ├── settingsModal.test.tsx
    ├── sidebar.test.tsx
    ├── unreadCounts.test.ts
    ├── urlHash.test.ts
    ├── appSearchJump.test.tsx
    ├── channelInfoKeyVisibility.test.tsx
    ├── chatHeaderKeyVisibility.test.tsx
    ├── searchView.test.tsx
    ├── useConversationMessages.test.ts
    ├── useConversationMessages.race.test.ts
    ├── useRepeaterDashboard.test.ts
    ├── useContactsAndChannels.test.ts
    ├── useWebSocket.dispatch.test.ts
    └── useWebSocket.lifecycle.test.ts

frontend/lib/
└── meshcore-decoder/      # Vendored local decoder package used by app + hashtag cracker

Architecture Notes

State ownership

App.tsx orchestrates high-level state and delegates to hooks:

• useRadioControl: radio health/config state, reconnect/reboot polling
• useAppSettings: settings CRUD, favorites, preferences migration
• useContactsAndChannels: contact/channel lists, creation, deletion
• useConversationRouter: URL hash → active conversation routing
• useConversationMessages: fetch, pagination, dedup/update helpers
• useUnreadCounts: unread counters, mention tracking, recent-sort timestamps
• useRepeaterDashboard: repeater dashboard state (login, pane data/retries, console, actions)

Initial load + realtime

• Initial data: REST fetches (api.ts) for config/settings/channels/contacts/unreads.
• WebSocket: realtime deltas/events.
• On WS connect, backend sends health only; contacts/channels still come from REST.

New Message modal

NewMessageModal resets form state on close. The component instance persists across open/close cycles for smooth animations.

Message behavior

• Outgoing sends are added to UI after the send API returns (not pre-send optimistic insertion), then persisted server-side.
• Backend also emits WS message for outgoing sends so other clients stay in sync.
• ACK/repeat updates arrive as message_acked events.
• Outgoing channel messages show a 30-second resend control; resend calls POST /api/messages/channel/{message_id}/resend.

Visualizer behavior

• VisualizerView.tsx hosts PacketVisualizer3D.tsx (desktop split-pane and mobile tabs).
• PacketVisualizer3D uses persistent Three.js geometries for links/highlights/particles and updates typed-array buffers in-place per frame.
• Packet repeat aggregation keys prefer decoder messageHash (path-insensitive), with hash fallback for malformed packets.
• Raw packet events carry both:
  • id: backend storage row identity (payload-level dedup)
  • observation_id: realtime per-arrival identity (session fidelity)
• Packet feed/visualizer render keys and dedup logic should use observation_id (fallback to id only for older payloads).

WebSocket (useWebSocket.ts)

• Auto reconnect (3s) with cleanup guard on unmount.
• Heartbeat ping every 30s.
• Event handlers: health, message, contact, raw_packet, message_acked, contact_deleted, channel_deleted, error, success, pong (ignored).
• For raw_packet events, use observation_id as event identity; id is a storage reference and may repeat.

URL Hash Navigation (utils/urlHash.ts)

Supported routes:

• #raw
• #map
• #map/focus/{pubkey_or_prefix}
• #visualizer
• #search
• #channel/{channelKey}
• #channel/{channelKey}/{label}
• #contact/{publicKey}
• #contact/{publicKey}/{label}

Legacy name-based hashes are still accepted for compatibility.

Conversation State Keys (utils/conversationState.ts)

getStateKey(type, id) produces:

• channels: channel-{channelKey}
• contacts: contact-{publicKey}

Use full contact public key here (not 12-char prefix).

conversationState.ts keeps an in-memory cache and localStorage helpers used for migration/compatibility. Canonical persistence for unread and sort metadata is server-side (app_settings + read-state endpoints).

Utilities

utils/pubkey.ts

Current public export:

• getContactDisplayName(name, pubkey)

It falls back to a 12-char prefix when name is missing.

utils/pathUtils.ts

Distance/validation helpers used by path + map UI.

utils/favorites.ts

LocalStorage migration helpers for favorites; canonical favorites are server-side.

Types and Contracts (types.ts)

AppSettings currently includes:

• max_radio_contacts
• favorites
• auto_decrypt_dm_on_advert
• sidebar_sort_order
• last_message_times
• preferences_migrated
• advert_interval
• last_advert_time
• flood_scope
• blocked_keys, blocked_names

Note: MQTT, bot, and community MQTT settings were migrated to the fanout_configs table (managed via /api/fanout). They are no longer part of AppSettings.

HealthStatus includes fanout_statuses: Record<string, FanoutStatusEntry> mapping config IDs to {name, type, status}. Also includes bots_disabled: boolean.

FanoutConfig represents a single fanout integration: {id, type, name, enabled, config, scope, sort_order, created_at}.

RawPacket.decrypted_info includes channel_key and contact_key for MQTT topic routing.

Contact Info Pane

Clicking a contact's avatar in ChatHeader or MessageList opens a ContactInfoPane sheet (right drawer) showing comprehensive contact details fetched from GET /api/contacts/{key}/detail:

• Header: avatar, name, public key, type badge, on-radio badge
• Info grid: last seen, first heard, last contacted, distance, hops
• GPS location (clickable → map)
• Favorite toggle
• Name history ("Also Known As") — shown only when the contact has used multiple names
• Message stats: DM count, channel message count
• Most active rooms (clickable → navigate to channel)
• Advert observation rate
• Nearest repeaters (resolved from first-hop path prefixes)
• Recent advert paths

State: infoPaneContactKey in App.tsx controls open/close. Live contact data from WebSocket updates is preferred over the initial detail snapshot.

Channel Info Pane

Clicking a channel name in ChatHeader opens a ChannelInfoPane sheet (right drawer) showing channel details fetched from GET /api/channels/{key}/detail:

• Header: channel name, key (clickable copy), type badge (hashtag/private key), on-radio badge
• Favorite toggle
• Message activity: time-windowed counts (1h, 24h, 48h, 7d, all time) + unique senders
• First message date
• Top senders in last 24h (name + count)

State: infoPaneChannelKey in App.tsx controls open/close. Live channel data from the channels array is preferred over the initial detail snapshot.

Repeater Dashboard

For repeater contacts (type=2), App.tsx renders RepeaterDashboard instead of the normal chat UI (ChatHeader + MessageList + MessageInput).

Login: RepeaterLogin component — password or guest login via POST /api/contacts/{key}/repeater/login.

Dashboard panes (after login): Telemetry, Neighbors, ACL, Radio Settings, Advert Intervals, Owner Info — each fetched via granular POST /api/contacts/{key}/repeater/{pane} endpoints. Panes retry up to 3 times client-side. "Load All" fetches all panes serially (parallel would queue behind the radio lock).

Actions pane: Send Advert, Sync Clock, Reboot — all send CLI commands via POST /api/contacts/{key}/command.

Console pane: Full CLI access via the same command endpoint. History is ephemeral (not persisted to DB).

All state is managed by useRepeaterDashboard hook. State resets on conversation change.

Message Search Pane

The SearchView component (components/SearchView.tsx) provides full-text search across all DMs and channel messages. Key behaviors:

• State: targetMessageId in App.tsx drives the jump-to-message flow. When a search result is clicked, handleNavigateToMessage sets targetMessageId and switches to the target conversation.
• Persistence: SearchView stays mounted after first open using the same hidden class pattern as CrackerPanel, preserving search state when navigating to results.
• Jump-to-message: useConversationMessages accepts optional targetMessageId. When set, it calls api.getMessagesAround() instead of normal fetch, loading context around the target message. MessageList scrolls to the target via data-message-id attribute and applies a message-highlight CSS animation.
• Bidirectional pagination: After jumping mid-history, hasNewerMessages enables forward pagination via fetchNewerMessages. The scroll-to-bottom button calls jumpToBottom (re-fetches latest page) instead of just scrolling.
• WS message suppression: When hasNewerMessages is true, incoming WS messages for the active conversation are not added to the message list (the user is viewing historical context, not the latest page).

Styling

UI styling is mostly utility-class driven (Tailwind-style classes in JSX) plus shared globals in index.css and styles.css. Do not rely on old class-only layout assumptions.

Security Posture (intentional)

• No authentication UI.
• Frontend assumes trusted network usage.
• Bot editor intentionally allows arbitrary backend bot code configuration.

Testing

Run all quality checks (backend + frontend) from the repo root:

./scripts/all_quality.sh

Or run frontend checks individually:

cd frontend
npm run test:run
npm run build

When touching cross-layer contracts, also run backend tests from repo root:

PYTHONPATH=. uv run pytest tests/ -v

Errata & Known Non-Issues

RawPacketList always scrolls to bottom

RawPacketList unconditionally scrolls to the latest packet on every update. This is intentional — the packet feed is a live status display, not an interactive log meant for lingering or long-term analysis. Users watching it want to see the newest packet, not hold a scroll position.

Editing Checklist

1. If API/WS payloads change, update types.ts, handlers, and tests.
2. If URL/hash behavior changes, update utils/urlHash.ts tests.
3. If read/unread semantics change, update useUnreadCounts tests.
4. Keep this file concise; prefer source links over speculative detail.