comments and descriptions

rulesdocs/refector_rules_and_tracking.md

@@ -22,6 +22,9 @@
 - Every component must live in its own folder, even when it remains a single-file implementation.
 - Split large JSX/components and large backing JS files into folderized modules.
 - Keep modules clear and focused, with title comments.
+- Every component/module file should start with a descriptive comment header containing:
+- a title line naming the file/module
+- a longer purpose/scope description (not a one-liner)
 - Each component must live entirely inside its own folder; do not leave wrapper/compatibility component files outside that folder.
 - Remove stale compatibility/leftover code only after usage verification.
 

webui/src/components/AdminPanel/AdminIpLogPanel.jsx

@@ -1,4 +1,6 @@
-// Admin-only IP log stream panel.
+// Admin Ip Log Panel
+// Purpose: Defines the Admin Ip Log Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function AdminIpLogPanel({ entries }) {
   const logs = entries || [];
   return (

webui/src/components/AdminPanel/AdminPanelContent.jsx

@@ -1,4 +1,6 @@
-// Admin control panel main composition and action handlers.
+// Admin Panel Content
+// Purpose: Defines the Admin Panel Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import RoverRoster from '../RoverRoster/index.jsx';

webui/src/components/AdminPanel/LlmCommentaryPanel.jsx

@@ -1,4 +1,6 @@
-// Admin LLM commentary monitor panel.
+// Llm Commentary Panel
+// Purpose: Defines the Llm Commentary Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useState } from 'react';
 import ChatMessageRow from '../ChatMessageRow/index.jsx';
 import { buildLlmLargeIndicatorFromState, buildLlmConversationRowsFromMessages } from './llmHelpers.js';

webui/src/components/AdminPanel/ReplaySnapshotHealth.jsx

@@ -1,4 +1,6 @@
-// Replay and snapshot health status panel.
+// Replay Snapshot Health
+// Purpose: Defines the Replay Snapshot Health module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { roverNameChromeStyle } from '../../lib/roverColor.js';
 
 export default function ReplaySnapshotHealth({ health, roster = [] }) {

webui/src/components/AdminPanel/index.jsx

@@ -1,3 +1,6 @@
+// Admin Panel
+// Purpose: Defines the Admin Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import AdminPanelContent from './AdminPanelContent.jsx';
 
 export default AdminPanelContent;

webui/src/components/AdminPanel/llmHelpers.js

@@ -1,4 +1,6 @@
-// LLM commentary monitor formatting helpers.
+// llm Helpers
+// Purpose: Defines the llm Helpers module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export function buildLlmLargeIndicatorFromState(state) {
   const runtime = state?.runtime || {};
   const output = state?.output || {};

webui/src/components/AlertFeed/index.jsx

@@ -1,3 +1,6 @@
+// Alert Feed
+// Purpose: Defines the Alert Feed module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import { useSessionActions, useSessionSelector } from '../../context/SessionContext.jsx';
 import { useSocket } from '../../context/SocketContext.jsx';

webui/src/components/AuthPanel/index.jsx

@@ -1,3 +1,6 @@
+// Auth Panel
+// Purpose: Defines the Auth Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useState } from 'react';
 import { useSessionActions } from '../../context/SessionContext.jsx';
 

webui/src/components/BatteryBar/index.jsx

@@ -1,3 +1,6 @@
+// Battery Bar
+// Purpose: Defines the Battery Bar module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { WARN_DISPLAY_PERCENT } from '../../lib/battery.js';
 
 const WARN_FLASH_MS = 1600;

webui/src/components/ButtonBoxPanel/index.jsx

@@ -1,3 +1,6 @@
+// Button Box Panel
+// Purpose: Defines the Button Box Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import { useSocket } from '../../context/SocketContext.jsx';

webui/src/components/ButtonBoxTile/index.jsx

@@ -1,3 +1,6 @@
+// Button Box Tile
+// Purpose: Defines the Button Box Tile module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function ButtonBoxTile({
   buttonId,
   count,

webui/src/components/CameraTiltControl/index.jsx

@@ -1,3 +1,6 @@
+// Camera Tilt Control
+// Purpose: Defines the Camera Tilt Control module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useRef, useState } from 'react';
 
 function formatDegrees(value) {

webui/src/components/ChatMessageRow/index.jsx

@@ -1,3 +1,6 @@
+// Chat Message Row
+// Purpose: Defines the Chat Message Row module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { FaDiscord } from 'react-icons/fa';
 import { roverBadgeStyle } from '../../lib/roverColor.js';
 

webui/src/components/ChatPanel/index.jsx

@@ -1,3 +1,6 @@
+// Chat Panel
+// Purpose: Defines the Chat Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useChat } from '../../context/ChatContext.jsx';
 import { useSessionSelector } from '../../context/SessionContext.jsx';

webui/src/components/ChatTypingRow/index.jsx

@@ -1,3 +1,6 @@
+// Chat Typing Row
+// Purpose: Defines the Chat Typing Row module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { ChatIdentity, chatRowClass } from '../ChatMessageRow/index.jsx';
 
 export default function ChatTypingRow({ message }) {

webui/src/components/CommunityGoalBanner/index.jsx

@@ -1,3 +1,6 @@
+// Community Goal Banner
+// Purpose: Defines the Community Goal Banner module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 

webui/src/components/DeterrenceChaos/index.jsx

@@ -1,3 +1,6 @@
+// Deterrence Chaos
+// Purpose: Defines the Deterrence Chaos module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect } from 'react';
 import { useSessionSelector } from '../../context/SessionContext.jsx';
 

webui/src/components/DriveDockAction/index.jsx

@@ -1,3 +1,6 @@
+// Drive Dock Action
+// Purpose: Defines the Drive Dock Action module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo, useState } from 'react';
 import { useControlSystem } from '../../controls/index.js';
 import { useTelemetryFrame } from '../../context/TelemetryContext.jsx';

webui/src/components/DriverVideoPanel/index.jsx

@@ -1,3 +1,6 @@
+// Driver Video Panel
+// Purpose: Defines the Driver Video Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useSessionSelector } from '../../context/SessionContext.jsx';
 import { useTelemetryFrame } from '../../context/TelemetryContext.jsx';

webui/src/components/FloatingFullscreenButton/index.jsx

@@ -1,3 +1,6 @@
+// Floating Fullscreen Button
+// Purpose: Defines the Floating Fullscreen Button module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function FloatingFullscreenButton({ side = 'right', onClick }) {
   const sideClass = side === 'left' ? 'left-2' : 'right-2';
   return (

webui/src/components/FullscreenPrompt/index.jsx

@@ -1,3 +1,6 @@
+// Fullscreen Prompt
+// Purpose: Defines the Fullscreen Prompt module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function FullscreenPrompt({ visible, mode, onEnterFullscreen, onDismiss }) {
   if (!visible) return null;
   const isIOSMode = mode === 'pwa-hint';

webui/src/components/GamepadMappingSettings/GamepadMappingSettingsContent.jsx

@@ -1,3 +1,6 @@
+// Gamepad Mapping Settings Content
+// Purpose: Defines the Gamepad Mapping Settings Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useSettingsNamespace } from '../../settings/index.js';
 import { GAMEPAD_PROFILE_DEFAULT, GAMEPAD_SETTINGS_DEFAULTS } from '../../settings/namespaces.js';

webui/src/components/GamepadMappingSettings/SliderField.jsx

@@ -1,4 +1,6 @@
-// Reusable slider field for gamepad calibration controls.
+// Slider Field
+// Purpose: Defines the Slider Field module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { NUMBER_FORMAT } from './constants.js';
 
 export default function SliderField({ label, description, min, max, step, value, onChange }) {

webui/src/components/GamepadMappingSettings/constants.js

@@ -1,4 +1,6 @@
-// Gamepad mapping constants and action catalog.
+// constants
+// Purpose: Defines the constants module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export const NUMBER_FORMAT = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
 
 export const ACTIONS = [

webui/src/components/GamepadMappingSettings/helpers.js

@@ -1,4 +1,6 @@
-// Gamepad mapping helper and capture functions.
+// helpers
+// Purpose: Defines the helpers module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { CAPTURE_AXIS_THRESHOLD, CAPTURE_BUTTON_THRESHOLD, NUMBER_FORMAT } from './constants.js';
 
 export function formatSource(source) {

webui/src/components/GamepadMappingSettings/index.jsx

@@ -1,3 +1,6 @@
+// Gamepad Mapping Settings
+// Purpose: Defines the Gamepad Mapping Settings module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import GamepadMappingSettingsContent from './GamepadMappingSettingsContent.jsx';
 
 export default GamepadMappingSettingsContent;

webui/src/components/HelpContentView/index.jsx

@@ -1,3 +1,6 @@
+// Help Content View
+// Purpose: Defines the Help Content View module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo } from 'react';
 import { formatKeyLabel } from '../../controls/keymapUtils.js';
 import { getHelpContent } from '../../help/content.js';

webui/src/components/HelpOverlay/index.jsx

@@ -1,3 +1,6 @@
+// Help Overlay
+// Purpose: Defines the Help Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useControlSystem } from '../../controls/index.js';
 import HelpContentView from '../HelpContentView/index.jsx';
 

webui/src/components/HelpPanel/index.jsx

@@ -1,3 +1,6 @@
+// Help Panel
+// Purpose: Defines the Help Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useControlSystem } from '../../controls/index.js';
 import HelpContentView from '../HelpContentView/index.jsx';
 

webui/src/components/HomeAssistantControls/index.jsx

@@ -1,3 +1,6 @@
+// Home Assistant Controls
+// Purpose: Defines the Home Assistant Controls module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useSessionActions, useSessionSelector } from '../../context/SessionContext.jsx';
 import { useControlSystem } from '../../controls/index.js';

webui/src/components/HornControl/index.jsx

@@ -1,3 +1,6 @@
+// Horn Control
+// Purpose: Defines the Horn Control module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useSettingsNamespace } from '../../settings/index.js';
 import { HORN_SETTINGS_DEFAULTS } from '../../settings/namespaces.js';

webui/src/components/KeymapSettings/index.jsx

@@ -1,3 +1,6 @@
+// Keymap Settings
+// Purpose: Defines the Keymap Settings module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo, useState, useEffect, useCallback } from 'react';
 import { useControlSystem } from '../../controls/index.js';
 import { DEFAULT_KEYMAP } from '../../controls/constants.js';

webui/src/components/LogPanel/index.jsx

@@ -1,3 +1,6 @@
+// Log Panel
+// Purpose: Defines the Log Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useSessionSelector } from '../../context/SessionContext.jsx';
 
 export default function LogPanel() {

webui/src/components/MobileControls/FloatingJoystick.jsx

@@ -1,4 +1,6 @@
-// Floating on-screen joystick used for mobile driving.
+// Floating Joystick
+// Purpose: Defines the Floating Joystick module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { clampUnit } from '../../controls/controlMath.js';
 

webui/src/components/MobileControls/MobileAuxButton.jsx

@@ -1,4 +1,6 @@
-// Hold-to-run aux motor button for mobile controls.
+// Mobile Aux Button
+// Purpose: Defines the Mobile Aux Button module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function MobileAuxButton({ id, label, values, color, disabled, onPress, onRelease }) {
   return (
     <button

webui/src/components/MobileControls/MobileControlsContent.jsx

@@ -1,4 +1,6 @@
-// Mobile controls layout and interaction wiring.
+// Mobile Controls Content
+// Purpose: Defines the Mobile Controls Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useCallback, useEffect, useRef } from 'react';
 import { useControlSystem } from '../../controls/index.js';
 import { clampUnit } from '../../controls/controlMath.js';

webui/src/components/MobileControls/constants.js

@@ -1,4 +1,6 @@
-// Mobile controls constants.
+// constants
+// Purpose: Defines the constants module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export const SOURCE = 'mobile-joystick';
 export const JOYSTICK_RADIUS = 80;
 export const JOYSTICK_SMOOTHING = 0.15;

webui/src/components/MobileControls/index.jsx

@@ -1,3 +1,6 @@
+// Mobile Controls
+// Purpose: Defines the Mobile Controls module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import MobilePortraitControls, { MobileActionsColumn, MobileDriveColumn } from './MobileControlsContent.jsx';
 
 export { MobileActionsColumn, MobileDriveColumn };

webui/src/components/ModeGateOverlay/index.jsx

@@ -1,3 +1,6 @@
+// Mode Gate Overlay
+// Purpose: Defines the Mode Gate Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import AuthPanel from '../AuthPanel/index.jsx';
 import { useSessionSelector } from '../../context/SessionContext.jsx';

webui/src/components/NicknameForm/index.jsx

@@ -1,3 +1,6 @@
+// Nickname Form
+// Purpose: Defines the Nickname Form module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import { useSettingsNamespace } from '../../settings/index.js';

webui/src/components/NightVisionControl/index.jsx

@@ -1,3 +1,6 @@
+// Night Vision Control
+// Purpose: Defines the Night Vision Control module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 
 function isBoolean(value) {

webui/src/components/OvercurrentLimiterPanel/index.jsx

@@ -1,3 +1,6 @@
+// Overcurrent Limiter Panel
+// Purpose: Defines the Overcurrent Limiter Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo } from 'react';
 import { useControlSystem } from '../../controls/index.js';
 import { OVERCURRENT_GROUPS } from '../../controls/overcurrentLimiter.js';

webui/src/components/RawUserPilePanel/index.jsx

@@ -1,3 +1,6 @@
+// Raw User Pile Panel
+// Purpose: Defines the Raw User Pile Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import NicknameForm from '../NicknameForm/index.jsx';

webui/src/components/ReplaySourcesPanel/index.jsx

@@ -1,3 +1,6 @@
+// Replay Sources Panel
+// Purpose: Defines the Replay Sources Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import { useSettingsNamespace } from '../../settings/index.js';

webui/src/components/RewardRunOverlay/index.jsx

@@ -1,3 +1,6 @@
+// Reward Run Overlay
+// Purpose: Defines the Reward Run Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useRef, useState } from 'react';
 import { useSocket } from '../../context/SocketContext.jsx';
 import { useSettingsNamespace } from '../../settings/index.js';

webui/src/components/RightPaneTabs/index.jsx

@@ -1,3 +1,6 @@
+// Right Pane Tabs
+// Purpose: Defines the Right Pane Tabs module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import RoomCameraPanel from '../RoomCameraPanel/index.jsx';
 import HomeAssistantControls from '../HomeAssistantControls/index.jsx';
 import SettingsPanel from '../SettingsPanel/index.jsx';

webui/src/components/RoomCameraFeed/index.jsx

@@ -1,3 +1,6 @@
+// Room Camera Feed
+// Purpose: Defines the Room Camera Feed module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 
 export default function RoomCameraFeed({ feed, label }) {

webui/src/components/RoomCameraPanel/index.jsx

@@ -1,3 +1,6 @@
+// Room Camera Panel
+// Purpose: Defines the Room Camera Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import { useSettingsNamespace } from '../../settings/index.js';

webui/src/components/RoverQueuesPanel/index.jsx

@@ -1,3 +1,6 @@
+// Rover Queues Panel
+// Purpose: Defines the Rover Queues Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import { useSessionActions, useSessionSelector } from '../../context/SessionContext.jsx';
 import { roverNameChromeStyle } from '../../lib/roverColor.js';

webui/src/components/RoverRoster/index.jsx

@@ -1,3 +1,6 @@
+// Rover Roster
+// Purpose: Defines the Rover Roster module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { roverNameChromeStyle } from '../../lib/roverColor.js';
 
 function classNames(...values) {

webui/src/components/SessionSnapshot/index.jsx

@@ -1,3 +1,6 @@
+// Session Snapshot
+// Purpose: Defines the Session Snapshot module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 

webui/src/components/SettingsPanel/index.jsx

@@ -1,3 +1,6 @@
+// Settings Panel
+// Purpose: Defines the Settings Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo } from 'react';
 import { useControlSystem } from '../../controls/index.js';
 import AuthPanel from '../AuthPanel/index.jsx';

webui/src/components/SocialButton/index.jsx

@@ -1,3 +1,6 @@
+// Social Button
+// Purpose: Defines the Social Button module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect } from 'react';
 import { FaBook, FaCoffee, FaCrown, FaDiscord, FaLink } from 'react-icons/fa';
 

webui/src/components/SocialButtonsGrid/index.jsx

@@ -1,3 +1,6 @@
+// Social Buttons Grid
+// Purpose: Defines the Social Buttons Grid module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useSession } from '../../context/SessionContext.jsx';
 import SocialButton from '../SocialButton/index.jsx';
 

webui/src/components/SocketLogPanel/index.jsx

@@ -1,3 +1,6 @@
+// Socket Log Panel
+// Purpose: Defines the Socket Log Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import { useSocket } from '../../context/SocketContext.jsx';
 

webui/src/components/Tabs/index.jsx

@@ -1,3 +1,6 @@
+// Tabs
+// Purpose: Defines the Tabs module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { createContext, useCallback, useContext, useMemo, useState, useEffect } from 'react';
 
 const TabsContext = createContext(null);

webui/src/components/TelemetryPanel/index.jsx

@@ -1,3 +1,6 @@
+// Telemetry Panel
+// Purpose: Defines the Telemetry Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo } from 'react';
 import { useSessionSelector } from '../../context/SessionContext.jsx';
 import { useTelemetryFrame } from '../../context/TelemetryContext.jsx';

webui/src/components/TopDownMap/TopDownMapContent.jsx

@@ -1,4 +1,6 @@
-// Top-down rover telemetry visual map.
+// Top Down Map Content
+// Purpose: Defines the Top Down Map Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 import { buildSegments } from './helpers.js';
 import {

webui/src/components/TopDownMap/helpers.js

@@ -1,4 +1,6 @@
-// Geometry and color helpers for top-down rover sensor map.
+// helpers
+// Purpose: Defines the helpers module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export function clamp01(value) {
   return Math.max(0, Math.min(1, value));
 }

webui/src/components/TopDownMap/index.jsx

@@ -1,3 +1,6 @@
+// Top Down Map
+// Purpose: Defines the Top Down Map module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import TopDownMapContent from './TopDownMapContent.jsx';
 
 export default TopDownMapContent;

webui/src/components/TopDownMap/visuals.jsx

@@ -1,4 +1,6 @@
-// SVG primitives for top-down rover map rendering.
+// visuals
+// Purpose: Defines the visuals module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 import { clamp01, currentColor, describeArc, lightBumpColor, cliffColor, polarToCartesian, toRad } from './helpers.js';
 

webui/src/components/TurnAlertListener/index.jsx

@@ -1,3 +1,6 @@
+// Turn Alert Listener
+// Purpose: Defines the Turn Alert Listener module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useRef } from 'react';
 import turnSound from '../../assets/turn_alert.mp3';
 import { useSessionActions, useSessionSelector } from '../../context/SessionContext.jsx';

webui/src/components/UserListPanel/index.jsx

@@ -1,3 +1,6 @@
+// User List Panel
+// Purpose: Defines the User List Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState, useCallback } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import NicknameForm from '../NicknameForm/index.jsx';

webui/src/components/VideoTile/HudChatInput.jsx

@@ -1,4 +1,6 @@
-// Inline HUD chat input for driver speech messages.
+// Hud Chat Input
+// Purpose: Defines the Hud Chat Input module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo, useState } from 'react';
 import { useChat } from '../../context/ChatContext.jsx';
 import { useSessionSelector } from '../../context/SessionContext.jsx';

webui/src/components/VideoTile/HudOverlay.jsx

@@ -1,4 +1,6 @@
-// Telemetry HUD and map overlay for VideoTile.
+// Hud Overlay
+// Purpose: Defines the Hud Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 import TopDownMap from '../TopDownMap/index.jsx';
 import { roverNameChromeStyle } from '../../lib/roverColor.js';

webui/src/components/VideoTile/LightBumpBars.jsx

@@ -1,4 +1,6 @@
-// Light bump signal bars used under the tile HUD.
+// Light Bump Bars
+// Purpose: Defines the Light Bump Bars module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 
 export default function LightBumpBars({ sensors }) {

webui/src/components/VideoTile/LowBatteryOverlay.jsx

@@ -1,4 +1,6 @@
-// Low battery warning overlay.
+// Low Battery Overlay
+// Purpose: Defines the Low Battery Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 
 export default function LowBatteryOverlay({ battery, compact = false }) {

webui/src/components/VideoTile/OvercurrentOverlay.jsx

@@ -1,4 +1,6 @@
-// Overcurrent warning overlay.
+// Overcurrent Overlay
+// Purpose: Defines the Overcurrent Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 import { OVERCURRENT_LABELS } from './constants.js';
 

webui/src/components/VideoTile/TurnCueOverlay.jsx

@@ -1,4 +1,6 @@
-// Turn cue overlay shown to active drivers.
+// Turn Cue Overlay
+// Purpose: Defines the Turn Cue Overlay module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import React from 'react';
 
 export default function TurnCueOverlay({

webui/src/components/VideoTile/constants.js

@@ -1,4 +1,6 @@
-// VideoTile timing and threshold constants.
+// constants
+// Purpose: Defines the constants module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export const RESTART_DELAY_MS = 2000;
 export const UNMUTE_RETRY_MS = 3000;
 export const AUDIO_RETRY_MS = 3000;

webui/src/components/VideoTile/index.jsx

@@ -1,3 +1,6 @@
+// Video Tile
+// Purpose: Defines the Video Tile module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { WhepPlayer } from '../../lib/whepPlayer.js';
 import { useHudMapSetting } from '../../hooks/useHudMapSetting.js';

webui/src/components/VipPanel/index.jsx

@@ -1,3 +1,6 @@
+// Vip Panel
+// Purpose: Defines the Vip Panel module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import { useSettingsNamespace } from '../../settings/index.js';

webui/src/components/vip/VipAudioUploadCard/KeyPill.jsx

@@ -1,4 +1,6 @@
-// Keybinding label pill for PTT hints.
+// Key Pill
+// Purpose: Defines the Key Pill module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function KeyPill({ label }) {
   if (!label) return null;
   return <span className="rounded border border-white/40 px-1 text-[0.7rem] text-white">{label}</span>;

webui/src/components/vip/VipAudioUploadCard/StatusIndicator.jsx

@@ -1,4 +1,6 @@
-// Compact status tile used throughout VIP audio card.
+// Status Indicator
+// Purpose: Defines the Status Indicator module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function StatusIndicator({ label, active, detail = '' }) {
   return (
     <div

webui/src/components/vip/VipAudioUploadCard/VipAudioUploadCardContent.jsx

@@ -1,3 +1,6 @@
+// Vip Audio Upload Card Content
+// Purpose: Defines the Vip Audio Upload Card Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { fieldClass } from '../constants.js';
 import { useControlSystem } from '../../../controls/index.js';

webui/src/components/vip/VipAudioUploadCard/audioCodec.js

@@ -1,4 +1,6 @@
-// PCM/WAV helpers for clip-mode recording payloads.
+// audio Codec
+// Purpose: Defines the audio Codec module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export function mergeFloatChunks(chunks) {
   const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
   const merged = new Float32Array(total);

webui/src/components/vip/VipAudioUploadCard/base64.js

@@ -1,4 +1,6 @@
-// Base64 and auth helpers for upload and WHIP requests.
+// base64
+// Purpose: Defines the base64 module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export function bytesToBase64(bytes) {
   let binary = '';
   const chunkSize = 0x8000;

webui/src/components/vip/VipAudioUploadCard/constants.js

@@ -1,4 +1,6 @@
-// VIP audio upload/mic forwarding constants.
+// constants
+// Purpose: Defines the constants module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export const MAX_UPLOAD_BYTES = 8 * 1024 * 1024;
 export const TARGET_SAMPLE_RATE = 16000;
 export const RTC_CONFIG = {

webui/src/components/vip/VipAudioUploadCard/index.jsx

@@ -1,3 +1,6 @@
+// Vip Audio Upload Card
+// Purpose: Defines the Vip Audio Upload Card module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import VipAudioUploadCardContent from './VipAudioUploadCardContent.jsx';
 
 export default VipAudioUploadCardContent;

webui/src/components/vip/VipAudioUploadCard/whipTransport.js

@@ -1,4 +1,6 @@
-// WHIP/WebRTC transport helpers for microphone forwarding.
+// whip Transport
+// Purpose: Defines the whip Transport module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export function waitForIceGatheringComplete(pc, timeoutMs = 1500) {
   return new Promise((resolve) => {
     if (!pc || pc.iceGatheringState === 'complete') {

webui/src/components/vip/VipIdentityCard.jsx

@@ -1,3 +1,6 @@
+// Vip Identity Card
+// Purpose: Defines the Vip Identity Card module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useState } from 'react';
 import { fieldClass, flowWrapClass, innerFlowClass, maskKey } from './constants.js';
 

webui/src/components/vip/VipNeatoCard.jsx

@@ -1,3 +1,6 @@
+// Vip Neato Card
+// Purpose: Defines the Vip Neato Card module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo, useState } from 'react';
 
 function normalizeState(value) {

webui/src/components/vip/VipPrivateRoverAccessCard.jsx

@@ -1,3 +1,6 @@
+// Vip Private Rover Access Card
+// Purpose: Defines the Vip Private Rover Access Card module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useMemo, useState } from 'react';
 import { flowWrapClass, innerFlowClass } from './constants.js';
 

webui/src/components/vip/VipVerificationCard.jsx

@@ -1,3 +1,6 @@
+// Vip Verification Card
+// Purpose: Defines the Vip Verification Card module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useState } from 'react';
 import NicknameForm from '../NicknameForm/index.jsx';
 import { flowWrapClass, innerFlowClass, fieldClass } from './constants.js';

webui/src/components/vip/constants.js

@@ -1,3 +1,6 @@
+// constants
+// Purpose: Defines the constants module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export const COOKIE_KEY_REGEX = /^cu_[a-f0-9]{32}$/;
 
 export const fieldClass = 'field-input w-full max-w-sm text-left focus:ring-emerald-500';

webui/src/mini/MiniSummaryApp/MiniSummaryAppRoot.jsx

@@ -1,4 +1,6 @@
-// Top-level mini summary app shell with hard-refresh timer and alerts.
+// Mini Summary App Root
+// Purpose: Defines the Mini Summary App Root module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect } from 'react';
 import AlertFeed from '../../components/AlertFeed/index.jsx';
 import MiniSummaryContent from './MiniSummaryContent.jsx';

webui/src/mini/MiniSummaryApp/MiniSummaryContent.jsx

@@ -1,4 +1,6 @@
-// Main mini summary screen composition and rotation logic.
+// Mini Summary Content
+// Purpose: Defines the Mini Summary Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useMemo, useState } from 'react';
 import { useSession } from '../../context/SessionContext.jsx';
 import { useTelemetryFrames } from '../../context/TelemetryContext.jsx';

webui/src/mini/MiniSummaryApp/components/AutoFitText.jsx

@@ -1,4 +1,6 @@
-// Auto-fitting single-line text component for mini summary layout.
+// Auto Fit Text
+// Purpose: Defines the Auto Fit Text module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useLayoutEffect, useRef, useState } from 'react';
 
 export default function AutoFitText({ children, className = '', maxSize = 1000, minSize = 14, style = undefined }) {

webui/src/mini/MiniSummaryApp/components/FitViewportFrame.jsx

@@ -1,4 +1,6 @@
-// 4:3 viewport fitting frame for active mini-summary video.
+// Fit Viewport Frame
+// Purpose: Defines the Fit Viewport Frame module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export default function FitViewportFrame({ children }) {
   return (
     <div className="flex h-full w-full items-center justify-start overflow-hidden bg-black">

webui/src/mini/MiniSummaryApp/components/InfoColumn.jsx

@@ -1,4 +1,6 @@
-// Rover information and optional preview column for mini summary UI.
+// Info Column
+// Purpose: Defines the Info Column module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import VideoTile from '../../../components/VideoTile/index.jsx';
 import BatteryBar from '../../../components/BatteryBar/index.jsx';
 import { roverNameChromeStyle } from '../../../lib/roverColor.js';

webui/src/mini/MiniSummaryApp/constants.js

@@ -1,3 +1,5 @@
-// Mini summary app timing constants.
+// constants
+// Purpose: Defines the constants module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 export const ROTATE_MS = 20000;
 export const HARD_REFRESH_MS = 1 * 60 * 60 * 1000;

webui/src/mini/MiniSummaryApp/utils.js

@@ -1,4 +1,6 @@
-// Mini summary app session/telemetry formatting utilities.
+// utils
+// Purpose: Defines the utils module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { buildBatteryVisual } from '../../lib/battery.js';
 
 export function formatDriverLabel({ roverId, session }) {

webui/src/spectate/SpectatorApp/SpectatorAppRoot.jsx

@@ -1,4 +1,6 @@
-// Spectator app compatibility root.
+// Spectator App Root
+// Purpose: Defines the Spectator App Root module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import SpectatorContent from './SpectatorContent.jsx';
 
 export default function SpectatorAppRoot() {

webui/src/spectate/SpectatorApp/SpectatorContent.jsx

@@ -1,4 +1,6 @@
-// Main spectator screen layout and feed wiring.
+// Spectator Content
+// Purpose: Defines the Spectator Content module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useSession } from '../../context/SessionContext.jsx';
 import { useTelemetryFrames } from '../../context/TelemetryContext.jsx';
 import { useVideoRequests } from '../../hooks/useVideoRequests.js';

webui/src/spectate/SpectatorApp/components/LogsRow.jsx

@@ -1,4 +1,6 @@
-// Log panel wrapper row for spectator layout.
+// Logs Row
+// Purpose: Defines the Logs Row module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import LogPanel from '../../../components/LogPanel/index.jsx';
 
 export default function LogsRow({ className = '' }) {

webui/src/spectate/SpectatorApp/components/RoverRow.jsx

@@ -1,4 +1,6 @@
-// Rover grid row for spectator view.
+// Rover Row
+// Purpose: Defines the Rover Row module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import RoverSpectatorCard from './RoverSpectatorCard.jsx';
 
 export default function RoverRow({ roster, frames, videoSources, snapshotFeeds, audioSources, session, canSpectateVideo }) {

webui/src/spectate/SpectatorApp/components/RoverSpectatorCard.jsx

@@ -1,4 +1,6 @@
-// Single rover spectator card containing live/snapshot tile and HUD.
+// Rover Spectator Card
+// Purpose: Defines the Rover Spectator Card module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import VideoTile from '../../../components/VideoTile/index.jsx';
 import { formatDriverLabel } from '../utils.js';
 

webui/src/spectate/SpectatorApp/components/SecondaryRow.jsx

@@ -1,4 +1,6 @@
-// Secondary panel row showing room cameras.
+// Secondary Row
+// Purpose: Defines the Secondary Row module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import RoomCameraPanel from '../../../components/RoomCameraPanel/index.jsx';
 
 export default function SecondaryRow() {

webui/src/spectate/SpectatorApp/hooks/usePortraitLayout.js

@@ -1,4 +1,6 @@
-// Detect portrait-oriented viewport layout mode for spectator UI.
+// use Portrait Layout
+// Purpose: Defines the use Portrait Layout module and the local helpers/components used in this file.
+// Scope: Keeps behavior unchanged while isolating this concern into a clear, single-responsibility unit.
 import { useEffect, useState } from 'react';
 
 export default function usePortraitLayout() {