chore: updating comments across package

.cursor/rules/comment-standards.mdc

@@ -0,0 +1,112 @@
+---
+description: Comment and documentation standards for all source files
+alwaysApply: true
+---
+
+# Comment Standards
+
+## File Structure (top to bottom)
+
+1. **Copyright header** — first line of every file
+2. **Module docstring** — brief JSDoc (`/** */`) or Python docstring (`"""`) explaining the file's purpose
+3. **Imports**
+4. **Section dividers** (optional, for files >100 lines with distinct logical groups)
+5. **Code with inline comments**
+
+## TypeScript / JavaScript
+
+### Copyright Header
+
+```typescript
+// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+```
+
+### Module Docstring
+
+Every file gets a JSDoc block after the copyright line describing purpose and scope:
+
+```typescript
+/**
+ * Manages the lifecycle of loaded Cesium resources (GeoJSON, imagery).
+ * Provides React context for adding, removing, toggling, and zooming to resources.
+ */
+```
+
+### Exported Functions — Full JSDoc
+
+```typescript
+/**
+ * Loads an image from S3 into Cesium, downloading it first if not cached locally.
+ *
+ * @param cesium - Cesium viewer wrapper.
+ * @param bucket - S3 bucket name.
+ * @returns The added imagery layer, or undefined if credentials expired.
+ */
+export async function loadImageInCesium(cesium: ..., bucket: string): Promise<ImageryLayer | undefined> {
+```
+
+### Internal Functions — Concise JSDoc
+
+```typescript
+/** Stops and removes a Docker container by name. */
+function stopAndRemoveContainer(containerName: string): void {
+```
+
+### Exported Interfaces/Types — Brief JSDoc
+
+```typescript
+/** A loaded GeoJSON feature collection displayed on the Cesium globe. */
+export interface FeatureCollectionResource { ... }
+```
+
+### Section Dividers
+
+Use in long files with distinct logical groups:
+
+```typescript
+/* ── Section Title ───────────────────────────────────────────────────── */
+```
+
+### Inline Comments
+
+- Explain **why**, not **what**
+- Use `//` style
+- Place on the line above the code, not at end of line (unless very short)
+
+### TODOs
+
+```typescript
+// TODO: description of work to be done
+```
+
+## Python
+
+### Copyright + Module Docstring
+
+```python
+# Copyright 2025-2026 Amazon.com, Inc. or its affiliates.
+
+"""
+Brief description of the module.
+
+Extended description if needed.
+"""
+```
+
+### Function Docstrings — Sphinx-style
+
+```python
+def get_extents(dataset_path: str) -> dict:
+    """
+    Returns the geographic extents of the given raster dataset.
+
+    :param dataset_path: Path to the raster dataset.
+    :return: Dictionary with keys 'north', 'south', 'east', 'west'.
+    """
+```
+
+## What NOT to Comment
+
+- Do not restate obvious code (`// get the layers` before `const layers = ...`)
+- Do not wrap TODOs in `/** */` blocks — use `//` line comments
+- Do not add `@param` for internal helpers with obvious signatures

electron/electron-env.d.ts

@@ -1,3 +1,7 @@
+// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+
+/** Electron environment type declarations for Vite process variables. */
+
 /// <reference types="vite-electron-plugin/electron-env" />
 
 declare namespace NodeJS {

electron/main/index.ts

@@ -1,3 +1,10 @@
+// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+
+/**
+ * Electron main process. Creates the browser window, loads the app,
+ * and manages the application lifecycle.
+ */
+
 import { app, BrowserWindow, shell, ipcMain } from 'electron'
 import { release } from 'node:os'
 import { join } from 'node:path'

electron/main/update.ts

@@ -1,3 +1,10 @@
+// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+
+/**
+ * Electron auto-updater integration. Checks for updates, manages downloads,
+ * and communicates progress to the renderer process via IPC.
+ */
+
 import { app, ipcMain } from 'electron'
 import {
   type ProgressInfo,

electron/preload/index.ts

@@ -1,3 +1,10 @@
+// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+
+/**
+ * Electron preload script. Shows a loading spinner while the app initializes
+ * and removes it when the renderer signals readiness.
+ */
+
 function domReady(condition: DocumentReadyState[] = ['complete', 'interactive']) {
   return new Promise(resolve => {
     if (condition.includes(document.readyState)) {

jest.config.js

@@ -1,5 +1,7 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/** Jest test runner configuration with ts-jest and path alias support. */
+
 /** @type {import('jest').Config} */
 const config = {
   preset: "ts-jest",

scripts/generate_cesium_terrain.py

@@ -1,4 +1,11 @@
-# Copyright 2023-2025 Amazon.com, Inc. or its affiliates.
+# Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+
+"""
+Generate Cesium terrain tiles from GeoTIFF files using Docker-based ctb-tile.
+
+Automates the conversion of raster elevation data into quantized-mesh terrain
+tiles compatible with the CesiumJS viewer.
+"""
 
 import argparse
 import datetime

src/App.tsx

@@ -1,5 +1,7 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/** Root React component that initializes the Cesium viewer and composes the application layout. */
+
 import "./styles.css";
 
 import React, { useState, useEffect, useCallback } from "react";

src/__tests__/cesiumFormatters.test.ts

@@ -1,5 +1,7 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/** Tests for GeoJSON feature property formatting and grouping. */
+
 import { formatFeatureProperties, type PropertyGroup } from "@/utils/cesiumFormatters";
 
 describe("formatFeatureProperties", () => {

src/__tests__/config.test.ts

@@ -1,5 +1,7 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/** Tests for AWS credential error detection logic. */
+
 import { isCredentialError } from "@/config";
 
 describe("isCredentialError", () => {

src/__tests__/handleAwsError.test.ts

@@ -1,5 +1,7 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/** Tests for the shared AWS credential error handler. */
+
 import { handleAwsError } from "@/hooks/useS3Browser";
 
 describe("handleAwsError", () => {

src/__tests__/logger.test.ts

@@ -1,5 +1,7 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/** Tests for the structured logger utility. */
+
 import { logger } from "@/utils/logger";
 
 describe("logger", () => {

src/components/FeaturePopup.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Floating popup that displays feature properties when a GeoJSON feature is clicked.
+ */
+
 import React, { useContext, useEffect, useRef, useState } from "react";
 import { CesiumContext } from "resium";
 import * as Cesium from "cesium";

src/components/ImageRequestStatus.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Animated status card showing image processing request progress and results.
+ */
+
 import React, { useEffect, useState } from "react";
 
 import type { ImageRequestData, ImageRequestState } from "@/types";

src/components/Logo.tsx

@@ -1,4 +1,8 @@
-// Copyright 2023-2025 Amazon.com, Inc. or its affiliates.
+// Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
+
+/**
+ * OSML logo overlay displayed on the globe.
+ */
 
 import React from 'react';
 import './Logo.css';

src/components/OsmlMenu.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Main slide-out panel with action buttons, layer management, and modal triggers.
+ */
+
 import React, { useContext, useState } from "react";
 import { CesiumContext } from "resium";
 

src/components/OsmlTray.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Top-level tray container that positions the OSML menu panel.
+ */
+
 import React from "react";
 
 import OsmlMenu from "@/components/OsmlMenu";

src/components/StatusDisplay.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Wrapper component that conditionally renders the image request status card.
+ */
+
 import React from "react";
 
 import ImageRequestStatus from "@/components/ImageRequestStatus";

src/components/alert/ConfigWarnings.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Auto-dismissing toast stack for AWS configuration warnings detected at startup.
+ */
+
 import { useEffect, useState } from "react";
 import { getConfigWarnings, type ConfigWarning } from "@/config";
 import "./ConfigWarnings.css";

src/components/alert/CredsExpiredAlert.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Toast alert shown when AWS credentials expire, with retry functionality.
+ */
+
 import { useState } from "react";
 import { GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { getAWSCreds, isCredentialError, REGION } from "@/config";

src/components/modal/DarkModal.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Reusable dark-themed modal dialog with header, body, and footer slots.
+ */
+
 import React, { useEffect, useRef } from "react";
 import "./DarkModal.css";
 

src/components/modal/ImageRequestModal.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Modal for submitting image processing requests to the ModelRunner service.
+ */
+
 import React from "react";
 import { Color } from "cesium";
 import { useContext, useEffect, useState } from "react";
@@ -39,9 +43,7 @@ import {
 import ExpandSection from "../ui/ExpandSection";
 import DarkModal from "./DarkModal";
 
-/* -----------------------------------------------
-   Color options
-   ----------------------------------------------- */
+/* ── Color options ───────────────────────────────────────────────────── */
 const COLOR_OPTIONS: LabeledOption[] = [
   { label: "Red", value: Color.RED.toCssColorString() },
   { label: "Orange", value: Color.ORANGE.toCssColorString() },
@@ -54,9 +56,7 @@ const COLOR_OPTIONS: LabeledOption[] = [
   { label: "Fuchsia", value: Color.FUCHSIA.toCssColorString() }
 ];
 
-/* -----------------------------------------------
-   Main Modal Component
-   ----------------------------------------------- */
+/* ── Main Modal Component ───────────────────────────────────────────── */
 const NewRequestModal = ({
   showImageRequestModal,
   setShowImageRequestModal,

src/components/modal/LoadDataModal.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Modal for importing GeoJSON feature collections from S3 or local storage.
+ */
+
 import fs from "fs";
 import { useContext, useState } from "react";
 import { CesiumContext } from "resium";

src/components/modal/LoadImageModal.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Modal for importing imagery from local files or S3 buckets into the globe.
+ */
+
 import fs from "fs";
 import { useContext, useState } from "react";
 import { CesiumContext } from "resium";

src/components/ui/DarkAutosuggest.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Dark-themed autosuggest input with dropdown filtering and keyboard navigation.
+ */
+
 import React, {
   useCallback,
   useEffect,

src/components/ui/DarkFormField.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Dark-themed form field wrapper with label and optional description.
+ */
+
 import React from "react";
 
 interface DarkFormFieldProps {

src/components/ui/DarkInput.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Minimal dark-themed text/number input component.
+ */
+
 import React from "react";
 
 interface DarkInputProps {

src/components/ui/DarkMultiselect.tsx

@@ -1,5 +1,9 @@
 // Copyright 2023-2026 Amazon.com, Inc. or its affiliates.
 
+/**
+ * Custom dark-themed multi-select dropdown with tag display.
+ */
+
 import React, { useEffect, useRef, useState } from "react";
 
 import type { LabeledOption } from "./types";