feat: error handling, logging, analytics, OG tags, and sticky sidebar (#44)

## Summary - Add comprehensive try/catch error handling across all API routes, middleware, and the Hono global error handler, piping every unhandled error to the `@nhcarrigan/logger` service to prevent silent crashes and unhandled Promise rejections - Add a `logError` utility on the frontend that forwards errors through the overridden `console.error` to the backend telemetry endpoint; apply it to every silent `catch {}` block in the game context, sound, notification, and clipboard utilities, and wrap the React tree in an `ErrorBoundary` - Add Plausible analytics, Open Graph + Twitter Card meta tags, Tree-Nation widget, and Google Ads to `index.html` - Make the game sidebar sticky with a `--resource-bar-height` CSS custom property offset so it stays viewport-height without overlapping the resource bar; reset sticky behaviour in the mobile responsive override ## Test plan - [ ] Lint passes: `pnpm lint` - [ ] Build passes: `pnpm build` - [ ] Verify errors thrown in API routes appear in the logger service rather than crashing the process - [ ] Verify frontend errors appear in the `/api/fe/error` backend log - [ ] Verify Open Graph tags render correctly when sharing the URL - [ ] Verify Plausible analytics fires on page load - [ ] Verify Tree-Nation badge renders in the sidebar - [ ] Verify sidebar stays fixed while the main content scrolls on desktop - [ ] Verify mobile layout is unaffected ✨ This issue was created with help from Hikari~ 🌸 Reviewed-on: #44 Co-authored-by: Hikari <hikari@nhcarrigan.com> Co-committed-by: Hikari <hikari@nhcarrigan.com>
2026-03-09 19:54:42 -07:00
parent 11e97325cb
commit a36c8e72a5
47 changed files with 2733 additions and 1724 deletions
@@ -0,0 +1,70 @@
+/**
+ * @file React Error Boundary for catching unhandled render-time errors.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { logError } from "../utils/logError.js";
+
+interface ErrorBoundaryProperties {
+  readonly children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+/**
+ * Catches unhandled render-time errors in the React tree, logs them to the
+ * backend telemetry service, and renders a fallback UI.
+ */
+class ErrorBoundary extends Component<
+  ErrorBoundaryProperties,
+  ErrorBoundaryState
+> {
+  // eslint-disable-next-line jsdoc/require-jsdoc -- React Error Boundary constructor is standard boilerplate
+  public constructor(properties: ErrorBoundaryProperties) {
+    super(properties);
+    this.state = { hasError: false };
+  }
+
+  /**
+   * Updates state so the next render shows the fallback UI.
+   * @returns The updated error boundary state.
+   */
+  public static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  /**
+   * Logs the error to the backend telemetry service.
+   * @param error - The error that was thrown during render.
+   * @param info - React error info containing the component stack trace.
+   */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- React lifecycle method cannot be static
+  public override componentDidCatch(error: Error, info: ErrorInfo): void {
+    logError("react_error_boundary", error, info.componentStack);
+  }
+
+  /**
+   * Renders the fallback UI when an error is caught, otherwise renders children.
+   * @returns The JSX element.
+   */
+  public override render(): ReactNode {
+    const { hasError } = this.state;
+    const { children } = this.props;
+
+    if (hasError) {
+      return (
+        <div className="error-screen">
+          <p>{"Something went wrong. Please refresh the page."}</p>
+        </div>
+      );
+    }
+
+    return children;
+  }
+}
+
+export { ErrorBoundary };
@@ -14,6 +14,7 @@ import {
  type PublicProfileResponse,
 } from "@elysium/types";
 import { type JSX, useEffect, useState } from "react";
+import { logError } from "../../utils/logError.js";

 interface CharacterPageProperties {
  readonly discordId: string;
@@ -78,12 +79,16 @@ const CharacterPage = ({ discordId }: CharacterPageProperties): JSX.Element => {
  }, [ discordId ]);

  function handleCopy(): void {
-    void navigator.clipboard.writeText(window.location.href).then(() => {
-      setCopied(true);
-      setTimeout(() => {
-        setCopied(false);
-      }, 2000);
-    });
+    void navigator.clipboard.writeText(window.location.href).
+      then(() => {
+        setCopied(true);
+        setTimeout(() => {
+          setCopied(false);
+        }, 2000);
+      }).
+      catch((error_: unknown) => {
+        logError("clipboard_copy", error_);
+      });
  }

  if (error !== null) {
@@ -19,6 +19,7 @@ import {
 import { type ChangeEvent, type JSX, useEffect, useRef, useState } from "react";
 import { updateProfile } from "../../api/client.js";
 import { useGame } from "../../context/gameContext.js";
+import { logError } from "../../utils/logError.js";

 interface EquippedItem {
  name:   string;
@@ -205,12 +206,16 @@ const CharacterSheetPanel = (): JSX.Element => {
  function handleShareClick(): void {
    const discordId = player?.discordId ?? "";
    const url = `${window.location.origin}/character/${discordId}`;
-    void navigator.clipboard.writeText(url).then(() => {
-      setCopied(true);
-      setTimeout(() => {
-        setCopied(false);
-      }, 2000);
-    });
+    void navigator.clipboard.writeText(url).
+      then(() => {
+        setCopied(true);
+        setTimeout(() => {
+          setCopied(false);
+        }, 2000);
+      }).
+      catch((error_: unknown) => {
+        logError("clipboard_copy", error_);
+      });
  }

  function handleNameChange(event: ChangeEvent<HTMLInputElement>): void {
@@ -189,6 +189,7 @@ const GameLayout = (): JSX.Element => {
      <div className="game-main">
        <aside className="game-sidebar">
          <ClickArea />
+          <div id="tree-nation-offset-website" />
          <p className="game-copyright">{"© NHCarrigan"}</p>
        </aside>

@@ -8,6 +8,7 @@
 /* eslint-disable complexity -- Many conditional stat visibility checks */
 import { useEffect, useState, type JSX } from "react";
 import { formatNumber } from "../../utils/format.js";
+import { logError } from "../../utils/logError.js";
 import type { PublicProfileResponse } from "@elysium/types";

 interface ProfilePageProperties {
@@ -52,12 +53,16 @@ const ProfilePage = ({ discordId }: ProfilePageProperties): JSX.Element => {
  }, [ discordId ]);

  function handleCopy(): void {
-    void navigator.clipboard.writeText(window.location.href).then(() => {
-      setCopied(true);
-      setTimeout(() => {
-        setCopied(false);
-      }, 2000);
-    });
+    void navigator.clipboard.writeText(window.location.href).
+      then(() => {
+        setCopied(true);
+        setTimeout(() => {
+          setCopied(false);
+        }, 2000);
+      }).
+      catch((error_: unknown) => {
+        logError("clipboard_copy", error_);
+      });
  }

  if (error !== null) {
@@ -59,6 +59,7 @@ import {
 } from "../engine/tick.js";
 import { updateChallengeProgress } from "../utils/dailyChallenges.js";
 import { formatNumber as formatNumberUtil } from "../utils/format.js";
+import { logError } from "../utils/logError.js";
 import { sendNotification } from "../utils/notification.js";
 import { playSound } from "../utils/sound.js";

@@ -1130,6 +1131,8 @@ export const GameProvider = ({
              ) {
                signatureReference.current = null;
                localStorage.removeItem("elysium_save_signature");
+              } else {
+                logError("auto_save", error_);
              }
            });
        }
@@ -1158,7 +1161,8 @@ export const GameProvider = ({
            }
            await reloadReference.current();
          }).
-          catch(() => {
+          catch((error_: unknown) => {
+            logError("auto_prestige", error_);

            /* Silently ignore — will retry next tick */
          }).
@@ -1200,7 +1204,8 @@ export const GameProvider = ({
              });
              setBattleResult({ bossName, result });
            }).
-            catch(() => {
+            catch((error_: unknown) => {
+              logError("auto_boss", error_);

              /* Silently ignore — will retry next tick */
            }).
@@ -1521,35 +1526,46 @@ export const GameProvider = ({
          },
        };
      });
-    } catch {
+    } catch (error_: unknown) {
+      logError("buy_prestige_upgrade", error_);
      // Silently ignore — server errors shouldn't crash the UI
    }
  }, []);

  const transcend = useCallback(async() => {
-    const result = await transcendApi({});
-    setShowTranscendenceToast(true);
-    if (enableSoundsReference.current) {
-      playSound("transcendence");
+    try {
+      const result = await transcendApi({});
+      setShowTranscendenceToast(true);
+      if (enableSoundsReference.current) {
+        playSound("transcendence");
+      }
+      if (enableNotificationsReference.current) {
+        sendNotification("🌌 Transcendence!", "You have transcended reality!");
+      }
+      await reload();
+      return result;
+    } catch (error_: unknown) {
+      logError("transcend", error_);
+      throw error_;
    }
-    if (enableNotificationsReference.current) {
-      sendNotification("🌌 Transcendence!", "You have transcended reality!");
-    }
-    await reload();
-    return result;
  }, [ reload ]);

  const apotheosis = useCallback(async() => {
-    const result = await achieveApotheosisApi({});
-    setShowApotheosisToast(true);
-    if (enableSoundsReference.current) {
-      playSound("apotheosis");
+    try {
+      const result = await achieveApotheosisApi({});
+      setShowApotheosisToast(true);
+      if (enableSoundsReference.current) {
+        playSound("apotheosis");
+      }
+      if (enableNotificationsReference.current) {
+        sendNotification("✨ Apotheosis!", "You have achieved godhood!");
+      }
+      await reload();
+      return result;
+    } catch (error_: unknown) {
+      logError("apotheosis", error_);
+      throw error_;
    }
-    if (enableNotificationsReference.current) {
-      sendNotification("✨ Apotheosis!", "You have achieved godhood!");
-    }
-    await reload();
-    return result;
  }, [ reload ]);

  const buyEchoUpgrade = useCallback(async(upgradeId: string) => {
@@ -1575,114 +1591,125 @@ export const GameProvider = ({
          },
        };
      });
-    } catch {
-      // Silently ignore server errors
+    } catch (error_: unknown) {
+      logError("buy_echo_upgrade", error_);
+      // Silently ignore — server errors shouldn't crash the UI
    }
  }, []);

  const startExploration = useCallback(async(areaId: string) => {
-    const response = await startExplorationApi({ areaId });
-    const areaData = EXPLORATION_AREAS.find((a) => {
-      return a.id === areaId;
-    });
-    if (areaData === undefined) {
-      return;
-    }
-    // eslint-disable-next-line stylistic/no-mixed-operators -- duration * 1000 is clear
-    const startedAt = response.endsAt - areaData.durationSeconds * 1000;
-    setState((previous) => {
-      if (previous?.exploration === undefined) {
-        return previous;
+    try {
+      const response = await startExplorationApi({ areaId });
+      const areaData = EXPLORATION_AREAS.find((a) => {
+        return a.id === areaId;
+      });
+      if (areaData === undefined) {
+        return;
      }
-      return {
-        ...previous,
-        exploration: {
-          ...previous.exploration,
-          areas: previous.exploration.areas.map((a) => {
-            return a.id === areaId
-              ? { ...a, startedAt: startedAt, status: "in_progress" as const }
-              : a;
-          }),
-        },
-      };
-    });
-  }, []);
-
-  const collectExploration = useCallback(
-    async(areaId: string): Promise<ExploreCollectResponse> => {
-      const result = await collectExplorationApi({ areaId });
+      // eslint-disable-next-line stylistic/no-mixed-operators -- duration * 1000 is clear
+      const startedAt = response.endsAt - areaData.durationSeconds * 1000;
      setState((previous) => {
        if (previous?.exploration === undefined) {
          return previous;
        }
-        let materials = [ ...previous.exploration.materials ];
-
-        // Apply material drops from the random loot roll
-        for (const drop of result.materialsFound) {
-          const existing = materials.find((mat) => {
-            return mat.materialId === drop.materialId;
-          });
-          if (existing === undefined) {
-            materials = [
-              ...materials,
-              { materialId: drop.materialId, quantity: drop.quantity },
-            ];
-          } else {
-            materials = materials.map((mat) => {
-              return mat.materialId === drop.materialId
-                ? { ...mat, quantity: mat.quantity + drop.quantity }
-                : mat;
-            });
-          }
-        }
-
-        // Apply material from event (if any)
-        const materialGained = result.event?.materialGained;
-        if (materialGained !== null && materialGained !== undefined) {
-          const { materialId, quantity } = materialGained;
-          const existing = materials.find((mat) => {
-            return mat.materialId === materialId;
-          });
-          if (existing === undefined) {
-            materials = [ ...materials, { materialId, quantity } ];
-          } else {
-            materials = materials.map((mat) => {
-              return mat.materialId === materialId
-                ? { ...mat, quantity: mat.quantity + quantity }
-                : mat;
-            });
-          }
-        }
-
        return {
          ...previous,
          exploration: {
            ...previous.exploration,
            areas: previous.exploration.areas.map((a) => {
              return a.id === areaId
-                ? { ...a, completedOnce: true, status: "available" as const }
+                ? { ...a, startedAt: startedAt, status: "in_progress" as const }
                : a;
            }),
-            materials: materials,
-          },
-          player: {
-            ...previous.player,
-            totalGoldEarned:
-              previous.player.totalGoldEarned
-              + Math.max(0, result.event?.goldChange ?? 0),
-          },
-          resources: {
-            ...previous.resources,
-            essence:
-              previous.resources.essence + (result.event?.essenceChange ?? 0),
-            gold: Math.max(
-              0,
-              previous.resources.gold + (result.event?.goldChange ?? 0),
-            ),
          },
        };
      });
-      return result;
+    } catch (error_: unknown) {
+      logError("start_exploration", error_);
+      throw error_;
+    }
+  }, []);
+
+  const collectExploration = useCallback(
+    async(areaId: string): Promise<ExploreCollectResponse> => {
+      try {
+        const result = await collectExplorationApi({ areaId });
+        setState((previous) => {
+          if (previous?.exploration === undefined) {
+            return previous;
+          }
+          let materials = [ ...previous.exploration.materials ];
+
+          // Apply material drops from the random loot roll
+          for (const drop of result.materialsFound) {
+            const existing = materials.find((mat) => {
+              return mat.materialId === drop.materialId;
+            });
+            if (existing === undefined) {
+              materials = [
+                ...materials,
+                { materialId: drop.materialId, quantity: drop.quantity },
+              ];
+            } else {
+              materials = materials.map((mat) => {
+                return mat.materialId === drop.materialId
+                  ? { ...mat, quantity: mat.quantity + drop.quantity }
+                  : mat;
+              });
+            }
+          }
+
+          // Apply material from event (if any)
+          const materialGained = result.event?.materialGained;
+          if (materialGained !== null && materialGained !== undefined) {
+            const { materialId, quantity } = materialGained;
+            const existing = materials.find((mat) => {
+              return mat.materialId === materialId;
+            });
+            if (existing === undefined) {
+              materials = [ ...materials, { materialId, quantity } ];
+            } else {
+              materials = materials.map((mat) => {
+                return mat.materialId === materialId
+                  ? { ...mat, quantity: mat.quantity + quantity }
+                  : mat;
+              });
+            }
+          }
+
+          return {
+            ...previous,
+            exploration: {
+              ...previous.exploration,
+              areas: previous.exploration.areas.map((a) => {
+                return a.id === areaId
+                  ? { ...a, completedOnce: true, status: "available" as const }
+                  : a;
+              }),
+              materials: materials,
+            },
+            player: {
+              ...previous.player,
+              totalGoldEarned:
+                previous.player.totalGoldEarned
+                + Math.max(0, result.event?.goldChange ?? 0),
+            },
+            resources: {
+              ...previous.resources,
+              essence:
+                previous.resources.essence + (result.event?.essenceChange ?? 0),
+              gold: Math.max(
+                0,
+                previous.resources.gold + (result.event?.goldChange ?? 0),
+              ),
+            },
+          };
+        });
+        return result;
+      } catch (error_: unknown) {
+        logError("collect_exploration", error_);
+        throw error_;
+      }
    },
    [],
  );
@@ -1694,35 +1721,40 @@ export const GameProvider = ({
    if (recipe === undefined) {
      return;
    }
-    const result = await craftRecipeApi({ recipeId });
-    setState((previous) => {
-      if (previous?.exploration === undefined) {
-        return previous;
-      }
-      let materials = [ ...previous.exploration.materials ];
-      for (const request of recipe.requiredMaterials) {
-        materials = materials.map((mat) => {
-          return mat.materialId === request.materialId
-            ? { ...mat, quantity: mat.quantity - request.quantity }
-            : mat;
-        });
-      }
-      return {
-        ...previous,
-        exploration: {
-          ...previous.exploration,
-          craftedClickMultiplier:   result.craftedClickMultiplier,
-          craftedCombatMultiplier:  result.craftedCombatMultiplier,
-          craftedEssenceMultiplier: result.craftedEssenceMultiplier,
-          craftedGoldMultiplier:    result.craftedGoldMultiplier,
-          craftedRecipeIds:         [
-            ...previous.exploration.craftedRecipeIds,
-            recipeId,
-          ],
-          materials: materials,
-        },
-      };
-    });
+    try {
+      const result = await craftRecipeApi({ recipeId });
+      setState((previous) => {
+        if (previous?.exploration === undefined) {
+          return previous;
+        }
+        let materials = [ ...previous.exploration.materials ];
+        for (const request of recipe.requiredMaterials) {
+          materials = materials.map((mat) => {
+            return mat.materialId === request.materialId
+              ? { ...mat, quantity: mat.quantity - request.quantity }
+              : mat;
+          });
+        }
+        return {
+          ...previous,
+          exploration: {
+            ...previous.exploration,
+            craftedClickMultiplier:   result.craftedClickMultiplier,
+            craftedCombatMultiplier:  result.craftedCombatMultiplier,
+            craftedEssenceMultiplier: result.craftedEssenceMultiplier,
+            craftedGoldMultiplier:    result.craftedGoldMultiplier,
+            craftedRecipeIds:         [
+              ...previous.exploration.craftedRecipeIds,
+              recipeId,
+            ],
+            materials: materials,
+          },
+        };
+      });
+    } catch (error_: unknown) {
+      logError("craft_recipe", error_);
+      throw error_;
+    }
  }, []);

  const toggleAutoPrestige = useCallback(() => {
@@ -1798,7 +1830,8 @@ export const GameProvider = ({
        return applyBossResult(previous, bossId, result);
      });
      setBattleResult({ bossName: boss.name, result: result });
-    } catch {
+    } catch (error_: unknown) {
+      logError("challenge_boss", error_);
      // Silently ignore — server errors shouldn't crash the UI
    }
  }, []);
@@ -8,8 +8,12 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { App } from "./app.js";
+import { ErrorBoundary } from "./components/errorBoundary.js";
+import { initialiseFrontendLogger } from "./utils/logger.js";
 import "./styles.css";

+initialiseFrontendLogger();
+
 const rootElement = document.getElementById("root");

 if (!rootElement) {
@@ -18,6 +22,8 @@ if (!rootElement) {

 createRoot(rootElement).render(
  <StrictMode>
-    <App />
+    <ErrorBoundary>
+      <App />
+    </ErrorBoundary>
  </StrictMode>,
 );
@@ -26,6 +26,7 @@
  --radius: 8px;
  --radius-lg: 12px;
  --font: "Segoe UI", system-ui, sans-serif;
+  --resource-bar-height: 3.5rem;
 }

 body {
@@ -136,6 +137,10 @@ body::before {
  flex-direction: column;
  align-items: center;
  gap: 1rem;
+  position: sticky;
+  top: var(--resource-bar-height);
+  height: calc(100vh - var(--resource-bar-height));
+  overflow-y: auto;
 }

 .game-content {
@@ -3181,8 +3186,11 @@ body::before {
    border-right: none;
    flex-direction: row;
    gap: 0.75rem;
+    height: auto;
    justify-content: center;
    padding: 0.5rem 0.75rem;
+    position: static;
+    top: auto;
    width: 100%;
  }

@@ -0,0 +1,19 @@
+/**
+ * @file Frontend error logging utility that forwards errors to the backend telemetry service.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+/* eslint-disable no-console -- Errors are forwarded to backend via the overridden console.error */
+
+/**
+ * Logs an error to the backend telemetry service.
+ * Accepts the same arguments as console.error — conventionally a context string
+ * followed by the error value.
+ * @param logArguments - The values to log, forwarded directly to console.error.
+ */
+const logError = (...logArguments: Array<unknown>): void => {
+  console.error(...logArguments);
+};
+
+export { logError };
@@ -0,0 +1,68 @@
+/**
+ * @file Frontend logger that forwards console output to the backend telemetry service.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+/* eslint-disable no-console -- This file intentionally overrides console methods */
+
+type Level = "debug" | "info" | "warn";
+
+const post = (path: string, body: object): void => {
+  void fetch(path, {
+    body:    JSON.stringify(body),
+    // eslint-disable-next-line @typescript-eslint/naming-convention -- HTTP header names use kebab-case
+    headers: { "Content-Type": "application/json" },
+    method:  "POST",
+  }).catch(() => {
+    // Intentionally swallowed — we cannot log logger failures without infinite recursion.
+  });
+};
+
+/**
+ * Overrides the global console.log and console.error methods so that all
+ * frontend log output is forwarded to the backend telemetry endpoints.
+ * Must be called once at application startup before any other code runs.
+ */
+const initialiseFrontendLogger = (): void => {
+  const originalLog = console.log.bind(console);
+  const originalError = console.error.bind(console);
+
+  console.log = (...consoleArguments: Array<unknown>): void => {
+    originalLog(...consoleArguments);
+    const level: Level = "info";
+    const message = consoleArguments.map((argument) => {
+      return typeof argument === "string"
+        ? argument
+        : JSON.stringify(argument);
+    }).join(" ");
+    post("/api/fe/log", { level, message });
+  };
+
+  console.error = (...consoleArguments: Array<unknown>): void => {
+    originalError(...consoleArguments);
+    const message = consoleArguments.map((argument) => {
+      if (argument instanceof Error) {
+        return `${argument.message}\n${argument.stack ?? ""}`;
+      }
+      return typeof argument === "string"
+        ? argument
+        : JSON.stringify(argument);
+    }).join(" ");
+    const context = "console.error";
+    post("/api/fe/error", { context, message });
+  };
+
+  console.warn = (...consoleArguments: Array<unknown>): void => {
+    originalLog(...consoleArguments);
+    const level: Level = "warn";
+    const message = consoleArguments.map((argument) => {
+      return typeof argument === "string"
+        ? argument
+        : JSON.stringify(argument);
+    }).join(" ");
+    post("/api/fe/log", { level, message });
+  };
+};
+
+export { initialiseFrontendLogger };
@@ -4,6 +4,7 @@
 * @license Naomi's Public License
 * @author Naomi Carrigan
 */
+import { logError } from "./logError.js";

 /**
 * Requests browser notification permission from the user.
@@ -38,7 +39,8 @@ const sendNotification = (title: string, body: string): void => {
  try {
    // eslint-disable-next-line no-new -- Notification constructor has side effects
    new Notification(title, { body: body, icon: "/favicon.ico" });
-  } catch {
+  } catch (error_: unknown) {
+    logError("send_notification", error_);
    // Silently ignore — notifications may fail silently
  }
 };
@@ -4,6 +4,7 @@
 * @license Naomi's Public License
 * @author Naomi Carrigan
 */
+import { logError } from "./logError.js";

 type SoundEvent =
  | "achievement"
@@ -101,7 +102,8 @@ const playSound = (event: SoundEvent): void => {
      oscillator.start(startTime);
      oscillator.stop(endTime);
    }
-  } catch {
+  } catch (error_: unknown) {
+    logError("play_sound", error_);
    // Silently ignore — audio may not be available in all environments
  }
 };