comments and descriptions

2026-09-15 17:12:59 -04:00 · 2026-04-28 19:39:13 -04:00
parent 07ad9ab253
commit f13b85109e
101 changed files with 303 additions and 43 deletions
@@ -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 (
@@ -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';
@@ -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';
@@ -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 = [] }) {
@@ -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;
@@ -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 || {};
@@ -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';
@@ -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';

@@ -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;
@@ -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';
@@ -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,
@@ -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) {
@@ -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';

@@ -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';
@@ -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 }) {
@@ -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';

@@ -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';

@@ -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';
@@ -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';
@@ -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 (
@@ -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';
@@ -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';
@@ -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 }) {
@@ -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 = [
@@ -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) {
@@ -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;
@@ -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';
@@ -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';

@@ -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';

@@ -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';
@@ -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';
@@ -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';
@@ -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() {
@@ -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';

@@ -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
@@ -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';
@@ -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;
@@ -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 };
@@ -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';
@@ -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';
@@ -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) {
@@ -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';
@@ -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';
@@ -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';
@@ -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';
@@ -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';
@@ -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 }) {
@@ -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';
@@ -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';
@@ -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) {
@@ -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';

@@ -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';
@@ -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';

@@ -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';

@@ -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';

@@ -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);
@@ -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';
@@ -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 {
@@ -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));
 }
@@ -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;
@@ -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';

@@ -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';
@@ -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';
@@ -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';
@@ -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';
@@ -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 }) {
@@ -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 }) {
@@ -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';

@@ -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({
@@ -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;
@@ -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';
@@ -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';
@@ -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>;
@@ -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
@@ -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';
@@ -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);
@@ -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;
@@ -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 = {
@@ -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;
@@ -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') {
@@ -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';

@@ -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) {
@@ -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';

@@ -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';
@@ -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';
@@ -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';
@@ -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';
@@ -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 }) {
@@ -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">
@@ -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';
@@ -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;
@@ -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 }) {
@@ -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() {
@@ -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';
@@ -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 = '' }) {
@@ -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 }) {
@@ -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';

@@ -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() {
@@ -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() {
@@ -1,4 +1,6 @@
-// Spectator app display formatting helpers.
+// 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.
 export function formatDriverLabel({ roverId, session }) {
  const activeDriverId = session?.activeDrivers?.[roverId] || null;
  const user = (session?.users || []).find((entry) => entry.socketId === activeDriverId);