feat: initial prototype — core game systems (#30)

## Summary

This PR represents the full v1 prototype, implementing the core game systems for Elysium.

- Full idle/clicker RPG loop: resource collection, crafting, boss fights, exploration, and quests
- Adventurer hiring with batch size selector and progressive tier cost scaling
- Prestige, transcendence, and apotheosis systems with auto-prestige support
- Character sheet, titles, leaderboards, companion system, and daily login bonuses
- Auto-quest and auto-boss toggles
- Discord webhook notifications on prestige/transcendence/apotheosis
- Discord role awarded on apotheosis
- Responsive design and overarching story/lore system
- In-game sound effects and browser notifications for key events
- Support link button in the resource bar
- Full test coverage (100% on `apps/api` and `packages/types`)
- CI pipeline: lint → build → test

## Closes

Closes #1
Closes #2
Closes #3
Closes #4
Closes #5
Closes #6
Closes #7
Closes #8
Closes #9
Closes #10
Closes #11
Closes #12
Closes #13
Closes #14
Closes #16
Closes #19
Closes #20
Closes #21
Closes #22
Closes #23
Closes #24
Closes #25
Closes #26
Closes #27
Closes #29

✨ This issue was created with help from Hikari~ 🌸

Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Reviewed-on: #30
Co-authored-by: Hikari <hikari@nhcarrigan.com>
Co-committed-by: Hikari <hikari@nhcarrigan.com>

apps/web/src/utils/dailyChallenges.ts

@@ -0,0 +1,53 @@
+/**
+ * @file Daily challenge progress utilities for Elysium.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+import type { DailyChallengeState, DailyChallengeType } from "@elysium/types";
+
+/**
+ * Increments progress for daily challenges matching the given type.
+ * Returns the updated challenge state and any crystals awarded for newly-completed challenges.
+ *
+ * Note: challenge generation and daily resets are handled server-side only.
+ * This utility is purely for client-side progress tracking.
+ * @param challengeState - The current state of all daily challenges.
+ * @param type - The type of challenge to update progress for.
+ * @param amount - The amount to increment progress by.
+ * @returns The updated challenges and total crystals awarded.
+ */
+export const updateChallengeProgress = (
+  challengeState: DailyChallengeState,
+  type: DailyChallengeType,
+  amount: number,
+): { updatedChallenges: DailyChallengeState; crystalsAwarded: number } => {
+  let crystalsAwarded = 0;
+
+  const updatedChallenges: DailyChallengeState = {
+    ...challengeState,
+    challenges: challengeState.challenges.map((challenge) => {
+      if (challenge.type !== type || challenge.completed) {
+        return challenge;
+      }
+
+      const progressValue = Math.min(
+        challenge.progress + amount,
+        challenge.target,
+      );
+      const nowCompleted = progressValue >= challenge.target;
+
+      if (nowCompleted) {
+        crystalsAwarded = crystalsAwarded + challenge.rewardCrystals;
+      }
+
+      return {
+        ...challenge,
+        completed: nowCompleted,
+        progress:  progressValue,
+      };
+    }),
+  };
+
+  return { crystalsAwarded, updatedChallenges };
+};

apps/web/src/utils/format.ts

@@ -0,0 +1,141 @@
+/* eslint-disable stylistic/lines-around-comment -- Need the comment! */
+/**
+ * @file Number formatting utilities for Elysium.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+import type { NumberFormat } from "@elysium/types";
+
+// Named suffixes up to 1e33 (Decillion). Letter-based suffixes take over from 1e36 onwards.
+const namedSuffixes: Array<{ threshold: number; suffix: string }> = [
+  // Decillion
+  { suffix: "Dc", threshold: 1e33 },
+  // Nonillion
+  { suffix: "No", threshold: 1e30 },
+  // Octillion
+  { suffix: "Oc", threshold: 1e27 },
+  // Septillion
+  { suffix: "Sp", threshold: 1e24 },
+  // Sextillion
+  { suffix: "Sx", threshold: 1e21 },
+  // Quintillion
+  { suffix: "Qi", threshold: 1e18 },
+  // Quadrillion
+  { suffix: "Qa", threshold: 1e15 },
+  // Trillion
+  { suffix: "T", threshold: 1e12 },
+  // Billion
+  { suffix: "B", threshold: 1e9 },
+  // Million
+  { suffix: "M", threshold: 1e6 },
+  // Thousand
+  { suffix: "K", threshold: 1e3 },
+];
+
+// Letter suffixes start at 1e36 ("a"), stepping by 1000 each time (i.e. +3 exponent per letter).
+const letterBaseExp = 36;
+
+/**
+ * Generates an alphabetic suffix for a given index:
+ * 0 → "a", 1 → "b", ..., 25 → "z",
+ * 26 → "aa", 27 → "ab", ..., 701 → "zz", 702 → "aaa", ...
+ * @param index - The zero-based index to convert to a letter suffix.
+ * @returns The alphabetic suffix string.
+ */
+const getLetterSuffix = (index: number): string => {
+  let result = "";
+  let n = index;
+  do {
+    const percent = n % 26;
+    result = String.fromCodePoint(97 + percent) + result;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return result;
+};
+
+/**
+ * Formats a number with a named or letter-based suffix.
+ * @param value - The number to format.
+ * @returns The formatted string with suffix.
+ */
+const formatSuffix = (value: number): string => {
+  if (value >= Math.pow(10, letterBaseExp)) {
+    const exp = Math.floor(Math.log10(value));
+    const stepsAboveBase = Math.floor((exp - letterBaseExp) / 3);
+    const steps = stepsAboveBase * 3;
+    const divisorExp = letterBaseExp + steps;
+    const divisor = Math.pow(10, divisorExp);
+    return `${(value / divisor).toFixed(2)}${getLetterSuffix(stepsAboveBase)}`;
+  }
+  for (const { threshold, suffix } of namedSuffixes) {
+    if (value >= threshold) {
+      return `${(value / threshold).toFixed(2)}${suffix}`;
+    }
+  }
+  return value < 1
+    ? value.toFixed(2)
+    : value.toFixed(1);
+};
+
+/**
+ * Formats a number in scientific notation: e.g. 1.23e15.
+ * Falls back to K/M/B/T style below 1 million.
+ * @param value - The number to format.
+ * @returns The formatted string in scientific notation.
+ */
+const formatScientific = (value: number): string => {
+  if (value < 1e6) {
+    return formatSuffix(value);
+  }
+  // ToExponential handles all magnitudes JS can represent (up to ~1.8e308)
+  return value.toExponential(2).replace("e+", "e");
+};
+
+/**
+ * Formats a number in engineering notation (exponent always a multiple of 3):
+ * e.g. 12.35E12, 1.23E300. Falls back to K/M/B/T style below 1 million.
+ * @param value - The number to format.
+ * @returns The formatted string in engineering notation.
+ */
+const formatEngineering = (value: number): string => {
+  if (value < 1e6) {
+    return formatSuffix(value);
+  }
+  const exp = Math.floor(Math.log10(value));
+  const engExp = Math.floor(exp / 3) * 3;
+  const mantissa = value / Math.pow(10, engExp);
+  return `${mantissa.toFixed(2)}E${String(engExp)}`;
+};
+
+/**
+ * Formats a number for display using the player's chosen notation style.
+ * Negative values are formatted with a leading minus sign.
+ * @param value - The number to format.
+ * @param format - The notation style to use.
+ * @returns The formatted number string.
+ */
+export const formatNumber = (
+  value: number,
+  format: NumberFormat = "suffix",
+): string => {
+  if (!Number.isFinite(value) || Number.isNaN(value)) {
+    return "0";
+  }
+  if (value < 0) {
+    return `-${formatNumber(-value, format)}`;
+  }
+
+  switch (format) {
+    case "scientific":
+      return formatScientific(value);
+    case "engineering":
+      return formatEngineering(value);
+    case "suffix":
+      return formatSuffix(value);
+    default: {
+      /* V8 ignore next -- @preserve */
+      return formatSuffix(value);
+    }
+  }
+};

apps/web/src/utils/notification.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Browser notification utilities.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+
+/**
+ * Requests browser notification permission from the user.
+ * @returns Whether permission was granted.
+ */
+const requestNotificationPermission = async(): Promise<boolean> => {
+  if (typeof Notification === "undefined") {
+    return false;
+  }
+  if (Notification.permission === "granted") {
+    return true;
+  }
+  if (Notification.permission === "denied") {
+    return false;
+  }
+  const permission = await Notification.requestPermission();
+  return permission === "granted";
+};
+
+/**
+ * Sends a browser notification if permission has been granted.
+ * @param title - The notification title text.
+ * @param body - The notification message displayed below the title.
+ */
+const sendNotification = (title: string, body: string): void => {
+  if (
+    typeof Notification === "undefined"
+    || Notification.permission !== "granted"
+  ) {
+    return;
+  }
+  try {
+    // eslint-disable-next-line no-new -- Notification constructor has side effects
+    new Notification(title, { body: body, icon: "/favicon.ico" });
+  } catch {
+    // Silently ignore — notifications may fail silently
+  }
+};
+
+export { requestNotificationPermission, sendNotification };

apps/web/src/utils/sound.ts

@@ -0,0 +1,110 @@
+/**
+ * @file Sound effect utilities using the Web Audio API.
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+
+type SoundEvent =
+  | "achievement"
+  | "apotheosis"
+  | "bossVictory"
+  | "prestige"
+  | "questCompleted"
+  | "questFailed"
+  | "transcendence";
+
+interface SoundPattern {
+  frequencies:  Array<number>;
+  gain:         number;
+  noteDuration: number;
+  type:         OscillatorType;
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention -- intentional constant name
+const SOUND_PATTERNS: Record<SoundEvent, SoundPattern> = {
+  achievement: {
+    frequencies:  [ 523, 659, 784, 1047 ],
+    gain:         0.3,
+    noteDuration: 0.12,
+    type:         "triangle",
+  },
+  apotheosis: {
+    frequencies:  [ 1047, 880, 784, 659, 523 ],
+    gain:         0.35,
+    noteDuration: 0.25,
+    type:         "sine",
+  },
+  bossVictory: {
+    frequencies:  [ 523, 784, 1047 ],
+    gain:         0.4,
+    noteDuration: 0.18,
+    type:         "square",
+  },
+  prestige: {
+    frequencies:  [ 392, 523, 659, 784 ],
+    gain:         0.35,
+    noteDuration: 0.15,
+    type:         "sawtooth",
+  },
+  questCompleted: {
+    frequencies:  [ 523, 659 ],
+    gain:         0.25,
+    noteDuration: 0.15,
+    type:         "sine",
+  },
+  questFailed: {
+    frequencies:  [ 392, 330, 261 ],
+    gain:         0.25,
+    noteDuration: 0.18,
+    type:         "triangle",
+  },
+  transcendence: {
+    frequencies:  [ 261, 329, 392, 523 ],
+    gain:         0.3,
+    noteDuration: 0.3,
+    type:         "sine",
+  },
+};
+
+// eslint-disable-next-line @typescript-eslint/init-declarations -- lazily initialised on first use
+let audioContext: AudioContext | undefined;
+
+const getAudioContext = (): AudioContext => {
+  if (audioContext === undefined) {
+    audioContext = new AudioContext();
+  }
+  return audioContext;
+};
+
+/**
+ * Plays a sound effect for a given game event using the Web Audio API.
+ * @param event - The game event to play a sound for.
+ */
+const playSound = (event: SoundEvent): void => {
+  try {
+    const context = getAudioContext();
+    const pattern = SOUND_PATTERNS[event];
+    for (const [ index, frequency ] of pattern.frequencies.entries()) {
+      const oscillator = context.createOscillator();
+      const gainNode = context.createGain();
+      oscillator.connect(gainNode);
+      gainNode.connect(context.destination);
+      oscillator.type = pattern.type;
+      oscillator.frequency.value = frequency;
+      const noteOffset = index * pattern.noteDuration;
+      const startTime = context.currentTime + noteOffset;
+      const endTime = startTime + pattern.noteDuration;
+      gainNode.gain.setValueAtTime(0, startTime);
+      gainNode.gain.linearRampToValueAtTime(pattern.gain, startTime + 0.01);
+      gainNode.gain.linearRampToValueAtTime(0, endTime);
+      oscillator.start(startTime);
+      oscillator.stop(endTime);
+    }
+  } catch {
+    // Silently ignore — audio may not be available in all environments
+  }
+};
+
+export type { SoundEvent };
+export { playSound };