Merge pull request #32 from Pandipipas/add-human-like-comments-to-key-files

Add human-style comments to key Electron and NodeCG flows

src/main/config/runtime-config.ts

@@ -15,6 +15,7 @@ const MIN_TCP_PORT = 1;
 const MAX_TCP_PORT = 65535;
 
 export function getRuntimeConfig(): AppRuntimeConfig {
+  // Centralized defaults keep local development and packaged builds consistent.
   return {
     title: getEnv("SCOREKO_APP_TITLE", "Scoreko"),
     userModelId: getEnv("SCOREKO_APP_USER_MODEL_ID", "com.scoreko.desktop"),
@@ -49,6 +50,7 @@ export function parseEnvInt(name: string, fallback: number): number {
 }
 
 export function parseEnvIntInRange(name: string, fallback: number, min: number, max: number): number {
+  // We throw here instead of silently coercing to avoid hidden misconfiguration in production.
   const rawValue = process.env[name];
   if (!rawValue) {
     return fallback;

src/main/main.ts

@@ -31,6 +31,7 @@ let loadingWindow: BrowserWindow | null = null;
 let shutdownState: AppShutdownState = "running";
 
 async function launchApplication(): Promise<void> {
+  // We create both windows early so startup feels instant while NodeCG is booting in the background.
   mainWindow = createMainWindow({ appConfig, rootPath, mainDashboardUrl });
   loadingWindow = createLoadingWindow({ appConfig, rootPath });
 
@@ -53,6 +54,7 @@ async function launchApplication(): Promise<void> {
 
   await mainWindow.loadURL(mainDashboardUrl);
 
+  // Keep the loading overlay visible for a minimum amount of time to avoid abrupt flashes.
   const remainingLoadingDelay = getRemainingDelayMs(appConfig.loadDelayMs, loadingShownAt);
   if (remainingLoadingDelay > 0) {
     await sleep(remainingLoadingDelay);
@@ -126,6 +128,7 @@ app.on("before-quit", (event) => {
     return;
   }
 
+  // Block the default quit flow until we ask NodeCG to stop cleanly.
   event.preventDefault();
 
   stopNodecgGracefully().finally(() => {

src/main/nodecg/process-manager.ts

@@ -53,6 +53,7 @@ export function createNodecgProcessManager({
   let lastStderrLine: string | null = null;
 
   const startNodecgProcess = async (): Promise<ChildProcess> => {
+    // Fail fast with actionable errors before spawning child processes.
     validateNodecgInstall(
       nodecgRootPath,
       appConfig.bundleName,
@@ -107,6 +108,7 @@ export function createNodecgProcessManager({
   };
 
   const waitForNodecgReady = async (startTime: number): Promise<void> => {
+    // Poll the local NodeCG URL until it answers or we hit the configured timeout.
     while (Date.now() - startTime < appConfig.startupTimeoutMs) {
       if (!nodecgProcess) {
         const exitDetails = lastExit
@@ -140,6 +142,7 @@ export function createNodecgProcessManager({
   };
 
   const stopNodecgProcessGracefully = (): Promise<void> => {
+    // Reuse the same stop promise to avoid sending multiple kill signals during app shutdown.
     if (stopNodecgPromise) {
       return stopNodecgPromise;
     }
@@ -267,6 +270,7 @@ function hasReadWriteAccess(candidatePath: string): boolean {
 
 function probePortAvailable(port: number): Promise<boolean> {
   return new Promise((resolve) => {
+    // A successful TCP connection means some process is already listening on the port.
     const socket = net.createConnection({ host: "127.0.0.1", port });
     let resolved = false;