From 7600d414a282edea7885dcd06a8cc923383312b3 Mon Sep 17 00:00:00 2001
From: Alexander Whitestone <alexpaynex@gmail.com>
Date: Tue, 24 Mar 2026 00:02:42 -0400
Subject: [PATCH] chore: add JSDoc types to all function parameters in app.js

- Added @returns JSDoc to buildConstellationLines() and animate()
- Added inline @type annotations to all callback parameters:
  - MouseEvent for mousemove handler
  - CustomEvent for player-joined, player-left, chat-message handlers
  - HTMLElement for querySelectorAll forEach callbacks
  - {j: number, dist: number} for neighbors.sort comparator

Fixes #144

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app.js | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/app.js b/app.js
index 6e85528..a934b10 100644
--- a/app.js
+++ b/app.js
@@ -61,6 +61,10 @@ scene.add(stars);
 
 // === CONSTELLATION LINES ===
 // Connect nearby stars with faint lines, limited to avoid clutter
+/**
+ * Builds constellation line segments connecting nearby stars.
+ * @returns {THREE.LineSegments}
+ */
 function buildConstellationLines() {
   const linePositions = [];
   const MAX_CONNECTIONS_PER_STAR = 3;
@@ -80,7 +84,7 @@ function buildConstellationLines() {
     }
 
     // Sort by distance and connect closest ones
-    neighbors.sort((a, b) => a.dist - b.dist);
+    neighbors.sort((/** @type {{j: number, dist: number}} */ a, /** @type {{j: number, dist: number}} */ b) => a.dist - b.dist);
     const toConnect = neighbors.slice(0, MAX_CONNECTIONS_PER_STAR - connectionCount[i]);
 
     for (const { j } of toConnect) {
@@ -114,7 +118,7 @@ let mouseY = 0;
 let targetRotX = 0;
 let targetRotY = 0;
 
-document.addEventListener('mousemove', (e) => {
+document.addEventListener('mousemove', (/** @type {MouseEvent} */ e) => {
   mouseX = (e.clientX / window.innerWidth - 0.5) * 2;
   mouseY = (e.clientY / window.innerHeight - 0.5) * 2;
 });
@@ -129,6 +133,10 @@ window.addEventListener('resize', () => {
 // === ANIMATION LOOP ===
 const clock = new THREE.Clock();
 
+/**
+ * Main animation loop — called each frame via requestAnimationFrame.
+ * @returns {void}
+ */
 function animate() {
   requestAnimationFrame(animate);
   const elapsed = clock.getElapsedTime();
@@ -164,10 +172,10 @@ document.getElementById('debug-toggle').addEventListener('click', () => {
   if (debugMode) {
     // Example: Visualize all collision boxes and light sources
     // Replace with actual logic when available
-    document.querySelectorAll('.collision-box').forEach(el => el.style.outline = '2px solid red');
-    document.querySelectorAll('.light-source').forEach(el => el.style.outline = '2px dashed yellow');
+    document.querySelectorAll('.collision-box').forEach((/** @type {HTMLElement} */ el) => el.style.outline = '2px solid red');
+    document.querySelectorAll('.light-source').forEach((/** @type {HTMLElement} */ el) => el.style.outline = '2px dashed yellow');
   } else {
-    document.querySelectorAll('.collision-box, .light-source').forEach(el => {
+    document.querySelectorAll('.collision-box, .light-source').forEach((/** @type {HTMLElement} */ el) => {
       el.style.outline = 'none';
     });
   }
@@ -178,15 +186,15 @@ import { wsClient } from './ws-client.js';
 
 wsClient.connect();
 
-window.addEventListener('player-joined', (event) => {
+window.addEventListener('player-joined', (/** @type {CustomEvent} */ event) => {
   console.log('Player joined:', event.detail);
 });
 
-window.addEventListener('player-left', (event) => {
+window.addEventListener('player-left', (/** @type {CustomEvent} */ event) => {
   console.log('Player left:', event.detail);
 });
 
-window.addEventListener('chat-message', (event) => {
+window.addEventListener('chat-message', (/** @type {CustomEvent} */ event) => {
   console.log('Chat message:', event.detail);
 });
 
-- 
2.43.0