From c293d3036f3254b01d22d8a7c5350c90d4137b51 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 1 Jan 2026 17:22:17 -0300
Subject: [PATCH 001/111] fix: navbar padding extrapolating max width
 (`box-sizing: content-box`)

---
 apps/frontend/src/modules/shared/components/layout/Header.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/shared/components/layout/Header.tsx b/apps/frontend/src/modules/shared/components/layout/Header.tsx
index 5cd18575..1998f73a 100644
--- a/apps/frontend/src/modules/shared/components/layout/Header.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/Header.tsx
@@ -33,7 +33,7 @@ export async function Header() {
   return (
     <header className='fixed w-[calc(100vw_-_16px)] h-14 flex flex-row justify-center items-center bg-zinc-900 border-b border-zinc-700 py-2 z-10'>
       {/* Navbar */}
-      <nav className='w-full flex flex-row justify-between items-center gap-8 md:gap-12 max-w-screen-xl px-6 sm:px-10 overflow-x-auto box-content [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden'>
+      <nav className='w-full flex flex-row justify-between items-center gap-8 md:gap-12 max-w-screen-xl px-6 sm:px-10 overflow-x-auto [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden'>
         {/* Icon */}
         <div className='flex-0 flex justify-start lg:justify-center min-w-fit'>
           <Link href='/'>

From 697e29ca579ff49ab5f6db1f044d6121ad132ed6 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 1 Jan 2026 20:05:57 -0300
Subject: [PATCH 002/111] fix: thumbnail color buttons missing border
 transparency

---
 .../src/modules/song/components/client/SongThumbnailInput.tsx   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
index 45316d37..27bdab49 100644
--- a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
@@ -123,7 +123,7 @@ const ColorButton: React.FC<ColorButtonProps> = ({
       <button
         type='button'
         className={cn(
-          'w-6 h-6 rounded-full flex-none border-2 border-zinc-200 border-opacity-30 disabled:opacity-30',
+          'w-6 h-6 rounded-full flex-none border-2 border-zinc-200/30 disabled:opacity-30',
           active && 'outline outline-2 outline-zinc-200',
         )}
         style={{ backgroundColor: color }}

From 9d20ad84934d4f97f25677aa1b20fe51756d8a3c Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 1 Jan 2026 20:06:33 -0300
Subject: [PATCH 003/111] fix: song upload field icon losing its size

---
 .../src/modules/song/components/client/SongSelector.tsx         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/song/components/client/SongSelector.tsx b/apps/frontend/src/modules/song/components/client/SongSelector.tsx
index ec9cae2c..f8f23af5 100644
--- a/apps/frontend/src/modules/song/components/client/SongSelector.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongSelector.tsx
@@ -55,7 +55,7 @@ export const SongSelector = () => {
           icon={faFile}
           className={`${
             isDragActive ? 'text-blue-400 scale-105' : 'text-zinc-600'
-          } transition-all duration-250 ease-in-out !h-20`}
+          } transition-all duration-250 ease-in-out !h-20 text-7xl`}
         />
 
         <FontAwesomeIcon

From 3664c2cd6d2243fbc5fc2c73382e6e36fa42a508 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 1 Jan 2026 21:53:00 -0300
Subject: [PATCH 004/111] refactor(thumbnail): replace `canvasFactory` with
 split browser and Node exports

A bunch of issues were happening during the build due to the dynamic module importing. This commit completely separates browser and Node bundles for the `@nbw/thumbnail` package such that no Node-only dependencies slip into the client bundle.
---
 .../song/song-upload/song-upload.service.ts   |   2 +-
 .../components/client/ThumbnailRenderer.tsx   |  53 +-----
 packages/thumbnail/package.json               |  37 ++--
 packages/thumbnail/src/browser/canvas.ts      |  23 +++
 packages/thumbnail/src/browser/draw.ts        |  15 ++
 packages/thumbnail/src/browser/index.ts       |   3 +
 packages/thumbnail/src/canvasFactory.ts       | 178 ------------------
 packages/thumbnail/src/node/canvas.ts         |  35 ++++
 packages/thumbnail/src/node/draw.ts           |  18 ++
 packages/thumbnail/src/node/index.ts          |   3 +
 .../src/{index.ts => shared/drawCore.ts}      |  87 +++------
 packages/thumbnail/src/shared/drawTypes.ts    |  31 +++
 packages/thumbnail/src/shared/types.ts        |  13 ++
 .../thumbnail/src/{ => shared}/utils.spec.ts  |   2 +-
 packages/thumbnail/src/{ => shared}/utils.ts  |  34 ++--
 packages/thumbnail/src/types.ts               |  38 ----
 16 files changed, 210 insertions(+), 362 deletions(-)
 create mode 100644 packages/thumbnail/src/browser/canvas.ts
 create mode 100644 packages/thumbnail/src/browser/draw.ts
 create mode 100644 packages/thumbnail/src/browser/index.ts
 delete mode 100644 packages/thumbnail/src/canvasFactory.ts
 create mode 100644 packages/thumbnail/src/node/canvas.ts
 create mode 100644 packages/thumbnail/src/node/draw.ts
 create mode 100644 packages/thumbnail/src/node/index.ts
 rename packages/thumbnail/src/{index.ts => shared/drawCore.ts} (59%)
 create mode 100644 packages/thumbnail/src/shared/drawTypes.ts
 create mode 100644 packages/thumbnail/src/shared/types.ts
 rename packages/thumbnail/src/{ => shared}/utils.spec.ts (99%)
 rename packages/thumbnail/src/{ => shared}/utils.ts (72%)
 delete mode 100644 packages/thumbnail/src/types.ts

diff --git a/apps/backend/src/song/song-upload/song-upload.service.ts b/apps/backend/src/song/song-upload/song-upload.service.ts
index 9e390939..b9ed8871 100644
--- a/apps/backend/src/song/song-upload/song-upload.service.ts
+++ b/apps/backend/src/song/song-upload/song-upload.service.ts
@@ -22,7 +22,7 @@ import {
   injectSongFileMetadata,
   obfuscateAndPackSong,
 } from '@nbw/song';
-import { drawToImage } from '@nbw/thumbnail';
+import { drawToImage } from '@nbw/thumbnail/node';
 import { FileService } from '@server/file/file.service';
 import { UserService } from '@server/user/user.service';
 
diff --git a/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx b/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
index 019d5041..6d11a28b 100644
--- a/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
+++ b/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
@@ -4,18 +4,10 @@ import { useEffect, useRef, useState } from 'react';
 import { UseFormReturn } from 'react-hook-form';
 
 import { NoteQuadTree } from '@nbw/song';
+import { drawNotesOffscreen, swap } from '@nbw/thumbnail/browser';
 
 import { UploadSongForm } from './SongForm.zod';
 
-// Dynamically import thumbnail functions to avoid SSR issues with HTMLCanvasElement
-const loadThumbnailFunctions = async () => {
-  const thumbnail = await import('@nbw/thumbnail');
-  return {
-    drawNotesOffscreen: thumbnail.drawNotesOffscreen,
-    swap: thumbnail.swap,
-  };
-};
-
 type ThumbnailRendererCanvasProps = {
   notes: NoteQuadTree;
   formMethods: UseFormReturn<UploadSongForm>;
@@ -28,11 +20,6 @@ export const ThumbnailRendererCanvas = ({
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const drawRequest = useRef<number | null>(null);
   const [loading, setLoading] = useState(true);
-  const [functionsLoaded, setFunctionsLoaded] = useState(false);
-  const thumbnailFunctionsRef = useRef<{
-    drawNotesOffscreen: typeof import('@nbw/thumbnail').drawNotesOffscreen;
-    swap: typeof import('@nbw/thumbnail').swap;
-  } | null>(null);
 
   const [zoomLevel, startTick, startLayer, backgroundColor] = formMethods.watch(
     [
@@ -43,23 +30,6 @@ export const ThumbnailRendererCanvas = ({
     ],
   );
 
-  // Load thumbnail functions on client side only
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-    if (thumbnailFunctionsRef.current) return;
-
-    loadThumbnailFunctions()
-      .then((funcs) => {
-        thumbnailFunctionsRef.current = funcs;
-        // Trigger a re-render to use the loaded functions
-        setFunctionsLoaded(true);
-        setLoading(false);
-      })
-      .catch((error) => {
-        console.error('Failed to load thumbnail functions:', error);
-      });
-  }, []);
-
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -76,12 +46,6 @@ export const ThumbnailRendererCanvas = ({
   }, []);
 
   useEffect(() => {
-    if (typeof window === 'undefined') return;
-    if (!thumbnailFunctionsRef.current || !functionsLoaded) {
-      setLoading(true);
-      return;
-    }
-
     setLoading(true);
 
     const canvas = canvasRef.current as HTMLCanvasElement | null;
@@ -92,11 +56,9 @@ export const ThumbnailRendererCanvas = ({
       cancelAnimationFrame(drawRequest.current);
     }
 
-    const { drawNotesOffscreen, swap } = thumbnailFunctionsRef.current;
-
     drawRequest.current = requestAnimationFrame(async () => {
       try {
-        const output = await drawNotesOffscreen({
+        const output = (await drawNotesOffscreen({
           notes,
           startTick,
           startLayer,
@@ -105,7 +67,7 @@ export const ThumbnailRendererCanvas = ({
           canvasWidth: canvas.width,
           imgWidth: 1280,
           imgHeight: 768,
-        });
+        })) as OffscreenCanvas;
 
         swap(output, canvas);
         setLoading(false);
@@ -114,14 +76,7 @@ export const ThumbnailRendererCanvas = ({
         setLoading(false);
       }
     });
-  }, [
-    notes,
-    startTick,
-    startLayer,
-    zoomLevel,
-    backgroundColor,
-    functionsLoaded,
-  ]);
+  }, [notes, startTick, startLayer, zoomLevel, backgroundColor]);
 
   return (
     <div className='relative w-full'>
diff --git a/packages/thumbnail/package.json b/packages/thumbnail/package.json
index f09b7340..4f4b95d9 100644
--- a/packages/thumbnail/package.json
+++ b/packages/thumbnail/package.json
@@ -1,29 +1,35 @@
 {
   "name": "@nbw/thumbnail",
-  "main": "dist/index.node.js",
-  "module": "dist/index.node.js",
-  "types": "dist/index.d.ts",
   "type": "module",
   "private": true,
+  "sideEffects": false,
   "exports": {
-    ".": {
-      "browser": "./dist/index.browser.js",
-      "node": "./dist/index.node.js",
-      "import": "./dist/index.node.js",
-      "types": "./dist/index.d.ts",
-      "development": "./src/index.ts"
+    "./browser": {
+      "import": "./dist/browser/index.js",
+      "types": "./dist/browser/index.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node/index.js",
+      "types": "./dist/node/index.d.ts"
     }
   },
   "scripts": {
-    "build": "bun run clean && bun run build:node && bun run build:browser && bun run build:types",
-    "build:node": "bun build src/index.ts --outdir dist --target node && mv dist/index.js dist/index.node.js",
-    "build:browser": "bun build src/index.ts --outdir dist --target browser --external @napi-rs/canvas && mv dist/index.js dist/index.browser.js",
+    "build": "bun run clean && bun run build:browser && bun run build:node && bun run build:types",
+    "build:browser": "bun build src/browser/index.ts --outdir dist/browser --target browser --external @napi-rs/canvas",
+    "build:node": "bun build src/node/index.ts --outdir dist/node --target node",
     "build:types": "tsc --project tsconfig.build.json",
     "clean": "rm -rf dist",
-    "dev": "bun build src/index.ts --outdir dist --target node --watch",
+    "dev:browser": "bun build src/browser/index.ts --outdir dist/browser --target node --watch",
+    "dev:node": "bun build src/node/index.ts --outdir dist/node --target node --watch",
     "lint": "eslint \"src/**/*.ts\" --fix",
     "test": "jest"
   },
+  "dependencies": {
+    "@nbw/song": "workspace:*"
+  },
+  "optionalDependencies": {
+    "@napi-rs/canvas": "^0.1.74"
+  },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5",
@@ -33,8 +39,7 @@
   "peerDependencies": {
     "typescript": "^5"
   },
-  "dependencies": {
-    "@napi-rs/canvas": "^0.1.74",
-    "@nbw/song": "workspace:*"
+  "engines": {
+    "node": ">=18"
   }
 }
diff --git a/packages/thumbnail/src/browser/canvas.ts b/packages/thumbnail/src/browser/canvas.ts
new file mode 100644
index 00000000..1dfb901b
--- /dev/null
+++ b/packages/thumbnail/src/browser/canvas.ts
@@ -0,0 +1,23 @@
+import type { DrawingCanvas } from '../shared/drawTypes';
+
+export const createCanvas = (w: number, h: number): DrawingCanvas =>
+  new OffscreenCanvas(w, h) as unknown as DrawingCanvas;
+
+export const loadImage = (src: string) =>
+  new Promise<HTMLImageElement>((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = reject;
+    img.src = src;
+  });
+
+export const useFont = () => {
+  const font = new FontFace('Lato', 'url(/fonts/Lato-Regular.ttf)');
+  font.load().then((f) => document.fonts.add(f));
+};
+
+export const noteBlockImage = loadImage('/img/note-block-grayscale.png');
+
+export const saveToImage = () => {
+  throw new Error('saveToImage not available in browser');
+};
diff --git a/packages/thumbnail/src/browser/draw.ts b/packages/thumbnail/src/browser/draw.ts
new file mode 100644
index 00000000..aa68d4f8
--- /dev/null
+++ b/packages/thumbnail/src/browser/draw.ts
@@ -0,0 +1,15 @@
+import { drawNotes } from '../shared/drawCore';
+import type { DrawParams } from '../shared/types';
+
+import { createCanvas, noteBlockImage, useFont } from './canvas';
+
+useFont();
+
+export const drawNotesOffscreen = async (params: DrawParams) => {
+  return await drawNotes(params, createCanvas, noteBlockImage);
+};
+
+export const swap = (src: OffscreenCanvas, dst: HTMLCanvasElement) => {
+  const ctx = dst.getContext('2d')!;
+  ctx.drawImage(src, 0, 0);
+};
diff --git a/packages/thumbnail/src/browser/index.ts b/packages/thumbnail/src/browser/index.ts
new file mode 100644
index 00000000..189a80cd
--- /dev/null
+++ b/packages/thumbnail/src/browser/index.ts
@@ -0,0 +1,3 @@
+export * from './canvas';
+export * from './draw';
+export * from '../shared/types';
diff --git a/packages/thumbnail/src/canvasFactory.ts b/packages/thumbnail/src/canvasFactory.ts
deleted file mode 100644
index d1c32fb6..00000000
--- a/packages/thumbnail/src/canvasFactory.ts
+++ /dev/null
@@ -1,178 +0,0 @@
-import type Path from 'path';
-
-import type NapiRs from '@napi-rs/canvas';
-
-import type { CanvasUtils } from './types';
-
-let canvasUtils: CanvasUtils;
-
-if (typeof document === 'undefined') {
-  // Node.js/Bun environment
-  try {
-    const canvasModule = require('@napi-rs/canvas') as typeof NapiRs;
-    const path = require('path') as typeof Path;
-
-    const {
-      createCanvas: nodeCreateCanvas,
-      loadImage: nodeLoadImage,
-      GlobalFonts,
-    } = canvasModule;
-
-    const getPath = (filename: string): string => {
-      const workingDir = process.cwd();
-
-      // Try different possible locations for the asset files
-      const possiblePaths = [
-        // When running from package directory
-        path.join(workingDir, filename.split('/').join(path.sep)),
-        // When running from root directory
-        path.join(
-          workingDir,
-          'packages',
-          'thumbnail',
-          filename.split('/').join(path.sep),
-        ),
-      ];
-
-      // Check which path exists
-      const fs = require('fs');
-
-      for (const fullPath of possiblePaths) {
-        if (fs.existsSync(fullPath)) {
-          return fullPath;
-        }
-      }
-
-      // Default to first path if none exist
-      return possiblePaths[0]!;
-    };
-
-    const saveToImage = (canvas: NapiRs.Canvas) => canvas.encode('png');
-
-    const useFont = () => {
-      const path = getPath('assets/fonts/Lato-Regular.ttf').toString();
-      console.log('Font path: ', path);
-
-      GlobalFonts.registerFromPath(path, 'Lato');
-    };
-
-    let noteBlockImage: Promise<any>;
-
-    try {
-      const path = getPath('assets/img/note-block-grayscale.png');
-
-      noteBlockImage = nodeLoadImage(path);
-    } catch (error) {
-      console.error('Error loading image: ', error);
-      noteBlockImage = Promise.reject(error);
-    }
-
-    canvasUtils = {
-      createCanvas: nodeCreateCanvas,
-      loadImage: nodeLoadImage,
-      getPath,
-      useFont,
-      saveToImage,
-      noteBlockImage,
-      DrawingCanvas: canvasModule.Canvas,
-      RenderedImage: canvasModule.Image,
-    };
-  } catch (error) {
-    // Fallback for when @napi-rs/canvas is not available (e.g., in browser build)
-    console.warn('@napi-rs/canvas not available, using browser fallbacks');
-
-    const createCanvas = (width: number, height: number) => {
-      if (typeof OffscreenCanvas !== 'undefined') {
-        return new OffscreenCanvas(width, height);
-      }
-
-      throw new Error('OffscreenCanvas not available');
-    };
-
-    const loadImage = (src: string): Promise<any> => {
-      return Promise.reject(
-        new Error('loadImage not available in this environment'),
-      );
-    };
-
-    const getPath = (filename: string) => filename;
-
-    const saveToImage = (_canvas: any) => {
-      throw new Error('saveToImage not implemented in browser');
-    };
-
-    const useFont = () => {
-      // No-op in fallback
-    };
-
-    const noteBlockImage = Promise.reject(
-      new Error('noteBlockImage not available in this environment'),
-    );
-
-    canvasUtils = {
-      createCanvas,
-      loadImage,
-      getPath,
-      useFont,
-      saveToImage,
-      noteBlockImage,
-      DrawingCanvas: HTMLCanvasElement as any,
-      RenderedImage: HTMLImageElement as any,
-    };
-  }
-} else {
-  // Browser environment
-  const createCanvas = (width: number, height: number) => {
-    return new OffscreenCanvas(width, height);
-  };
-
-  const loadImage = (src: string): Promise<HTMLImageElement> => {
-    return new Promise((resolve, reject) => {
-      const img = new Image();
-      img.onload = () => resolve(img);
-      img.onerror = reject;
-      img.src = src;
-    });
-  };
-
-  const getPath = (filename: string) => filename;
-
-  const saveToImage = (_canvas: any) => {
-    console.warn('saveToImage not implemented in browser');
-    throw new Error('saveToImage not implemented in browser');
-  };
-
-  const useFont = () => {
-    const font = new FontFace('Lato', 'url(/fonts/Lato-Regular.ttf)');
-
-    font.load().then((loadedFont) => {
-      document.fonts.add(loadedFont);
-    });
-  };
-
-  const noteBlockImagePath = getPath('/img/note-block-grayscale.png');
-
-  const noteBlockImage = loadImage(noteBlockImagePath);
-
-  canvasUtils = {
-    createCanvas,
-    loadImage,
-    getPath,
-    useFont,
-    saveToImage,
-    noteBlockImage,
-    DrawingCanvas: HTMLCanvasElement,
-    RenderedImage: HTMLImageElement,
-  };
-}
-
-export const {
-  createCanvas,
-  loadImage,
-  getPath,
-  useFont,
-  saveToImage,
-  noteBlockImage,
-  DrawingCanvas,
-  RenderedImage,
-} = canvasUtils;
diff --git a/packages/thumbnail/src/node/canvas.ts b/packages/thumbnail/src/node/canvas.ts
new file mode 100644
index 00000000..f8bc06a2
--- /dev/null
+++ b/packages/thumbnail/src/node/canvas.ts
@@ -0,0 +1,35 @@
+import fs from 'fs';
+import path from 'path';
+
+import {
+  createCanvas as napiCreateCanvas,
+  loadImage,
+  GlobalFonts,
+  Canvas,
+} from '@napi-rs/canvas';
+
+import type { DrawingCanvas } from '../shared/drawTypes';
+
+export const createCanvas = (w: number, h: number): DrawingCanvas =>
+  napiCreateCanvas(w, h) as unknown as DrawingCanvas;
+
+export const getPath = (filename: string) => {
+  const candidates = [
+    path.join(process.cwd(), filename),
+    path.join(process.cwd(), 'packages/thumbnail', filename),
+  ];
+  return candidates.find(fs.existsSync) ?? candidates[0]!;
+};
+
+export const useFont = () => {
+  GlobalFonts.registerFromPath(
+    getPath('assets/fonts/Lato-Regular.ttf'),
+    'Lato',
+  );
+};
+
+export const noteBlockImage = loadImage(
+  getPath('assets/img/note-block-grayscale.png'),
+);
+
+export const saveToImage = (canvas: Canvas) => canvas.encode('png');
diff --git a/packages/thumbnail/src/node/draw.ts b/packages/thumbnail/src/node/draw.ts
new file mode 100644
index 00000000..71c517b7
--- /dev/null
+++ b/packages/thumbnail/src/node/draw.ts
@@ -0,0 +1,18 @@
+import type { Canvas } from '@napi-rs/canvas';
+
+import { drawNotes } from '../shared/drawCore';
+import type { DrawParams } from '../shared/types';
+
+import { createCanvas, noteBlockImage, saveToImage, useFont } from './canvas';
+
+useFont();
+
+export const drawNotesOffscreen = async (params: DrawParams) => {
+  return await drawNotes(params, createCanvas, noteBlockImage);
+};
+
+export const drawToImage = async (params: DrawParams) => {
+  const canvas = await drawNotesOffscreen(params);
+  const nodeCanvas = canvas as Canvas; // Type=narrow to Node canvas for saving
+  return Buffer.from(await saveToImage(nodeCanvas));
+};
diff --git a/packages/thumbnail/src/node/index.ts b/packages/thumbnail/src/node/index.ts
new file mode 100644
index 00000000..189a80cd
--- /dev/null
+++ b/packages/thumbnail/src/node/index.ts
@@ -0,0 +1,3 @@
+export * from './canvas';
+export * from './draw';
+export * from '../shared/types';
diff --git a/packages/thumbnail/src/index.ts b/packages/thumbnail/src/shared/drawCore.ts
similarity index 59%
rename from packages/thumbnail/src/index.ts
rename to packages/thumbnail/src/shared/drawCore.ts
index 588e7c9e..30f2f230 100644
--- a/packages/thumbnail/src/index.ts
+++ b/packages/thumbnail/src/shared/drawCore.ts
@@ -1,56 +1,29 @@
-export * from './canvasFactory';
-export * from './types';
-export * from './utils';
-import type { Note } from '@nbw/song';
-
-import {
-  createCanvas,
-  noteBlockImage,
-  saveToImage,
-  useFont,
-} from './canvasFactory';
-import type { Canvas, DrawParams } from './types';
+import type { DrawingCanvas, ImageLike } from './drawTypes';
+import type { DrawParams } from './types';
 import { getKeyText, instrumentColors, isDarkColor, tintImage } from './utils';
 
-useFont();
+export async function drawNotes(
+  params: DrawParams,
+  createCanvas: (w: number, h: number) => DrawingCanvas,
+  noteBlockImage: Promise<ImageLike>,
+) {
+  const {
+    notes,
+    startTick,
+    startLayer,
+    zoomLevel,
+    backgroundColor,
+    canvasWidth,
+    imgWidth = 1280,
+    imgHeight = 768,
+  } = params;
 
-export const swap = async (src: Canvas, dst: Canvas) => {
-  /**
-   * Run a `drawFunction` that returns a canvas and draw it to the passed `canvas`.
-   *
-   * @param drawFunction - Function that draws to a canvas and returns it
-   * @param canvas - Canvas to draw the output of `drawFunction` to
-   *
-   * @returns Nothing
-   */
-  // Get canvas context
-  const ctx = dst.getContext('2d');
-
-  if (!ctx) {
-    throw new Error('Could not get canvas context');
-  }
-
-  // Swap the canvas
-  ctx.drawImage(src, 0, 0);
-};
-
-export const drawNotesOffscreen = async ({
-  notes,
-  startTick,
-  startLayer,
-  zoomLevel,
-  backgroundColor,
-  canvasWidth,
-  //canvasHeight,
-  imgWidth = 1280,
-  imgHeight = 768,
-}: DrawParams) => {
   // Create new offscreen canvas
   const canvas = createCanvas(imgWidth, imgHeight);
   const ctx = canvas.getContext('2d');
 
   if (!ctx) {
-    throw new Error('Could not get offscreen canvas context');
+    throw new Error('Could not get canvas context');
   }
 
   // Disable anti-aliasing
@@ -101,7 +74,7 @@ export const drawNotesOffscreen = async ({
     y2: endLayer,
   });
 
-  visibleNotes.forEach(async (note: Note) => {
+  for (const note of visibleNotes) {
     // Calculate position
     const x = (note.tick - startTick) * 8 * zoomFactor;
     const y = (note.layer - startLayer) * 8 * zoomFactor;
@@ -113,7 +86,7 @@ export const drawNotesOffscreen = async ({
 
     // Draw the note block
     ctx.drawImage(
-      tintImage(loadedNoteBlockImage, overlayColor),
+      tintImage(loadedNoteBlockImage, overlayColor, createCanvas),
       x,
       y,
       8 * zoomFactor,
@@ -127,23 +100,7 @@ export const drawNotesOffscreen = async ({
     ctx.textAlign = 'center';
     ctx.textBaseline = 'middle';
     ctx.fillText(keyText, x + 4 * zoomFactor, y + 4 * zoomFactor);
-  });
-
-  return canvas;
-};
-
-export const drawToImage = async (params: DrawParams): Promise<Buffer> => {
-  let canvas;
-  const { imgWidth, imgHeight } = params;
-
-  if (!canvas) {
-    canvas = createCanvas(imgWidth, imgHeight);
   }
 
-  const output = await drawNotesOffscreen(params);
-  const byteArray = await saveToImage(output);
-
-  // Convert to Buffer
-  const buffer = Buffer.from(byteArray);
-  return buffer;
-};
+  return canvas;
+}
diff --git a/packages/thumbnail/src/shared/drawTypes.ts b/packages/thumbnail/src/shared/drawTypes.ts
new file mode 100644
index 00000000..907deadf
--- /dev/null
+++ b/packages/thumbnail/src/shared/drawTypes.ts
@@ -0,0 +1,31 @@
+export interface DrawContext2D {
+  imageSmoothingEnabled: boolean;
+  fillStyle: string | CanvasGradient | CanvasPattern;
+  font: string;
+  textAlign: CanvasTextAlign;
+  textBaseline: CanvasTextBaseline;
+  globalCompositeOperation: string;
+  globalAlpha: number;
+  scale(x: number, y: number): void;
+  clearRect(x: number, y: number, w: number, h: number): void;
+  fillRect(x: number, y: number, w: number, h: number): void;
+  drawImage(
+    image: ImageLike,
+    dx: number,
+    dy: number,
+    dw: number,
+    dh: number,
+  ): void;
+  fillText(text: string, x: number, y: number): void;
+}
+
+export interface ImageLike {
+  width: number;
+  height: number;
+}
+
+export interface DrawingCanvas {
+  width: number;
+  height: number;
+  getContext(type: '2d'): DrawContext2D;
+}
diff --git a/packages/thumbnail/src/shared/types.ts b/packages/thumbnail/src/shared/types.ts
new file mode 100644
index 00000000..33506f22
--- /dev/null
+++ b/packages/thumbnail/src/shared/types.ts
@@ -0,0 +1,13 @@
+import type { NoteQuadTree } from '@nbw/song';
+
+export interface DrawParams {
+  notes: NoteQuadTree;
+  startTick: number;
+  startLayer: number;
+  zoomLevel: number;
+  backgroundColor: string;
+  canvasWidth?: number;
+  canvasHeight?: number;
+  imgWidth: number;
+  imgHeight: number;
+}
diff --git a/packages/thumbnail/src/utils.spec.ts b/packages/thumbnail/src/shared/utils.spec.ts
similarity index 99%
rename from packages/thumbnail/src/utils.spec.ts
rename to packages/thumbnail/src/shared/utils.spec.ts
index 802d38ba..13928a00 100644
--- a/packages/thumbnail/src/utils.spec.ts
+++ b/packages/thumbnail/src/shared/utils.spec.ts
@@ -1,4 +1,4 @@
-import { getKeyText, instrumentColors, isDarkColor } from './utils';
+import { getKeyText, instrumentColors, isDarkColor } from './utils.js';
 
 describe('instrumentColors', () => {
   it('should contain 16 color codes', () => {
diff --git a/packages/thumbnail/src/utils.ts b/packages/thumbnail/src/shared/utils.ts
similarity index 72%
rename from packages/thumbnail/src/utils.ts
rename to packages/thumbnail/src/shared/utils.ts
index 52ad53af..bd96978b 100644
--- a/packages/thumbnail/src/utils.ts
+++ b/packages/thumbnail/src/shared/utils.ts
@@ -1,5 +1,9 @@
-import { createCanvas } from './canvasFactory';
-import type { Canvas, Image } from './types';
+import type { DrawingCanvas, DrawContext2D } from './drawTypes';
+
+export interface ImageLike {
+  width: number;
+  height: number;
+}
 
 export const instrumentColors = [
   '#1964ac',
@@ -20,36 +24,38 @@ export const instrumentColors = [
   '#575757',
 ];
 
-const tintedImages: Record<string, Canvas> = {};
+const tintedImages: Record<string, DrawingCanvas> = {};
+
+// Function to apply a tint to an image
+export const tintImage = (
+  image: ImageLike,
+  color: string,
+  createCanvas: (w: number, h: number) => DrawingCanvas,
+): DrawingCanvas => {
+  const key = `${color}`;
 
-// Function to apply tint to an image
-export const tintImage = (image: Image, color: string): Canvas => {
-  if (tintedImages[color]) {
-    return tintedImages[color];
+  if (tintedImages[key]) {
+    return tintedImages[key];
   }
 
   const canvas = createCanvas(image.width, image.height);
-  const ctx = canvas.getContext('2d');
+  const ctx: DrawContext2D = canvas.getContext('2d');
 
   if (!ctx) {
     throw new Error('Could not get canvas context');
   }
 
-  // Fill background with the color
   ctx.fillStyle = color;
   ctx.fillRect(0, 0, canvas.width, canvas.height);
 
-  // Apply the note block texture to the color
   ctx.globalCompositeOperation = 'hard-light';
   ctx.globalAlpha = 0.67;
-  ctx.drawImage(image, 0, 0);
+  ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
 
-  // Reset canvas settings
   ctx.globalCompositeOperation = 'source-over';
   ctx.globalAlpha = 1;
 
-  tintedImages[color] = canvas;
-
+  tintedImages[key] = canvas;
   return canvas;
 };
 
diff --git a/packages/thumbnail/src/types.ts b/packages/thumbnail/src/types.ts
deleted file mode 100644
index 19e71c37..00000000
--- a/packages/thumbnail/src/types.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import type NapiRs from '@napi-rs/canvas';
-
-import type { NoteQuadTree } from '@nbw/song';
-
-import { DrawingCanvas, RenderedImage } from './canvasFactory';
-
-export interface DrawParams {
-  notes: NoteQuadTree;
-  startTick: number;
-  startLayer: number;
-  zoomLevel: number;
-  backgroundColor: string;
-  canvasWidth?: number;
-  canvasHeight?: number;
-  imgWidth: number;
-  imgHeight: number;
-}
-
-export type Canvas = typeof DrawingCanvas;
-
-export type Image = typeof RenderedImage; /*
-import type {
-  Canvas as NapiCanvas,
-  Image as NapiImage,
-  GlobalFonts as NapiGlobalFonts,
-} from '@napi-rs/canvas';
-*/
-
-export interface CanvasUtils {
-  createCanvas(width: number, height: number): any;
-  loadImage(src: string): Promise<any>;
-  getPath(filename: string): string | URL;
-  useFont(): void;
-  saveToImage(canvas: HTMLCanvasElement | NapiRs.Canvas): Promise<Uint8Array>;
-  noteBlockImage: Promise<any> | any;
-  DrawingCanvas: any;
-  RenderedImage: any;
-}

From 3694956ee34559eb9a7a77a35db3ac1ecd193a70 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 1 Jan 2026 22:02:25 -0300
Subject: [PATCH 005/111] fix: noteCount and duration are possibly null in
 search param assignment

---
 apps/frontend/src/app/(content)/search/page.tsx | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/apps/frontend/src/app/(content)/search/page.tsx b/apps/frontend/src/app/(content)/search/page.tsx
index 61276b91..9f30a9c1 100644
--- a/apps/frontend/src/app/(content)/search/page.tsx
+++ b/apps/frontend/src/app/(content)/search/page.tsx
@@ -479,10 +479,11 @@ const SearchSongPage = () => {
       category,
       uploader,
       limit,
-      noteCountMin: noteCountMin > 0 ? noteCountMin : undefined,
-      noteCountMax: noteCountMax < 10000 ? noteCountMax : undefined,
-      durationMin: durationMin > 0 ? durationMin : undefined,
-      durationMax: durationMax < 10000 ? durationMax : undefined,
+      noteCountMin: noteCountMin && noteCountMin > 0 ? noteCountMin : undefined,
+      noteCountMax:
+        noteCountMax && noteCountMax < 10000 ? noteCountMax : undefined,
+      durationMin: durationMin && durationMin > 0 ? durationMin : undefined,
+      durationMax: durationMax && durationMax < 10000 ? durationMax : undefined,
       features: features || undefined,
       instruments: instruments || undefined,
     };

From ab54e70bc055a17828841bafe7d643b331b10767 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Thu, 1 Jan 2026 22:07:23 -0300
Subject: [PATCH 006/111] fix: add type import for JSX in CustomMarkdown
 component

---
 apps/frontend/src/modules/shared/components/CustomMarkdown.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx b/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx
index 51cb62e7..fdad1fec 100644
--- a/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx
+++ b/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx
@@ -1,4 +1,5 @@
 import Link from 'next/link';
+import type { JSX } from 'react';
 import Markdown, { ExtraProps } from 'react-markdown';
 
 export const CustomMarkdown = ({

From 001a3649a0309ba3e0719d38ff211a66322f746e Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Thu, 1 Jan 2026 22:15:24 -0300
Subject: [PATCH 007/111] feat(search): add SearchLayout component and wrap
 SearchSongPage in Suspense for loading state

---
 apps/frontend/src/app/(content)/search/layout.tsx | 10 ++++++++++
 apps/frontend/src/app/(content)/search/page.tsx   | 12 ++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 apps/frontend/src/app/(content)/search/layout.tsx

diff --git a/apps/frontend/src/app/(content)/search/layout.tsx b/apps/frontend/src/app/(content)/search/layout.tsx
new file mode 100644
index 00000000..f0bd3e9c
--- /dev/null
+++ b/apps/frontend/src/app/(content)/search/layout.tsx
@@ -0,0 +1,10 @@
+export const dynamic = 'force-dynamic';
+export const revalidate = 0;
+
+export default function SearchLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <>{children}</>;
+}
diff --git a/apps/frontend/src/app/(content)/search/page.tsx b/apps/frontend/src/app/(content)/search/page.tsx
index 9f30a9c1..91ed2c49 100644
--- a/apps/frontend/src/app/(content)/search/page.tsx
+++ b/apps/frontend/src/app/(content)/search/page.tsx
@@ -12,7 +12,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import Image from 'next/image';
 import Link from 'next/link';
 import { parseAsInteger, parseAsString, useQueryStates } from 'nuqs';
-import { useEffect, useMemo, useState } from 'react';
+import { Suspense, useEffect, useMemo, useState } from 'react';
 import Skeleton from 'react-loading-skeleton';
 import { create } from 'zustand';
 
@@ -627,4 +627,12 @@ const SearchSongPage = () => {
   );
 };
 
-export default SearchSongPage;
+const SearchPageWrapper = () => {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <SearchSongPage />
+    </Suspense>
+  );
+};
+
+export default SearchPageWrapper;

From 15b47dc6ab612e76ad7c91073b32b7f28afbd101 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 09:50:11 -0300
Subject: [PATCH 008/111] fix: upgrade `@hookform/resolvers` from 3.10.0 to
 5.2.2

The lib couldn't validate errors after upgrading to Zod 4.
---
 apps/frontend/package.json | 2 +-
 bun.lock                   | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index 296f3c78..0785ad84 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -14,7 +14,7 @@
     "@fortawesome/free-solid-svg-icons": "^6.7.2",
     "@fortawesome/react-fontawesome": "^0.2.6",
     "@headlessui/react": "^1.7.19",
-    "@hookform/resolvers": "^3.10.0",
+    "@hookform/resolvers": "^5.2.2",
     "@mdx-js/loader": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
     "@nbw/config": "workspace:*",
diff --git a/bun.lock b/bun.lock
index 232e3c66..c105ebcb 100644
--- a/bun.lock
+++ b/bun.lock
@@ -111,7 +111,7 @@
         "@fortawesome/free-solid-svg-icons": "^6.7.2",
         "@fortawesome/react-fontawesome": "^0.2.6",
         "@headlessui/react": "^1.7.19",
-        "@hookform/resolvers": "^3.10.0",
+        "@hookform/resolvers": "^5.2.2",
         "@mdx-js/loader": "^3.1.1",
         "@mdx-js/react": "^3.1.1",
         "@nbw/config": "workspace:*",
@@ -490,7 +490,7 @@
 
     "@headlessui/react": ["@headlessui/react@1.7.19", "", { "dependencies": { "@tanstack/react-virtual": "^3.0.0-beta.60", "client-only": "^0.0.1" }, "peerDependencies": { "react": "^16 || ^17 || ^18", "react-dom": "^16 || ^17 || ^18" } }, "sha512-Ll+8q3OlMJfJbAKM/+/Y2q6PPYbryqNTXDbryx7SXLIDamkF6iQFbriYHga0dY44PvDhvvBWCx1Xj4U5+G4hOw=="],
 
-    "@hookform/resolvers": ["@hookform/resolvers@3.10.0", "", { "peerDependencies": { "react-hook-form": "^7.0.0" } }, "sha512-79Dv+3mDF7i+2ajj7SkypSKHhl1cbln1OGavqrsF7p6mbUv11xpqpacPsGDCTRvCSjEEIez2ef1NveSVL3b0Ag=="],
+    "@hookform/resolvers": ["@hookform/resolvers@5.2.2", "", { "dependencies": { "@standard-schema/utils": "^0.3.0" }, "peerDependencies": { "react-hook-form": "^7.55.0" } }, "sha512-A/IxlMLShx3KjV/HeTcTfaMxdwy690+L/ZADoeaTltLx+CVuzkeVIPuybK3jrRfw7YZnmdKsVVHAlEPIAEUNlA=="],
 
     "@humanfs/core": ["@humanfs/core@0.19.1", "", {}, "sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA=="],
 
@@ -954,6 +954,8 @@
 
     "@standard-schema/spec": ["@standard-schema/spec@1.0.0", "", {}, "sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA=="],
 
+    "@standard-schema/utils": ["@standard-schema/utils@0.3.0", "", {}, "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g=="],
+
     "@swc/helpers": ["@swc/helpers@0.5.15", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g=="],
 
     "@tailwindcss/node": ["@tailwindcss/node@4.1.17", "", { "dependencies": { "@jridgewell/remapping": "^2.3.4", "enhanced-resolve": "^5.18.3", "jiti": "^2.6.1", "lightningcss": "1.30.2", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.1.17" } }, "sha512-csIkHIgLb3JisEFQ0vxr2Y57GUNYh447C8xzwj89U/8fdW8LhProdxvnVH6U8M2Y73QKiTIH+LWbK3V2BBZsAg=="],

From 0d8199b97e7c5d9c9f02f5e06f98b426988baec7 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 09:52:11 -0300
Subject: [PATCH 009/111] fix: upgrade zod schema's `message` field to `error`
 (deprecated in v4)

See:
https://zod.dev/v4/changelog?id=deprecates-message
---
 .../song/components/client/SongForm.zod.ts     | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/apps/frontend/src/modules/song/components/client/SongForm.zod.ts b/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
index beb3df93..0f9da439 100644
--- a/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
+++ b/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
@@ -38,39 +38,35 @@ const licenses = Object.keys(UPLOAD_CONSTANTS.licenses) as Readonly<string[]>;
 export const SongFormSchema = zod.object({
   allowDownload: zod.boolean().default(true),
 
-  // @ts-ignore
   visibility: zod.enum(visibility).default('public'),
   title: zod
     .string()
     .max(UPLOAD_CONSTANTS.title.maxLength, {
-      message: `Title must be shorter than ${UPLOAD_CONSTANTS.title.maxLength} characters`,
+      error: `Title must be shorter than ${UPLOAD_CONSTANTS.title.maxLength} characters`,
     })
     .min(1, {
-      message: 'Title is required',
+      error: 'Title is required',
     }),
   originalAuthor: zod
     .string()
     .max(UPLOAD_CONSTANTS.originalAuthor.maxLength, {
-      message: `Original author must be shorter than ${UPLOAD_CONSTANTS.originalAuthor.maxLength} characters`,
+      error: `Original author must be shorter than ${UPLOAD_CONSTANTS.originalAuthor.maxLength} characters`,
     })
     .min(0),
   author: zod.string().optional(),
   description: zod.string().max(UPLOAD_CONSTANTS.description.maxLength, {
-    message: `Description must be less than ${UPLOAD_CONSTANTS.description.maxLength} characters`,
+    error: `Description must be less than ${UPLOAD_CONSTANTS.description.maxLength} characters`,
   }),
   thumbnailData: thumbnailDataSchema,
   customInstruments: zod.array(zod.string()),
   license: zod
-
-    // @ts-ignore
-    .enum(licenses, {
+    .enum(['none', ...licenses] as const)
+    .refine((v) => v !== 'none', {
       message: 'Please select a license',
     })
-    .refine((value) => Object.keys(UPLOAD_CONSTANTS.licenses).includes(value))
     .default(UPLOAD_CONSTANTS.license.default),
 
-  // @ts-ignore
-  category: zod.enum(categories).default(UPLOAD_CONSTANTS.CATEGORY_DEFAULT),
+  category: zod.enum(categories).default(UPLOAD_CONSTANTS.category.default),
 });
 
 export const uploadSongFormSchema = SongFormSchema.extend({});

From d8db8de9e082e8599be218cc3dee245b32955fe5 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 10:18:00 -0300
Subject: [PATCH 010/111] fix: add default form values in upload form

---
 .../components/client/context/UploadSong.context.tsx   | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
index 361a10d4..1a55328d 100644
--- a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
+++ b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
@@ -11,7 +11,7 @@ import {
 import { toast } from 'react-hot-toast';
 import { create } from 'zustand';
 
-import { BG_COLORS, THUMBNAIL_CONSTANTS } from '@nbw/config';
+import { BG_COLORS, THUMBNAIL_CONSTANTS, UPLOAD_CONSTANTS } from '@nbw/config';
 import { parseSongFromBuffer, type SongFileType } from '@nbw/song';
 import axiosInstance from '@web/lib/axios';
 import { InvalidTokenError, getTokenLocal } from '@web/lib/axios/token.utils';
@@ -131,6 +131,14 @@ export const UploadSongProvider = ({
   const formMethods = useForm<UploadSongForm>({
     resolver: zodResolver(uploadSongFormSchema),
     mode: 'onBlur',
+    // Prevents values from appearing empty on first render
+    defaultValues: {
+      category: UPLOAD_CONSTANTS.category.default,
+      license: UPLOAD_CONSTANTS.license.default,
+      visibility: 'public',
+      allowDownload: true,
+      customInstruments: [],
+    },
   });
 
   const {

From 98d11ad1829eb1a39f26a2ff6b13b0d560860235 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 10:18:49 -0300
Subject: [PATCH 011/111] refactor: make `errors` access in
 `formMethods.formState` clearer

---
 .../components/client/context/EditSong.context.tsx         | 7 ++-----
 .../components/client/context/UploadSong.context.tsx       | 7 ++-----
 2 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx b/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
index 6ca3b712..e7339dd4 100644
--- a/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
+++ b/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
@@ -57,10 +57,7 @@ export const EditSongProvider = ({
 
   const [originalData, setOriginalData] = useState<UploadSongDto | null>(null);
 
-  const {
-    register,
-    formState: { errors },
-  } = formMethods;
+  const { register } = formMethods;
 
   const router = useRouter();
 
@@ -331,7 +328,7 @@ export const EditSongProvider = ({
         instrumentSounds,
         setInstrumentSound,
         register,
-        errors,
+        errors: formMethods.formState.errors,
         song,
         sendError,
         isSubmitting,
diff --git a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
index 1a55328d..47cdf40f 100644
--- a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
+++ b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
@@ -141,10 +141,7 @@ export const UploadSongProvider = ({
     },
   });
 
-  const {
-    register,
-    formState: { errors },
-  } = formMethods;
+  const { register } = formMethods;
 
   async function submitSongData(): Promise<void> {
     // Get song file from state
@@ -327,7 +324,7 @@ export const UploadSongProvider = ({
   const formContextValue: UploadSongFormContextType = {
     formMethods,
     register,
-    errors,
+    errors: formMethods.formState.errors,
     setFile: setFileHandler,
     setInstrumentSound,
     submitSong,

From fef1d823e958f451642e807ce3894d96cb456509 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 10:19:28 -0300
Subject: [PATCH 012/111] chore: move `@napi-rs/canvas` to optional
 dependencies in bun.lock

---
 bun.lock | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/bun.lock b/bun.lock
index c105ebcb..a7ed6734 100644
--- a/bun.lock
+++ b/bun.lock
@@ -232,7 +232,6 @@
     "packages/thumbnail": {
       "name": "@nbw/thumbnail",
       "dependencies": {
-        "@napi-rs/canvas": "^0.1.74",
         "@nbw/song": "workspace:*",
       },
       "devDependencies": {
@@ -241,6 +240,9 @@
         "ts-jest": "^29.2.5",
         "typescript": "^5",
       },
+      "optionalDependencies": {
+        "@napi-rs/canvas": "^0.1.74",
+      },
       "peerDependencies": {
         "typescript": "^5",
       },

From e4c05122a358c7db37122c5d51b2236395ed59fa Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 10:20:04 -0300
Subject: [PATCH 013/111] chore: sort packages in backend's `package.json`

---
 apps/backend/package.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/apps/backend/package.json b/apps/backend/package.json
index 672781e1..4c07695e 100644
--- a/apps/backend/package.json
+++ b/apps/backend/package.json
@@ -25,6 +25,11 @@
     "@aws-sdk/client-s3": "3.946.0",
     "@aws-sdk/s3-request-presigner": "3.946.0",
     "@encode42/nbs.js": "^5.0.2",
+    "@nbw/config": "workspace:*",
+    "@nbw/database": "workspace:*",
+    "@nbw/song": "workspace:*",
+    "@nbw/sounds": "workspace:*",
+    "@nbw/thumbnail": "workspace:*",
     "@nestjs-modules/mailer": "^2.0.2",
     "@nestjs/common": "^11.1.9",
     "@nestjs/config": "^4.0.2",
@@ -56,12 +61,7 @@
     "rxjs": "^7.8.2",
     "uuid": "^13.0.0",
     "zod": "^4.1.13",
-    "zod-validation-error": "^5.0.0",
-    "@nbw/database": "workspace:*",
-    "@nbw/song": "workspace:*",
-    "@nbw/thumbnail": "workspace:*",
-    "@nbw/sounds": "workspace:*",
-    "@nbw/config": "workspace:*"
+    "zod-validation-error": "^5.0.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.1.0",

From 3bda4b86ddbb345a0291bc77f03fbd71d72a2ecb Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 10:20:46 -0300
Subject: [PATCH 014/111] fix: add default empty array for custom instruments
 in upload form

---
 .../frontend/src/modules/song/components/client/SongForm.zod.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/song/components/client/SongForm.zod.ts b/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
index 0f9da439..1e893ff4 100644
--- a/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
+++ b/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
@@ -58,7 +58,7 @@ export const SongFormSchema = zod.object({
     error: `Description must be less than ${UPLOAD_CONSTANTS.description.maxLength} characters`,
   }),
   thumbnailData: thumbnailDataSchema,
-  customInstruments: zod.array(zod.string()),
+  customInstruments: zod.array(zod.string()).default([]),
   license: zod
     .enum(['none', ...licenses] as const)
     .refine((v) => v !== 'none', {

From d7832dbeeb6dad626cfc12f4960c842ebb6be003 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 2 Jan 2026 10:21:17 -0300
Subject: [PATCH 015/111] fix: reset form and store state when navigating away
 from upload page

---
 .../components/client/context/UploadSong.context.tsx      | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
index 47cdf40f..3a0f446f 100644
--- a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
+++ b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
@@ -321,6 +321,14 @@ export const UploadSongProvider = ({
     };
   }, [formMethods.formState.isDirty, isUploadComplete]);
 
+  // Reset form and store state when component unmounts
+  useEffect(() => {
+    return () => {
+      formMethods.reset();
+      store.reset();
+    };
+  }, []);
+
   const formContextValue: UploadSongFormContextType = {
     formMethods,
     register,

From 88bb9792caf8470cf5e85d995965694d1b16100f Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sat, 3 Jan 2026 04:28:38 -0300
Subject: [PATCH 016/111] fix: split form typings in `Input`/`Output` and call
 `parse` on form data before submit

Conforms to zod v4 whic
---
 .../client/context/EditSong.context.tsx       | 71 ++++++++++---------
 .../client/context/UploadSong.context.tsx     | 24 ++++---
 .../song/components/client/SongForm.zod.ts    | 12 ++--
 3 files changed, 62 insertions(+), 45 deletions(-)

diff --git a/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx b/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
index e7339dd4..cd3d0329 100644
--- a/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
+++ b/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
@@ -18,15 +18,16 @@ import { parseSongFromBuffer, type SongFileType } from '@nbw/song';
 import axiosInstance from '@web/lib/axios';
 import { getTokenLocal } from '@web/lib/axios/token.utils';
 import {
-  EditSongForm,
+  EditSongFormInput,
+  EditSongFormOutput,
   editSongFormSchema,
 } from '@web/modules/song/components/client/SongForm.zod';
 
 export type useEditSongProviderType = {
-  formMethods: UseFormReturn<EditSongForm>;
+  formMethods: UseFormReturn<EditSongFormInput>;
   submitSong: () => void;
-  register: UseFormRegister<EditSongForm>;
-  errors: FieldErrors<EditSongForm>;
+  register: UseFormRegister<EditSongFormInput>;
+  errors: FieldErrors<EditSongFormInput>;
   song: SongFileType | null;
   instrumentSounds: string[];
   setInstrumentSound: (index: number, value: string) => void;
@@ -45,7 +46,7 @@ export const EditSongProvider = ({
 }: {
   children: React.ReactNode;
 }) => {
-  const formMethods = useForm<EditSongForm>({
+  const formMethods = useForm<EditSongFormInput>({
     resolver: zodResolver(editSongFormSchema),
     mode: 'onBlur',
   });
@@ -67,23 +68,26 @@ export const EditSongProvider = ({
         return false;
       }
 
+      const rawValues = formMethods.getValues();
+      const parsedValues: EditSongFormOutput =
+        editSongFormSchema.parse(rawValues);
+
       const formValues = {
-        allowDownload: formMethods.getValues().allowDownload,
-        visibility: formMethods.getValues().visibility,
-        title: formMethods.getValues().title,
-        originalAuthor: formMethods.getValues().originalAuthor,
-        description: formMethods.getValues().description,
+        allowDownload: parsedValues.allowDownload,
+        visibility: parsedValues.visibility,
+        title: parsedValues.title,
+        originalAuthor: parsedValues.originalAuthor,
+        description: parsedValues.description,
         thumbnailData: {
-          zoomLevel: formMethods.getValues().thumbnailData.zoomLevel,
-          startTick: formMethods.getValues().thumbnailData.startTick,
-          startLayer: formMethods.getValues().thumbnailData.startLayer,
-          backgroundColor:
-            formMethods.getValues().thumbnailData.backgroundColor,
+          zoomLevel: parsedValues.thumbnailData.zoomLevel,
+          startTick: parsedValues.thumbnailData.startTick,
+          startLayer: parsedValues.thumbnailData.startLayer,
+          backgroundColor: parsedValues.thumbnailData.backgroundColor,
         },
-        artist: formMethods.getValues().author,
-        customInstruments: formMethods.getValues().customInstruments,
-        license: formMethods.getValues().license,
-        category: formMethods.getValues().category,
+        artist: parsedValues.author,
+        customInstruments: parsedValues.customInstruments,
+        license: parsedValues.license,
+        category: parsedValues.category,
       };
 
       const comparisons = [
@@ -123,23 +127,26 @@ export const EditSongProvider = ({
   );
 
   const submitSong = async (): Promise<void> => {
+    const rawValues = formMethods.getValues();
+    const parsedValues: EditSongFormOutput =
+      editSongFormSchema.parse(rawValues);
+
     // Build form data
     const formValues: UploadSongDto = {
-      allowDownload: formMethods.getValues().allowDownload,
-      visibility: formMethods.getValues()
-        .visibility as UploadSongDto['visibility'],
-      title: formMethods.getValues().title,
-      originalAuthor: formMethods.getValues().originalAuthor,
-      description: formMethods.getValues().description,
+      allowDownload: parsedValues.allowDownload,
+      visibility: parsedValues.visibility as UploadSongDto['visibility'],
+      title: parsedValues.title,
+      originalAuthor: parsedValues.originalAuthor,
+      description: parsedValues.description,
       thumbnailData: {
-        zoomLevel: formMethods.getValues().thumbnailData.zoomLevel,
-        startTick: formMethods.getValues().thumbnailData.startTick,
-        startLayer: formMethods.getValues().thumbnailData.startLayer,
-        backgroundColor: formMethods.getValues().thumbnailData.backgroundColor,
+        zoomLevel: parsedValues.thumbnailData.zoomLevel,
+        startTick: parsedValues.thumbnailData.startTick,
+        startLayer: parsedValues.thumbnailData.startLayer,
+        backgroundColor: parsedValues.thumbnailData.backgroundColor,
       },
-      customInstruments: formMethods.getValues().customInstruments,
-      license: formMethods.getValues().license as UploadSongDto['license'],
-      category: formMethods.getValues().category as UploadSongDto['category'],
+      customInstruments: parsedValues.customInstruments,
+      license: parsedValues.license as UploadSongDto['license'],
+      category: parsedValues.category as UploadSongDto['category'],
       file: zodUndefined,
     };
 
diff --git a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
index 3a0f446f..12ccb606 100644
--- a/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
+++ b/apps/frontend/src/modules/song-upload/components/client/context/UploadSong.context.tsx
@@ -16,7 +16,8 @@ import { parseSongFromBuffer, type SongFileType } from '@nbw/song';
 import axiosInstance from '@web/lib/axios';
 import { InvalidTokenError, getTokenLocal } from '@web/lib/axios/token.utils';
 import {
-  UploadSongForm,
+  UploadSongFormInput,
+  UploadSongFormOutput,
   uploadSongFormSchema,
 } from '@web/modules/song/components/client/SongForm.zod';
 
@@ -76,9 +77,9 @@ export const useUploadSongStore = create<UploadSongStore>((set, get) => ({
 
 // Context for form methods (React Hook Form needs to be initialized in a component)
 interface UploadSongFormContextType {
-  formMethods: UseFormReturn<UploadSongForm>;
-  register: UseFormRegister<UploadSongForm>;
-  errors: FieldErrors<UploadSongForm>;
+  formMethods: UseFormReturn<UploadSongFormInput>;
+  register: UseFormRegister<UploadSongFormInput>;
+  errors: FieldErrors<UploadSongFormInput>;
   setFile: (file: File | null) => Promise<void>;
   setInstrumentSound: (index: number, value: string) => void;
   submitSong: () => Promise<void>;
@@ -94,10 +95,10 @@ export type useUploadSongProviderType = {
   setFile: (file: File | null) => void;
   instrumentSounds: string[];
   setInstrumentSound: (index: number, value: string) => void;
-  formMethods: UseFormReturn<UploadSongForm>;
+  formMethods: UseFormReturn<UploadSongFormInput>;
   submitSong: () => void;
-  register: UseFormRegister<UploadSongForm>;
-  errors: FieldErrors<UploadSongForm>;
+  register: UseFormRegister<UploadSongFormInput>;
+  errors: FieldErrors<UploadSongFormInput>;
   sendError: string | null;
   isSubmitting: boolean;
   isUploadComplete: boolean;
@@ -128,7 +129,7 @@ export const UploadSongProvider = ({
     setUploadedSongId,
   } = store;
 
-  const formMethods = useForm<UploadSongForm>({
+  const formMethods = useForm<UploadSongFormInput>({
     resolver: zodResolver(uploadSongFormSchema),
     mode: 'onBlur',
     // Prevents values from appearing empty on first render
@@ -164,7 +165,12 @@ export const UploadSongProvider = ({
     // Build form data
     const formData = new FormData();
     formData.append('file', blob, filename || 'song.nbs');
-    const formValues = formMethods.getValues();
+
+    // Parse and normalize values
+    const rawValues = formMethods.getValues();
+
+    const formValues: UploadSongFormOutput =
+      uploadSongFormSchema.parse(rawValues);
 
     Object.entries(formValues)
       .filter(
diff --git a/apps/frontend/src/modules/song/components/client/SongForm.zod.ts b/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
index 1e893ff4..f6855b1f 100644
--- a/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
+++ b/apps/frontend/src/modules/song/components/client/SongForm.zod.ts
@@ -75,8 +75,12 @@ export const editSongFormSchema = SongFormSchema.extend({
   id: zod.string(),
 });
 
-export type ThumbnailDataForm = zod.infer<typeof thumbnailDataSchema>;
+// forms
+export type ThumbnailDataFormInput = zod.input<typeof thumbnailDataSchema>;
+export type UploadSongFormInput = zod.input<typeof uploadSongFormSchema>;
+export type EditSongFormInput = zod.input<typeof editSongFormSchema>;
 
-export type UploadSongForm = zod.infer<typeof uploadSongFormSchema>;
-
-export type EditSongForm = zod.infer<typeof editSongFormSchema>;
+// parsed data
+export type ThumbnailDataFormOutput = zod.infer<typeof thumbnailDataSchema>;
+export type UploadSongFormOutput = zod.output<typeof uploadSongFormSchema>;
+export type EditSongFormOutput = zod.output<typeof editSongFormSchema>;

From c451be0ab708bfe1230405026f0af630ca03a5e9 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sat, 3 Jan 2026 23:10:57 -0300
Subject: [PATCH 017/111] chore: add setting to use project's TypeScript
 version instead of bundled VS Code's

https://stackoverflow.com/a/75470675/9045426
https://stackoverflow.com/a/75357623/9045426
---
 .vscode/settings.json | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index ad6a31bc..76a9c3a4 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -16,5 +16,7 @@
   "files.associations": {
     ".css": "tailwindcss",
     "*.scss": "tailwindcss"
-  }
+  },
+  "typescript.tsdk": "./node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true
 }

From 757b729585e8372f71e2f36edae10874779b442f Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sat, 3 Jan 2026 23:13:35 -0300
Subject: [PATCH 018/111] chore: replace root `tsconfig.json` with `references`
 field

---
 tsconfig.build.json | 18 ++++++++++++++++++
 tsconfig.json       | 18 ------------------
 2 files changed, 18 insertions(+), 18 deletions(-)
 create mode 100644 tsconfig.build.json
 delete mode 100644 tsconfig.json

diff --git a/tsconfig.build.json b/tsconfig.build.json
new file mode 100644
index 00000000..49978a90
--- /dev/null
+++ b/tsconfig.build.json
@@ -0,0 +1,18 @@
+{
+  // Root build orchestrator.
+  // This file does NOT compile code - only defines project references for `tsc -b`.
+  // Real projects live in /apps and /packages and extend tsconfig.base.json.
+
+  // This config does not type-check files directly.
+  // Use `tsc -b` or `tsc -b --noEmit`.
+  "files": [],
+  "references": [
+    { "path": "apps/frontend" },
+    { "path": "apps/backend" },
+    { "path": "packages/configs" },
+    { "path": "packages/database" },
+    { "path": "packages/song" },
+    { "path": "packages/sounds" },
+    { "path": "packages/thumbnail" }
+  ]
+}
diff --git a/tsconfig.json b/tsconfig.json
deleted file mode 100644
index ef156702..00000000
--- a/tsconfig.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "extends": "./tsconfig.base.json",
-  "compilerOptions": {
-    "module": "nodenext",
-    // Root project specific overrides
-    "strictNullChecks": true,
-    "noImplicitAny": true,
-    "strictBindCallApply": true,
-    "strictPropertyInitialization": false
-  },
-  "exclude": [
-    "node_modules",
-    "**/dist/**/*",
-    "**/dist/**/*",
-    "**/*.js",
-    "**/*.mjs"
-  ]
-}

From 2720e2555550c7e471ac2a3a82244629a6a3a668 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sat, 3 Jan 2026 23:23:38 -0300
Subject: [PATCH 019/111] chore: enable `composite` in package-inherited root
 TS config

All packages should be `composite` so they're aware of each other within the monorepo's context.

We also extract common settings `emitDeclarationOnly`, `declaration` and `outDir` so this standard config is extended by all packages, avoiding the need to redefine them individually per package.

`"noEmit": false` is required for `"composite": true`, so this change is also included here.
---
 tsconfig.package.json | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/tsconfig.package.json b/tsconfig.package.json
index 7027807e..6ff029e3 100644
--- a/tsconfig.package.json
+++ b/tsconfig.package.json
@@ -1,12 +1,17 @@
 {
   "extends": "./tsconfig.base.json",
   "compilerOptions": {
+    // Package-specific settings
+    "composite": true,
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "outDir": "dist",
     // Modern bundler mode
     "module": "ESNext",
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
-    "noEmit": true,
     "jsx": "react-jsx",
     // Additional strict checks for packages
     "noUncheckedIndexedAccess": true,

From 16d85c8db2395065784bc9ed80f441f67cc61fcf Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 00:21:56 -0300
Subject: [PATCH 020/111] chore: rename `tsconfig.build.json` to
 `tsconfig.json`

---
 packages/song/tsconfig.build.json    | 11 -----------
 packages/song/tsconfig.json          |  3 ++-
 tsconfig.build.json => tsconfig.json |  0
 3 files changed, 2 insertions(+), 12 deletions(-)
 delete mode 100644 packages/song/tsconfig.build.json
 rename tsconfig.build.json => tsconfig.json (100%)

diff --git a/packages/song/tsconfig.build.json b/packages/song/tsconfig.build.json
deleted file mode 100644
index 0fc16b66..00000000
--- a/packages/song/tsconfig.build.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": false,
-    "emitDeclarationOnly": true,
-    "declaration": true,
-    "outDir": "dist"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
-}
diff --git a/packages/song/tsconfig.json b/packages/song/tsconfig.json
index 8ac70592..7c179325 100644
--- a/packages/song/tsconfig.json
+++ b/packages/song/tsconfig.json
@@ -1,3 +1,4 @@
 {
-  "extends": "../../tsconfig.package.json"
+  "extends": "../../tsconfig.package.json",
+  "include": ["src"]
 }
diff --git a/tsconfig.build.json b/tsconfig.json
similarity index 100%
rename from tsconfig.build.json
rename to tsconfig.json

From b5216a08ebabc9058509e75cf569f7d14f7ee640 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 00:43:47 -0300
Subject: [PATCH 021/111] chore: review base TS settings in global
 `tsconfig.base.json`

strictPropertyInitialization:
- Remained after removing:
"strictNullChecks": true, "noImplicitAny": true, "strictBindCallApply": true,
which are already implied by "strict": true
- Overrides default value for "strict": true to allow for decorators (Nest.js, class-validator etc.)
- May be moved to specific packages instead, but doesn't cause harm if kept

allowJs:
- Likely added due to the adasync.js experiment
- We don't have any other .js files on the repo

incremental:
- Removed because `composite: true` already implies `incremental`
- incremental without composite produces .tsbuildinfo in weird places

exclude:
- if not explicitly included, none of these paths will be part of the TS project
- **/*.spec.ts excludes test files, which should be type-checked as well
---
 tsconfig.base.json | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/tsconfig.base.json b/tsconfig.base.json
index 4201cfdd..66165032 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -6,16 +6,13 @@
     "skipLibCheck": true,
     "noFallthroughCasesInSwitch": true,
     "forceConsistentCasingInFileNames": true,
+    "strictPropertyInitialization": false,
     // Modern JavaScript features
     "target": "ESNext",
     "lib": ["ESNext"],
-    "allowJs": true,
     "moduleDetection": "force",
-    // Build performance
-    "incremental": true,
     // Decorator support for backend compatibility
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true
-  },
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
+  }
 }

From 3c8beda0a1219b0df31e15e0804d16999de3a75f Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 00:51:54 -0300
Subject: [PATCH 022/111] chore: review base TS settings for packages in
 `tsconfig.package.json`

allowImportingTsExtensions:
- Unused (unnecessary)

jsx:
- Belongs in the frontend config, not globally
---
 tsconfig.package.json | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tsconfig.package.json b/tsconfig.package.json
index 6ff029e3..fd9a1265 100644
--- a/tsconfig.package.json
+++ b/tsconfig.package.json
@@ -10,9 +10,7 @@
     // Modern bundler mode
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
-    "jsx": "react-jsx",
     // Additional strict checks for packages
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,

From 01e098407b44098f47492f5a42b386b93fc14b18 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 01:00:03 -0300
Subject: [PATCH 023/111] chore: merge `tsconfig.build.json` into
 `tsconfig.json` for packages

While it's fine (and recommended) to have a separate TS config for building in apps, for packages, it adds unnecessary complexity and possible IDE/build mismatches in error reporting. So we're resorting to one simple rule: unless we can justify why a separate build config is needed in one sentence, it should be out - it's easy to reintroduce something later if things break.

The necessary rules have been merged into the base tsconfig.json and other unnecessary rules have been removed from either/both of them.
---
 packages/configs/tsconfig.build.json   | 14 --------------
 packages/configs/tsconfig.json         |  6 +-----
 packages/database/tsconfig.build.json  | 16 ----------------
 packages/database/tsconfig.json        | 17 +----------------
 packages/sounds/tsconfig.build.json    | 11 -----------
 packages/sounds/tsconfig.json          |  4 +---
 packages/thumbnail/tsconfig.build.json | 11 -----------
 7 files changed, 3 insertions(+), 76 deletions(-)
 delete mode 100644 packages/configs/tsconfig.build.json
 delete mode 100644 packages/database/tsconfig.build.json
 delete mode 100644 packages/sounds/tsconfig.build.json
 delete mode 100644 packages/thumbnail/tsconfig.build.json

diff --git a/packages/configs/tsconfig.build.json b/packages/configs/tsconfig.build.json
deleted file mode 100644
index 22eb2159..00000000
--- a/packages/configs/tsconfig.build.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": false,
-    "declaration": true,
-    "outDir": "dist",
-    "allowImportingTsExtensions": false,
-    "verbatimModuleSyntax": false,
-    "module": "esnext",
-    "moduleResolution": "bundler"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
-}
diff --git a/packages/configs/tsconfig.json b/packages/configs/tsconfig.json
index 069a1dc8..7c179325 100644
--- a/packages/configs/tsconfig.json
+++ b/packages/configs/tsconfig.json
@@ -1,8 +1,4 @@
 {
   "extends": "../../tsconfig.package.json",
-  "compilerOptions": {
-    // Package-specific overrides (if any)
-    "module": "esnext",
-    "moduleResolution": "bundler"
-  }
+  "include": ["src"]
 }
diff --git a/packages/database/tsconfig.build.json b/packages/database/tsconfig.build.json
deleted file mode 100644
index 15e1f5c2..00000000
--- a/packages/database/tsconfig.build.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "emitDecoratorMetadata": true,
-    "noEmit": false,
-    "declaration": true,
-    "outDir": "dist",
-    "allowImportingTsExtensions": false,
-    "verbatimModuleSyntax": false,
-    "moduleResolution": "node",
-    "module": "ESNext",
-    "typeRoots": ["./node_modules/@types"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
-}
diff --git a/packages/database/tsconfig.json b/packages/database/tsconfig.json
index 1a7a926f..42d932fb 100644
--- a/packages/database/tsconfig.json
+++ b/packages/database/tsconfig.json
@@ -2,21 +2,6 @@
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
     // Database-specific settings
-    "declaration": true,
-    "removeComments": true,
-    "allowSyntheticDefaultImports": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "baseUrl": "./",
-    "emitDecoratorMetadata": true,
-    // Relaxed strict settings for database entities
-    "strictNullChecks": false,
-    "noImplicitAny": false,
-    "strictBindCallApply": false,
-    "forceConsistentCasingInFileNames": false,
-    // Path mapping
-    "paths": {
-      "@database/*": ["src/*"]
-    }
+    "emitDecoratorMetadata": true // Necessary for class-validator
   }
 }
diff --git a/packages/sounds/tsconfig.build.json b/packages/sounds/tsconfig.build.json
deleted file mode 100644
index 0fc16b66..00000000
--- a/packages/sounds/tsconfig.build.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": false,
-    "emitDeclarationOnly": true,
-    "declaration": true,
-    "outDir": "dist"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
-}
diff --git a/packages/sounds/tsconfig.json b/packages/sounds/tsconfig.json
index 92f024c9..7c179325 100644
--- a/packages/sounds/tsconfig.json
+++ b/packages/sounds/tsconfig.json
@@ -1,6 +1,4 @@
 {
   "extends": "../../tsconfig.package.json",
-  "compilerOptions": {
-    "baseUrl": "./src"
-  }
+  "include": ["src"]
 }
diff --git a/packages/thumbnail/tsconfig.build.json b/packages/thumbnail/tsconfig.build.json
deleted file mode 100644
index 0fc16b66..00000000
--- a/packages/thumbnail/tsconfig.build.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": false,
-    "emitDeclarationOnly": true,
-    "declaration": true,
-    "outDir": "dist"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
-}

From d5f531d286edc388aa3f239409cdb2911dd4bce8 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 01:06:05 -0300
Subject: [PATCH 024/111] fix: remove `@database` path alias in database
 package

This change was prompted by the removal of this line from `database/tsconfig.json` in commit 01e098407b44098f47492f5a42b386b93fc14b18:

    "paths": {
      "@database/*": ["src/*"]
    }

This adds an internal alias to the package itself, whereas this would only be needed in cross-package references.
This bypassed package boundaries, creating an internal public API that does not exist. For this reason and to be consistent with the rest of the project, internal imports are being changed to use relative path syntax.
---
 packages/database/src/common/dto/PageQuery.dto.ts           | 3 ++-
 packages/database/src/song/dto/SongPreview.dto.ts           | 2 +-
 packages/database/src/song/dto/SongView.dto.ts              | 4 ++--
 packages/database/src/song/dto/UploadSongResponseDto.dto.ts | 2 +-
 4 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/database/src/common/dto/PageQuery.dto.ts b/packages/database/src/common/dto/PageQuery.dto.ts
index 6c508b1e..a0f0025c 100644
--- a/packages/database/src/common/dto/PageQuery.dto.ts
+++ b/packages/database/src/common/dto/PageQuery.dto.ts
@@ -11,9 +11,10 @@ import {
   Min,
 } from 'class-validator';
 
-import type { TimespanType } from '@database/song/dto/types';
 import { TIMESPANS } from '@nbw/config';
 
+import type { TimespanType } from '../../song/dto/types';
+
 export class PageQueryDTO {
   @Min(1)
   @ApiProperty({
diff --git a/packages/database/src/song/dto/SongPreview.dto.ts b/packages/database/src/song/dto/SongPreview.dto.ts
index 97acff3c..58bdc344 100644
--- a/packages/database/src/song/dto/SongPreview.dto.ts
+++ b/packages/database/src/song/dto/SongPreview.dto.ts
@@ -1,6 +1,6 @@
 import { IsNotEmpty, IsString, IsUrl, MaxLength } from 'class-validator';
 
-import type { SongWithUser } from '@database/song/entity/song.entity';
+import type { SongWithUser } from '../../song/entity/song.entity';
 
 type SongPreviewUploader = {
   username: string;
diff --git a/packages/database/src/song/dto/SongView.dto.ts b/packages/database/src/song/dto/SongView.dto.ts
index b7b5ed6f..58d07c04 100644
--- a/packages/database/src/song/dto/SongView.dto.ts
+++ b/packages/database/src/song/dto/SongView.dto.ts
@@ -7,8 +7,8 @@ import {
   IsUrl,
 } from 'class-validator';
 
-import { SongStats } from '@database/song/dto/SongStats';
-import type { SongDocument } from '@database/song/entity/song.entity';
+import { SongStats } from '../../song/dto/SongStats';
+import type { SongDocument } from '../../song/entity/song.entity';
 
 import type { CategoryType, LicenseType, VisibilityType } from './types';
 
diff --git a/packages/database/src/song/dto/UploadSongResponseDto.dto.ts b/packages/database/src/song/dto/UploadSongResponseDto.dto.ts
index 2fedb3e1..b83acb2b 100644
--- a/packages/database/src/song/dto/UploadSongResponseDto.dto.ts
+++ b/packages/database/src/song/dto/UploadSongResponseDto.dto.ts
@@ -7,7 +7,7 @@ import {
   ValidateNested,
 } from 'class-validator';
 
-import type { SongWithUser } from '@database/song/entity/song.entity';
+import type { SongWithUser } from '../../song/entity/song.entity';
 
 import * as SongViewDto from './SongView.dto';
 import { ThumbnailData } from './ThumbnailData.dto';

From 21867170608e528d043ef1dad9d73cc46c7ee2c5 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 01:22:18 -0300
Subject: [PATCH 025/111] chore: remove `build:types` script from packages and
 replace with `tsc -b`

We no longer have a separate `tsconfig.build.ts` specific for building, so there doesn't make sense to be a separate command for building types - it's not meant to be run standalone anyway, as each package is now composite.
---
 packages/configs/package.json   | 3 +--
 packages/song/package.json      | 3 +--
 packages/sounds/package.json    | 3 +--
 packages/thumbnail/package.json | 1 -
 4 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/packages/configs/package.json b/packages/configs/package.json
index b641eb87..8d0d3e69 100644
--- a/packages/configs/package.json
+++ b/packages/configs/package.json
@@ -13,8 +13,7 @@
     }
   },
   "scripts": {
-    "build": "bun run clean && bun build src/index.ts --outdir dist --target node && bun run build:types",
-    "build:types": "tsc --project tsconfig.build.json",
+    "build": "bun run clean && bun build src/index.ts --outdir dist --target node && tsc -b",
     "clean": "rm -rf dist",
     "dev": "bun build src/index.ts --outdir dist --target node --watch",
     "lint": "eslint \"src/**/*.ts\" --fix",
diff --git a/packages/song/package.json b/packages/song/package.json
index 0f0003d3..84a3e03c 100644
--- a/packages/song/package.json
+++ b/packages/song/package.json
@@ -15,10 +15,9 @@
     }
   },
   "scripts": {
-    "build": "bun run clean && bun run build:node && bun run build:browser && bun run build:types",
+    "build": "bun run clean && bun run build:node && bun run build:browser && tsc -b",
     "build:node": "bun build src/index.ts --outdir dist --target node && mv dist/index.js dist/index.node.js",
     "build:browser": "bun build src/index.ts --outdir dist --target browser && mv dist/index.js dist/index.browser.js",
-    "build:types": "tsc --project tsconfig.build.json",
     "clean": "rm -rf dist",
     "dev": "bun build src/index.ts --outdir dist --target node --watch",
     "lint": "eslint \"src/**/*.ts\" --fix",
diff --git a/packages/sounds/package.json b/packages/sounds/package.json
index 88bd226f..70abe826 100644
--- a/packages/sounds/package.json
+++ b/packages/sounds/package.json
@@ -13,8 +13,7 @@
     }
   },
   "scripts": {
-    "build": "bun run clean && bun build src/index.ts --outdir dist --target node && bun run build:types",
-    "build:types": "tsc --project tsconfig.build.json",
+    "build": "bun run clean && bun build src/index.ts --outdir dist --target node && tsc -b",
     "clean": "rm -rf dist",
     "dev": "bun build src/index.ts --outdir dist --target node --watch",
     "lint": "eslint \"src/**/*.ts\" --fix",
diff --git a/packages/thumbnail/package.json b/packages/thumbnail/package.json
index 4f4b95d9..55f73053 100644
--- a/packages/thumbnail/package.json
+++ b/packages/thumbnail/package.json
@@ -17,7 +17,6 @@
     "build": "bun run clean && bun run build:browser && bun run build:node && bun run build:types",
     "build:browser": "bun build src/browser/index.ts --outdir dist/browser --target browser --external @napi-rs/canvas",
     "build:node": "bun build src/node/index.ts --outdir dist/node --target node",
-    "build:types": "tsc --project tsconfig.build.json",
     "clean": "rm -rf dist",
     "dev:browser": "bun build src/browser/index.ts --outdir dist/browser --target node --watch",
     "dev:node": "bun build src/node/index.ts --outdir dist/node --target node --watch",

From bcf7af3a5ef0d04f04698fcf753edcbef1561ac4 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 01:24:11 -0300
Subject: [PATCH 026/111] chore: add `typecheck` command to workspace root

Runs against the root `tsconfig.json`, which defines the build graph for the entire project.
The `-b` option actually makes sure the entire chain is built, then reports the errors.
---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index ec99f8c3..1338fdd6 100644
--- a/package.json
+++ b/package.json
@@ -54,6 +54,7 @@
     "dev:web": "bun run --filter '@nbw/frontend' dev",
     "dev:apps": "bun run --filter './apps/*' dev",
     "dev": "concurrently --names 'backend,frontend' --prefix-colors 'cyan,magenta' 'cd apps/backend && bun run start:dev' 'cd apps/frontend && bun run dev'",
+    "typecheck": "tsc -b --noEmit",
     "lint": "eslint \"**/*.{ts,tsx}\" --fix",
     "lint:check": "eslint \"**/*.{ts,tsx}\"",
     "format": "prettier --write .",

From 2b0eeff7cfb8230236932af535e92435432cf48d Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 01:51:10 -0300
Subject: [PATCH 027/111] chore: make backend and frontend TS projects
 `composite` (following root `references`)

---
 apps/backend/tsconfig.json  | 1 +
 apps/frontend/tsconfig.json | 1 +
 2 files changed, 2 insertions(+)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 7dc80e0f..08d461db 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
+    "composite": true,
     // NestJS specific settings
     "module": "commonjs",
     "target": "ES2021",
diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index 515247c9..3a86295a 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
+    "composite": true,
     // Next.js specific settings
     "target": "es5",
     "lib": ["dom", "dom.iterable", "esnext"],

From 67daa09515d1f682936b58e205dd1ac7ba312ccc Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 01:52:21 -0300
Subject: [PATCH 028/111] chore: clean up frontend's `tsconfig.json`

- Removes no-op duplication
- Removes redundant configs (e.g. strictNullChecks, noImplicitAny, strictBindCallApply already included in strict: true)
---
 apps/frontend/tsconfig.json | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index 3a86295a..f4228eeb 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -16,9 +16,6 @@
     "isolatedModules": true,
     // Override base strict settings for Next.js compatibility
     "strict": true,
-    "strictNullChecks": true,
-    "noImplicitAny": true,
-    "strictBindCallApply": true,
     "strictPropertyInitialization": false,
     // Next.js plugins and types
     "plugins": [
@@ -38,10 +35,5 @@
     "**/*.tsx",
     "**/*.mdx",
     ".next/types/**/*.ts"
-  ],
-  "types": ["mdx"],
-  // Path mapping
-  "paths": {
-    "@web/*": ["./src/*"]
-  }
+  ]
 }

From dc7f599edb553cdd2f33b58e1f35bed91687a243 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 11:43:37 -0300
Subject: [PATCH 029/111] chore: clean up backend's `tsconfig.json`

- Merged `baseUrl` into `paths`
- Removed exclusion of tests, node_modules and dist
- Included `scripts` folder in the config
- Removed relaxed strict settings (pitfall)
- Removed redundant `outDir` (already defined in base config)
- Add missing comment in start section
- Remove tsconfig.build.json (no longer necessary)
---
 apps/backend/tsconfig.build.json |  4 ----
 apps/backend/tsconfig.json       | 13 ++-----------
 2 files changed, 2 insertions(+), 15 deletions(-)
 delete mode 100644 apps/backend/tsconfig.build.json

diff --git a/apps/backend/tsconfig.build.json b/apps/backend/tsconfig.build.json
deleted file mode 100644
index 64f86c6b..00000000
--- a/apps/backend/tsconfig.build.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
-}
diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 08d461db..64ed9240 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -9,20 +9,11 @@
     "removeComments": true,
     "allowSyntheticDefaultImports": true,
     "sourceMap": true,
-    "outDir": "./dist",
-    "baseUrl": "./",
     "emitDecoratorMetadata": true,
-    // Relaxed strict settings for backend
-    "strictNullChecks": false,
-    "noImplicitAny": false,
-    "strictBindCallApply": false,
-    "forceConsistentCasingInFileNames": false,
-    "noFallthroughCasesInSwitch": false,
     // Path mapping
     "paths": {
-      "@server/*": ["src/*"]
+      "@server/*": ["./src/*"]
     }
   },
-  "include": ["src/**/*.ts", "src/**/*.d.ts"],
-  "exclude": ["node_modules", "dist", "e2e/**/*", "test/**/*"]
+  "include": ["src", "scripts"]
 }

From 710d79e3803a3ef55f0b5791a6a1a4e1eb1935b9 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 11:51:33 -0300
Subject: [PATCH 030/111] style: add comments and line breaks to
 frontend/backend tsconfig

---
 apps/backend/tsconfig.json  | 3 +++
 apps/frontend/tsconfig.json | 5 +++++
 2 files changed, 8 insertions(+)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 64ed9240..be7af5a2 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
+    // This is a referenced package
     "composite": true,
+
     // NestJS specific settings
     "module": "commonjs",
     "target": "ES2021",
@@ -10,6 +12,7 @@
     "allowSyntheticDefaultImports": true,
     "sourceMap": true,
     "emitDecoratorMetadata": true,
+
     // Path mapping
     "paths": {
       "@server/*": ["./src/*"]
diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index f4228eeb..fe8b9aea 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
+    // This is a referenced package
     "composite": true,
+
     // Next.js specific settings
     "target": "es5",
     "lib": ["dom", "dom.iterable", "esnext"],
@@ -14,9 +16,11 @@
     "esModuleInterop": true,
     "resolveJsonModule": true,
     "isolatedModules": true,
+
     // Override base strict settings for Next.js compatibility
     "strict": true,
     "strictPropertyInitialization": false,
+
     // Next.js plugins and types
     "plugins": [
       {
@@ -24,6 +28,7 @@
       }
     ],
     "types": ["mdx"],
+
     // Path mapping
     "paths": {
       "@web/*": ["./src/*"]

From b5e6023ea2f601fa146b6e96313ff38d8cac6a43 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 12:58:48 -0300
Subject: [PATCH 031/111] style: fully comment settings in base and package
 `tsconfig.json`

---
 tsconfig.base.json    | 42 +++++++++++++++++++++++++++++++++++++-----
 tsconfig.package.json | 36 ++++++++++++++++++++++++++++++++----
 2 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/tsconfig.base.json b/tsconfig.base.json
index 66165032..5f5450ea 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -1,17 +1,49 @@
 {
   "compilerOptions": {
+    // Default output directory.
+    // Actual emitting is controlled by extending configs (packages/apps).
     "outDir": "./dist",
-    // Base strict settings
+
+    // ==============================
+    // Global type-safety invariant
+    // ==============================
+
+    // These rules define the minimum safety bar for the entire repo.
+    // Disabling any of its sub-rules should be rare and explicitly justified.
     "strict": true,
-    "skipLibCheck": true,
+
+    // Disabled to allow compatibility with frameworks and libraries that
+    // initialize fields outside constructors (e.g. ORMs, DI containers).
+    "strictPropertyInitialization": false,
+
+    // Prevents subtle runtime bugs caused by switch fallthrough.
     "noFallthroughCasesInSwitch": true,
+
+    // Enforces consistent file casing across platforms (Windows/macOS/Linux).
     "forceConsistentCasingInFileNames": true,
-    "strictPropertyInitialization": false,
-    // Modern JavaScript features
+
+    // Improves build performance by skipping type-checking of .d.ts files.
+    // Safe as long as dependencies are trusted.
+    "skipLibCheck": true,
+
+    // ==============================
+    // Language & runtime model
+    // ==============================
+
+    // Target modern runtimes; downleveling is handled by bundlers if needed.
     "target": "ESNext",
     "lib": ["ESNext"],
+
+    // Forces explicit module boundaries.
+    // Prevents accidental global scripts and implicit module inference.
     "moduleDetection": "force",
-    // Decorator support for backend compatibility
+
+    // ==============================
+    // Decorators (backend / ORM support)
+    // ==============================
+
+    // Required for libraries relying on legacy decorators and runtime metadata
+    // (e.g. class-validator).
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true
   }
diff --git a/tsconfig.package.json b/tsconfig.package.json
index fd9a1265..4fdac436 100644
--- a/tsconfig.package.json
+++ b/tsconfig.package.json
@@ -1,20 +1,48 @@
 {
   "extends": "./tsconfig.base.json",
   "compilerOptions": {
-    // Package-specific settings
+    // ==============================
+    // Project reference participation
+    // ==============================
+
+    // Required for tsc --build and incremental compilation.
     "composite": true,
+
+    // Packages emit types only; JS output is handled by bundlers.
     "noEmit": false,
     "emitDeclarationOnly": true,
     "declaration": true,
     "outDir": "dist",
-    // Modern bundler mode
+
+    // ==============================
+    // Module system (bundler-friendly)
+    // ==============================
+
+    // Preserve native ESM syntax and let the bundler handle resolution.
     "module": "ESNext",
     "moduleResolution": "bundler",
+
+    // Do not rewrite imports/exports.
+    // Ensures the emitted .d.ts matches source semantics exactly.
     "verbatimModuleSyntax": true,
-    // Additional strict checks for packages
+
+    // ==============================
+    // Extra safety for library code
+    // ==============================
+
+    // Prevents unsafe indexed access (e.g. obj[key] returning undefined).
     "noUncheckedIndexedAccess": true,
+
+    // Requires `override` keyword when overriding class methods.
+    // Helps prevent accidental API mismatches.
     "noImplicitOverride": true,
-    // Relaxed flags (can be enabled per package)
+
+    // ==============================
+    // Linting rules
+    // ==============================
+
+    // Disabled since they are covered by ESLint rules.
+    // Can be enabled in individual packages if desired.
     "noUnusedLocals": false,
     "noUnusedParameters": false,
     "noPropertyAccessFromIndexSignature": false

From f508b89accefe53e81981f45bb07394db3589806 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 4 Jan 2026 13:01:35 -0300
Subject: [PATCH 032/111] chore: add type checking workflow on push and pull
 request

---
 .github/workflows/typecheck.yml | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 .github/workflows/typecheck.yml

diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
new file mode 100644
index 00000000..f1b4d8cc
--- /dev/null
+++ b/.github/workflows/typecheck.yml
@@ -0,0 +1,32 @@
+name: Type Check
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+  pull_request:
+    branches:
+      - develop
+      - main
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    env:
+      THUMBNAIL_URL: ${{ vars.THUMBNAIL_URL }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Type check (project references)
+        run: bun run typecheck

From a0115043008d850d743bb5752c70a93f83b0d3b4 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 19:49:16 -0300
Subject: [PATCH 033/111] chore: add `eslint-import-resolver-typescript`
 dependency

---
 bun.lock     | 31 +++++++++++++++++++++++--------
 package.json |  1 +
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/bun.lock b/bun.lock
index a7ed6734..b2cdbafe 100644
--- a/bun.lock
+++ b/bun.lock
@@ -17,6 +17,7 @@
         "concurrently": "^9.2.1",
         "eslint": "^9.36.0",
         "eslint-config-prettier": "^8.10.2",
+        "eslint-import-resolver-typescript": "^4.4.4",
         "eslint-plugin-import": "^2.32.0",
         "eslint-plugin-mdx": "^3.6.2",
         "eslint-plugin-unused-imports": "^4.2.0",
@@ -1668,9 +1669,11 @@
 
     "eslint-config-prettier": ["eslint-config-prettier@8.10.2", "", { "peerDependencies": { "eslint": ">=7.0.0" }, "bin": { "eslint-config-prettier": "bin/cli.js" } }, "sha512-/IGJ6+Dka158JnP5n5YFMOszjDWrXggGz1LaK/guZq9vZTmniaKlHcsscvkAhn9y4U+BU3JuUdYvtAMcv30y4A=="],
 
+    "eslint-import-context": ["eslint-import-context@0.1.9", "", { "dependencies": { "get-tsconfig": "^4.10.1", "stable-hash-x": "^0.2.0" }, "peerDependencies": { "unrs-resolver": "^1.0.0" }, "optionalPeers": ["unrs-resolver"] }, "sha512-K9Hb+yRaGAGUbwjhFNHvSmmkZs9+zbuoe3kFQ4V1wYjrepUFYM2dZAfNtjbbj3qsPfUfsA68Bx/ICWQMi+C8Eg=="],
+
     "eslint-import-resolver-node": ["eslint-import-resolver-node@0.3.9", "", { "dependencies": { "debug": "^3.2.7", "is-core-module": "^2.13.0", "resolve": "^1.22.4" } }, "sha512-WFj2isz22JahUv+B788TlO3N6zL3nNJGU8CcZbPZvVEkBPaJdCV4vy5wyghty5ROFbCRnm132v8BScu5/1BQ8g=="],
 
-    "eslint-import-resolver-typescript": ["eslint-import-resolver-typescript@3.10.1", "", { "dependencies": { "@nolyfill/is-core-module": "1.0.39", "debug": "^4.4.0", "get-tsconfig": "^4.10.0", "is-bun-module": "^2.0.0", "stable-hash": "^0.0.5", "tinyglobby": "^0.2.13", "unrs-resolver": "^1.6.2" }, "peerDependencies": { "eslint": "*", "eslint-plugin-import": "*", "eslint-plugin-import-x": "*" }, "optionalPeers": ["eslint-plugin-import", "eslint-plugin-import-x"] }, "sha512-A1rHYb06zjMGAxdLSkN2fXPBwuSaQ0iO5M/hdyS0Ajj1VBaRp0sPD3dn1FhME3c/JluGFbwSxyCfqdSbtQLAHQ=="],
+    "eslint-import-resolver-typescript": ["eslint-import-resolver-typescript@4.4.4", "", { "dependencies": { "debug": "^4.4.1", "eslint-import-context": "^0.1.8", "get-tsconfig": "^4.10.1", "is-bun-module": "^2.0.0", "stable-hash-x": "^0.2.0", "tinyglobby": "^0.2.14", "unrs-resolver": "^1.7.11" }, "peerDependencies": { "eslint": "*", "eslint-plugin-import": "*", "eslint-plugin-import-x": "*" }, "optionalPeers": ["eslint-plugin-import", "eslint-plugin-import-x"] }, "sha512-1iM2zeBvrYmUNTj2vSC/90JTHDth+dfOfiNKkxApWRsTJYNrc8rOdxxIf5vazX+BiAXTeOT0UvWpGI/7qIWQOw=="],
 
     "eslint-mdx": ["eslint-mdx@3.6.2", "", { "dependencies": { "acorn": "^8.15.0", "acorn-jsx": "^5.3.2", "espree": "^9.6.1 || ^10.4.0", "estree-util-visit": "^2.0.0", "remark-mdx": "^3.1.0", "remark-parse": "^11.0.0", "remark-stringify": "^11.0.0", "synckit": "^0.11.8", "unified": "^11.0.5", "unified-engine": "^11.2.2", "unist-util-visit": "^5.0.0", "uvu": "^0.5.6", "vfile": "^6.0.3" }, "peerDependencies": { "eslint": ">=8.0.0", "remark-lint-file-extension": "*" }, "optionalPeers": ["remark-lint-file-extension"] }, "sha512-5hczn5iSSEcwtNtVXFwCKIk6iLEDaZpwc3vjYDl/B779OzaAAK/ou16J2xVdO6ecOLEO1WZqp7MRCQ/WsKDUig=="],
 
@@ -2626,7 +2629,7 @@
 
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
-    "picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+    "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
     "pidtree": ["pidtree@0.6.0", "", { "bin": { "pidtree": "bin/pidtree.js" } }, "sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g=="],
 
@@ -2898,6 +2901,8 @@
 
     "stable-hash": ["stable-hash@0.0.5", "", {}, "sha512-+L3ccpzibovGXFK+Ap/f8LOS0ahMrHTf3xu7mMLSpEGU0EO9ucaysSylKo9eRDFNhWve/y275iPmIZ4z39a9iA=="],
 
+    "stable-hash-x": ["stable-hash-x@0.2.0", "", {}, "sha512-o3yWv49B/o4QZk5ZcsALc6t0+eCelPc44zZsLtCQnZPDwFpDYSWcDnrv2TtMmMbQ7uKo3J0HTURCqckw23czNQ=="],
+
     "stack-utils": ["stack-utils@2.0.6", "", { "dependencies": { "escape-string-regexp": "^2.0.0" } }, "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ=="],
 
     "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
@@ -3424,6 +3429,8 @@
 
     "ansi-escapes/type-fest": ["type-fest@0.21.3", "", {}, "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w=="],
 
+    "anymatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "babel-plugin-istanbul/istanbul-lib-instrument": ["istanbul-lib-instrument@5.2.1", "", { "dependencies": { "@babel/core": "^7.12.3", "@babel/parser": "^7.14.7", "@istanbuljs/schema": "^0.1.2", "istanbul-lib-coverage": "^3.2.0", "semver": "^6.3.0" } }, "sha512-pzqtp31nLv/XFOzXGuvhCb8qhjmTVo5vjVk19XE4CRlSWz0KoeJ3bw9XsA7nOp9YBf4qHjwBxkDzKcME/J29Yg=="],
 
     "bl/readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
@@ -3456,6 +3463,8 @@
 
     "eslint/ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
 
+    "eslint-config-next/eslint-import-resolver-typescript": ["eslint-import-resolver-typescript@3.10.1", "", { "dependencies": { "@nolyfill/is-core-module": "1.0.39", "debug": "^4.4.0", "get-tsconfig": "^4.10.0", "is-bun-module": "^2.0.0", "stable-hash": "^0.0.5", "tinyglobby": "^0.2.13", "unrs-resolver": "^1.6.2" }, "peerDependencies": { "eslint": "*", "eslint-plugin-import": "*", "eslint-plugin-import-x": "*" }, "optionalPeers": ["eslint-plugin-import", "eslint-plugin-import-x"] }, "sha512-A1rHYb06zjMGAxdLSkN2fXPBwuSaQ0iO5M/hdyS0Ajj1VBaRp0sPD3dn1FhME3c/JluGFbwSxyCfqdSbtQLAHQ=="],
+
     "eslint-config-next/globals": ["globals@16.4.0", "", {}, "sha512-ob/2LcVVaVGCYN+r14cnwnoDPUufjiYgSqRhiFD0Q1iI4Odora5RE8Iv1D24hAz5oMophRGkGz+yuvQmmUMnMw=="],
 
     "eslint-import-resolver-node/debug": ["debug@3.2.7", "", { "dependencies": { "ms": "^2.1.1" } }, "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ=="],
@@ -3474,8 +3483,6 @@
 
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
-    "fdir/picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
-
     "filelist/minimatch": ["minimatch@5.1.6", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g=="],
 
     "fixpack/chalk": ["chalk@3.0.0", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-4D3B6Wf41KOYRFdszmDqMCGq5VV/uMAB273JILmO+3jAlh8X4qDtdtgCR3fxtbLEMzSx22QdhnDcJvu2u1fVwg=="],
@@ -3540,8 +3547,6 @@
 
     "jest-snapshot/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
 
-    "jest-util/picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
-
     "jest-watcher/@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
 
     "js-beautify/glob": ["glob@10.4.5", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg=="],
@@ -3568,6 +3573,8 @@
 
     "make-dir/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
 
+    "micromatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "mjml-cli/chokidar": ["chokidar@3.6.0", "", { "dependencies": { "anymatch": "~3.1.2", "braces": "~3.0.2", "glob-parent": "~5.1.2", "is-binary-path": "~2.1.0", "is-glob": "~4.0.1", "normalize-path": "~3.0.0", "readdirp": "~3.6.0" }, "optionalDependencies": { "fsevents": "~2.3.2" } }, "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw=="],
 
     "mjml-cli/glob": ["glob@10.4.5", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg=="],
@@ -3968,8 +3975,6 @@
 
     "test-exclude/glob": ["glob@7.1.7", "", { "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", "minimatch": "^3.0.4", "once": "^1.3.0", "path-is-absolute": "^1.0.0" } }, "sha512-OvD9ENzPLbegENnYP5UUfJIirTg4+XwMWGaQfQTY0JenxNvvIKP3U3/tAQSPIu/lHxXYSZmpXlUHeqAIdKzBLQ=="],
 
-    "tinyglobby/picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
-
     "ts-jest/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
 
     "ts-loader/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
@@ -4066,6 +4071,8 @@
 
     "@jest/transform/jest-util/ci-info": ["ci-info@3.9.0", "", {}, "sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ=="],
 
+    "@jest/transform/jest-util/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "@nbw/backend/@types/bun/bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
 
     "@nbw/backend/@types/node/undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
@@ -4188,6 +4195,8 @@
 
     "create-jest/jest-util/ci-info": ["ci-info@3.9.0", "", {}, "sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ=="],
 
+    "create-jest/jest-util/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "editorconfig/minimatch/brace-expansion": ["brace-expansion@2.0.2", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ=="],
 
     "eslint-plugin-import/tsconfig-paths/json5": ["json5@1.0.2", "", { "dependencies": { "minimist": "^1.2.0" }, "bin": { "json5": "lib/cli.js" } }, "sha512-g1MWMLBiz8FKi1e4w0UyVL3w+iJceWAFBAaBnnGKOpNa5f8TLktkbre1+s6oICydWAm+HRUGTmI+//xv2hvXYA=="],
@@ -4528,6 +4537,8 @@
 
     "log-update/cli-cursor/restore-cursor/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
 
+    "mjml-cli/chokidar/readdirp/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "mjml-cli/glob/path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
 
     "multer/type-is/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
@@ -4642,6 +4653,8 @@
 
     "@nbw/thumbnail/jest/@jest/core/jest-snapshot/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
 
+    "@nbw/thumbnail/jest/@jest/core/jest-util/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "@nbw/thumbnail/jest/@jest/core/pretty-format/@jest/schemas": ["@jest/schemas@29.6.3", "", { "dependencies": { "@sinclair/typebox": "^0.27.8" } }, "sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA=="],
 
     "@nbw/thumbnail/jest/@jest/core/pretty-format/ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
@@ -4672,6 +4685,8 @@
 
     "@nbw/thumbnail/jest/jest-cli/jest-util/ci-info": ["ci-info@3.9.0", "", {}, "sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ=="],
 
+    "@nbw/thumbnail/jest/jest-cli/jest-util/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
     "@nbw/thumbnail/jest/jest-cli/jest-validate/pretty-format": ["pretty-format@29.7.0", "", { "dependencies": { "@jest/schemas": "^29.6.3", "ansi-styles": "^5.0.0", "react-is": "^18.0.0" } }, "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ=="],
 
     "@nestjs/mongoose/mongoose/mongodb/mongodb-connection-string-url/@types/whatwg-url": ["@types/whatwg-url@8.2.2", "", { "dependencies": { "@types/node": "*", "@types/webidl-conversions": "*" } }, "sha512-FtQu10RWgn3D9U4aazdwIE2yzphmTJREDqNdODHrbrZmmMqI0vMheC/6NE/J1Yveaj8H+ela+YwWTjq5PGmuhA=="],
diff --git a/package.json b/package.json
index 1338fdd6..6d8e442f 100644
--- a/package.json
+++ b/package.json
@@ -82,6 +82,7 @@
     "concurrently": "^9.2.1",
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^8.10.2",
+    "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-mdx": "^3.6.2",
     "eslint-plugin-unused-imports": "^4.2.0",

From 06dbb5c5dd56f709bb404aa9cf120d74126847e9 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 19:52:36 -0300
Subject: [PATCH 034/111] chore: add separate TS config for ESLint

- add `tsconfig.eslint.json`
- unify projects under ESLint config
- make all TS configs in monorepo visible to parser

Result: ESLint treats the project as a single, cohesive unit rather than separate projects.
---
 eslint.config.mjs    | 13 ++++++++-----
 tsconfig.eslint.json | 20 ++++++++++++++++++++
 2 files changed, 28 insertions(+), 5 deletions(-)
 create mode 100644 tsconfig.eslint.json

diff --git a/eslint.config.mjs b/eslint.config.mjs
index 688d6684..dedf562d 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -31,6 +31,13 @@ export default defineConfig(
   {
     files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}'],
     languageOptions: {
+      parserOptions: {
+        project: [
+          './tsconfig.base.json',
+          './packages/*/tsconfig.json',
+          './apps/*/tsconfig.json',
+        ],
+      },
       globals: { ...globals.node, ...globals.es2021, ...globals.bun },
     },
     plugins: {
@@ -40,11 +47,7 @@ export default defineConfig(
     settings: {
       'import/resolver': {
         typescript: {
-          project: [
-            'apps/*/tsconfig.json',
-            'packages/*/tsconfig.json',
-            './tsconfig.json',
-          ],
+          project: './tsconfig.eslint.json',
         },
         node: true,
       },
diff --git a/tsconfig.eslint.json b/tsconfig.eslint.json
new file mode 100644
index 00000000..a627c79a
--- /dev/null
+++ b/tsconfig.eslint.json
@@ -0,0 +1,20 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@web/*": ["apps/frontend/src/*"],
+      "@server/*": ["apps/backend/src/*"]
+    }
+  },
+  "references": [
+    { "path": "apps/frontend" },
+    { "path": "apps/backend" },
+    { "path": "packages/configs" },
+    { "path": "packages/database" },
+    { "path": "packages/song" },
+    { "path": "packages/sounds" },
+    { "path": "packages/thumbnail" }
+  ]
+}

From 2b3c4a761eea61990603a01349c65ea6d121ef09 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 19:53:32 -0300
Subject: [PATCH 035/111] chore: add `baseUrl` and `@nbw` path alias to root TS
 config

---
 tsconfig.base.json | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tsconfig.base.json b/tsconfig.base.json
index 5f5450ea..18ce6011 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -4,6 +4,14 @@
     // Actual emitting is controlled by extending configs (packages/apps).
     "outDir": "./dist",
 
+    // Project root for module resolution.
+    "baseUrl": ".",
+
+    // Path mapping for monorepo packages.
+    "paths": {
+      "@nbw/*": ["packages/*"]
+    },
+
     // ==============================
     // Global type-safety invariant
     // ==============================

From 9faf154c9fcbb931481fefe9c0f4151699d194aa Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 19:58:13 -0300
Subject: [PATCH 036/111] chore: ensure that orchestrator TS config doesn't
 emit types

Prevents the file from being used for type generation at all.
---
 tsconfig.json | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tsconfig.json b/tsconfig.json
index 49978a90..48dd729b 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -5,6 +5,9 @@
 
   // This config does not type-check files directly.
   // Use `tsc -b` or `tsc -b --noEmit`.
+  "compilerOptions": {
+    "noEmit": true
+  },
   "files": [],
   "references": [
     { "path": "apps/frontend" },

From 79f2bf94f6289c62eea8a6914357367d53c4a4de Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 13:30:17 -0300
Subject: [PATCH 037/111] chore: remove `outDir` from base TS config

It's arguable whether we should govern where each individual package's output directory from the base config.

While it's okay to leave here as standardization, we oughtn't enforce this at the root level for every package, as exceptions may exist.

We've removed this setting from the root in favor of defining it explicitly in each package, which is something reasonable to keep their own responsibility (even if it requires some duplication).
---
 tsconfig.base.json    | 4 ----
 tsconfig.package.json | 1 -
 2 files changed, 5 deletions(-)

diff --git a/tsconfig.base.json b/tsconfig.base.json
index 18ce6011..b52ee70a 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -1,9 +1,5 @@
 {
   "compilerOptions": {
-    // Default output directory.
-    // Actual emitting is controlled by extending configs (packages/apps).
-    "outDir": "./dist",
-
     // Project root for module resolution.
     "baseUrl": ".",
 
diff --git a/tsconfig.package.json b/tsconfig.package.json
index 4fdac436..d4ac7340 100644
--- a/tsconfig.package.json
+++ b/tsconfig.package.json
@@ -12,7 +12,6 @@
     "noEmit": false,
     "emitDeclarationOnly": true,
     "declaration": true,
-    "outDir": "dist",
 
     // ==============================
     // Module system (bundler-friendly)

From 8498c2f3ad4e950ee20ddc64f1dd3da7b85a7edb Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 19:59:30 -0300
Subject: [PATCH 038/111] fix: add `baseUrl` to app TS configs

---
 apps/backend/tsconfig.json  | 3 ++-
 apps/frontend/tsconfig.json | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index be7af5a2..0a35d985 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -14,8 +14,9 @@
     "emitDecoratorMetadata": true,
 
     // Path mapping
+    "baseUrl": ".",
     "paths": {
-      "@server/*": ["./src/*"]
+      "@server/*": ["src/*"]
     }
   },
   "include": ["src", "scripts"]
diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index fe8b9aea..3780e8be 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -30,8 +30,9 @@
     "types": ["mdx"],
 
     // Path mapping
+    "baseUrl": ".",
     "paths": {
-      "@web/*": ["./src/*"]
+      "@web/*": ["src/*"]
     }
   },
   "include": [

From f85b959d560f3afb0fbaecbb6b8b881d2303d003 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 20:07:34 -0300
Subject: [PATCH 039/111] fix: ensure types are emitted in `configs` package
 through `rootDir` and `outDir`

---
 packages/configs/tsconfig.json | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/configs/tsconfig.json b/packages/configs/tsconfig.json
index 7c179325..e7c50a5e 100644
--- a/packages/configs/tsconfig.json
+++ b/packages/configs/tsconfig.json
@@ -1,4 +1,11 @@
 {
   "extends": "../../tsconfig.package.json",
-  "include": ["src"]
+  "compilerOptions": {
+    // Explicit rootDir ensures that TypeScript emits declaration files.
+    // Required for small or reference-only packages where TS cannot
+    // infer a stable project root (the case for this 'config' package).
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
 }

From ab269fc9f2902f44e1a42a58784b199f481549bb Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 5 Jan 2026 20:09:00 -0300
Subject: [PATCH 040/111] fix: enforce `src -> dist` output structure for all
 packages

---
 packages/database/tsconfig.json  | 6 +++++-
 packages/song/tsconfig.json      | 6 +++++-
 packages/sounds/tsconfig.json    | 6 +++++-
 packages/thumbnail/tsconfig.json | 6 +++++-
 4 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/packages/database/tsconfig.json b/packages/database/tsconfig.json
index 42d932fb..c2e8e762 100644
--- a/packages/database/tsconfig.json
+++ b/packages/database/tsconfig.json
@@ -1,7 +1,11 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+
     // Database-specific settings
     "emitDecoratorMetadata": true // Necessary for class-validator
-  }
+  },
+  "include": ["src/**/*.ts"]
 }
diff --git a/packages/song/tsconfig.json b/packages/song/tsconfig.json
index 7c179325..e83ed4d3 100644
--- a/packages/song/tsconfig.json
+++ b/packages/song/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.package.json",
-  "include": ["src"]
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
 }
diff --git a/packages/sounds/tsconfig.json b/packages/sounds/tsconfig.json
index 7c179325..e83ed4d3 100644
--- a/packages/sounds/tsconfig.json
+++ b/packages/sounds/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.package.json",
-  "include": ["src"]
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
 }
diff --git a/packages/thumbnail/tsconfig.json b/packages/thumbnail/tsconfig.json
index 168733fc..0fec8883 100644
--- a/packages/thumbnail/tsconfig.json
+++ b/packages/thumbnail/tsconfig.json
@@ -1,7 +1,11 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+
     // DOM support for canvas operations
     "lib": ["dom", "dom.iterable", "esnext"]
-  }
+  },
+  "include": ["src/**/*.ts"]
 }

From 4eab8c956f47a0d81b53ad388379735b5a08a8e5 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 12:50:44 -0300
Subject: [PATCH 041/111] build: re-introduce separate `js` and `types` steps
 in database build

The `database` package is the one exception where builds aren't handled by our bundler (bun), but by tsc. In every other case, tsc only acts as a type genenerator. Here, we must open an exception to make sure the project builds correctly. But instead of using command-line flags to enable or disable emit, we explicitly configure different TS projects fitting each stage's requirements.
---
 packages/database/package.json        |  4 ++--
 packages/database/tsconfig.build.json | 21 +++++++++++++++++++++
 packages/database/tsconfig.json       |  4 ++--
 packages/database/tsconfig.types.json |  8 ++++++++
 4 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 packages/database/tsconfig.build.json
 create mode 100644 packages/database/tsconfig.types.json

diff --git a/packages/database/package.json b/packages/database/package.json
index 6b09960d..61e5d06f 100644
--- a/packages/database/package.json
+++ b/packages/database/package.json
@@ -17,8 +17,8 @@
   },
   "scripts": {
     "build": "bun run clean && bun run build:js && bun run build:types",
-    "build:js": "tsc --project tsconfig.build.json --declaration false --emitDeclarationOnly false",
-    "build:types": "tsc --project tsconfig.build.json --emitDeclarationOnly",
+    "build:js": "tsc --project tsconfig.build.json",
+    "build:types": "tsc --project tsconfig.types.json",
     "clean": "rm -rf dist",
     "dev": "tsc --project tsconfig.build.json --watch",
     "lint": "eslint \"src/**/*.ts\" --fix",
diff --git a/packages/database/tsconfig.build.json b/packages/database/tsconfig.build.json
new file mode 100644
index 00000000..0fc0958a
--- /dev/null
+++ b/packages/database/tsconfig.build.json
@@ -0,0 +1,21 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    // Unlike other packages where we use a bundler to output JS,
+    // this package uses tsc for its build step.
+    // We must disable the default 'composite' config to output JS.
+    "composite": false,
+    "declaration": false,
+    "emitDeclarationOnly": false,
+
+    // Module target for Node runtime
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "target": "ES2021",
+
+    // Allow ES imports
+    "verbatimModuleSyntax": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["**/*.spec.ts", "**/*.test.ts"]
+}
diff --git a/packages/database/tsconfig.json b/packages/database/tsconfig.json
index c2e8e762..0a4d9be7 100644
--- a/packages/database/tsconfig.json
+++ b/packages/database/tsconfig.json
@@ -4,8 +4,8 @@
     "rootDir": "src",
     "outDir": "dist",
 
-    // Database-specific settings
-    "emitDecoratorMetadata": true // Necessary for class-validator
+    // Database runtime requirements
+    "emitDecoratorMetadata": true
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/database/tsconfig.types.json b/packages/database/tsconfig.types.json
new file mode 100644
index 00000000..be175bda
--- /dev/null
+++ b/packages/database/tsconfig.types.json
@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    // Emit-only configuration for building types.
+    "declaration": true,
+    "emitDeclarationOnly": true
+  }
+}

From 774326d51b80f907029bd0f0794c8e101b97fed9 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 13:16:03 -0300
Subject: [PATCH 042/111] chore: ensure TS build cache files are output to
 `dist`

`tsconfig.tsbuildinfo` files were being emitted near `tsconfig.json` instead of `dist/`, which creates pollution and doesn't delete the files when the compilation must restart from scratch.

See:
https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile
---
 apps/backend/tsconfig.json       | 2 ++
 apps/frontend/tsconfig.json      | 2 ++
 packages/configs/tsconfig.json   | 3 ++-
 packages/database/tsconfig.json  | 1 +
 packages/song/tsconfig.json      | 3 ++-
 packages/sounds/tsconfig.json    | 3 ++-
 packages/thumbnail/tsconfig.json | 1 +
 7 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 0a35d985..d0e12899 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -3,6 +3,8 @@
   "compilerOptions": {
     // This is a referenced package
     "composite": true,
+    // Store build cache files in a non-source location
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // NestJS specific settings
     "module": "commonjs",
diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index 3780e8be..c851d984 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -3,6 +3,8 @@
   "compilerOptions": {
     // This is a referenced package
     "composite": true,
+    // Store build cache files in a non-source location
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // Next.js specific settings
     "target": "es5",
diff --git a/packages/configs/tsconfig.json b/packages/configs/tsconfig.json
index e7c50a5e..89fd5895 100644
--- a/packages/configs/tsconfig.json
+++ b/packages/configs/tsconfig.json
@@ -5,7 +5,8 @@
     // Required for small or reference-only packages where TS cannot
     // infer a stable project root (the case for this 'config' package).
     "rootDir": "src",
-    "outDir": "dist"
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/database/tsconfig.json b/packages/database/tsconfig.json
index 0a4d9be7..9547fe19 100644
--- a/packages/database/tsconfig.json
+++ b/packages/database/tsconfig.json
@@ -3,6 +3,7 @@
   "compilerOptions": {
     "rootDir": "src",
     "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // Database runtime requirements
     "emitDecoratorMetadata": true
diff --git a/packages/song/tsconfig.json b/packages/song/tsconfig.json
index e83ed4d3..5273baea 100644
--- a/packages/song/tsconfig.json
+++ b/packages/song/tsconfig.json
@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "dist"
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/sounds/tsconfig.json b/packages/sounds/tsconfig.json
index e83ed4d3..5273baea 100644
--- a/packages/sounds/tsconfig.json
+++ b/packages/sounds/tsconfig.json
@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "dist"
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/thumbnail/tsconfig.json b/packages/thumbnail/tsconfig.json
index 0fec8883..be7e6f6d 100644
--- a/packages/thumbnail/tsconfig.json
+++ b/packages/thumbnail/tsconfig.json
@@ -3,6 +3,7 @@
   "compilerOptions": {
     "rootDir": "src",
     "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // DOM support for canvas operations
     "lib": ["dom", "dom.iterable", "esnext"]

From d148680fced082bd9d52a452bc7ddaebead1926a Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 13:26:00 -0300
Subject: [PATCH 043/111] chore: let TS infer build cache output location as
 `dist/`

In [1], we have:

2. If rootDir and outDir are set, [...].
3. If outDir is set, [...].

3) is actually the behavior we want, and it comes by default (without needing to specify `tsBuildInfoFile` in the config) if we remove `rootDir` from the configuration. Then, what's going to happen, as per [2], is:

"The inferred value for rootDir is the longest common path of all non-declaration input files [...]".

So it resolves to `src` in our projects without us needing to be explicit!

See:
[1] https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile
[2] https://www.typescriptlang.org/tsconfig/#rootDir
---
 apps/backend/tsconfig.json       | 3 ---
 apps/frontend/tsconfig.json      | 3 ---
 packages/configs/tsconfig.json   | 7 +------
 packages/database/tsconfig.json  | 2 --
 packages/song/tsconfig.json      | 4 +---
 packages/sounds/tsconfig.json    | 4 +---
 packages/thumbnail/tsconfig.json | 2 --
 7 files changed, 3 insertions(+), 22 deletions(-)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index d0e12899..461171ea 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -3,9 +3,6 @@
   "compilerOptions": {
     // This is a referenced package
     "composite": true,
-    // Store build cache files in a non-source location
-    "tsBuildInfoFile": "dist/.tsbuildinfo",
-
     // NestJS specific settings
     "module": "commonjs",
     "target": "ES2021",
diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index c851d984..50bec94e 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -3,9 +3,6 @@
   "compilerOptions": {
     // This is a referenced package
     "composite": true,
-    // Store build cache files in a non-source location
-    "tsBuildInfoFile": "dist/.tsbuildinfo",
-
     // Next.js specific settings
     "target": "es5",
     "lib": ["dom", "dom.iterable", "esnext"],
diff --git a/packages/configs/tsconfig.json b/packages/configs/tsconfig.json
index 89fd5895..50237165 100644
--- a/packages/configs/tsconfig.json
+++ b/packages/configs/tsconfig.json
@@ -1,12 +1,7 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    // Explicit rootDir ensures that TypeScript emits declaration files.
-    // Required for small or reference-only packages where TS cannot
-    // infer a stable project root (the case for this 'config' package).
-    "rootDir": "src",
-    "outDir": "dist",
-    "tsBuildInfoFile": "dist/.tsbuildinfo"
+    "outDir": "dist"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/database/tsconfig.json b/packages/database/tsconfig.json
index 9547fe19..ba7946ba 100644
--- a/packages/database/tsconfig.json
+++ b/packages/database/tsconfig.json
@@ -1,9 +1,7 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "rootDir": "src",
     "outDir": "dist",
-    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // Database runtime requirements
     "emitDecoratorMetadata": true
diff --git a/packages/song/tsconfig.json b/packages/song/tsconfig.json
index 5273baea..50237165 100644
--- a/packages/song/tsconfig.json
+++ b/packages/song/tsconfig.json
@@ -1,9 +1,7 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "tsBuildInfoFile": "dist/.tsbuildinfo"
+    "outDir": "dist"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/sounds/tsconfig.json b/packages/sounds/tsconfig.json
index 5273baea..50237165 100644
--- a/packages/sounds/tsconfig.json
+++ b/packages/sounds/tsconfig.json
@@ -1,9 +1,7 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "tsBuildInfoFile": "dist/.tsbuildinfo"
+    "outDir": "dist"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/thumbnail/tsconfig.json b/packages/thumbnail/tsconfig.json
index be7e6f6d..a3b1f8cd 100644
--- a/packages/thumbnail/tsconfig.json
+++ b/packages/thumbnail/tsconfig.json
@@ -1,9 +1,7 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "rootDir": "src",
     "outDir": "dist",
-    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // DOM support for canvas operations
     "lib": ["dom", "dom.iterable", "esnext"]

From 3dbd11f3fcae5438e268e75f771e1d7f4bb03360 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 16:19:32 -0300
Subject: [PATCH 044/111] fix: incorrect import alias in `database` package

---
 packages/database/src/song/dto/UploadSongDto.dto.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/database/src/song/dto/UploadSongDto.dto.ts b/packages/database/src/song/dto/UploadSongDto.dto.ts
index 5e9e3e08..8e973050 100644
--- a/packages/database/src/song/dto/UploadSongDto.dto.ts
+++ b/packages/database/src/song/dto/UploadSongDto.dto.ts
@@ -10,9 +10,10 @@ import {
   ValidateNested,
 } from 'class-validator';
 
-import type { SongDocument } from '@database/song/entity/song.entity';
 import { UPLOAD_CONSTANTS } from '@nbw/config';
 
+import type { SongDocument } from '../../song/entity/song.entity';
+
 import { ThumbnailData } from './ThumbnailData.dto';
 import type { CategoryType, LicenseType, VisibilityType } from './types';
 

From 0ca8c478f07ec2caf89dd8509e4fcb577f1c90d7 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 16:20:09 -0300
Subject: [PATCH 045/111] fix: `thumbnail` package using removed `build:types`
 script

---
 packages/thumbnail/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/thumbnail/package.json b/packages/thumbnail/package.json
index 55f73053..cd4b7ded 100644
--- a/packages/thumbnail/package.json
+++ b/packages/thumbnail/package.json
@@ -14,7 +14,7 @@
     }
   },
   "scripts": {
-    "build": "bun run clean && bun run build:browser && bun run build:node && bun run build:types",
+    "build": "bun run clean && bun run build:browser && bun run build:node && tsc -b",
     "build:browser": "bun build src/browser/index.ts --outdir dist/browser --target browser --external @napi-rs/canvas",
     "build:node": "bun build src/node/index.ts --outdir dist/node --target node",
     "clean": "rm -rf dist",

From 5d94120af9cce96cdedd565c04b79fa10d476ce1 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Tue, 6 Jan 2026 17:02:54 -0300
Subject: [PATCH 046/111] chore: remove `composite` from frontend and backend
 packages

"You should add `composite: true` to your `tsconfig.json` when creating a TypeScript library or shared component that will be referenced by other TypeScript projects, enabling faster, incremental builds and efficient dependency management in a monorepo setup, ensuring referenced projects are built first. It signals to the TypeScript compiler that this project outputs build information (`.tsbuildinfo`) for quick lookups and requires `declaration: true`."

See:
https://github.com/microsoft/TypeScript/issues/60465

https://stackoverflow.com/a/79383253/9045426

https://devblogs.microsoft.com/typescript/announcing-typescript-5-7-rc/#faster-project-ownership-checks-in-editors-for-composite-projects:~:text=every%20project%20that%20can%20be%20referenced%20by%20another%20(non%2Dworkspace)%20project%20must%20enable%20a%20flag%20called%20composite%2C
---
 apps/backend/tsconfig.json  | 2 --
 apps/frontend/tsconfig.json | 2 --
 2 files changed, 4 deletions(-)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 461171ea..400170a1 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -1,8 +1,6 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    // This is a referenced package
-    "composite": true,
     // NestJS specific settings
     "module": "commonjs",
     "target": "ES2021",
diff --git a/apps/frontend/tsconfig.json b/apps/frontend/tsconfig.json
index 50bec94e..0b662962 100644
--- a/apps/frontend/tsconfig.json
+++ b/apps/frontend/tsconfig.json
@@ -1,8 +1,6 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    // This is a referenced package
-    "composite": true,
     // Next.js specific settings
     "target": "es5",
     "lib": ["dom", "dom.iterable", "esnext"],

From 5e5bf4a6139f4969daf06484ce617f80407d52ba Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sat, 10 Jan 2026 17:16:00 -0300
Subject: [PATCH 047/111] chore: re-add `rootDir` and `tsInfoBuildFile` on
 package projects

---
 packages/configs/tsconfig.json   | 4 +++-
 packages/database/tsconfig.json  | 2 ++
 packages/song/tsconfig.json      | 4 +++-
 packages/sounds/tsconfig.json    | 4 +++-
 packages/thumbnail/tsconfig.json | 2 ++
 5 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/configs/tsconfig.json b/packages/configs/tsconfig.json
index 50237165..5273baea 100644
--- a/packages/configs/tsconfig.json
+++ b/packages/configs/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "outDir": "dist"
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/database/tsconfig.json b/packages/database/tsconfig.json
index ba7946ba..9547fe19 100644
--- a/packages/database/tsconfig.json
+++ b/packages/database/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
+    "rootDir": "src",
     "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // Database runtime requirements
     "emitDecoratorMetadata": true
diff --git a/packages/song/tsconfig.json b/packages/song/tsconfig.json
index 50237165..5273baea 100644
--- a/packages/song/tsconfig.json
+++ b/packages/song/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "outDir": "dist"
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/sounds/tsconfig.json b/packages/sounds/tsconfig.json
index 50237165..5273baea 100644
--- a/packages/sounds/tsconfig.json
+++ b/packages/sounds/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "outDir": "dist"
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/thumbnail/tsconfig.json b/packages/thumbnail/tsconfig.json
index a3b1f8cd..be7e6f6d 100644
--- a/packages/thumbnail/tsconfig.json
+++ b/packages/thumbnail/tsconfig.json
@@ -1,7 +1,9 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
+    "rootDir": "src",
     "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo",
 
     // DOM support for canvas operations
     "lib": ["dom", "dom.iterable", "esnext"]

From 3914f6a29c15a5ab31fe2c92088a8bcaa61008cc Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 17:37:04 -0300
Subject: [PATCH 048/111] chore: refactor build scripts and improve TypeScript
 configuration

- Updated build scripts in `configs` and `song` packages to streamline the build process using Bun.
- Added external packages to the build configuration to prevent bundling of specific dependencies.
- Enhanced TypeScript configuration by specifying `rootDir` for better output structure and organization.
- Introduced a new build script in the `configs` package to handle cleaning, building, and fixing declaration files.
- Updated `SongPreviewDto` to use a specific `VisibilityType` for improved type safety.
---
 apps/backend/scripts/build.ts                 |  22 ++--
 apps/frontend/next.config.mjs                 |   5 +-
 packages/configs/package.json                 |   2 +-
 packages/configs/scripts/build.ts             |  87 +++++++++++++
 packages/configs/tsconfig.json                |   3 +-
 .../database/src/song/dto/SongPreview.dto.ts  |   4 +-
 packages/song/package.json                    |   3 +-
 packages/song/scripts/build.ts                | 119 ++++++++++++++++++
 packages/song/src/types.ts                    |  27 +++-
 packages/song/tsconfig.json                   |   3 +-
 10 files changed, 257 insertions(+), 18 deletions(-)
 create mode 100644 packages/configs/scripts/build.ts
 create mode 100644 packages/song/scripts/build.ts

diff --git a/apps/backend/scripts/build.ts b/apps/backend/scripts/build.ts
index 5417739e..2dbb03c2 100644
--- a/apps/backend/scripts/build.ts
+++ b/apps/backend/scripts/build.ts
@@ -65,14 +65,20 @@ const build = async () => {
     target: 'bun',
     minify: false,
     sourcemap: 'linked',
-    external: optionalRequirePackages.filter((pkg) => {
-      try {
-        require(pkg);
-        return false;
-      } catch (_) {
-        return true;
-      }
-    }),
+    external: [
+      ...optionalRequirePackages.filter((pkg) => {
+        try {
+          require(pkg);
+          return false;
+        } catch (_) {
+          return true;
+        }
+      }),
+      '@nbw/config',
+      '@nbw/database',
+      '@nbw/song',
+      '@nbw/sounds',
+    ],
     splitting: true,
   });
 
diff --git a/apps/frontend/next.config.mjs b/apps/frontend/next.config.mjs
index cdcf10ed..46a3c3fd 100644
--- a/apps/frontend/next.config.mjs
+++ b/apps/frontend/next.config.mjs
@@ -4,6 +4,8 @@ import createMDX from '@next/mdx';
 
 const nextConfig = {
   pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
+  // Externalize packages that use Node.js built-in modules for server components
+  serverExternalPackages: ['@nbw/database', '@nbw/config'],
   // See: https://github.com/Automattic/node-canvas/issues/867#issuecomment-1925284985
   webpack: (config, { isServer }) => {
     config.externals.push({
@@ -12,8 +14,9 @@ const nextConfig = {
 
     // Prevent @nbw/thumbnail from being bundled on the server
     // It uses HTMLCanvasElement which is not available in Node.js
+    // Also externalize backend packages that use Node.js modules
     if (isServer) {
-      config.externals.push('@nbw/thumbnail');
+      config.externals.push('@nbw/thumbnail', '@nbw/database');
     }
 
     return config;
diff --git a/packages/configs/package.json b/packages/configs/package.json
index 8d0d3e69..26f7f0b5 100644
--- a/packages/configs/package.json
+++ b/packages/configs/package.json
@@ -13,7 +13,7 @@
     }
   },
   "scripts": {
-    "build": "bun run clean && bun build src/index.ts --outdir dist --target node && tsc -b",
+    "build": "bun run scripts/build.ts",
     "clean": "rm -rf dist",
     "dev": "bun build src/index.ts --outdir dist --target node --watch",
     "lint": "eslint \"src/**/*.ts\" --fix",
diff --git a/packages/configs/scripts/build.ts b/packages/configs/scripts/build.ts
new file mode 100644
index 00000000..b0444cc1
--- /dev/null
+++ b/packages/configs/scripts/build.ts
@@ -0,0 +1,87 @@
+import { $ } from 'bun';
+import { existsSync, readdirSync, renameSync, rmSync } from 'fs';
+import { join } from 'path';
+
+// When running via "bun run scripts/build.ts", process.cwd() is the package root
+const packageRoot = process.cwd();
+
+async function clean() {
+  const distPath = join(packageRoot, 'dist');
+  if (existsSync(distPath)) {
+    rmSync(distPath, { recursive: true, force: true });
+  }
+}
+
+async function buildWithBun() {
+  const result = await Bun.build({
+    entrypoints: [join(packageRoot, 'src', 'index.ts')],
+    outdir: join(packageRoot, 'dist'),
+    target: 'node',
+  });
+
+  if (!result.success) {
+    console.error('Bun build failed:', result.logs);
+    process.exit(1);
+  }
+
+  console.log('Bun build completed successfully');
+}
+
+async function buildTypes() {
+  // Change to package root directory for tsc command
+  const result = await $`cd ${packageRoot} && tsc -b`.quiet();
+
+  if (result.exitCode !== 0) {
+    console.error('TypeScript build failed');
+    process.exit(1);
+  }
+
+  console.log('TypeScript declaration files generated');
+}
+
+function fixDeclarationFiles() {
+  const distSrcPath = join(packageRoot, 'dist', 'src');
+  const distPath = join(packageRoot, 'dist');
+
+  if (existsSync(distSrcPath)) {
+    const files = readdirSync(distSrcPath);
+
+    // Move all .d.ts files from dist/src to dist
+    for (const file of files) {
+      if (file.endsWith('.d.ts')) {
+        const srcFile = join(distSrcPath, file);
+        const destFile = join(distPath, file);
+        renameSync(srcFile, destFile);
+        console.log(`Moved ${file} to dist/`);
+      }
+    }
+
+    // Remove the now-empty dist/src directory
+    try {
+      rmSync(distSrcPath, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore errors if directory is not empty or doesn't exist
+    }
+  }
+}
+
+async function build() {
+  console.log('Cleaning dist directory...');
+  await clean();
+
+  console.log('Building with Bun...');
+  await buildWithBun();
+
+  console.log('Building TypeScript declaration files...');
+  await buildTypes();
+
+  console.log('Fixing declaration file locations...');
+  fixDeclarationFiles();
+
+  console.log('Build completed successfully!');
+}
+
+build().catch((error) => {
+  console.error('Build failed:', error);
+  process.exit(1);
+});
diff --git a/packages/configs/tsconfig.json b/packages/configs/tsconfig.json
index 50237165..a80d76b2 100644
--- a/packages/configs/tsconfig.json
+++ b/packages/configs/tsconfig.json
@@ -1,7 +1,8 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "outDir": "dist"
+    "outDir": "dist",
+    "rootDir": "src"
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/database/src/song/dto/SongPreview.dto.ts b/packages/database/src/song/dto/SongPreview.dto.ts
index 58bdc344..38ce760a 100644
--- a/packages/database/src/song/dto/SongPreview.dto.ts
+++ b/packages/database/src/song/dto/SongPreview.dto.ts
@@ -2,6 +2,8 @@ import { IsNotEmpty, IsString, IsUrl, MaxLength } from 'class-validator';
 
 import type { SongWithUser } from '../../song/entity/song.entity';
 
+import type { VisibilityType } from './types';
+
 type SongPreviewUploader = {
   username: string;
   profileImage: string;
@@ -50,7 +52,7 @@ export class SongPreviewDto {
 
   @IsNotEmpty()
   @IsString()
-  visibility: string;
+  visibility: VisibilityType;
 
   constructor(partial: Partial<SongPreviewDto>) {
     Object.assign(this, partial);
diff --git a/packages/song/package.json b/packages/song/package.json
index 84a3e03c..612ae51e 100644
--- a/packages/song/package.json
+++ b/packages/song/package.json
@@ -15,7 +15,7 @@
     }
   },
   "scripts": {
-    "build": "bun run clean && bun run build:node && bun run build:browser && tsc -b",
+    "build": "bun run scripts/build.ts",
     "build:node": "bun build src/index.ts --outdir dist --target node && mv dist/index.js dist/index.node.js",
     "build:browser": "bun build src/index.ts --outdir dist --target browser && mv dist/index.js dist/index.browser.js",
     "clean": "rm -rf dist",
@@ -30,7 +30,6 @@
   },
   "dependencies": {
     "@encode42/nbs.js": "^5.0.2",
-    "@nbw/database": "workspace:*",
     "@timohausmann/quadtree-ts": "^2.2.2",
     "jszip": "^3.10.1",
     "unidecode": "^1.1.0"
diff --git a/packages/song/scripts/build.ts b/packages/song/scripts/build.ts
new file mode 100644
index 00000000..c3eb47a9
--- /dev/null
+++ b/packages/song/scripts/build.ts
@@ -0,0 +1,119 @@
+import { $ } from 'bun';
+import { existsSync, readdirSync, renameSync, rmSync } from 'fs';
+import { join } from 'path';
+
+// When running via "bun run scripts/build.ts", process.cwd() is the package root
+const packageRoot = process.cwd();
+
+async function clean() {
+  const distPath = join(packageRoot, 'dist');
+  if (existsSync(distPath)) {
+    rmSync(distPath, { recursive: true, force: true });
+  }
+}
+
+async function buildNode() {
+  const result = await Bun.build({
+    entrypoints: [join(packageRoot, 'src', 'index.ts')],
+    outdir: join(packageRoot, 'dist'),
+    target: 'node',
+  });
+
+  if (!result.success) {
+    console.error('Bun build (node) failed:', result.logs);
+    process.exit(1);
+  }
+
+  // Rename index.js to index.node.js
+  const indexJs = join(packageRoot, 'dist', 'index.js');
+  const indexNodeJs = join(packageRoot, 'dist', 'index.node.js');
+  if (existsSync(indexJs)) {
+    renameSync(indexJs, indexNodeJs);
+  }
+
+  console.log('Bun build (node) completed successfully');
+}
+
+async function buildBrowser() {
+  const result = await Bun.build({
+    entrypoints: [join(packageRoot, 'src', 'index.ts')],
+    outdir: join(packageRoot, 'dist'),
+    target: 'browser',
+  });
+
+  if (!result.success) {
+    console.error('Bun build (browser) failed:', result.logs);
+    process.exit(1);
+  }
+
+  // Rename index.js to index.browser.js
+  const indexJs = join(packageRoot, 'dist', 'index.js');
+  const indexBrowserJs = join(packageRoot, 'dist', 'index.browser.js');
+  if (existsSync(indexJs)) {
+    renameSync(indexJs, indexBrowserJs);
+  }
+
+  console.log('Bun build (browser) completed successfully');
+}
+
+async function buildTypes() {
+  // Change to package root directory for tsc command
+  const result = await $`cd ${packageRoot} && tsc -b`.quiet();
+
+  if (result.exitCode !== 0) {
+    console.error('TypeScript build failed');
+    process.exit(1);
+  }
+
+  console.log('TypeScript declaration files generated');
+}
+
+function fixDeclarationFiles() {
+  const distSrcPath = join(packageRoot, 'dist', 'src');
+  const distPath = join(packageRoot, 'dist');
+
+  if (existsSync(distSrcPath)) {
+    const files = readdirSync(distSrcPath);
+
+    // Move all .d.ts files from dist/src to dist
+    for (const file of files) {
+      if (file.endsWith('.d.ts')) {
+        const srcFile = join(distSrcPath, file);
+        const destFile = join(distPath, file);
+        renameSync(srcFile, destFile);
+        console.log(`Moved ${file} to dist/`);
+      }
+    }
+
+    // Remove the now-empty dist/src directory
+    try {
+      rmSync(distSrcPath, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore errors if directory is not empty or doesn't exist
+    }
+  }
+}
+
+async function build() {
+  console.log('Cleaning dist directory...');
+  await clean();
+
+  console.log('Building with Bun (node target)...');
+  await buildNode();
+
+  console.log('Building with Bun (browser target)...');
+  await buildBrowser();
+
+  console.log('Building TypeScript declaration files...');
+  await buildTypes();
+
+  console.log('Fixing declaration file locations...');
+  fixDeclarationFiles();
+
+  console.log('Build completed successfully!');
+}
+
+build().catch((error) => {
+  console.error('Build failed:', error);
+  process.exit(1);
+});
diff --git a/packages/song/src/types.ts b/packages/song/src/types.ts
index 1de71613..19dc4bbe 100644
--- a/packages/song/src/types.ts
+++ b/packages/song/src/types.ts
@@ -1,5 +1,3 @@
-import { SongStats } from '@nbw/database';
-
 import { NoteQuadTree } from './notes';
 
 export type SongFileType = {
@@ -30,4 +28,27 @@ export type Instrument = {
   count: number;
 };
 
-export type SongStatsType = InstanceType<typeof SongStats>;
+// Type definition matching SongStats from @nbw/database
+// Defined here to avoid pulling in backend dependencies
+export type SongStatsType = {
+  midiFileName: string;
+  noteCount: number;
+  tickCount: number;
+  layerCount: number;
+  tempo: number;
+  tempoRange: number[] | null;
+  timeSignature: number;
+  duration: number;
+  loop: boolean;
+  loopStartTick: number;
+  minutesSpent: number;
+  vanillaInstrumentCount: number;
+  customInstrumentCount: number;
+  firstCustomInstrumentIndex: number;
+  outOfRangeNoteCount: number;
+  detunedNoteCount: number;
+  customInstrumentNoteCount: number;
+  incompatibleNoteCount: number;
+  compatible: boolean;
+  instrumentNoteCounts: number[];
+};
diff --git a/packages/song/tsconfig.json b/packages/song/tsconfig.json
index 50237165..a80d76b2 100644
--- a/packages/song/tsconfig.json
+++ b/packages/song/tsconfig.json
@@ -1,7 +1,8 @@
 {
   "extends": "../../tsconfig.package.json",
   "compilerOptions": {
-    "outDir": "dist"
+    "outDir": "dist",
+    "rootDir": "src"
   },
   "include": ["src/**/*.ts"]
 }

From 9c75b72f229660c2af91dcaf05869fc500cdc3ca Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 17:54:41 -0300
Subject: [PATCH 049/111] refactor: update imports to use 'type' for TypeScript
 types in various components

---
 apps/frontend/src/app/(content)/search/page.tsx                 | 2 +-
 apps/frontend/src/app/(content)/song/[id]/page.tsx              | 2 +-
 apps/frontend/src/modules/browse/components/SongCard.tsx        | 2 +-
 .../browse/components/client/context/FeaturedSongs.context.tsx  | 2 +-
 .../browse/components/client/context/HomePage.context.tsx       | 2 +-
 .../browse/components/client/context/RecentSongs.context.tsx    | 2 +-
 .../frontend/src/modules/my-songs/components/client/SongRow.tsx | 2 +-
 .../src/modules/shared/components/layout/RandomSongButton.tsx   | 2 +-
 .../src/modules/song-edit/components/client/EditSongPage.tsx    | 2 +-
 .../src/modules/song/components/client/DownloadSongModal.tsx    | 2 +-
 apps/frontend/src/modules/song/components/client/SongCanvas.tsx | 2 +-
 11 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/apps/frontend/src/app/(content)/search/page.tsx b/apps/frontend/src/app/(content)/search/page.tsx
index 91ed2c49..de4388ee 100644
--- a/apps/frontend/src/app/(content)/search/page.tsx
+++ b/apps/frontend/src/app/(content)/search/page.tsx
@@ -17,7 +17,7 @@ import Skeleton from 'react-loading-skeleton';
 import { create } from 'zustand';
 
 import { UPLOAD_CONSTANTS, SEARCH_FEATURES, INSTRUMENTS } from '@nbw/config';
-import { SongPreviewDtoType } from '@nbw/database';
+import type { SongPreviewDtoType } from '@nbw/database';
 import axiosInstance from '@web/lib/axios';
 import LoadMoreButton from '@web/modules/browse/components/client/LoadMoreButton';
 import SongCard from '@web/modules/browse/components/SongCard';
diff --git a/apps/frontend/src/app/(content)/song/[id]/page.tsx b/apps/frontend/src/app/(content)/song/[id]/page.tsx
index 44d852c4..75a489d8 100644
--- a/apps/frontend/src/app/(content)/song/[id]/page.tsx
+++ b/apps/frontend/src/app/(content)/song/[id]/page.tsx
@@ -1,7 +1,7 @@
 import type { Metadata } from 'next';
 import { cookies } from 'next/headers';
 
-import { SongViewDtoType } from '@nbw/database';
+import type { SongViewDtoType } from '@nbw/database';
 import axios from '@web/lib/axios';
 import { SongPage } from '@web/modules/song/components/SongPage';
 
diff --git a/apps/frontend/src/modules/browse/components/SongCard.tsx b/apps/frontend/src/modules/browse/components/SongCard.tsx
index 33e62bfe..e2e3d4ac 100644
--- a/apps/frontend/src/modules/browse/components/SongCard.tsx
+++ b/apps/frontend/src/modules/browse/components/SongCard.tsx
@@ -5,7 +5,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import Link from 'next/link';
 import Skeleton from 'react-loading-skeleton';
 
-import { SongPreviewDtoType } from '@nbw/database';
+import type { SongPreviewDtoType } from '@nbw/database';
 import { formatDuration, formatTimeAgo } from '@web/modules/shared/util/format';
 
 import SongThumbnail from '../../shared/components/layout/SongThumbnail';
diff --git a/apps/frontend/src/modules/browse/components/client/context/FeaturedSongs.context.tsx b/apps/frontend/src/modules/browse/components/client/context/FeaturedSongs.context.tsx
index c61d116e..f9dda42b 100644
--- a/apps/frontend/src/modules/browse/components/client/context/FeaturedSongs.context.tsx
+++ b/apps/frontend/src/modules/browse/components/client/context/FeaturedSongs.context.tsx
@@ -4,7 +4,7 @@ import { useEffect } from 'react';
 import { create } from 'zustand';
 
 import { TIMESPANS } from '@nbw/config';
-import { type FeaturedSongsDto, type SongPreviewDto } from '@nbw/database';
+import type { FeaturedSongsDto, SongPreviewDto } from '@nbw/database';
 
 type TimespanType = (typeof TIMESPANS)[number];
 
diff --git a/apps/frontend/src/modules/browse/components/client/context/HomePage.context.tsx b/apps/frontend/src/modules/browse/components/client/context/HomePage.context.tsx
index f16a9346..fa0ec87b 100644
--- a/apps/frontend/src/modules/browse/components/client/context/HomePage.context.tsx
+++ b/apps/frontend/src/modules/browse/components/client/context/HomePage.context.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { FeaturedSongsDtoType, SongPreviewDtoType } from '@nbw/database';
+import type { FeaturedSongsDtoType, SongPreviewDtoType } from '@nbw/database';
 
 import {
   FeaturedSongsProvider,
diff --git a/apps/frontend/src/modules/browse/components/client/context/RecentSongs.context.tsx b/apps/frontend/src/modules/browse/components/client/context/RecentSongs.context.tsx
index dfb02318..8e5efd6d 100644
--- a/apps/frontend/src/modules/browse/components/client/context/RecentSongs.context.tsx
+++ b/apps/frontend/src/modules/browse/components/client/context/RecentSongs.context.tsx
@@ -3,7 +3,7 @@
 import { useEffect } from 'react';
 import { create } from 'zustand';
 
-import { PageDto, SongPreviewDtoType } from '@nbw/database';
+import type { PageDto, SongPreviewDtoType } from '@nbw/database';
 import axiosInstance from '@web/lib/axios';
 
 interface RecentSongsState {
diff --git a/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx b/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx
index a875b484..418e8f38 100644
--- a/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx
+++ b/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx
@@ -8,7 +8,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import Link from 'next/link';
 import Skeleton from 'react-loading-skeleton';
 
-import { SongPreviewDtoType } from '@nbw/database';
+import type { SongPreviewDtoType } from '@nbw/database';
 import SongThumbnail from '@web/modules/shared/components/layout/SongThumbnail';
 import { formatDuration } from '@web/modules/shared/util/format';
 
diff --git a/apps/frontend/src/modules/shared/components/layout/RandomSongButton.tsx b/apps/frontend/src/modules/shared/components/layout/RandomSongButton.tsx
index 6eeff915..9d82e188 100644
--- a/apps/frontend/src/modules/shared/components/layout/RandomSongButton.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/RandomSongButton.tsx
@@ -4,7 +4,7 @@ import { faDice } from '@fortawesome/free-solid-svg-icons';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import { useRouter } from 'next/navigation';
 
-import { PageDto, SongPreviewDto } from '@nbw/database';
+import type { PageDto, SongPreviewDto } from '@nbw/database';
 import axios from '@web/lib/axios';
 
 import { MusicalNote } from './MusicalNote';
diff --git a/apps/frontend/src/modules/song-edit/components/client/EditSongPage.tsx b/apps/frontend/src/modules/song-edit/components/client/EditSongPage.tsx
index 36be5f6a..e6da180d 100644
--- a/apps/frontend/src/modules/song-edit/components/client/EditSongPage.tsx
+++ b/apps/frontend/src/modules/song-edit/components/client/EditSongPage.tsx
@@ -1,4 +1,4 @@
-import { UploadSongDtoType } from '@nbw/database';
+import type { UploadSongDtoType } from '@nbw/database';
 import axiosInstance from '@web/lib/axios';
 import {
   getTokenServer,
diff --git a/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx b/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx
index b6095ef4..b1b75efa 100644
--- a/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx
+++ b/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx
@@ -2,7 +2,7 @@
 
 import { useState } from 'react';
 
-import { SongViewDtoType } from '@nbw/database';
+import type { SongViewDtoType } from '@nbw/database';
 import { DownloadPopupAdSlot } from '@web/modules/shared/components/client/ads/AdSlots';
 import GenericModal from '@web/modules/shared/components/client/GenericModal';
 
diff --git a/apps/frontend/src/modules/song/components/client/SongCanvas.tsx b/apps/frontend/src/modules/song/components/client/SongCanvas.tsx
index 0deb67a0..07e34e6d 100644
--- a/apps/frontend/src/modules/song/components/client/SongCanvas.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongCanvas.tsx
@@ -2,7 +2,7 @@
 
 import { useEffect, useRef } from 'react';
 
-import { SongViewDtoType } from '@nbw/database';
+import type { SongViewDtoType } from '@nbw/database';
 import axios from '@web/lib/axios';
 
 export const SongCanvas = ({ song }: { song: SongViewDtoType }) => {

From b323da581ecf3eef974a3d21a3438540edb4f14d Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 18:05:47 -0300
Subject: [PATCH 050/111] fix: BlogPageProps and HelpPageProps to use Promise
 for params

---
 apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx | 2 +-
 apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx b/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx
index cbc777ba..5773f799 100644
--- a/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx
@@ -7,7 +7,7 @@ import { PostType, getPostData } from '@web/lib/posts';
 import { CustomMarkdown } from '@web/modules/shared/components/CustomMarkdown';
 
 type BlogPageProps = {
-  params: { id: string };
+  params: Promise<{ id: string }>;
 };
 
 export async function generateMetadata({
diff --git a/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx b/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
index 5ace7da7..4f8ed867 100644
--- a/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
@@ -7,7 +7,7 @@ import { PostType, getPostData } from '@web/lib/posts';
 import { CustomMarkdown } from '@web/modules/shared/components/CustomMarkdown';
 
 type HelpPageProps = {
-  params: { id: string };
+  params: Promise<{ id: string }>;
 };
 
 export async function generateMetadata({

From ddec03c85e042c72becc1fe1a6c238fe02c6c24c Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 18:16:39 -0300
Subject: [PATCH 051/111] refactor: refactor search page components into
 dedicated module

---
 .../src/app/(content)/search/page.tsx         | 627 +-----------------
 .../modules/song-search/SearchSongPage.tsx    | 611 +++++++++++++++++
 2 files changed, 613 insertions(+), 625 deletions(-)
 create mode 100644 apps/frontend/src/modules/song-search/SearchSongPage.tsx

diff --git a/apps/frontend/src/app/(content)/search/page.tsx b/apps/frontend/src/app/(content)/search/page.tsx
index 91ed2c49..861c7620 100644
--- a/apps/frontend/src/app/(content)/search/page.tsx
+++ b/apps/frontend/src/app/(content)/search/page.tsx
@@ -1,631 +1,8 @@
 'use client';
 
-import {
-  faArrowDown19,
-  faArrowDown91,
-  faArrowDownAZ,
-  faArrowDownZA,
-  faEllipsis,
-  faFilter,
-} from '@fortawesome/free-solid-svg-icons';
-import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
-import Image from 'next/image';
-import Link from 'next/link';
-import { parseAsInteger, parseAsString, useQueryStates } from 'nuqs';
-import { Suspense, useEffect, useMemo, useState } from 'react';
-import Skeleton from 'react-loading-skeleton';
-import { create } from 'zustand';
+import { Suspense } from 'react';
 
-import { UPLOAD_CONSTANTS, SEARCH_FEATURES, INSTRUMENTS } from '@nbw/config';
-import { SongPreviewDtoType } from '@nbw/database';
-import axiosInstance from '@web/lib/axios';
-import LoadMoreButton from '@web/modules/browse/components/client/LoadMoreButton';
-import SongCard from '@web/modules/browse/components/SongCard';
-import SongCardGroup from '@web/modules/browse/components/SongCardGroup';
-import { DualRangeSlider } from '@web/modules/shared/components/ui/dualRangeSlider';
-import MultipleSelector from '@web/modules/shared/components/ui/multipleSelectorProps';
-
-interface SearchParams {
-  q?: string;
-  sort?: string;
-  order?: string;
-  category?: string;
-  uploader?: string;
-  limit?: number;
-  noteCountMin?: number;
-  noteCountMax?: number;
-  durationMin?: number;
-  durationMax?: number;
-  features?: string;
-  instruments?: string;
-}
-
-interface PageDto<T> {
-  content: T[];
-  page: number;
-  limit: number;
-  total: number;
-}
-
-// TODO: importing these enums from '@nbw/database' is causing issues.
-// They shouldn't be redefined here.
-enum SongSortType {
-  RECENT = 'recent',
-  RANDOM = 'random',
-  PLAY_COUNT = 'playCount',
-  TITLE = 'title',
-  DURATION = 'duration',
-  NOTE_COUNT = 'noteCount',
-}
-
-enum SongOrderType {
-  ASC = 'asc',
-  DESC = 'desc',
-}
-
-// TODO: refactor with PAGE_SIZE constant
-const PLACEHOLDER_COUNT = 12;
-
-const makePlaceholders = () =>
-  Array.from({ length: PLACEHOLDER_COUNT }, () => null);
-
-interface SongSearchState {
-  songs: Array<SongPreviewDtoType | null>;
-  loading: boolean;
-  hasMore: boolean;
-  currentPage: number;
-  totalResults: number;
-}
-
-interface SongSearchActions {
-  searchSongs: (params: SearchParams, pageNum: number) => Promise<void>;
-  loadMore: (params: SearchParams) => Promise<void>;
-}
-
-const initialState: SongSearchState = {
-  songs: [],
-  loading: true,
-  hasMore: true,
-  currentPage: 1,
-  totalResults: 0,
-};
-
-export const useSongSearchStore = create<SongSearchState & SongSearchActions>(
-  (set, get) => ({
-    ...initialState,
-
-    // The core data fetching action
-    searchSongs: async (params, pageNum) => {
-      // New search/sort (page 1): reset to placeholders. Load more: append placeholders.
-      if (pageNum === 1) {
-        set({
-          loading: true,
-          songs: makePlaceholders(),
-          currentPage: 1,
-          hasMore: true,
-        });
-      } else {
-        set((state) => ({
-          loading: true,
-          songs: [...state.songs, ...makePlaceholders()],
-        }));
-      }
-
-      try {
-        const response = await axiosInstance.get<PageDto<SongPreviewDtoType>>(
-          '/song',
-          { params: { ...params, page: pageNum } },
-        );
-
-        const { content, total } = response.data;
-        const limit = params.limit || 12;
-
-        set((state) => ({
-          // Remove placeholders and add the new results
-          songs:
-            pageNum === 1
-              ? content
-              : [...state.songs.filter((s) => s !== null), ...content],
-          totalResults: total,
-          currentPage: pageNum,
-          // Check if there are more pages to load
-          hasMore: content.length >= limit,
-        }));
-      } catch (error) {
-        console.error('Error searching songs:', error);
-        set({ songs: [], hasMore: false, totalResults: 0 }); // Reset on error
-      } finally {
-        set({ loading: false });
-      }
-    },
-
-    // Convenience action for loading the next page
-    loadMore: async (params) => {
-      const { loading, hasMore, currentPage } = get();
-      if (loading || !hasMore) return; // Prevent multiple calls
-
-      const nextPage = currentPage + 1;
-      await get().searchSongs(params, nextPage);
-    },
-  }),
-);
-
-interface SearchHeaderProps {
-  query: string;
-  loading: boolean;
-  songsCount: number;
-  totalResults: number;
-}
-
-/**
- * Displays the main header for the search page, including the title
- * and a summary of the results found.
- */
-const SearchHeader = ({
-  query,
-  loading,
-  songsCount,
-  totalResults,
-}: SearchHeaderProps) => {
-  const isSearch = useMemo(() => query !== '', [query]);
-
-  const title = useMemo(() => {
-    if (loading) return '';
-    if (isSearch) {
-      // TODO: implement this with proper variable substitution for translations
-      if (totalResults != 1) {
-        return `${totalResults.toLocaleString('en-UK')} results for "${query}"`;
-      }
-      return `1 result for "${query}"`;
-    }
-    return 'Browse songs';
-  }, [loading, isSearch, query, songsCount, totalResults]);
-
-  return (
-    <div className='flex items-center gap-4'>
-      <h2 className='text-2xl font-light text-zinc-400 min-w-64 h-8'>
-        {title || <Skeleton />}
-      </h2>
-    </div>
-  );
-};
-
-interface SearchFiltersProps {
-  filters: {
-    category: string;
-    sort: string;
-    order: string;
-    limit: number;
-    uploader: string;
-    noteCountMin: number;
-    noteCountMax: number;
-    durationMin: number;
-    durationMax: number;
-    features: string;
-    instruments: string;
-  };
-  onFilterChange: (params: Record<string, string | number>) => void;
-}
-
-const SearchFilters = ({ filters, onFilterChange }: SearchFiltersProps) => {
-  const {
-    category,
-    sort,
-    order,
-    limit,
-    uploader,
-    noteCountMin,
-    noteCountMax,
-    durationMin,
-    durationMax,
-    features,
-    instruments,
-  } = filters;
-
-  // Helper to parse comma-separated string to array of Option objects
-  const parseOptions = (str: string, optionsMap: Record<string, string>) => {
-    if (!str) return [];
-    return str
-      .split(',')
-      .filter((v) => v.trim())
-      .map((value) => {
-        // Find the label by searching in the options map
-        const entry = Object.entries(optionsMap).find(
-          ([, v]) => v === value.trim(),
-        );
-        return {
-          value: value.trim(),
-          label: entry ? entry[0] : value.trim(),
-        };
-      });
-  };
-
-  // Helper to convert array of Option objects to comma-separated string
-  const optionsToString = (options: Array<{ value: string; label: string }>) =>
-    options.map((opt) => opt.value).join(',');
-
-  return (
-    <aside className='bg-zinc-800/50 rounded-lg p-4 sticky top-4 h-fit'>
-      <div className='flex items-center gap-2 mb-4'>
-        <FontAwesomeIcon icon={faFilter} className='text-zinc-400' />
-        <h2 className='text-lg font-semibold'>Filters</h2>
-      </div>
-
-      <div className='flex flex-col gap-4'>
-        {/* Note Count Filter */}
-        <div>
-          <label className='block text-sm font-medium mb-2 text-zinc-300'>
-            Note Count
-          </label>
-          <DualRangeSlider
-            label={(value) => (value ? `${value} notes` : 'All notes')}
-            min={0}
-            max={10000}
-            step={100}
-            value={[noteCountMin, noteCountMax]}
-            onValueChange={(value) => {
-              const [min, max] = value;
-              const params: Record<string, string | number> = {};
-              if (min !== 0) params.noteCountMin = min;
-              if (max !== 10000) params.noteCountMax = max;
-              onFilterChange(params);
-            }}
-          />
-        </div>
-
-        {/* Duration Count Filter */}
-        <div>
-          <label className='block text-sm font-medium mb-2 text-zinc-300'>
-            Duration Count
-          </label>
-          <DualRangeSlider
-            label={(value) => {
-              // convert seconds to HH:MM:SS, use hours only if greater than 1 hour
-              if (value) {
-                const hours = Math.floor(value / 3600);
-                const minutes = Math.floor((value % 3600) / 60);
-                const seconds = value % 60;
-                return `${hours}:${minutes}:${seconds}`;
-              }
-              return 'All duration';
-            }}
-            min={0}
-            max={10000}
-            step={100}
-            value={[durationMin, durationMax]}
-            onValueChange={(value) => {
-              const [min, max] = value;
-              const params: Record<string, string | number> = {};
-              if (min !== 0) params.durationMin = min;
-              if (max !== 10000) params.durationMax = max;
-              onFilterChange(params);
-            }}
-          />
-        </div>
-
-        {/* Category Filter */}
-        <div>
-          <label className='block text-sm font-medium mb-2 text-zinc-300'>
-            Category
-          </label>
-          <MultipleSelector
-            value={
-              category
-                ? category
-                    .split(',')
-                    .filter((c) => c.trim())
-                    .map((c) => {
-                      const trimmed = c.trim();
-                      const label =
-                        UPLOAD_CONSTANTS.categories[
-                          trimmed as keyof typeof UPLOAD_CONSTANTS.categories
-                        ] || trimmed;
-                      return { value: trimmed, label };
-                    })
-                : []
-            }
-            onChange={(value) => {
-              const categoryValue = optionsToString(value);
-              const params: Record<string, string | number> = {};
-              if (categoryValue) params.category = categoryValue;
-              onFilterChange(params);
-            }}
-            options={Object.entries(UPLOAD_CONSTANTS.categories).map(
-              ([key, value]) => ({ value: key, label: value }),
-            )}
-            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
-          />
-        </div>
-
-        {/* Feature Filter */}
-        <div>
-          <label className='block text-sm font-medium mb-2 text-zinc-300'>
-            Features
-          </label>
-          <MultipleSelector
-            value={parseOptions(features, SEARCH_FEATURES)}
-            onChange={(value) => {
-              const featuresValue = optionsToString(value);
-              const params: Record<string, string | number> = {};
-              if (featuresValue) params.features = featuresValue;
-              onFilterChange(params);
-            }}
-            options={Object.entries(SEARCH_FEATURES).map(([key, value]) => ({
-              value: value,
-              label: key,
-            }))}
-            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
-          />
-        </div>
-
-        {/* Instrument Filter */}
-        <div>
-          <label className='block text-sm font-medium mb-2 text-zinc-300'>
-            Instrument
-          </label>
-          <MultipleSelector
-            value={parseOptions(instruments, INSTRUMENTS)}
-            onChange={(value) => {
-              const instrumentsValue = optionsToString(value);
-              const params: Record<string, string | number> = {};
-              if (instrumentsValue) params.instruments = instrumentsValue;
-              onFilterChange(params);
-            }}
-            options={Object.entries(INSTRUMENTS).map(([key, value]) => ({
-              value: value,
-              label: key,
-            }))}
-            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
-          />
-        </div>
-      </div>
-    </aside>
-  );
-};
-
-const NoResults = () => (
-  <div className='flex flex-col items-center justify-center gap-4 max-w-52 mx-auto'>
-    <Image src='/empty-chest.png' alt='' width={150} height={200} aria-hidden />
-    <h3 className='text-2xl w-full'>No songs found</h3>
-    <p className='text-zinc-400 text-sm text-wrap'>
-      Try adjusting your search terms, or browse our{' '}
-      <Link
-        href='/'
-        className='text-blue-400 hover:underline hover:text-blue-300'
-      >
-        featured songs
-      </Link>{' '}
-      instead.
-    </p>
-  </div>
-);
-
-interface SearchResultsProps {
-  songs: Array<SongPreviewDtoType | null>;
-  loading: boolean;
-  hasMore: boolean;
-  onLoadMore: () => void;
-}
-
-const SearchResults = ({ songs, hasMore, onLoadMore }: SearchResultsProps) => (
-  <>
-    <SongCardGroup>
-      {songs.map((song, i) => (
-        <SongCard
-          key={song ? `${song.publicId}-${i}` : `placeholder-${i}`}
-          song={song}
-        />
-      ))}
-    </SongCardGroup>
-
-    {/* Load more / End indicator */}
-    <div className='flex flex-col w-full justify-between items-center mt-4'>
-      {hasMore ? (
-        <LoadMoreButton onClick={onLoadMore} />
-      ) : (
-        <div className='flex flex-col items-center gap-2 text-zinc-500'>
-          <FontAwesomeIcon icon={faEllipsis} className='text-2xl' />
-        </div>
-      )}
-    </div>
-  </>
-);
-
-const SearchSongPage = () => {
-  const [queryState, setQueryState] = useQueryStates({
-    q: parseAsString.withDefault(''),
-    sort: parseAsString.withDefault(SongSortType.RECENT),
-    order: parseAsString.withDefault(SongOrderType.DESC),
-    category: parseAsString.withDefault(''),
-    uploader: parseAsString.withDefault(''),
-    page: parseAsInteger.withDefault(1),
-    limit: parseAsInteger.withDefault(12),
-    noteCountMin: parseAsInteger,
-    noteCountMax: parseAsInteger,
-    durationMin: parseAsInteger,
-    durationMax: parseAsInteger,
-    features: parseAsString,
-    instruments: parseAsString,
-  });
-
-  const {
-    q: query,
-    sort,
-    order,
-    category,
-    uploader,
-    page: currentPageParam,
-    limit,
-    noteCountMin,
-    noteCountMax,
-    durationMin,
-    durationMax,
-    features,
-    instruments,
-  } = queryState;
-
-  const initialPage = currentPageParam ?? 1;
-
-  const { songs, loading, hasMore, totalResults, searchSongs } =
-    useSongSearchStore();
-
-  const [showFilters, setShowFilters] = useState(false);
-
-  useEffect(() => {
-    const params: SearchParams = {
-      q: query,
-      sort,
-      order,
-      category,
-      uploader,
-      limit,
-      noteCountMin: noteCountMin && noteCountMin > 0 ? noteCountMin : undefined,
-      noteCountMax:
-        noteCountMax && noteCountMax < 10000 ? noteCountMax : undefined,
-      durationMin: durationMin && durationMin > 0 ? durationMin : undefined,
-      durationMax: durationMax && durationMax < 10000 ? durationMax : undefined,
-      features: features || undefined,
-      instruments: instruments || undefined,
-    };
-    searchSongs(params, initialPage);
-  }, [
-    query,
-    sort,
-    order,
-    category,
-    uploader,
-    initialPage,
-    limit,
-    noteCountMin,
-    noteCountMax,
-    durationMin,
-    durationMax,
-    features,
-    instruments,
-    searchSongs,
-  ]);
-
-  const handleLoadMore = () => {
-    setQueryState({ page: (currentPageParam ?? 1) + 1 });
-  };
-
-  const handleSortChange = (value: string) => {
-    setQueryState({ sort: value, page: 1 });
-  };
-
-  const handleOrderChange = () => {
-    const newOrder =
-      order === SongOrderType.ASC ? SongOrderType.DESC : SongOrderType.ASC;
-    setQueryState({ order: newOrder, page: 1 });
-  };
-
-  /* Use 19/91 button if sorting by a numeric value, otherwise use AZ/ZA */
-  const orderIcon = useMemo(() => {
-    if (sort === SongSortType.TITLE) {
-      return order === SongOrderType.ASC ? faArrowDownAZ : faArrowDownZA;
-    } else {
-      return order === SongOrderType.ASC ? faArrowDown19 : faArrowDown91;
-    }
-  }, [sort, order]);
-
-  return (
-    <div className='container mx-auto py-8 relative'>
-      <div className='flex flex-col lg:flex-row gap-6'>
-        {/* Filters Sidebar */}
-        {/* {showFilters && (
-          <div className='w-full lg:w-72 shrink-0'>
-            <SearchFilters
-              filters={{
-                category,
-                sort,
-                order,
-                limit,
-                uploader,
-                noteCountMin,
-                noteCountMax,
-                durationMin,
-                durationMax,
-                features,
-                instruments,
-              }}
-              onFilterChange={(params) => updateURL(params)}
-            />
-          </div>
-        )} */}
-
-        {/* Main Content */}
-        <div className='flex-1 min-w-0'>
-          <div className='flex flex-wrap items-center justify-between gap-4 mb-6'>
-            <div className='flex-1 min-w-[260px]'>
-              <SearchHeader
-                query={query}
-                loading={loading}
-                songsCount={songs.length}
-                totalResults={totalResults}
-              />
-            </div>
-            <div className='flex items-center gap-3'>
-              {/* <button
-                type='button'
-                onClick={() => setShowFilters((prev) => !prev)}
-                className='inline-flex items-center gap-2 px-3 py-2 rounded-md border border-zinc-700 bg-zinc-900 hover:bg-zinc-800 transition-colors text-sm'
-              >
-                <FontAwesomeIcon icon={faFilter} />
-                {showFilters ? 'Hide filters' : 'Show filters'}
-              </button> */}
-              <div className='flex items-center gap-2'>
-                <span className='text-sm text-zinc-400'>Sort by:</span>
-                <select
-                  value={sort}
-                  onChange={(e) => handleSortChange(e.target.value)}
-                  disabled={loading}
-                  className='h-10 w-48 rounded-md bg-zinc-900 border-2 border-zinc-600 hover:enabled:border-zinc-500 disabled:opacity-50 focus:border-blue-500 focus:outline-none px-1.5 text-sm transition-colors'
-                >
-                  <option value={SongSortType.RECENT}>Recent</option>
-                  <option value={SongSortType.PLAY_COUNT}>Popular</option>
-                  <option value={SongSortType.TITLE}>Title</option>
-                  <option value={SongSortType.DURATION}>Duration</option>
-                  <option value={SongSortType.NOTE_COUNT}>Note count</option>
-                </select>
-              </div>
-
-              {/* Order button */}
-              <button
-                className='bg-zinc-700 hover:enabled:bg-zinc-600 disabled:opacity-50 h-10 w-10 rounded-md flex items-center justify-center transition-colors enabled:cursor-pointer'
-                onClick={handleOrderChange}
-                disabled={loading}
-                aria-label={
-                  order === SongOrderType.ASC
-                    ? 'Sort ascending'
-                    : 'Sort descending'
-                }
-              >
-                <FontAwesomeIcon
-                  icon={orderIcon}
-                  size='1x'
-                  className='size-4.5'
-                />
-              </button>
-            </div>
-          </div>
-
-          {/* Results */}
-          {songs.length > 0 && (
-            <SearchResults
-              songs={songs}
-              loading={loading}
-              hasMore={hasMore}
-              onLoadMore={handleLoadMore}
-            />
-          )}
-
-          {/* No results */}
-          {!loading && songs.length === 0 && <NoResults />}
-        </div>
-      </div>
-    </div>
-  );
-};
+import { SearchSongPage } from '@web/modules/song-search/SearchSongPage';
 
 const SearchPageWrapper = () => {
   return (
diff --git a/apps/frontend/src/modules/song-search/SearchSongPage.tsx b/apps/frontend/src/modules/song-search/SearchSongPage.tsx
new file mode 100644
index 00000000..67919c1a
--- /dev/null
+++ b/apps/frontend/src/modules/song-search/SearchSongPage.tsx
@@ -0,0 +1,611 @@
+'use client';
+import {
+  faArrowDown19,
+  faArrowDown91,
+  faArrowDownAZ,
+  faArrowDownZA,
+  faEllipsis,
+  faFilter,
+} from '@fortawesome/free-solid-svg-icons';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import Image from 'next/image';
+import Link from 'next/link';
+import { parseAsInteger, parseAsString, useQueryStates } from 'nuqs';
+import { useEffect, useMemo, useState } from 'react';
+import Skeleton from 'react-loading-skeleton';
+import { create } from 'zustand';
+
+import { UPLOAD_CONSTANTS, SEARCH_FEATURES, INSTRUMENTS } from '@nbw/config';
+import { SongPreviewDtoType } from '@nbw/database';
+import axiosInstance from '@web/lib/axios';
+import LoadMoreButton from '@web/modules/browse/components/client/LoadMoreButton';
+import SongCard from '@web/modules/browse/components/SongCard';
+import SongCardGroup from '@web/modules/browse/components/SongCardGroup';
+import { DualRangeSlider } from '@web/modules/shared/components/ui/dualRangeSlider';
+import MultipleSelector from '@web/modules/shared/components/ui/multipleSelectorProps';
+
+interface SearchParams {
+  q?: string;
+  sort?: string;
+  order?: string;
+  category?: string;
+  uploader?: string;
+  limit?: number;
+  noteCountMin?: number;
+  noteCountMax?: number;
+  durationMin?: number;
+  durationMax?: number;
+  features?: string;
+  instruments?: string;
+}
+interface PageDto<T> {
+  content: T[];
+  page: number;
+  limit: number;
+  total: number;
+}
+// TODO: importing these enums from '@nbw/database' is causing issues.
+// They shouldn't be redefined here.
+enum SongSortType {
+  RECENT = 'recent',
+  RANDOM = 'random',
+  PLAY_COUNT = 'playCount',
+  TITLE = 'title',
+  DURATION = 'duration',
+  NOTE_COUNT = 'noteCount',
+}
+enum SongOrderType {
+  ASC = 'asc',
+  DESC = 'desc',
+}
+// TODO: refactor with PAGE_SIZE constant
+const PLACEHOLDER_COUNT = 12;
+const makePlaceholders = () =>
+  Array.from({ length: PLACEHOLDER_COUNT }, () => null);
+interface SongSearchState {
+  songs: Array<SongPreviewDtoType | null>;
+  loading: boolean;
+  hasMore: boolean;
+  currentPage: number;
+  totalResults: number;
+}
+interface SongSearchActions {
+  searchSongs: (params: SearchParams, pageNum: number) => Promise<void>;
+  loadMore: (params: SearchParams) => Promise<void>;
+}
+const initialState: SongSearchState = {
+  songs: [],
+  loading: true,
+  hasMore: true,
+  currentPage: 1,
+  totalResults: 0,
+};
+
+export const useSongSearchStore = create<SongSearchState & SongSearchActions>(
+  (set, get) => ({
+    ...initialState,
+
+    // The core data fetching action
+    searchSongs: async (params, pageNum) => {
+      // New search/sort (page 1): reset to placeholders. Load more: append placeholders.
+      if (pageNum === 1) {
+        set({
+          loading: true,
+          songs: makePlaceholders(),
+          currentPage: 1,
+          hasMore: true,
+        });
+      } else {
+        set((state) => ({
+          loading: true,
+          songs: [...state.songs, ...makePlaceholders()],
+        }));
+      }
+
+      try {
+        const response = await axiosInstance.get<PageDto<SongPreviewDtoType>>(
+          '/song',
+          { params: { ...params, page: pageNum } },
+        );
+
+        const { content, total } = response.data;
+        const limit = params.limit || 12;
+
+        set((state) => ({
+          // Remove placeholders and add the new results
+          songs:
+            pageNum === 1
+              ? content
+              : [...state.songs.filter((s) => s !== null), ...content],
+          totalResults: total,
+          currentPage: pageNum,
+          // Check if there are more pages to load
+          hasMore: content.length >= limit,
+        }));
+      } catch (error) {
+        console.error('Error searching songs:', error);
+        set({ songs: [], hasMore: false, totalResults: 0 }); // Reset on error
+      } finally {
+        set({ loading: false });
+      }
+    },
+
+    // Convenience action for loading the next page
+    loadMore: async (params) => {
+      const { loading, hasMore, currentPage } = get();
+      if (loading || !hasMore) return; // Prevent multiple calls
+
+      const nextPage = currentPage + 1;
+      await get().searchSongs(params, nextPage);
+    },
+  }),
+);
+interface SearchHeaderProps {
+  query: string;
+  loading: boolean;
+  songsCount: number;
+  totalResults: number;
+}
+/**
+ * Displays the main header for the search page, including the title
+ * and a summary of the results found.
+ */
+const SearchHeader = ({
+  query,
+  loading,
+  songsCount,
+  totalResults,
+}: SearchHeaderProps) => {
+  const isSearch = useMemo(() => query !== '', [query]);
+
+  const title = useMemo(() => {
+    if (loading) return '';
+    if (isSearch) {
+      // TODO: implement this with proper variable substitution for translations
+      if (totalResults != 1) {
+        return `${totalResults.toLocaleString('en-UK')} results for "${query}"`;
+      }
+      return `1 result for "${query}"`;
+    }
+    return 'Browse songs';
+  }, [loading, isSearch, query, songsCount, totalResults]);
+
+  return (
+    <div className='flex items-center gap-4'>
+      <h2 className='text-2xl font-light text-zinc-400 min-w-64 h-8'>
+        {title || <Skeleton />}
+      </h2>
+    </div>
+  );
+};
+interface SearchFiltersProps {
+  filters: {
+    category: string;
+    sort: string;
+    order: string;
+    limit: number;
+    uploader: string;
+    noteCountMin: number;
+    noteCountMax: number;
+    durationMin: number;
+    durationMax: number;
+    features: string;
+    instruments: string;
+  };
+  onFilterChange: (params: Record<string, string | number>) => void;
+}
+const SearchFilters = ({ filters, onFilterChange }: SearchFiltersProps) => {
+  const {
+    category,
+    sort,
+    order,
+    limit,
+    uploader,
+    noteCountMin,
+    noteCountMax,
+    durationMin,
+    durationMax,
+    features,
+    instruments,
+  } = filters;
+
+  // Helper to parse comma-separated string to array of Option objects
+  const parseOptions = (str: string, optionsMap: Record<string, string>) => {
+    if (!str) return [];
+    return str
+      .split(',')
+      .filter((v) => v.trim())
+      .map((value) => {
+        // Find the label by searching in the options map
+        const entry = Object.entries(optionsMap).find(
+          ([, v]) => v === value.trim(),
+        );
+        return {
+          value: value.trim(),
+          label: entry ? entry[0] : value.trim(),
+        };
+      });
+  };
+
+  // Helper to convert array of Option objects to comma-separated string
+  const optionsToString = (options: Array<{ value: string; label: string }>) =>
+    options.map((opt) => opt.value).join(',');
+
+  return (
+    <aside className='bg-zinc-800/50 rounded-lg p-4 sticky top-4 h-fit'>
+      <div className='flex items-center gap-2 mb-4'>
+        <FontAwesomeIcon icon={faFilter} className='text-zinc-400' />
+        <h2 className='text-lg font-semibold'>Filters</h2>
+      </div>
+
+      <div className='flex flex-col gap-4'>
+        {/* Note Count Filter */}
+        <div>
+          <label className='block text-sm font-medium mb-2 text-zinc-300'>
+            Note Count
+          </label>
+          <DualRangeSlider
+            label={(value) => (value ? `${value} notes` : 'All notes')}
+            min={0}
+            max={10000}
+            step={100}
+            value={[noteCountMin, noteCountMax]}
+            onValueChange={(value) => {
+              const [min, max] = value;
+              const params: Record<string, string | number> = {};
+              if (min !== 0) params.noteCountMin = min;
+              if (max !== 10000) params.noteCountMax = max;
+              onFilterChange(params);
+            }}
+          />
+        </div>
+
+        {/* Duration Count Filter */}
+        <div>
+          <label className='block text-sm font-medium mb-2 text-zinc-300'>
+            Duration Count
+          </label>
+          <DualRangeSlider
+            label={(value) => {
+              // convert seconds to HH:MM:SS, use hours only if greater than 1 hour
+              if (value) {
+                const hours = Math.floor(value / 3600);
+                const minutes = Math.floor((value % 3600) / 60);
+                const seconds = value % 60;
+                return `${hours}:${minutes}:${seconds}`;
+              }
+              return 'All duration';
+            }}
+            min={0}
+            max={10000}
+            step={100}
+            value={[durationMin, durationMax]}
+            onValueChange={(value) => {
+              const [min, max] = value;
+              const params: Record<string, string | number> = {};
+              if (min !== 0) params.durationMin = min;
+              if (max !== 10000) params.durationMax = max;
+              onFilterChange(params);
+            }}
+          />
+        </div>
+
+        {/* Category Filter */}
+        <div>
+          <label className='block text-sm font-medium mb-2 text-zinc-300'>
+            Category
+          </label>
+          <MultipleSelector
+            value={
+              category
+                ? category
+                    .split(',')
+                    .filter((c) => c.trim())
+                    .map((c) => {
+                      const trimmed = c.trim();
+                      const label =
+                        UPLOAD_CONSTANTS.categories[
+                          trimmed as keyof typeof UPLOAD_CONSTANTS.categories
+                        ] || trimmed;
+                      return { value: trimmed, label };
+                    })
+                : []
+            }
+            onChange={(value) => {
+              const categoryValue = optionsToString(value);
+              const params: Record<string, string | number> = {};
+              if (categoryValue) params.category = categoryValue;
+              onFilterChange(params);
+            }}
+            options={Object.entries(UPLOAD_CONSTANTS.categories).map(
+              ([key, value]) => ({ value: key, label: value }),
+            )}
+            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
+          />
+        </div>
+
+        {/* Feature Filter */}
+        <div>
+          <label className='block text-sm font-medium mb-2 text-zinc-300'>
+            Features
+          </label>
+          <MultipleSelector
+            value={parseOptions(features, SEARCH_FEATURES)}
+            onChange={(value) => {
+              const featuresValue = optionsToString(value);
+              const params: Record<string, string | number> = {};
+              if (featuresValue) params.features = featuresValue;
+              onFilterChange(params);
+            }}
+            options={Object.entries(SEARCH_FEATURES).map(([key, value]) => ({
+              value: value,
+              label: key,
+            }))}
+            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
+          />
+        </div>
+
+        {/* Instrument Filter */}
+        <div>
+          <label className='block text-sm font-medium mb-2 text-zinc-300'>
+            Instrument
+          </label>
+          <MultipleSelector
+            value={parseOptions(instruments, INSTRUMENTS)}
+            onChange={(value) => {
+              const instrumentsValue = optionsToString(value);
+              const params: Record<string, string | number> = {};
+              if (instrumentsValue) params.instruments = instrumentsValue;
+              onFilterChange(params);
+            }}
+            options={Object.entries(INSTRUMENTS).map(([key, value]) => ({
+              value: value,
+              label: key,
+            }))}
+            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
+          />
+        </div>
+      </div>
+    </aside>
+  );
+};
+const NoResults = () => (
+  <div className='flex flex-col items-center justify-center gap-4 max-w-52 mx-auto'>
+    <Image src='/empty-chest.png' alt='' width={150} height={200} aria-hidden />
+    <h3 className='text-2xl w-full'>No songs found</h3>
+    <p className='text-zinc-400 text-sm text-wrap'>
+      Try adjusting your search terms, or browse our{' '}
+      <Link
+        href='/'
+        className='text-blue-400 hover:underline hover:text-blue-300'
+      >
+        featured songs
+      </Link>{' '}
+      instead.
+    </p>
+  </div>
+);
+interface SearchResultsProps {
+  songs: Array<SongPreviewDtoType | null>;
+  loading: boolean;
+  hasMore: boolean;
+  onLoadMore: () => void;
+}
+const SearchResults = ({ songs, hasMore, onLoadMore }: SearchResultsProps) => (
+  <>
+    <SongCardGroup>
+      {songs.map((song, i) => (
+        <SongCard
+          key={song ? `${song.publicId}-${i}` : `placeholder-${i}`}
+          song={song}
+        />
+      ))}
+    </SongCardGroup>
+
+    {/* Load more / End indicator */}
+    <div className='flex flex-col w-full justify-between items-center mt-4'>
+      {hasMore ? (
+        <LoadMoreButton onClick={onLoadMore} />
+      ) : (
+        <div className='flex flex-col items-center gap-2 text-zinc-500'>
+          <FontAwesomeIcon icon={faEllipsis} className='text-2xl' />
+        </div>
+      )}
+    </div>
+  </>
+);
+export const SearchSongPage = () => {
+  const [queryState, setQueryState] = useQueryStates({
+    q: parseAsString.withDefault(''),
+    sort: parseAsString.withDefault(SongSortType.RECENT),
+    order: parseAsString.withDefault(SongOrderType.DESC),
+    category: parseAsString.withDefault(''),
+    uploader: parseAsString.withDefault(''),
+    page: parseAsInteger.withDefault(1),
+    limit: parseAsInteger.withDefault(12),
+    noteCountMin: parseAsInteger,
+    noteCountMax: parseAsInteger,
+    durationMin: parseAsInteger,
+    durationMax: parseAsInteger,
+    features: parseAsString,
+    instruments: parseAsString,
+  });
+
+  const {
+    q: query,
+    sort,
+    order,
+    category,
+    uploader,
+    page: currentPageParam,
+    limit,
+    noteCountMin,
+    noteCountMax,
+    durationMin,
+    durationMax,
+    features,
+    instruments,
+  } = queryState;
+
+  const initialPage = currentPageParam ?? 1;
+
+  const { songs, loading, hasMore, totalResults, searchSongs } =
+    useSongSearchStore();
+
+  const [showFilters, setShowFilters] = useState(false);
+
+  useEffect(() => {
+    const params: SearchParams = {
+      q: query,
+      sort,
+      order,
+      category,
+      uploader,
+      limit,
+      noteCountMin: noteCountMin && noteCountMin > 0 ? noteCountMin : undefined,
+      noteCountMax:
+        noteCountMax && noteCountMax < 10000 ? noteCountMax : undefined,
+      durationMin: durationMin && durationMin > 0 ? durationMin : undefined,
+      durationMax: durationMax && durationMax < 10000 ? durationMax : undefined,
+      features: features || undefined,
+      instruments: instruments || undefined,
+    };
+    searchSongs(params, initialPage);
+  }, [
+    query,
+    sort,
+    order,
+    category,
+    uploader,
+    initialPage,
+    limit,
+    noteCountMin,
+    noteCountMax,
+    durationMin,
+    durationMax,
+    features,
+    instruments,
+    searchSongs,
+  ]);
+
+  const handleLoadMore = () => {
+    setQueryState({ page: (currentPageParam ?? 1) + 1 });
+  };
+
+  const handleSortChange = (value: string) => {
+    setQueryState({ sort: value, page: 1 });
+  };
+
+  const handleOrderChange = () => {
+    const newOrder =
+      order === SongOrderType.ASC ? SongOrderType.DESC : SongOrderType.ASC;
+    setQueryState({ order: newOrder, page: 1 });
+  };
+
+  /* Use 19/91 button if sorting by a numeric value, otherwise use AZ/ZA */
+  const orderIcon = useMemo(() => {
+    if (sort === SongSortType.TITLE) {
+      return order === SongOrderType.ASC ? faArrowDownAZ : faArrowDownZA;
+    } else {
+      return order === SongOrderType.ASC ? faArrowDown19 : faArrowDown91;
+    }
+  }, [sort, order]);
+
+  return (
+    <div className='container mx-auto py-8 relative'>
+      <div className='flex flex-col lg:flex-row gap-6'>
+        {/* Filters Sidebar */}
+        {/* {showFilters && (
+              <div className='w-full lg:w-72 shrink-0'>
+                <SearchFilters
+                  filters={{
+                    category,
+                    sort,
+                    order,
+                    limit,
+                    uploader,
+                    noteCountMin,
+                    noteCountMax,
+                    durationMin,
+                    durationMax,
+                    features,
+                    instruments,
+                  }}
+                  onFilterChange={(params) => updateURL(params)}
+                />
+              </div>
+            )} */}
+
+        {/* Main Content */}
+        <div className='flex-1 min-w-0'>
+          <div className='flex flex-wrap items-center justify-between gap-4 mb-6'>
+            <div className='flex-1 min-w-[260px]'>
+              <SearchHeader
+                query={query}
+                loading={loading}
+                songsCount={songs.length}
+                totalResults={totalResults}
+              />
+            </div>
+            <div className='flex items-center gap-3'>
+              {/* <button
+              type='button'
+              onClick={() => setShowFilters((prev) => !prev)}
+              className='inline-flex items-center gap-2 px-3 py-2 rounded-md border border-zinc-700 bg-zinc-900 hover:bg-zinc-800 transition-colors text-sm'
+            >
+              <FontAwesomeIcon icon={faFilter} />
+              {showFilters ? 'Hide filters' : 'Show filters'}
+            </button> */}
+              <div className='flex items-center gap-2'>
+                <span className='text-sm text-zinc-400'>Sort by:</span>
+                <select
+                  value={sort}
+                  onChange={(e) => handleSortChange(e.target.value)}
+                  disabled={loading}
+                  className='h-10 w-48 rounded-md bg-zinc-900 border-2 border-zinc-600 hover:enabled:border-zinc-500 disabled:opacity-50 focus:border-blue-500 focus:outline-none px-1.5 text-sm transition-colors'
+                >
+                  <option value={SongSortType.RECENT}>Recent</option>
+                  <option value={SongSortType.PLAY_COUNT}>Popular</option>
+                  <option value={SongSortType.TITLE}>Title</option>
+                  <option value={SongSortType.DURATION}>Duration</option>
+                  <option value={SongSortType.NOTE_COUNT}>Note count</option>
+                </select>
+              </div>
+
+              {/* Order button */}
+              <button
+                className='bg-zinc-700 hover:enabled:bg-zinc-600 disabled:opacity-50 h-10 w-10 rounded-md flex items-center justify-center transition-colors enabled:cursor-pointer'
+                onClick={handleOrderChange}
+                disabled={loading}
+                aria-label={
+                  order === SongOrderType.ASC
+                    ? 'Sort ascending'
+                    : 'Sort descending'
+                }
+              >
+                <FontAwesomeIcon
+                  icon={orderIcon}
+                  size='1x'
+                  className='size-4.5'
+                />
+              </button>
+            </div>
+          </div>
+
+          {/* Results */}
+          {songs.length > 0 && (
+            <SearchResults
+              songs={songs}
+              loading={loading}
+              hasMore={hasMore}
+              onLoadMore={handleLoadMore}
+            />
+          )}
+
+          {/* No results */}
+          {!loading && songs.length === 0 && <NoResults />}
+        </div>
+      </div>
+    </div>
+  );
+};

From 7536bd78d7bb70c04b395eb42e48e5fa04da20c9 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 18:27:09 -0300
Subject: [PATCH 052/111] Fix: update build script to use webpack

---
 apps/frontend/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index 0785ad84..f6186544 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "dev": "next dev",
-    "build": "next build",
+    "build": "next build --webpack",
     "start": "next start",
     "lint": "eslint \"src/**/*.{ts,tsx}\" --fix",
     "test": "jest"

From 8a18083be9836f06c93a8278f0a365a4bbed0b6b Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 18:33:34 -0300
Subject: [PATCH 053/111] fix: HelpPost component to handle async params

---
 apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx b/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
index 4f8ed867..d776871e 100644
--- a/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
@@ -34,8 +34,8 @@ export async function generateMetadata({
   };
 }
 
-const HelpPost = ({ params }: HelpPageProps) => {
-  const { id } = params;
+const HelpPost = async ({ params }: HelpPageProps) => {
+  const { id } = await params;
   let post: PostType;
 
   try {

From 696f3f92828aa37dd8cf2a0ce8a36769f98c8a76 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 18:34:08 -0300
Subject: [PATCH 054/111] fix: update form types and default values in
 Thumbnail components

---
 .../song/components/client/SongThumbnailInput.tsx | 15 +++++++++------
 .../song/components/client/ThumbnailRenderer.tsx  | 14 ++++++++------
 2 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
index 27bdab49..40acb09b 100644
--- a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
@@ -11,7 +11,7 @@ import {
 import { Slider } from '@web/modules/shared/components/ui/slider';
 
 import { useSongProvider } from './context/Song.context';
-import { EditSongForm, UploadSongForm } from './SongForm.zod';
+import { EditSongFormInput, UploadSongFormInput } from './SongForm.zod';
 import { ThumbnailRendererCanvas } from './ThumbnailRenderer';
 
 const formatZoomLevel = (zoomLevel: number) => {
@@ -20,7 +20,8 @@ const formatZoomLevel = (zoomLevel: number) => {
 };
 
 type ThumbnailSlidersProps = {
-  formMethods: UseFormReturn<UploadSongForm> & UseFormReturn<EditSongForm>;
+  formMethods: UseFormReturn<UploadSongFormInput> &
+    UseFormReturn<EditSongFormInput>;
   isLocked: boolean;
   maxTick: number;
   maxLayer: number;
@@ -48,7 +49,7 @@ const ThumbnailSliders: React.FC<ThumbnailSlidersProps> = ({
       <div>
         <Slider
           id='zoom-level'
-          value={[zoomLevel]}
+          value={[zoomLevel ?? THUMBNAIL_CONSTANTS.zoomLevel.default]}
           onValueChange={(value) => {
             setValue('thumbnailData.zoomLevel', value[0], {
               shouldValidate: true,
@@ -60,14 +61,16 @@ const ThumbnailSliders: React.FC<ThumbnailSlidersProps> = ({
           max={THUMBNAIL_CONSTANTS.zoomLevel.max}
         />
       </div>
-      <div>{formatZoomLevel(zoomLevel)}</div>
+      <div>
+        {formatZoomLevel(zoomLevel ?? THUMBNAIL_CONSTANTS.zoomLevel.default)}
+      </div>
       <div>
         <label htmlFor='start-tick'>Start Tick</label>
       </div>
       <div className='w-full'>
         <Slider
           id='start-tick'
-          value={[startTick]}
+          value={[startTick ?? THUMBNAIL_CONSTANTS.startTick.default]}
           onValueChange={(value) => {
             setValue('thumbnailData.startTick', value[0], {
               shouldValidate: true,
@@ -86,7 +89,7 @@ const ThumbnailSliders: React.FC<ThumbnailSlidersProps> = ({
       <div className='w-full'>
         <Slider
           id='start-layer'
-          value={[startLayer]}
+          value={[startLayer ?? THUMBNAIL_CONSTANTS.startLayer.default]}
           onValueChange={(value) => {
             setValue('thumbnailData.startLayer', value[0], {
               shouldValidate: true,
diff --git a/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx b/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
index 6d11a28b..6cd0da89 100644
--- a/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
+++ b/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
@@ -3,14 +3,15 @@
 import { useEffect, useRef, useState } from 'react';
 import { UseFormReturn } from 'react-hook-form';
 
+import { THUMBNAIL_CONSTANTS } from '@nbw/config';
 import { NoteQuadTree } from '@nbw/song';
 import { drawNotesOffscreen, swap } from '@nbw/thumbnail/browser';
 
-import { UploadSongForm } from './SongForm.zod';
+import { UploadSongFormInput } from './SongForm.zod';
 
 type ThumbnailRendererCanvasProps = {
   notes: NoteQuadTree;
-  formMethods: UseFormReturn<UploadSongForm>;
+  formMethods: UseFormReturn<UploadSongFormInput>;
 };
 
 export const ThumbnailRendererCanvas = ({
@@ -60,10 +61,11 @@ export const ThumbnailRendererCanvas = ({
       try {
         const output = (await drawNotesOffscreen({
           notes,
-          startTick,
-          startLayer,
-          zoomLevel,
-          backgroundColor,
+          startTick: startTick ?? THUMBNAIL_CONSTANTS.startTick.default,
+          startLayer: startLayer ?? THUMBNAIL_CONSTANTS.startLayer.default,
+          zoomLevel: zoomLevel ?? THUMBNAIL_CONSTANTS.zoomLevel.default,
+          backgroundColor:
+            backgroundColor ?? THUMBNAIL_CONSTANTS.backgroundColor.default,
           canvasWidth: canvas.width,
           imgWidth: 1280,
           imgHeight: 768,

From 5e5985c92c13ee8b9611ab8067e046b71504109e Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 10 Jan 2026 19:23:08 -0300
Subject: [PATCH 055/111] test: Updated AuthController and SongController to
 test the current codebase

---
 apps/backend/src/auth/auth.controller.spec.ts | 30 +++++++--
 .../src/song/my-songs/my-songs.controller.ts  |  7 ++-
 apps/backend/src/song/song.controller.spec.ts | 63 ++++++++++++-------
 apps/backend/src/song/song.controller.ts      |  3 +
 apps/backend/src/song/song.service.spec.ts    | 40 +++++++++---
 packages/database/tsconfig.build.json         |  4 +-
 6 files changed, 105 insertions(+), 42 deletions(-)

diff --git a/apps/backend/src/auth/auth.controller.spec.ts b/apps/backend/src/auth/auth.controller.spec.ts
index d6bae4fa..0a68ba35 100644
--- a/apps/backend/src/auth/auth.controller.spec.ts
+++ b/apps/backend/src/auth/auth.controller.spec.ts
@@ -22,6 +22,9 @@ describe('AuthController', () => {
   let authService: AuthService;
 
   beforeEach(async () => {
+    // Clear all mocks before each test to ensure test isolation
+    jest.clearAllMocks();
+
     const module: TestingModule = await Test.createTestingModule({
       controllers: [AuthController],
       providers: [
@@ -68,8 +71,13 @@ describe('AuthController', () => {
 
   describe('githubLogin', () => {
     it('should call AuthService.githubLogin', async () => {
-      await controller.githubLogin();
-      expect(authService.githubLogin).toHaveBeenCalled();
+      // githubLogin is just a Passport guard entry point - it doesn't call authService
+      // The actual login is handled by the callback endpoint (githubRedirect)
+      controller.githubLogin();
+      // Verify the method exists and can be called without errors
+      expect(controller.githubLogin).toBeDefined();
+      // Verify authService was NOT called (since this is just a guard entry point)
+      expect(authService.githubLogin).not.toHaveBeenCalled();
     });
   });
 
@@ -97,8 +105,13 @@ describe('AuthController', () => {
 
   describe('googleLogin', () => {
     it('should call AuthService.googleLogin', async () => {
-      await controller.googleLogin();
-      expect(authService.googleLogin).toHaveBeenCalled();
+      // googleLogin is just a Passport guard entry point - it doesn't call authService
+      // The actual login is handled by the callback endpoint (googleRedirect)
+      controller.googleLogin();
+      // Verify the method exists and can be called without errors
+      expect(controller.googleLogin).toBeDefined();
+      // Verify authService was NOT called (since this is just a guard entry point)
+      expect(authService.googleLogin).not.toHaveBeenCalled();
     });
   });
 
@@ -126,8 +139,13 @@ describe('AuthController', () => {
 
   describe('discordLogin', () => {
     it('should call AuthService.discordLogin', async () => {
-      await controller.discordLogin();
-      expect(authService.discordLogin).toHaveBeenCalled();
+      // discordLogin is just a Passport guard entry point - it doesn't call authService
+      // The actual login is handled by the callback endpoint (discordRedirect)
+      controller.discordLogin();
+      // Verify the method exists and can be called without errors
+      expect(controller.discordLogin).toBeDefined();
+      // Verify authService was NOT called (since this is just a guard entry point)
+      expect(authService.discordLogin).not.toHaveBeenCalled();
     });
   });
 
diff --git a/apps/backend/src/song/my-songs/my-songs.controller.ts b/apps/backend/src/song/my-songs/my-songs.controller.ts
index c1e5b8ec..ece24049 100644
--- a/apps/backend/src/song/my-songs/my-songs.controller.ts
+++ b/apps/backend/src/song/my-songs/my-songs.controller.ts
@@ -1,4 +1,4 @@
-import { Controller, Get, Query, UseGuards } from '@nestjs/common';
+import { Controller, Get, Inject, Query, UseGuards } from '@nestjs/common';
 import { AuthGuard } from '@nestjs/passport';
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
 
@@ -12,7 +12,10 @@ import { SongService } from '../song.service';
 @Controller('my-songs')
 @ApiTags('song')
 export class MySongsController {
-  constructor(public readonly songService: SongService) {}
+  constructor(
+    @Inject(SongService)
+    public readonly songService: SongService,
+  ) {}
 
   @Get('/')
   @ApiOperation({
diff --git a/apps/backend/src/song/song.controller.spec.ts b/apps/backend/src/song/song.controller.spec.ts
index 51865a09..ad035e5a 100644
--- a/apps/backend/src/song/song.controller.spec.ts
+++ b/apps/backend/src/song/song.controller.spec.ts
@@ -31,6 +31,7 @@ const mockSongService = {
   getSongEdit: jest.fn(),
   patchSong: jest.fn(),
   getSongDownloadUrl: jest.fn(),
+  getSongFileBuffer: jest.fn(),
   deleteSong: jest.fn(),
   uploadSong: jest.fn(),
   getRandomSongs: jest.fn(),
@@ -46,6 +47,9 @@ describe('SongController', () => {
   let songService: SongService;
 
   beforeEach(async () => {
+    // Clear all mocks before each test
+    jest.clearAllMocks();
+
     const module: TestingModule = await Test.createTestingModule({
       controllers: [SongController],
       providers: [
@@ -66,8 +70,8 @@ describe('SongController', () => {
     songController = module.get<SongController>(SongController);
     songService = module.get<SongService>(SongService);
 
-    // Clear all mocks
-    jest.clearAllMocks();
+    // Verify the service is injected
+    expect(songController.songService).toBeDefined();
   });
 
   it('should be defined', () => {
@@ -79,7 +83,12 @@ describe('SongController', () => {
       const query: SongListQueryDTO = { page: 1, limit: 10 };
       const songList: SongPreviewDto[] = [];
 
-      mockSongService.getSongByPage.mockResolvedValueOnce(songList);
+      mockSongService.querySongs.mockResolvedValueOnce({
+        content: songList,
+        page: 1,
+        limit: 10,
+        total: 0,
+      });
 
       const result = await songController.getSongList(query);
 
@@ -88,7 +97,7 @@ describe('SongController', () => {
       expect(result.page).toBe(1);
       expect(result.limit).toBe(10);
       expect(result.total).toBe(0);
-      expect(songService.getSongByPage).toHaveBeenCalled();
+      expect(songService.querySongs).toHaveBeenCalled();
     });
 
     it('should handle search query', async () => {
@@ -357,7 +366,7 @@ describe('SongController', () => {
     it('should handle errors', async () => {
       const query: SongListQueryDTO = { page: 1, limit: 10 };
 
-      mockSongService.getSongByPage.mockRejectedValueOnce(new Error('Error'));
+      mockSongService.querySongs.mockRejectedValueOnce(new Error('Error'));
 
       await expect(songController.getSongList(query)).rejects.toThrow('Error');
     });
@@ -437,7 +446,7 @@ describe('SongController', () => {
       expect(result.total).toBe(5);
       expect(result.page).toBe(1);
       expect(result.limit).toBe(10);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
 
     it('should handle search with empty query string', async () => {
@@ -457,7 +466,7 @@ describe('SongController', () => {
       expect(result).toBeInstanceOf(PageDto);
       expect(result.content).toEqual(songList);
       expect(result.total).toBe(0);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, '', undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, '');
     });
 
     it('should handle search with null query string', async () => {
@@ -476,7 +485,7 @@ describe('SongController', () => {
 
       expect(result).toBeInstanceOf(PageDto);
       expect(result.content).toEqual(songList);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, '', undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, '');
     });
 
     it('should handle search with multiple pages', async () => {
@@ -499,7 +508,7 @@ describe('SongController', () => {
       expect(result.content).toHaveLength(10);
       expect(result.total).toBe(25);
       expect(result.page).toBe(2);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
 
     it('should handle search with large result set', async () => {
@@ -521,7 +530,7 @@ describe('SongController', () => {
       expect(result).toBeInstanceOf(PageDto);
       expect(result.content).toHaveLength(50);
       expect(result.total).toBe(500);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
 
     it('should handle search on last page with partial results', async () => {
@@ -561,7 +570,7 @@ describe('SongController', () => {
       const result = await songController.searchSongs(query, q);
 
       expect(result).toBeInstanceOf(PageDto);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
 
     it('should handle search with very long query string', async () => {
@@ -579,7 +588,7 @@ describe('SongController', () => {
       const result = await songController.searchSongs(query, q);
 
       expect(result).toBeInstanceOf(PageDto);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
 
     it('should handle search with custom limit', async () => {
@@ -627,7 +636,7 @@ describe('SongController', () => {
 
       expect(result).toBeInstanceOf(PageDto);
       expect(result.content).toHaveLength(10);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
 
     it('should return correct pagination info with search results', async () => {
@@ -699,7 +708,7 @@ describe('SongController', () => {
       const result = await songController.searchSongs(query, q);
 
       expect(result).toBeInstanceOf(PageDto);
-      expect(songService.querySongs).toHaveBeenCalledWith(query, q, undefined);
+      expect(songService.querySongs).toHaveBeenCalledWith(query, q ?? '');
     });
   });
 
@@ -803,23 +812,31 @@ describe('SongController', () => {
 
       const res = {
         set: jest.fn(),
-        redirect: jest.fn(),
+        send: jest.fn(),
       } as unknown as Response;
 
-      const url = 'test-url';
+      const buffer = Buffer.from('test-song-data');
+      const filename = 'test-song.nbs';
 
-      mockSongService.getSongDownloadUrl.mockResolvedValueOnce(url);
+      mockSongService.getSongFileBuffer.mockResolvedValueOnce({
+        buffer,
+        filename,
+      });
 
       await songController.getSongFile(id, src, user, res);
 
       expect(res.set).toHaveBeenCalledWith({
-        'Content-Disposition': 'attachment; filename="song.nbs"',
+        'Content-Type': 'application/octet-stream',
+        'Content-Disposition': `attachment; filename="${filename.replace(
+          /[/"]/g,
+          '_',
+        )}"`,
         'Access-Control-Expose-Headers': 'Content-Disposition',
       });
 
-      expect(res.redirect).toHaveBeenCalledWith(HttpStatus.FOUND, url);
+      expect(res.send).toHaveBeenCalledWith(Buffer.from(buffer));
 
-      expect(songService.getSongDownloadUrl).toHaveBeenCalledWith(
+      expect(songService.getSongFileBuffer).toHaveBeenCalledWith(
         id,
         user,
         src,
@@ -836,16 +853,16 @@ describe('SongController', () => {
 
       const res = {
         set: jest.fn(),
-        redirect: jest.fn(),
+        send: jest.fn(),
       } as unknown as Response;
 
-      mockSongService.getSongDownloadUrl.mockRejectedValueOnce(
+      mockSongService.getSongFileBuffer.mockRejectedValueOnce(
         new Error('Error'),
       );
 
       await expect(
         songController.getSongFile(id, src, user, res),
-      ).rejects.toThrow('Error');
+      ).rejects.toThrow('An error occurred while retrieving the song file');
     });
   });
 
diff --git a/apps/backend/src/song/song.controller.ts b/apps/backend/src/song/song.controller.ts
index d50f2a8f..2dc2b7a2 100644
--- a/apps/backend/src/song/song.controller.ts
+++ b/apps/backend/src/song/song.controller.ts
@@ -8,6 +8,7 @@ import {
   Headers,
   HttpException,
   HttpStatus,
+  Inject,
   Logger,
   Param,
   Patch,
@@ -65,7 +66,9 @@ export class SongController {
   };
 
   constructor(
+    @Inject(SongService)
     public readonly songService: SongService,
+    @Inject(FileService)
     public readonly fileService: FileService,
   ) {}
 
diff --git a/apps/backend/src/song/song.service.spec.ts b/apps/backend/src/song/song.service.spec.ts
index 4a944f7f..7c140daa 100644
--- a/apps/backend/src/song/song.service.spec.ts
+++ b/apps/backend/src/song/song.service.spec.ts
@@ -24,6 +24,7 @@ import { SongService } from './song.service';
 const mockFileService = {
   deleteSong: jest.fn(),
   getSongDownloadUrl: jest.fn(),
+  getSongFile: jest.fn(),
 };
 
 const mockSongUploadService = {
@@ -39,6 +40,16 @@ const mockSongWebhookService = {
   syncSongWebhook: jest.fn(),
 };
 
+const mockSongModel = {
+  create: jest.fn(),
+  findOne: jest.fn(),
+  find: jest.fn(),
+  deleteOne: jest.fn(),
+  countDocuments: jest.fn(),
+  aggregate: jest.fn(),
+  populate: jest.fn(),
+};
+
 describe('SongService', () => {
   let service: SongService;
   let fileService: FileService;
@@ -46,6 +57,9 @@ describe('SongService', () => {
   let songModel: Model<SongEntity>;
 
   beforeEach(async () => {
+    // Clear all mocks before each test
+    jest.clearAllMocks();
+
     const module: TestingModule = await Test.createTestingModule({
       providers: [
         SongService,
@@ -55,7 +69,7 @@ describe('SongService', () => {
         },
         {
           provide: getModelToken(SongEntity.name),
-          useValue: mongoose.model(SongEntity.name, SongSchema),
+          useValue: mockSongModel,
         },
         {
           provide: FileService,
@@ -1014,13 +1028,13 @@ describe('SongService', () => {
         { _id: 'category2', count: 5 },
       ];
 
-      jest.spyOn(songModel, 'aggregate').mockResolvedValue(categories);
+      mockSongModel.aggregate.mockResolvedValue(categories);
 
       const result = await service.getCategories();
 
       expect(result).toEqual({ category1: 10, category2: 5 });
 
-      expect(songModel.aggregate).toHaveBeenCalledWith([
+      expect(mockSongModel.aggregate).toHaveBeenCalledWith([
         { $match: { visibility: 'public' } },
         { $group: { _id: '$category', count: { $sum: 1 } } },
         { $sort: { count: -1 } },
@@ -1211,8 +1225,8 @@ describe('SongService', () => {
         exec: jest.fn().mockResolvedValue(songList),
       };
 
-      jest.spyOn(songModel, 'aggregate').mockReturnValue(mockAggregate as any);
-      jest.spyOn(songModel, 'populate').mockResolvedValue(songList);
+      mockSongModel.aggregate.mockReturnValue(mockAggregate as any);
+      mockSongModel.populate.mockResolvedValue(songList);
 
       const result = await service.getRandomSongs(count);
 
@@ -1220,10 +1234,14 @@ describe('SongService', () => {
         songList.map((song) => SongPreviewDto.fromSongDocumentWithUser(song)),
       );
 
-      expect(songModel.aggregate).toHaveBeenCalledWith([
+      expect(mockSongModel.aggregate).toHaveBeenCalledWith([
         { $match: { visibility: 'public' } },
         { $sample: { size: count } },
       ]);
+      expect(mockSongModel.populate).toHaveBeenCalledWith(songList, {
+        path: 'uploader',
+        select: 'username profileImage -_id',
+      });
     });
 
     it('should return random songs with category filter', async () => {
@@ -1235,8 +1253,8 @@ describe('SongService', () => {
         exec: jest.fn().mockResolvedValue(songList),
       };
 
-      jest.spyOn(songModel, 'aggregate').mockReturnValue(mockAggregate as any);
-      jest.spyOn(songModel, 'populate').mockResolvedValue(songList);
+      mockSongModel.aggregate.mockReturnValue(mockAggregate as any);
+      mockSongModel.populate.mockResolvedValue(songList);
 
       const result = await service.getRandomSongs(count, category);
 
@@ -1244,10 +1262,14 @@ describe('SongService', () => {
         songList.map((song) => SongPreviewDto.fromSongDocumentWithUser(song)),
       );
 
-      expect(songModel.aggregate).toHaveBeenCalledWith([
+      expect(mockSongModel.aggregate).toHaveBeenCalledWith([
         { $match: { visibility: 'public', category: 'pop' } },
         { $sample: { size: count } },
       ]);
+      expect(mockSongModel.populate).toHaveBeenCalledWith(songList, {
+        path: 'uploader',
+        select: 'username profileImage -_id',
+      });
     });
   });
 });
diff --git a/packages/database/tsconfig.build.json b/packages/database/tsconfig.build.json
index 0fc0958a..472e06a3 100644
--- a/packages/database/tsconfig.build.json
+++ b/packages/database/tsconfig.build.json
@@ -8,8 +8,8 @@
     "declaration": false,
     "emitDeclarationOnly": false,
 
-    // Module target for Node runtime
-    "module": "CommonJS",
+    // Module target for Node runtime (ESM to match package.json "type": "module")
+    "module": "ES2022",
     "moduleResolution": "node",
     "target": "ES2021",
 

From 65bb8aeb40726be138d5c191b0dd10496fc4d65a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sat, 10 Jan 2026 23:39:35 +0000
Subject: [PATCH 056/111] chore(deps): bump next from 16.0.8 to 16.0.10 in
 /apps/frontend

Bumps [next](https://github.com/vercel/next.js) from 16.0.8 to 16.0.10.
- [Release notes](https://github.com/vercel/next.js/releases)
- [Changelog](https://github.com/vercel/next.js/blob/canary/release.js)
- [Commits](https://github.com/vercel/next.js/compare/v16.0.8...v16.0.10)

---
updated-dependencies:
- dependency-name: next
  dependency-version: 16.0.10
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 apps/frontend/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index f6186544..e60a678a 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -42,7 +42,7 @@
     "i": "^0.3.7",
     "js-confetti": "^0.13.1",
     "lucide-react": "^0.556.0",
-    "next": "16.0.8",
+    "next": "16.0.10",
     "next-recaptcha-v3": "^1.5.3",
     "nextjs-toploader": "^3.9.17",
     "npm": "^11.7.0",

From 3fa19104cb9c4a38f5e815caa40443c152343ca7 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sun, 11 Jan 2026 11:51:10 -0300
Subject: [PATCH 057/111] update dev script in package.json to include webpack

---
 apps/frontend/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index f6186544..09e6a894 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --webpack",
     "build": "next build --webpack",
     "start": "next start",
     "lint": "eslint \"src/**/*.{ts,tsx}\" --fix",

From 3eb22fa7c40442194f63a02fe07fea02aa7438ea Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 11 Jan 2026 14:25:17 -0300
Subject: [PATCH 058/111] fix: adjust shadcn/ui's settings file to use actual
 project settings

---
 apps/frontend/components.json | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/apps/frontend/components.json b/apps/frontend/components.json
index d81b404a..d09c9490 100644
--- a/apps/frontend/components.json
+++ b/apps/frontend/components.json
@@ -6,9 +6,11 @@
   "tailwind": {
     "config": "tailwind.config.js",
     "css": "src/app/globals.css",
-    "baseColor": "neutral",
-    "cssVariables": true,
-    "prefix": ""
+    "baseColor": "zinc",
+    "cssVariables": false,
+    "prefix": "",
+    "rsc": true,
+    "tsx": true
   },
   "iconLibrary": "lucide",
   "aliases": {

From deff8092b6cb07bf1db8301c6a4d23bd5ecb2c22 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 11 Jan 2026 14:26:53 -0300
Subject: [PATCH 059/111] fix: disable @shadcn/ui styles temporarily

These styles affected the project globally - I'd like to review the entire project as a whole to ensure we make the best use of the theme's stylesheet.
---
 apps/frontend/src/app/globals.css | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/frontend/src/app/globals.css b/apps/frontend/src/app/globals.css
index ac1db4c4..b5e385a9 100644
--- a/apps/frontend/src/app/globals.css
+++ b/apps/frontend/src/app/globals.css
@@ -180,7 +180,8 @@ body {
 ins.adsbygoogle[data-ad-status='unfilled'] {
   display: none !important;
 }
-/*---break---*/
+
+/*
 @theme inline {
   --transition-timing-function-out-back: cubic-bezier(0.34, 1.56, 0.51, 1.2);
   --radius-sm: calc(var(--radius) - 4px);
@@ -219,7 +220,7 @@ ins.adsbygoogle[data-ad-status='unfilled'] {
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
 }
-/*---break---*/
+
 :root {
   --radius: 0.625rem;
   --background: oklch(1 0 0);
@@ -254,7 +255,7 @@ ins.adsbygoogle[data-ad-status='unfilled'] {
   --sidebar-border: oklch(0.922 0 0);
   --sidebar-ring: oklch(0.708 0 0);
 }
-/*---break---*/
+
 .dark {
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
@@ -288,7 +289,7 @@ ins.adsbygoogle[data-ad-status='unfilled'] {
   --sidebar-border: oklch(1 0 0 / 10%);
   --sidebar-ring: oklch(0.556 0 0);
 }
-/*---break---*/
+
 @layer base {
   * {
     border-color: var(--color-border);
@@ -300,3 +301,4 @@ ins.adsbygoogle[data-ad-status='unfilled'] {
     color: var(--color-foreground);
   }
 }
+*/

From d7d9c753609af1acc967d36f41f303a33a4e2543 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 11 Jan 2026 14:29:11 -0300
Subject: [PATCH 060/111] chore: add `--webpack` flag to `next dev` command

Turbopack is not working with our particular setup of importing the `@nbw/database` package in the frontend. Webpack lets us mark that package as external to 'make it work', but it's not an ideal solution. We're working on refactoring the project to segregate DTOs from the `database` package so they can be imported in the frontend without dragging in things from the backend.
---
 apps/frontend/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index f6186544..09e6a894 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --webpack",
     "build": "next build --webpack",
     "start": "next start",
     "lint": "eslint \"src/**/*.{ts,tsx}\" --fix",

From c332eb5f0ed80d3173bf095ca9b8c09ae36cb2ec Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sun, 11 Jan 2026 14:31:04 -0300
Subject: [PATCH 061/111] refactor: update TypeScript configurations and
 improve type handling in auth and song modules

---
 apps/backend/src/auth/auth.service.spec.ts    |  2 +-
 apps/backend/src/auth/auth.service.ts         | 22 ++++++++++-------
 .../src/auth/strategies/JWT.strategy.spec.ts  |  4 ++--
 .../discord.strategy/discord.strategy.spec.ts |  2 +-
 .../auth/strategies/discord.strategy/index.ts |  2 +-
 .../auth/strategies/github.strategy.spec.ts   |  2 +-
 .../src/auth/strategies/github.strategy.ts    |  4 ++--
 .../auth/strategies/google.strategy.spec.ts   |  2 +-
 apps/backend/src/lib/GetRequestUser.spec.ts   |  2 +-
 apps/backend/src/song/song.controller.spec.ts | 24 +++++++++----------
 apps/backend/src/song/song.controller.ts      |  4 +++-
 apps/backend/src/song/song.service.spec.ts    |  2 --
 apps/backend/src/types/thumbnail.d.ts         | 14 +++++++++++
 apps/backend/tsconfig.json                    |  2 ++
 bun.lock                                      |  1 -
 15 files changed, 55 insertions(+), 34 deletions(-)
 create mode 100644 apps/backend/src/types/thumbnail.d.ts

diff --git a/apps/backend/src/auth/auth.service.spec.ts b/apps/backend/src/auth/auth.service.spec.ts
index 311fece9..2fb54343 100644
--- a/apps/backend/src/auth/auth.service.spec.ts
+++ b/apps/backend/src/auth/auth.service.spec.ts
@@ -192,7 +192,7 @@ describe('AuthService', () => {
       const refreshToken = 'refresh-token';
 
       spyOn(jwtService, 'signAsync').mockImplementation(
-        (payload, options: any) => {
+        (payload: any, options: any) => {
           if (options.secret === 'test-jwt-secret') {
             return Promise.resolve(accessToken);
           } else if (options.secret === 'test-jwt-refresh-secret') {
diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index aab47ca4..36072a8b 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -171,14 +171,20 @@ export class AuthService {
 
   public async createJwtPayload(payload: TokenPayload): Promise<Tokens> {
     const [accessToken, refreshToken] = await Promise.all([
-      this.jwtService.signAsync(payload, {
-        secret: this.JWT_SECRET,
-        expiresIn: this.JWT_EXPIRES_IN,
-      }),
-      this.jwtService.signAsync(payload, {
-        secret: this.JWT_REFRESH_SECRET,
-        expiresIn: this.JWT_REFRESH_EXPIRES_IN,
-      }),
+      this.jwtService.signAsync(
+        payload as object,
+        {
+          secret: this.JWT_SECRET,
+          expiresIn: this.JWT_EXPIRES_IN,
+        } as any,
+      ),
+      this.jwtService.signAsync(
+        payload as object,
+        {
+          secret: this.JWT_REFRESH_SECRET,
+          expiresIn: this.JWT_REFRESH_EXPIRES_IN,
+        } as any,
+      ),
     ]);
 
     return {
diff --git a/apps/backend/src/auth/strategies/JWT.strategy.spec.ts b/apps/backend/src/auth/strategies/JWT.strategy.spec.ts
index 052cae9e..c17b4f3f 100644
--- a/apps/backend/src/auth/strategies/JWT.strategy.spec.ts
+++ b/apps/backend/src/auth/strategies/JWT.strategy.spec.ts
@@ -33,7 +33,7 @@ describe('JwtStrategy', () => {
     it('should throw an error if JWT_SECRET is not set', () => {
       jest.spyOn(configService, 'getOrThrow').mockReturnValue(null);
 
-      expect(() => new JwtStrategy(configService)).toThrowError(
+      expect(() => new JwtStrategy(configService)).toThrow(
         'JwtStrategy requires a secret or key',
       );
     });
@@ -84,7 +84,7 @@ describe('JwtStrategy', () => {
 
       const payload = { userId: 'test-user-id' };
 
-      expect(() => jwtStrategy.validate(req, payload)).toThrowError(
+      expect(() => jwtStrategy.validate(req, payload)).toThrow(
         'No refresh token',
       );
     });
diff --git a/apps/backend/src/auth/strategies/discord.strategy/discord.strategy.spec.ts b/apps/backend/src/auth/strategies/discord.strategy/discord.strategy.spec.ts
index 0dbc8608..588074d7 100644
--- a/apps/backend/src/auth/strategies/discord.strategy/discord.strategy.spec.ts
+++ b/apps/backend/src/auth/strategies/discord.strategy/discord.strategy.spec.ts
@@ -43,7 +43,7 @@ describe('DiscordStrategy', () => {
     it('should throw an error if Discord config is missing', () => {
       jest.spyOn(configService, 'getOrThrow').mockReturnValueOnce(null);
 
-      expect(() => new DiscordStrategy(configService)).toThrowError(
+      expect(() => new DiscordStrategy(configService)).toThrow(
         'OAuth2Strategy requires a clientID option',
       );
     });
diff --git a/apps/backend/src/auth/strategies/discord.strategy/index.ts b/apps/backend/src/auth/strategies/discord.strategy/index.ts
index c31ea7e0..de2d6ebd 100644
--- a/apps/backend/src/auth/strategies/discord.strategy/index.ts
+++ b/apps/backend/src/auth/strategies/discord.strategy/index.ts
@@ -27,7 +27,7 @@ export class DiscordStrategy extends PassportStrategy(strategy, 'discord') {
       callbackUrl: `${SERVER_URL}/v1/auth/discord/callback`,
       scope: [DiscordPermissionScope.Email, DiscordPermissionScope.Identify],
       fetchScope: true,
-      prompt: 'none',
+      prompt: 'none' as const,
     };
 
     super(config);
diff --git a/apps/backend/src/auth/strategies/github.strategy.spec.ts b/apps/backend/src/auth/strategies/github.strategy.spec.ts
index c8793e00..a13b099b 100644
--- a/apps/backend/src/auth/strategies/github.strategy.spec.ts
+++ b/apps/backend/src/auth/strategies/github.strategy.spec.ts
@@ -43,7 +43,7 @@ describe('GithubStrategy', () => {
     it('should throw an error if GitHub config is missing', () => {
       jest.spyOn(configService, 'getOrThrow').mockReturnValueOnce(null);
 
-      expect(() => new GithubStrategy(configService)).toThrowError(
+      expect(() => new GithubStrategy(configService)).toThrow(
         'OAuth2Strategy requires a clientID option',
       );
     });
diff --git a/apps/backend/src/auth/strategies/github.strategy.ts b/apps/backend/src/auth/strategies/github.strategy.ts
index b7ea82ab..fbcc74d2 100644
--- a/apps/backend/src/auth/strategies/github.strategy.ts
+++ b/apps/backend/src/auth/strategies/github.strategy.ts
@@ -22,10 +22,10 @@ export class GithubStrategy extends PassportStrategy(strategy, 'github') {
     super({
       clientID: GITHUB_CLIENT_ID,
       clientSecret: GITHUB_CLIENT_SECRET,
-      redirect_uri: `${SERVER_URL}/v1/auth/github/callback`,
+      callbackURL: `${SERVER_URL}/v1/auth/github/callback`,
       scope: 'user:read,user:email',
       state: false,
-    });
+    } as any);
   }
 
   async validate(accessToken: string, refreshToken: string, profile: any) {
diff --git a/apps/backend/src/auth/strategies/google.strategy.spec.ts b/apps/backend/src/auth/strategies/google.strategy.spec.ts
index c1f1233e..ccee9e71 100644
--- a/apps/backend/src/auth/strategies/google.strategy.spec.ts
+++ b/apps/backend/src/auth/strategies/google.strategy.spec.ts
@@ -44,7 +44,7 @@ describe('GoogleStrategy', () => {
     it('should throw an error if Google config is missing', () => {
       jest.spyOn(configService, 'getOrThrow').mockReturnValueOnce(null);
 
-      expect(() => new GoogleStrategy(configService)).toThrowError(
+      expect(() => new GoogleStrategy(configService)).toThrow(
         'OAuth2Strategy requires a clientID option',
       );
     });
diff --git a/apps/backend/src/lib/GetRequestUser.spec.ts b/apps/backend/src/lib/GetRequestUser.spec.ts
index ebc2e65f..e85694fd 100644
--- a/apps/backend/src/lib/GetRequestUser.spec.ts
+++ b/apps/backend/src/lib/GetRequestUser.spec.ts
@@ -28,7 +28,7 @@ describe('validateUser', () => {
   });
 
   it('should throw an error if the user does not exist', () => {
-    expect(() => validateUser(null)).toThrowError(
+    expect(() => validateUser(null)).toThrow(
       new HttpException(
         {
           error: {
diff --git a/apps/backend/src/song/song.controller.spec.ts b/apps/backend/src/song/song.controller.spec.ts
index 51865a09..1a2fa4d6 100644
--- a/apps/backend/src/song/song.controller.spec.ts
+++ b/apps/backend/src/song/song.controller.spec.ts
@@ -249,7 +249,7 @@ describe('SongController', () => {
       const query: SongListQueryDTO = { page: 1, limit: 10 };
       const songList: SongPreviewDto[] = Array(10)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -271,7 +271,7 @@ describe('SongController', () => {
       const query: SongListQueryDTO = { page: 1, limit: 10 };
       const songList: SongPreviewDto[] = Array(5)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -291,7 +291,7 @@ describe('SongController', () => {
       const query: SongListQueryDTO = { page: 3, limit: 10 };
       const songList: SongPreviewDto[] = Array(10)
         .fill(null)
-        .map((_, i) => ({ id: `song-${20 + i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${20 + i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -312,7 +312,7 @@ describe('SongController', () => {
       const query: SongListQueryDTO = { page: 1, limit: 10, q: 'test search' };
       const songList: SongPreviewDto[] = Array(8)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -337,7 +337,7 @@ describe('SongController', () => {
       };
       const songList: SongPreviewDto[] = Array(3)
         .fill(null)
-        .map((_, i) => ({ id: `rock-song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `rock-song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -421,7 +421,7 @@ describe('SongController', () => {
       const q = 'test query';
       const songList: SongPreviewDto[] = Array(5)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -484,7 +484,7 @@ describe('SongController', () => {
       const q = 'test search';
       const songList: SongPreviewDto[] = Array(10)
         .fill(null)
-        .map((_, i) => ({ id: `song-${10 + i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${10 + i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -507,7 +507,7 @@ describe('SongController', () => {
       const q = 'popular song';
       const songList: SongPreviewDto[] = Array(50)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -529,7 +529,7 @@ describe('SongController', () => {
       const q = 'search term';
       const songList: SongPreviewDto[] = Array(3)
         .fill(null)
-        .map((_, i) => ({ id: `song-${40 + i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${40 + i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -587,7 +587,7 @@ describe('SongController', () => {
       const q = 'test';
       const songList: SongPreviewDto[] = Array(25)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -614,7 +614,7 @@ describe('SongController', () => {
       const q = 'trending';
       const songList: SongPreviewDto[] = Array(10)
         .fill(null)
-        .map((_, i) => ({ id: `song-${i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
@@ -635,7 +635,7 @@ describe('SongController', () => {
       const q = 'search';
       const songList: SongPreviewDto[] = Array(20)
         .fill(null)
-        .map((_, i) => ({ id: `song-${40 + i}` } as SongPreviewDto));
+        .map((_, i) => ({ id: `song-${40 + i}` } as unknown as SongPreviewDto));
 
       mockSongService.querySongs.mockResolvedValueOnce({
         content: songList,
diff --git a/apps/backend/src/song/song.controller.ts b/apps/backend/src/song/song.controller.ts
index d50f2a8f..2d311b8b 100644
--- a/apps/backend/src/song/song.controller.ts
+++ b/apps/backend/src/song/song.controller.ts
@@ -129,7 +129,9 @@ export class SongController {
       [SongSortType.NOTE_COUNT, 'stats.noteCount'],
     ]);
 
-    const sortField = sortFieldMap.get(query.sort) ?? 'createdAt';
+    const sortField = query.sort
+      ? sortFieldMap.get(query.sort) ?? 'createdAt'
+      : 'createdAt';
     const isDescending = query.order ? query.order === 'desc' : true;
 
     // Build PageQueryDTO with the sort field
diff --git a/apps/backend/src/song/song.service.spec.ts b/apps/backend/src/song/song.service.spec.ts
index 4a944f7f..4d0e7f21 100644
--- a/apps/backend/src/song/song.service.spec.ts
+++ b/apps/backend/src/song/song.service.spec.ts
@@ -1212,7 +1212,6 @@ describe('SongService', () => {
       };
 
       jest.spyOn(songModel, 'aggregate').mockReturnValue(mockAggregate as any);
-      jest.spyOn(songModel, 'populate').mockResolvedValue(songList);
 
       const result = await service.getRandomSongs(count);
 
@@ -1236,7 +1235,6 @@ describe('SongService', () => {
       };
 
       jest.spyOn(songModel, 'aggregate').mockReturnValue(mockAggregate as any);
-      jest.spyOn(songModel, 'populate').mockResolvedValue(songList);
 
       const result = await service.getRandomSongs(count, category);
 
diff --git a/apps/backend/src/types/thumbnail.d.ts b/apps/backend/src/types/thumbnail.d.ts
new file mode 100644
index 00000000..172e7cde
--- /dev/null
+++ b/apps/backend/src/types/thumbnail.d.ts
@@ -0,0 +1,14 @@
+declare module '@nbw/thumbnail/node' {
+  interface DrawParams {
+    notes: unknown;
+    startTick: number;
+    startLayer: number;
+    zoomLevel: number;
+    backgroundColor: string;
+    imgWidth: number;
+    imgHeight: number;
+  }
+
+  export function drawToImage(params: DrawParams): Promise<Buffer>;
+  export function drawNotesOffscreen(params: DrawParams): Promise<unknown>;
+}
diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 400170a1..35b9a8d0 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -9,6 +9,8 @@
     "allowSyntheticDefaultImports": true,
     "sourceMap": true,
     "emitDecoratorMetadata": true,
+    "moduleResolution": "node",
+    "noEmit": true,
 
     // Path mapping
     "baseUrl": ".",
diff --git a/bun.lock b/bun.lock
index b2cdbafe..d68c86ae 100644
--- a/bun.lock
+++ b/bun.lock
@@ -206,7 +206,6 @@
       "name": "@nbw/song",
       "dependencies": {
         "@encode42/nbs.js": "^5.0.2",
-        "@nbw/database": "workspace:*",
         "@timohausmann/quadtree-ts": "^2.2.2",
         "jszip": "^3.10.1",
         "unidecode": "^1.1.0",

From 57c969c2dc7ff2dc76ee351cbcbf1531bd59a1dd Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sun, 11 Jan 2026 14:46:06 -0300
Subject: [PATCH 062/111] chore(deps): update Next.js and related packages to
 version 16.0.10

---
 bun.lock | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/bun.lock b/bun.lock
index d68c86ae..c5cf1237 100644
--- a/bun.lock
+++ b/bun.lock
@@ -140,7 +140,7 @@
         "i": "^0.3.7",
         "js-confetti": "^0.13.1",
         "lucide-react": "^0.556.0",
-        "next": "16.0.8",
+        "next": "16.0.10",
         "next-recaptcha-v3": "^1.5.3",
         "nextjs-toploader": "^3.9.17",
         "npm": "^11.7.0",
@@ -720,27 +720,27 @@
 
     "@nestjs/throttler": ["@nestjs/throttler@6.5.0", "", { "peerDependencies": { "@nestjs/common": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0", "@nestjs/core": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0", "reflect-metadata": "^0.1.13 || ^0.2.0" } }, "sha512-9j0ZRfH0QE1qyrj9JjIRDz5gQLPqq9yVC2nHsrosDVAfI5HHw08/aUAWx9DZLSdQf4HDkmhTTEGLrRFHENvchQ=="],
 
-    "@next/env": ["@next/env@16.0.8", "", {}, "sha512-xP4WrQZuj9MdmLJy3eWFHepo+R3vznsMSS8Dy3wdA7FKpjCiesQ6DxZvdGziQisj0tEtCgBKJzjcAc4yZOgLEQ=="],
+    "@next/env": ["@next/env@16.0.10", "", {}, "sha512-8tuaQkyDVgeONQ1MeT9Mkk8pQmZapMKFh5B+OrFUlG3rVmYTXcXlBetBgTurKXGaIZvkoqRT9JL5K3phXcgang=="],
 
     "@next/eslint-plugin-next": ["@next/eslint-plugin-next@16.0.8", "", { "dependencies": { "fast-glob": "3.3.1" } }, "sha512-1miV0qXDcLUaOdHridVPCh4i39ElRIAraseVIbb3BEqyZ5ol9sPyjTP/GNTPV5rBxqxjF6/vv5zQTVbhiNaLqA=="],
 
     "@next/mdx": ["@next/mdx@16.0.8", "", { "dependencies": { "source-map": "^0.7.0" }, "peerDependencies": { "@mdx-js/loader": ">=0.15.0", "@mdx-js/react": ">=0.15.0" }, "optionalPeers": ["@mdx-js/loader", "@mdx-js/react"] }, "sha512-GPv0ouRVp6T/qaOZj3LJiiIUFputrHvC/FVgyedbCaIsfbXmfu+Ky24KWWjf6uQSvDWQnQTk3UMSHqHb5UMYLw=="],
 
-    "@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.0.8", "", { "os": "darwin", "cpu": "arm64" }, "sha512-yjVMvTQN21ZHOclQnhSFbjBTEizle+1uo4NV6L4rtS9WO3nfjaeJYw+H91G+nEf3Ef43TaEZvY5mPWfB/De7tA=="],
+    "@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.0.10", "", { "os": "darwin", "cpu": "arm64" }, "sha512-4XgdKtdVsaflErz+B5XeG0T5PeXKDdruDf3CRpnhN+8UebNa5N2H58+3GDgpn/9GBurrQ1uWW768FfscwYkJRg=="],
 
-    "@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.0.8", "", { "os": "darwin", "cpu": "x64" }, "sha512-+zu2N3QQ0ZOb6RyqQKfcu/pn0UPGmg+mUDqpAAEviAcEVEYgDckemOpiMRsBP3IsEKpcoKuNzekDcPczEeEIzA=="],
+    "@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.0.10", "", { "os": "darwin", "cpu": "x64" }, "sha512-spbEObMvRKkQ3CkYVOME+ocPDFo5UqHb8EMTS78/0mQ+O1nqE8toHJVioZo4TvebATxgA8XMTHHrScPrn68OGw=="],
 
-    "@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.0.8", "", { "os": "linux", "cpu": "arm64" }, "sha512-LConttk+BeD0e6RG0jGEP9GfvdaBVMYsLJ5aDDweKiJVVCu6sGvo+Ohz9nQhvj7EQDVVRJMCGhl19DmJwGr6bQ=="],
+    "@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.0.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-uQtWE3X0iGB8apTIskOMi2w/MKONrPOUCi5yLO+v3O8Mb5c7K4Q5KD1jvTpTF5gJKa3VH/ijKjKUq9O9UhwOYw=="],
 
-    "@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.0.8", "", { "os": "linux", "cpu": "arm64" }, "sha512-JaXFAlqn8fJV+GhhA9lpg6da/NCN/v9ub98n3HoayoUSPOVdoxEEt86iT58jXqQCs/R3dv5ZnxGkW8aF4obMrQ=="],
+    "@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.0.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-llA+hiDTrYvyWI21Z0L1GiXwjQaanPVQQwru5peOgtooeJ8qx3tlqRV2P7uH2pKQaUfHxI/WVarvI5oYgGxaTw=="],
 
-    "@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.0.8", "", { "os": "linux", "cpu": "x64" }, "sha512-O7M9it6HyNhsJp3HNAsJoHk5BUsfj7hRshfptpGcVsPZ1u0KQ/oVy8oxF7tlwxA5tR43VUP0yRmAGm1us514ng=="],
+    "@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.0.10", "", { "os": "linux", "cpu": "x64" }, "sha512-AK2q5H0+a9nsXbeZ3FZdMtbtu9jxW4R/NgzZ6+lrTm3d6Zb7jYrWcgjcpM1k8uuqlSy4xIyPR2YiuUr+wXsavA=="],
 
-    "@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.0.8", "", { "os": "linux", "cpu": "x64" }, "sha512-8+KClEC/GLI2dLYcrWwHu5JyC5cZYCFnccVIvmxpo6K+XQt4qzqM5L4coofNDZYkct/VCCyJWGbZZDsg6w6LFA=="],
+    "@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.0.10", "", { "os": "linux", "cpu": "x64" }, "sha512-1TDG9PDKivNw5550S111gsO4RGennLVl9cipPhtkXIFVwo31YZ73nEbLjNC8qG3SgTz/QZyYyaFYMeY4BKZR/g=="],
 
-    "@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.0.8", "", { "os": "win32", "cpu": "arm64" }, "sha512-rpQ/PgTEgH68SiXmhu/cJ2hk9aZ6YgFvspzQWe2I9HufY6g7V02DXRr/xrVqOaKm2lenBFPNQ+KAaeveywqV+A=="],
+    "@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.0.10", "", { "os": "win32", "cpu": "arm64" }, "sha512-aEZIS4Hh32xdJQbHz121pyuVZniSNoqDVx1yIr2hy+ZwJGipeqnMZBJHyMxv2tiuAXGx6/xpTcQJ6btIiBjgmg=="],
 
-    "@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.0.8", "", { "os": "win32", "cpu": "x64" }, "sha512-jWpWjWcMQu2iZz4pEK2IktcfR+OA9+cCG8zenyLpcW8rN4rzjfOzH4yj/b1FiEAZHKS+5Vq8+bZyHi+2yqHbFA=="],
+    "@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.0.10", "", { "os": "win32", "cpu": "x64" }, "sha512-E+njfCoFLb01RAFEnGZn6ERoOqhK1Gl3Lfz1Kjnj0Ulfu7oJbuMyvBKNj/bw8XZnenHDASlygTjZICQW+rYW1Q=="],
 
     "@next/third-parties": ["@next/third-parties@16.0.8", "", { "dependencies": { "third-party-capital": "1.0.20" }, "peerDependencies": { "next": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0-beta.0", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0" } }, "sha512-F8TNI1GFm7ivZX6HBMDVsDklAXOHlACbtw7w3WFbDk2oFXdVgKZBfdK+ILhjTBK4ibIXzLMWO1Py3bgSETKHYQ=="],
 
@@ -2474,7 +2474,7 @@
 
     "neo-async": ["neo-async@2.6.2", "", {}, "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw=="],
 
-    "next": ["next@16.0.8", "", { "dependencies": { "@next/env": "16.0.8", "@swc/helpers": "0.5.15", "caniuse-lite": "^1.0.30001579", "postcss": "8.4.31", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.0.8", "@next/swc-darwin-x64": "16.0.8", "@next/swc-linux-arm64-gnu": "16.0.8", "@next/swc-linux-arm64-musl": "16.0.8", "@next/swc-linux-x64-gnu": "16.0.8", "@next/swc-linux-x64-musl": "16.0.8", "@next/swc-win32-arm64-msvc": "16.0.8", "@next/swc-win32-x64-msvc": "16.0.8", "sharp": "^0.34.4" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-LmcZzG04JuzNXi48s5P+TnJBsTGPJunViNKV/iE4uM6kstjTQsQhvsAv+xF6MJxU2Pr26tl15eVbp0jQnsv6/g=="],
+    "next": ["next@16.0.10", "", { "dependencies": { "@next/env": "16.0.10", "@swc/helpers": "0.5.15", "caniuse-lite": "^1.0.30001579", "postcss": "8.4.31", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.0.10", "@next/swc-darwin-x64": "16.0.10", "@next/swc-linux-arm64-gnu": "16.0.10", "@next/swc-linux-arm64-musl": "16.0.10", "@next/swc-linux-x64-gnu": "16.0.10", "@next/swc-linux-x64-musl": "16.0.10", "@next/swc-win32-arm64-msvc": "16.0.10", "@next/swc-win32-x64-msvc": "16.0.10", "sharp": "^0.34.4" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-RtWh5PUgI+vxlV3HdR+IfWA1UUHu0+Ram/JBO4vWB54cVPentCD0e+lxyAYEsDTqGGMg7qpjhKh6dc6aW7W/sA=="],
 
     "next-recaptcha-v3": ["next-recaptcha-v3@1.5.3", "", { "peerDependencies": { "next": "^13 || ^14 || ^15 || ^16", "react": "^18 || ^19" } }, "sha512-Osnt1gj0+Mor8rc42NCzpteQrrSbcxskGLOeWLU/T0xdXtJE90y/gFyp87/yN1goIMI+gXs5f0PMymMa29nuLA=="],
 

From ed398097de180c2c7a4a4da7e104cf22b1906184 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 14 Jan 2026 21:18:24 -0300
Subject: [PATCH 063/111] chore: add `@nbw/thumbnail/node` type defs on backend

---
 apps/backend/src/types/thumbnail.d.ts | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/apps/backend/src/types/thumbnail.d.ts b/apps/backend/src/types/thumbnail.d.ts
index 172e7cde..c4e70c18 100644
--- a/apps/backend/src/types/thumbnail.d.ts
+++ b/apps/backend/src/types/thumbnail.d.ts
@@ -1,3 +1,28 @@
+/*
+ * Type Definitions for '@nbw/thumbnail/node' Module
+ *
+ * PURPOSE:
+ * This declaration file explicitly declares type definitions for the '@nbw/thumbnail/node'
+ * module. While the '@nbw/thumbnail' package exports both Node.js and browser-specific
+ * implementations via the modern 'exports' field in package.json, the backend's
+ * moduleResolution is set to 'node' (= node10, required for CommonJS module system compatibility),
+ * which does not understand the 'exports' field. This file bridges that gap.
+ *
+ * BACKGROUND:
+ * The @nbw/thumbnail package uses conditional exports to provide different entry points
+ * for Node.js and browser environments. Modern module resolution (e.g., 'bundler', 'node16+')
+ * understands this, but the 'node' resolver does not, causing import resolution issues like
+ * 'Cannot find module '@nbw/thumbnail' or its corresponding type declarations.'
+ *
+ * MAINTENANCE NOTE:
+ * If the @nbw/thumbnail package's exports change or if new functions/interfaces are added,
+ * this file must be updated to reflect those changes. Sync the DrawParams interface and
+ * exported functions with the actual implementation in packages/thumbnail/src/node/.
+ *
+ * ALTERNATIVES:
+ * // TODO: Update backend's moduleResolution to 'bundler', 'node16' or 'nodenext'
+ */
+
 declare module '@nbw/thumbnail/node' {
   interface DrawParams {
     notes: unknown;

From d34865f2441174425798a00b9288807152c63d8f Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 14 Jan 2026 21:57:36 -0300
Subject: [PATCH 064/111] chore(types): change backend's `moduleResolution` to
 `bundler`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This change stems from the fact that Nest.js now defaults to

```
    "module": "nodenext",
    "moduleResolution": "nodenext"
```

in recent releases. See:
https://github.com/nestjs/nest/issues/15919#issuecomment-3533271585

This change lets us support modern `exports` syntax such as `@nbw/thumbnail/node`, without requiring external type declarations or even causing any additional typing errors (which was the case with `moduleResolution: nodenext` due to its stricter syntax around exports and extensions).

Type-checking works fine, builds work fine, the backend starts just fine. ✅
---
 apps/backend/tsconfig.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/backend/tsconfig.json b/apps/backend/tsconfig.json
index 35b9a8d0..a23a38c9 100644
--- a/apps/backend/tsconfig.json
+++ b/apps/backend/tsconfig.json
@@ -2,14 +2,14 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     // NestJS specific settings
-    "module": "commonjs",
-    "target": "ES2021",
+    "module": "esnext",
+    "target": "esnext",
     "declaration": true,
     "removeComments": true,
     "allowSyntheticDefaultImports": true,
     "sourceMap": true,
     "emitDecoratorMetadata": true,
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "noEmit": true,
 
     // Path mapping

From 58a90d8e95e4d1e10e4eeabcfa94888d817e6716 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 14 Jan 2026 21:58:26 -0300
Subject: [PATCH 065/111] chore(types): remove type definitions for
 `@nbw/thumbnail/node`

No longer needed after changing `moduleResolution` to `bundler` in the backend.
---
 apps/backend/src/types/thumbnail.d.ts | 39 ---------------------------
 1 file changed, 39 deletions(-)
 delete mode 100644 apps/backend/src/types/thumbnail.d.ts

diff --git a/apps/backend/src/types/thumbnail.d.ts b/apps/backend/src/types/thumbnail.d.ts
deleted file mode 100644
index c4e70c18..00000000
--- a/apps/backend/src/types/thumbnail.d.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-/*
- * Type Definitions for '@nbw/thumbnail/node' Module
- *
- * PURPOSE:
- * This declaration file explicitly declares type definitions for the '@nbw/thumbnail/node'
- * module. While the '@nbw/thumbnail' package exports both Node.js and browser-specific
- * implementations via the modern 'exports' field in package.json, the backend's
- * moduleResolution is set to 'node' (= node10, required for CommonJS module system compatibility),
- * which does not understand the 'exports' field. This file bridges that gap.
- *
- * BACKGROUND:
- * The @nbw/thumbnail package uses conditional exports to provide different entry points
- * for Node.js and browser environments. Modern module resolution (e.g., 'bundler', 'node16+')
- * understands this, but the 'node' resolver does not, causing import resolution issues like
- * 'Cannot find module '@nbw/thumbnail' or its corresponding type declarations.'
- *
- * MAINTENANCE NOTE:
- * If the @nbw/thumbnail package's exports change or if new functions/interfaces are added,
- * this file must be updated to reflect those changes. Sync the DrawParams interface and
- * exported functions with the actual implementation in packages/thumbnail/src/node/.
- *
- * ALTERNATIVES:
- * // TODO: Update backend's moduleResolution to 'bundler', 'node16' or 'nodenext'
- */
-
-declare module '@nbw/thumbnail/node' {
-  interface DrawParams {
-    notes: unknown;
-    startTick: number;
-    startLayer: number;
-    zoomLevel: number;
-    backgroundColor: string;
-    imgWidth: number;
-    imgHeight: number;
-  }
-
-  export function drawToImage(params: DrawParams): Promise<Buffer>;
-  export function drawNotesOffscreen(params: DrawParams): Promise<unknown>;
-}

From 742930141f6d33a99454098a394998c6dd1db85a Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:06:12 -0300
Subject: [PATCH 066/111] refactor(types): remove redundant ternary operator in
 song query `sort` param

---
 apps/backend/src/song/song.controller.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/apps/backend/src/song/song.controller.ts b/apps/backend/src/song/song.controller.ts
index 4c315f3b..c1005d66 100644
--- a/apps/backend/src/song/song.controller.ts
+++ b/apps/backend/src/song/song.controller.ts
@@ -132,9 +132,7 @@ export class SongController {
       [SongSortType.NOTE_COUNT, 'stats.noteCount'],
     ]);
 
-    const sortField = query.sort
-      ? sortFieldMap.get(query.sort) ?? 'createdAt'
-      : 'createdAt';
+    const sortField = sortFieldMap.get(query.sort ?? SongSortType.RECENT);
     const isDescending = query.order ? query.order === 'desc' : true;
 
     // Build PageQueryDTO with the sort field

From c5a22d58bebc844834137a973826994098b724af Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:14:07 -0300
Subject: [PATCH 067/111] refactor(types): remove catch-all types for
 `jwtService.signAsync` call

---
 apps/backend/src/auth/auth.service.ts | 22 ++++++++--------------
 1 file changed, 8 insertions(+), 14 deletions(-)

diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index 36072a8b..8bfca85e 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -171,20 +171,14 @@ export class AuthService {
 
   public async createJwtPayload(payload: TokenPayload): Promise<Tokens> {
     const [accessToken, refreshToken] = await Promise.all([
-      this.jwtService.signAsync(
-        payload as object,
-        {
-          secret: this.JWT_SECRET,
-          expiresIn: this.JWT_EXPIRES_IN,
-        } as any,
-      ),
-      this.jwtService.signAsync(
-        payload as object,
-        {
-          secret: this.JWT_REFRESH_SECRET,
-          expiresIn: this.JWT_REFRESH_EXPIRES_IN,
-        } as any,
-      ),
+      this.jwtService.signAsync<TokenPayload>(payload, {
+        secret: this.JWT_SECRET,
+        expiresIn: this.JWT_EXPIRES_IN,
+      }),
+      this.jwtService.signAsync<TokenPayload>(payload, {
+        secret: this.JWT_REFRESH_SECRET,
+        expiresIn: this.JWT_REFRESH_EXPIRES_IN,
+      }),
     ]);
 
     return {

From 8e431228b5814710e66a523ac0e3a82eeed6d87f Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:17:26 -0300
Subject: [PATCH 068/111] fix(config): parse duration env configs on startup
 and coerce to `ms.StringValue`

---
 apps/backend/src/auth/auth.module.ts          | 11 ++---
 apps/backend/src/auth/auth.service.ts         |  9 ++--
 .../src/config/EnvironmentVariables.ts        | 44 ++++++++++++++++---
 3 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/apps/backend/src/auth/auth.module.ts b/apps/backend/src/auth/auth.module.ts
index e266b0bf..2a7b7a84 100644
--- a/apps/backend/src/auth/auth.module.ts
+++ b/apps/backend/src/auth/auth.module.ts
@@ -1,6 +1,7 @@
 import { DynamicModule, Logger, Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { JwtModule } from '@nestjs/jwt';
+import ms from 'ms';
 
 import { MailingModule } from '@server/mailing/mailing.module';
 import { UserModule } from '@server/user/user.module';
@@ -26,8 +27,8 @@ export class AuthModule {
           inject: [ConfigService],
           imports: [ConfigModule],
           useFactory: async (config: ConfigService) => {
-            const JWT_SECRET = config.get('JWT_SECRET');
-            const JWT_EXPIRES_IN = config.get('JWT_EXPIRES_IN');
+            const JWT_SECRET = config.get<ms.StringValue>('JWT_SECRET');
+            const JWT_EXPIRES_IN = config.get<ms.StringValue>('JWT_EXPIRES_IN');
 
             if (!JWT_SECRET) {
               Logger.error('JWT_SECRET is not set');
@@ -58,7 +59,7 @@ export class AuthModule {
           inject: [ConfigService],
           provide: 'COOKIE_EXPIRES_IN',
           useFactory: (configService: ConfigService) =>
-            configService.getOrThrow<string>('COOKIE_EXPIRES_IN'),
+            configService.getOrThrow<ms.StringValue>('COOKIE_EXPIRES_IN'),
         },
         {
           inject: [ConfigService],
@@ -82,7 +83,7 @@ export class AuthModule {
           inject: [ConfigService],
           provide: 'JWT_EXPIRES_IN',
           useFactory: (configService: ConfigService) =>
-            configService.getOrThrow<string>('JWT_EXPIRES_IN'),
+            configService.getOrThrow<ms.StringValue>('JWT_EXPIRES_IN'),
         },
         {
           inject: [ConfigService],
@@ -94,7 +95,7 @@ export class AuthModule {
           inject: [ConfigService],
           provide: 'JWT_REFRESH_EXPIRES_IN',
           useFactory: (configService: ConfigService) =>
-            configService.getOrThrow<string>('JWT_REFRESH_EXPIRES_IN'),
+            configService.getOrThrow<ms.StringValue>('JWT_REFRESH_EXPIRES_IN'),
         },
         {
           inject: [ConfigService],
diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index 8bfca85e..53237ea1 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -2,6 +2,7 @@ import { Inject, Injectable, Logger } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 import axios from 'axios';
 import type { Request, Response } from 'express';
+import ms from 'ms';
 
 import { CreateUser } from '@nbw/database';
 import type { UserDocument } from '@nbw/database';
@@ -22,18 +23,18 @@ export class AuthService {
     @Inject(JwtService)
     private readonly jwtService: JwtService,
     @Inject('COOKIE_EXPIRES_IN')
-    private readonly COOKIE_EXPIRES_IN: string,
+    private readonly COOKIE_EXPIRES_IN: ms.StringValue,
     @Inject('FRONTEND_URL')
     private readonly FRONTEND_URL: string,
 
     @Inject('JWT_SECRET')
     private readonly JWT_SECRET: string,
     @Inject('JWT_EXPIRES_IN')
-    private readonly JWT_EXPIRES_IN: string,
+    private readonly JWT_EXPIRES_IN: ms.StringValue,
     @Inject('JWT_REFRESH_SECRET')
     private readonly JWT_REFRESH_SECRET: string,
     @Inject('JWT_REFRESH_EXPIRES_IN')
-    private readonly JWT_REFRESH_EXPIRES_IN: string,
+    private readonly JWT_REFRESH_EXPIRES_IN: ms.StringValue,
     @Inject('APP_DOMAIN')
     private readonly APP_DOMAIN?: string,
   ) {}
@@ -199,7 +200,7 @@ export class AuthService {
 
     const frontEndURL = this.FRONTEND_URL;
     const domain = this.APP_DOMAIN;
-    const maxAge = parseInt(this.COOKIE_EXPIRES_IN) * 1000;
+    const maxAge = ms(this.COOKIE_EXPIRES_IN) * 1000;
 
     res.cookie('token', token.access_token, {
       domain: domain,
diff --git a/apps/backend/src/config/EnvironmentVariables.ts b/apps/backend/src/config/EnvironmentVariables.ts
index cbb15109..73e5afd2 100644
--- a/apps/backend/src/config/EnvironmentVariables.ts
+++ b/apps/backend/src/config/EnvironmentVariables.ts
@@ -1,5 +1,35 @@
 import { plainToInstance } from 'class-transformer';
-import { IsEnum, IsOptional, IsString, validateSync } from 'class-validator';
+import {
+  IsEnum,
+  IsOptional,
+  IsString,
+  registerDecorator,
+  validateSync,
+  ValidationArguments,
+  ValidationOptions,
+} from 'class-validator';
+import ms from 'ms';
+
+// Validate if the value is a valid duration string from the 'ms' library
+function IsDuration(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      name: 'isDuration',
+      target: object.constructor,
+      propertyName: propertyName,
+      options: validationOptions,
+      validator: {
+        validate(value: unknown) {
+          if (typeof value !== 'string') return false;
+          return typeof ms(value as ms.StringValue) === 'number';
+        },
+        defaultMessage(args: ValidationArguments) {
+          return `${args.property} must be a valid duration string (e.g., "1h", "30m", "7d")`;
+        },
+      },
+    });
+  };
+}
 
 enum Environment {
   Development = 'development',
@@ -38,14 +68,14 @@ export class EnvironmentVariables {
   @IsString()
   JWT_SECRET: string;
 
-  @IsString()
-  JWT_EXPIRES_IN: string;
+  @IsDuration()
+  JWT_EXPIRES_IN: ms.StringValue;
 
   @IsString()
   JWT_REFRESH_SECRET: string;
 
-  @IsString()
-  JWT_REFRESH_EXPIRES_IN: string;
+  @IsDuration()
+  JWT_REFRESH_EXPIRES_IN: ms.StringValue;
 
   // database
   @IsString()
@@ -91,8 +121,8 @@ export class EnvironmentVariables {
   @IsString()
   DISCORD_WEBHOOK_URL: string;
 
-  @IsString()
-  COOKIE_EXPIRES_IN: string;
+  @IsDuration()
+  COOKIE_EXPIRES_IN: ms.StringValue;
 }
 
 export function validate(config: Record<string, unknown>) {

From bf1acef919e196198e97b35f6019135099bbf7d4 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:20:00 -0300
Subject: [PATCH 069/111] fix(config) use `config.getOrThrow` to simplify logic
 in `AuthModule`

+ don't assume 60s if no value is provided
---
 apps/backend/src/auth/auth.module.ts | 18 +++++-------------
 1 file changed, 5 insertions(+), 13 deletions(-)

diff --git a/apps/backend/src/auth/auth.module.ts b/apps/backend/src/auth/auth.module.ts
index 2a7b7a84..725ad27e 100644
--- a/apps/backend/src/auth/auth.module.ts
+++ b/apps/backend/src/auth/auth.module.ts
@@ -1,4 +1,4 @@
-import { DynamicModule, Logger, Module } from '@nestjs/common';
+import { DynamicModule, Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { JwtModule } from '@nestjs/jwt';
 import ms from 'ms';
@@ -27,21 +27,13 @@ export class AuthModule {
           inject: [ConfigService],
           imports: [ConfigModule],
           useFactory: async (config: ConfigService) => {
-            const JWT_SECRET = config.get<ms.StringValue>('JWT_SECRET');
-            const JWT_EXPIRES_IN = config.get<ms.StringValue>('JWT_EXPIRES_IN');
-
-            if (!JWT_SECRET) {
-              Logger.error('JWT_SECRET is not set');
-              throw new Error('JWT_SECRET is not set');
-            }
-
-            if (!JWT_EXPIRES_IN) {
-              Logger.warn('JWT_EXPIRES_IN is not set, using default of 60s');
-            }
+            const JWT_SECRET = config.getOrThrow<ms.StringValue>('JWT_SECRET');
+            const JWT_EXPIRES_IN =
+              config.getOrThrow<ms.StringValue>('JWT_EXPIRES_IN');
 
             return {
               secret: JWT_SECRET,
-              signOptions: { expiresIn: JWT_EXPIRES_IN || '60s' },
+              signOptions: { expiresIn: JWT_EXPIRES_IN },
             };
           },
         }),

From 98c472bce3085a234ff67a099bbe446774472caf Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:21:20 -0300
Subject: [PATCH 070/111] fix(config): validator's `defaultMessage` not being
 shown on env validation

---
 apps/backend/src/config/EnvironmentVariables.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/apps/backend/src/config/EnvironmentVariables.ts b/apps/backend/src/config/EnvironmentVariables.ts
index 73e5afd2..a933ce57 100644
--- a/apps/backend/src/config/EnvironmentVariables.ts
+++ b/apps/backend/src/config/EnvironmentVariables.ts
@@ -135,7 +135,13 @@ export function validate(config: Record<string, unknown>) {
   });
 
   if (errors.length > 0) {
-    throw new Error(errors.toString());
+    const messages = errors
+      .map((error) => {
+        const constraints = Object.values(error.constraints || {});
+        return `  - ${error.property}: ${constraints.join(', ')}`;
+      })
+      .join('\n');
+    throw new Error(`Environment validation failed:\n${messages}`);
   }
 
   return validatedConfig;

From ba1d3b90067c57e1d35fcda4b89015532c804030 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:39:33 -0300
Subject: [PATCH 071/111] chore(types): add TODO for improving typing on GitHub
 login strategy

---
 apps/backend/src/auth/strategies/github.strategy.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/backend/src/auth/strategies/github.strategy.ts b/apps/backend/src/auth/strategies/github.strategy.ts
index fbcc74d2..048a491e 100644
--- a/apps/backend/src/auth/strategies/github.strategy.ts
+++ b/apps/backend/src/auth/strategies/github.strategy.ts
@@ -25,7 +25,7 @@ export class GithubStrategy extends PassportStrategy(strategy, 'github') {
       callbackURL: `${SERVER_URL}/v1/auth/github/callback`,
       scope: 'user:read,user:email',
       state: false,
-    } as any);
+    } as any); // TODO: Fix types
   }
 
   async validate(accessToken: string, refreshToken: string, profile: any) {

From b25030b5b09f7a6441793b5b773c83a359c148f9 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 15 Jan 2026 21:28:47 -0300
Subject: [PATCH 072/111] test(song): remove duplicate authorization tests

---
 apps/backend/src/song/song.service.spec.ts | 50 ----------------------
 1 file changed, 50 deletions(-)

diff --git a/apps/backend/src/song/song.service.spec.ts b/apps/backend/src/song/song.service.spec.ts
index bdb63285..edf8dfb6 100644
--- a/apps/backend/src/song/song.service.spec.ts
+++ b/apps/backend/src/song/song.service.spec.ts
@@ -308,23 +308,6 @@ describe('SongService', () => {
         HttpException,
       );
     });
-
-    it('should throw an error if user is unauthorized', async () => {
-      const publicId = 'test-id';
-      const user: UserDocument = { _id: 'test-user-id' } as UserDocument;
-      const songEntity = new SongEntity();
-      songEntity.uploader = new mongoose.Types.ObjectId(); // Different uploader
-
-      const mockFindOne = {
-        exec: jest.fn().mockResolvedValue(songEntity),
-      };
-
-      jest.spyOn(songModel, 'findOne').mockReturnValue(mockFindOne as any);
-
-      await expect(service.deleteSong(publicId, user)).rejects.toThrow(
-        HttpException,
-      );
-    });
   });
 
   describe('patchSong', () => {
@@ -495,39 +478,6 @@ describe('SongService', () => {
       );
     });
 
-    it('should throw an error if user is unauthorized', async () => {
-      const publicId = 'test-id';
-      const user: UserDocument = { _id: 'test-user-id' } as UserDocument;
-
-      const body: UploadSongDto = {
-        title: 'Test Song',
-        originalAuthor: 'Test Author',
-        description: 'Test Description',
-        category: 'alternative',
-        visibility: 'public',
-        license: 'standard',
-        customInstruments: [],
-        thumbnailData: {
-          startTick: 0,
-          startLayer: 0,
-          zoomLevel: 1,
-          backgroundColor: '#000000',
-        },
-        file: 'somebytes',
-        allowDownload: false,
-      };
-
-      const songEntity = {
-        uploader: 'different-user-id',
-      } as any;
-
-      jest.spyOn(songModel, 'findOne').mockReturnValue(songEntity);
-
-      await expect(service.patchSong(publicId, body, user)).rejects.toThrow(
-        HttpException,
-      );
-    });
-
     it('should throw an error if user no changes are provided', async () => {
       const publicId = 'test-id';
       const user: UserDocument = { _id: 'test-user-id' } as UserDocument;

From 04beab8ea9fa6b9a886d881eb481f2879805ab91 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 16 Jan 2026 01:14:55 -0300
Subject: [PATCH 073/111] chore: upgrade tailwindcss to 4.1.18

---
 apps/frontend/package.json |  4 +--
 bun.lock                   | 53 +++++++++++++++++++-------------------
 2 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index 80d26fdf..2af666cd 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -59,7 +59,7 @@
     "schema-dts": "^1.1.5",
     "sharp": "^0.34.5",
     "tailwind-merge": "^3.4.0",
-    "tailwindcss": "4.1.17",
+    "tailwindcss": "^4.1.18",
     "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.9.3",
     "zod": "^4.1.13",
@@ -68,7 +68,7 @@
   },
   "devDependencies": {
     "@shrutibalasa/tailwind-grid-auto-fit": "^1.1.0",
-    "@tailwindcss/postcss": "^4.1.17",
+    "@tailwindcss/postcss": "^4.1.18",
     "@types/mdx": "^2.0.13",
     "@types/react-modal": "^3.16.3",
     "eslint-config-next": "16.0.8",
diff --git a/bun.lock b/bun.lock
index c5cf1237..327d539b 100644
--- a/bun.lock
+++ b/bun.lock
@@ -7,6 +7,7 @@
       "dependencies": {
         "@nbw/sounds": "workspace:*",
         "@types/jest": "^30.0.0",
+        "tailwindcss": "^4.1.18",
       },
       "devDependencies": {
         "@eslint/js": "^9.36.0",
@@ -157,7 +158,7 @@
         "schema-dts": "^1.1.5",
         "sharp": "^0.34.5",
         "tailwind-merge": "^3.4.0",
-        "tailwindcss": "4.1.17",
+        "tailwindcss": "^4.1.18",
         "tailwindcss-animate": "^1.0.7",
         "typescript": "^5.9.3",
         "zod": "^4.1.13",
@@ -166,7 +167,7 @@
       },
       "devDependencies": {
         "@shrutibalasa/tailwind-grid-auto-fit": "^1.1.0",
-        "@tailwindcss/postcss": "^4.1.17",
+        "@tailwindcss/postcss": "^4.1.18",
         "@types/mdx": "^2.0.13",
         "@types/react-modal": "^3.16.3",
         "eslint-config-next": "16.0.8",
@@ -960,35 +961,35 @@
 
     "@swc/helpers": ["@swc/helpers@0.5.15", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g=="],
 
-    "@tailwindcss/node": ["@tailwindcss/node@4.1.17", "", { "dependencies": { "@jridgewell/remapping": "^2.3.4", "enhanced-resolve": "^5.18.3", "jiti": "^2.6.1", "lightningcss": "1.30.2", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.1.17" } }, "sha512-csIkHIgLb3JisEFQ0vxr2Y57GUNYh447C8xzwj89U/8fdW8LhProdxvnVH6U8M2Y73QKiTIH+LWbK3V2BBZsAg=="],
+    "@tailwindcss/node": ["@tailwindcss/node@4.1.18", "", { "dependencies": { "@jridgewell/remapping": "^2.3.4", "enhanced-resolve": "^5.18.3", "jiti": "^2.6.1", "lightningcss": "1.30.2", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.1.18" } }, "sha512-DoR7U1P7iYhw16qJ49fgXUlry1t4CpXeErJHnQ44JgTSKMaZUdf17cfn5mHchfJ4KRBZRFA/Coo+MUF5+gOaCQ=="],
 
-    "@tailwindcss/oxide": ["@tailwindcss/oxide@4.1.17", "", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.1.17", "@tailwindcss/oxide-darwin-arm64": "4.1.17", "@tailwindcss/oxide-darwin-x64": "4.1.17", "@tailwindcss/oxide-freebsd-x64": "4.1.17", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.1.17", "@tailwindcss/oxide-linux-arm64-gnu": "4.1.17", "@tailwindcss/oxide-linux-arm64-musl": "4.1.17", "@tailwindcss/oxide-linux-x64-gnu": "4.1.17", "@tailwindcss/oxide-linux-x64-musl": "4.1.17", "@tailwindcss/oxide-wasm32-wasi": "4.1.17", "@tailwindcss/oxide-win32-arm64-msvc": "4.1.17", "@tailwindcss/oxide-win32-x64-msvc": "4.1.17" } }, "sha512-F0F7d01fmkQhsTjXezGBLdrl1KresJTcI3DB8EkScCldyKp3Msz4hub4uyYaVnk88BAS1g5DQjjF6F5qczheLA=="],
+    "@tailwindcss/oxide": ["@tailwindcss/oxide@4.1.18", "", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.1.18", "@tailwindcss/oxide-darwin-arm64": "4.1.18", "@tailwindcss/oxide-darwin-x64": "4.1.18", "@tailwindcss/oxide-freebsd-x64": "4.1.18", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.1.18", "@tailwindcss/oxide-linux-arm64-gnu": "4.1.18", "@tailwindcss/oxide-linux-arm64-musl": "4.1.18", "@tailwindcss/oxide-linux-x64-gnu": "4.1.18", "@tailwindcss/oxide-linux-x64-musl": "4.1.18", "@tailwindcss/oxide-wasm32-wasi": "4.1.18", "@tailwindcss/oxide-win32-arm64-msvc": "4.1.18", "@tailwindcss/oxide-win32-x64-msvc": "4.1.18" } }, "sha512-EgCR5tTS5bUSKQgzeMClT6iCY3ToqE1y+ZB0AKldj809QXk1Y+3jB0upOYZrn9aGIzPtUsP7sX4QQ4XtjBB95A=="],
 
-    "@tailwindcss/oxide-android-arm64": ["@tailwindcss/oxide-android-arm64@4.1.17", "", { "os": "android", "cpu": "arm64" }, "sha512-BMqpkJHgOZ5z78qqiGE6ZIRExyaHyuxjgrJ6eBO5+hfrfGkuya0lYfw8fRHG77gdTjWkNWEEm+qeG2cDMxArLQ=="],
+    "@tailwindcss/oxide-android-arm64": ["@tailwindcss/oxide-android-arm64@4.1.18", "", { "os": "android", "cpu": "arm64" }, "sha512-dJHz7+Ugr9U/diKJA0W6N/6/cjI+ZTAoxPf9Iz9BFRF2GzEX8IvXxFIi/dZBloVJX/MZGvRuFA9rqwdiIEZQ0Q=="],
 
-    "@tailwindcss/oxide-darwin-arm64": ["@tailwindcss/oxide-darwin-arm64@4.1.17", "", { "os": "darwin", "cpu": "arm64" }, "sha512-EquyumkQweUBNk1zGEU/wfZo2qkp/nQKRZM8bUYO0J+Lums5+wl2CcG1f9BgAjn/u9pJzdYddHWBiFXJTcxmOg=="],
+    "@tailwindcss/oxide-darwin-arm64": ["@tailwindcss/oxide-darwin-arm64@4.1.18", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Gc2q4Qhs660bhjyBSKgq6BYvwDz4G+BuyJ5H1xfhmDR3D8HnHCmT/BSkvSL0vQLy/nkMLY20PQ2OoYMO15Jd0A=="],
 
-    "@tailwindcss/oxide-darwin-x64": ["@tailwindcss/oxide-darwin-x64@4.1.17", "", { "os": "darwin", "cpu": "x64" }, "sha512-gdhEPLzke2Pog8s12oADwYu0IAw04Y2tlmgVzIN0+046ytcgx8uZmCzEg4VcQh+AHKiS7xaL8kGo/QTiNEGRog=="],
+    "@tailwindcss/oxide-darwin-x64": ["@tailwindcss/oxide-darwin-x64@4.1.18", "", { "os": "darwin", "cpu": "x64" }, "sha512-FL5oxr2xQsFrc3X9o1fjHKBYBMD1QZNyc1Xzw/h5Qu4XnEBi3dZn96HcHm41c/euGV+GRiXFfh2hUCyKi/e+yw=="],
 
-    "@tailwindcss/oxide-freebsd-x64": ["@tailwindcss/oxide-freebsd-x64@4.1.17", "", { "os": "freebsd", "cpu": "x64" }, "sha512-hxGS81KskMxML9DXsaXT1H0DyA+ZBIbyG/sSAjWNe2EDl7TkPOBI42GBV3u38itzGUOmFfCzk1iAjDXds8Oh0g=="],
+    "@tailwindcss/oxide-freebsd-x64": ["@tailwindcss/oxide-freebsd-x64@4.1.18", "", { "os": "freebsd", "cpu": "x64" }, "sha512-Fj+RHgu5bDodmV1dM9yAxlfJwkkWvLiRjbhuO2LEtwtlYlBgiAT4x/j5wQr1tC3SANAgD+0YcmWVrj8R9trVMA=="],
 
-    "@tailwindcss/oxide-linux-arm-gnueabihf": ["@tailwindcss/oxide-linux-arm-gnueabihf@4.1.17", "", { "os": "linux", "cpu": "arm" }, "sha512-k7jWk5E3ldAdw0cNglhjSgv501u7yrMf8oeZ0cElhxU6Y2o7f8yqelOp3fhf7evjIS6ujTI3U8pKUXV2I4iXHQ=="],
+    "@tailwindcss/oxide-linux-arm-gnueabihf": ["@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18", "", { "os": "linux", "cpu": "arm" }, "sha512-Fp+Wzk/Ws4dZn+LV2Nqx3IilnhH51YZoRaYHQsVq3RQvEl+71VGKFpkfHrLM/Li+kt5c0DJe/bHXK1eHgDmdiA=="],
 
-    "@tailwindcss/oxide-linux-arm64-gnu": ["@tailwindcss/oxide-linux-arm64-gnu@4.1.17", "", { "os": "linux", "cpu": "arm64" }, "sha512-HVDOm/mxK6+TbARwdW17WrgDYEGzmoYayrCgmLEw7FxTPLcp/glBisuyWkFz/jb7ZfiAXAXUACfyItn+nTgsdQ=="],
+    "@tailwindcss/oxide-linux-arm64-gnu": ["@tailwindcss/oxide-linux-arm64-gnu@4.1.18", "", { "os": "linux", "cpu": "arm64" }, "sha512-S0n3jboLysNbh55Vrt7pk9wgpyTTPD0fdQeh7wQfMqLPM/Hrxi+dVsLsPrycQjGKEQk85Kgbx+6+QnYNiHalnw=="],
 
-    "@tailwindcss/oxide-linux-arm64-musl": ["@tailwindcss/oxide-linux-arm64-musl@4.1.17", "", { "os": "linux", "cpu": "arm64" }, "sha512-HvZLfGr42i5anKtIeQzxdkw/wPqIbpeZqe7vd3V9vI3RQxe3xU1fLjss0TjyhxWcBaipk7NYwSrwTwK1hJARMg=="],
+    "@tailwindcss/oxide-linux-arm64-musl": ["@tailwindcss/oxide-linux-arm64-musl@4.1.18", "", { "os": "linux", "cpu": "arm64" }, "sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg=="],
 
-    "@tailwindcss/oxide-linux-x64-gnu": ["@tailwindcss/oxide-linux-x64-gnu@4.1.17", "", { "os": "linux", "cpu": "x64" }, "sha512-M3XZuORCGB7VPOEDH+nzpJ21XPvK5PyjlkSFkFziNHGLc5d6g3di2McAAblmaSUNl8IOmzYwLx9NsE7bplNkwQ=="],
+    "@tailwindcss/oxide-linux-x64-gnu": ["@tailwindcss/oxide-linux-x64-gnu@4.1.18", "", { "os": "linux", "cpu": "x64" }, "sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g=="],
 
-    "@tailwindcss/oxide-linux-x64-musl": ["@tailwindcss/oxide-linux-x64-musl@4.1.17", "", { "os": "linux", "cpu": "x64" }, "sha512-k7f+pf9eXLEey4pBlw+8dgfJHY4PZ5qOUFDyNf7SI6lHjQ9Zt7+NcscjpwdCEbYi6FI5c2KDTDWyf2iHcCSyyQ=="],
+    "@tailwindcss/oxide-linux-x64-musl": ["@tailwindcss/oxide-linux-x64-musl@4.1.18", "", { "os": "linux", "cpu": "x64" }, "sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ=="],
 
-    "@tailwindcss/oxide-wasm32-wasi": ["@tailwindcss/oxide-wasm32-wasi@4.1.17", "", { "dependencies": { "@emnapi/core": "^1.6.0", "@emnapi/runtime": "^1.6.0", "@emnapi/wasi-threads": "^1.1.0", "@napi-rs/wasm-runtime": "^1.0.7", "@tybys/wasm-util": "^0.10.1", "tslib": "^2.4.0" }, "cpu": "none" }, "sha512-cEytGqSSoy7zK4JRWiTCx43FsKP/zGr0CsuMawhH67ONlH+T79VteQeJQRO/X7L0juEUA8ZyuYikcRBf0vsxhg=="],
+    "@tailwindcss/oxide-wasm32-wasi": ["@tailwindcss/oxide-wasm32-wasi@4.1.18", "", { "dependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1", "@emnapi/wasi-threads": "^1.1.0", "@napi-rs/wasm-runtime": "^1.1.0", "@tybys/wasm-util": "^0.10.1", "tslib": "^2.4.0" }, "cpu": "none" }, "sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA=="],
 
-    "@tailwindcss/oxide-win32-arm64-msvc": ["@tailwindcss/oxide-win32-arm64-msvc@4.1.17", "", { "os": "win32", "cpu": "arm64" }, "sha512-JU5AHr7gKbZlOGvMdb4722/0aYbU+tN6lv1kONx0JK2cGsh7g148zVWLM0IKR3NeKLv+L90chBVYcJ8uJWbC9A=="],
+    "@tailwindcss/oxide-win32-arm64-msvc": ["@tailwindcss/oxide-win32-arm64-msvc@4.1.18", "", { "os": "win32", "cpu": "arm64" }, "sha512-HjSA7mr9HmC8fu6bdsZvZ+dhjyGCLdotjVOgLA2vEqxEBZaQo9YTX4kwgEvPCpRh8o4uWc4J/wEoFzhEmjvPbA=="],
 
-    "@tailwindcss/oxide-win32-x64-msvc": ["@tailwindcss/oxide-win32-x64-msvc@4.1.17", "", { "os": "win32", "cpu": "x64" }, "sha512-SKWM4waLuqx0IH+FMDUw6R66Hu4OuTALFgnleKbqhgGU30DY20NORZMZUKgLRjQXNN2TLzKvh48QXTig4h4bGw=="],
+    "@tailwindcss/oxide-win32-x64-msvc": ["@tailwindcss/oxide-win32-x64-msvc@4.1.18", "", { "os": "win32", "cpu": "x64" }, "sha512-bJWbyYpUlqamC8dpR7pfjA0I7vdF6t5VpUGMWRkXVE3AXgIZjYUYAK7II1GNaxR8J1SSrSrppRar8G++JekE3Q=="],
 
-    "@tailwindcss/postcss": ["@tailwindcss/postcss@4.1.17", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "@tailwindcss/node": "4.1.17", "@tailwindcss/oxide": "4.1.17", "postcss": "^8.4.41", "tailwindcss": "4.1.17" } }, "sha512-+nKl9N9mN5uJ+M7dBOOCzINw94MPstNR/GtIhz1fpZysxL/4a+No64jCBD6CPN+bIHWFx3KWuu8XJRrj/572Dw=="],
+    "@tailwindcss/postcss": ["@tailwindcss/postcss@4.1.18", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "@tailwindcss/node": "4.1.18", "@tailwindcss/oxide": "4.1.18", "postcss": "^8.4.41", "tailwindcss": "4.1.18" } }, "sha512-Ce0GFnzAOuPyfV5SxjXGn0CubwGcuDB0zcdaPuCSzAa/2vII24JTkH+I6jcbXLb1ctjZMZZI6OjDaLPJQL1S0g=="],
 
     "@tanstack/react-virtual": ["@tanstack/react-virtual@3.13.12", "", { "dependencies": { "@tanstack/virtual-core": "3.13.12" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Gd13QdxPSukP8ZrkbgS2RwoZseTTbQPLnQEn7HY/rqtM+8Zt95f7xKC7N0EsKs7aoz0WzZ+fditZux+F8EzYxA=="],
 
@@ -2976,7 +2977,7 @@
 
     "tailwind-merge": ["tailwind-merge@3.4.0", "", {}, "sha512-uSaO4gnW+b3Y2aWoWfFpX62vn2sR3skfhbjsEnaBI81WD1wBLlHZe5sWf0AqjksNdYTbGBEd0UasQMT3SNV15g=="],
 
-    "tailwindcss": ["tailwindcss@4.1.17", "", {}, "sha512-j9Ee2YjuQqYT9bbRTfTZht9W/ytp5H+jJpZKiYdP/bpnXARAuELt9ofP0lPnmHjbga7SNQIxdTAXCmtKVYjN+Q=="],
+    "tailwindcss": ["tailwindcss@4.1.18", "", {}, "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw=="],
 
     "tailwindcss-animate": ["tailwindcss-animate@1.0.7", "", { "peerDependencies": { "tailwindcss": ">=3.0.0 || insiders" } }, "sha512-bl6mpH3T7I3UFxuvDEXLxy/VuFxBk5bbzplh7tXI68mwMokNYd1t9qPBHlnyTwfa4JGC4zP516I1hYYtQ/vspA=="],
 
@@ -3316,17 +3317,17 @@
 
     "@nbw/backend/@types/node": ["@types/node@24.10.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-WOhQTZ4G8xZ1tjJTvKOpyEVSGgOTvJAfDK3FNFgELyaTpzhdgHVHeqW8V+UJvzF5BT+/B54T/1S2K6gd9c7bbA=="],
 
-    "@nbw/config/@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+    "@nbw/config/@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
-    "@nbw/database/@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+    "@nbw/database/@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
     "@nbw/frontend/@types/node": ["@types/node@24.10.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-WOhQTZ4G8xZ1tjJTvKOpyEVSGgOTvJAfDK3FNFgELyaTpzhdgHVHeqW8V+UJvzF5BT+/B54T/1S2K6gd9c7bbA=="],
 
-    "@nbw/song/@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+    "@nbw/song/@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
     "@nbw/sounds/@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
 
-    "@nbw/thumbnail/@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+    "@nbw/thumbnail/@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
     "@nbw/thumbnail/jest": ["jest@29.7.0", "", { "dependencies": { "@jest/core": "^29.7.0", "@jest/types": "^29.6.3", "import-local": "^3.0.2", "jest-cli": "^29.7.0" }, "peerDependencies": { "node-notifier": "^8.0.1 || ^9.0.0 || ^10.0.0" }, "optionalPeers": ["node-notifier"], "bin": { "jest": "bin/jest.js" } }, "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw=="],
 
@@ -4076,17 +4077,17 @@
 
     "@nbw/backend/@types/node/undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
-    "@nbw/config/@types/bun/bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+    "@nbw/config/@types/bun/bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
-    "@nbw/database/@types/bun/bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+    "@nbw/database/@types/bun/bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
     "@nbw/frontend/@types/node/undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
-    "@nbw/song/@types/bun/bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+    "@nbw/song/@types/bun/bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
     "@nbw/sounds/@types/bun/bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
 
-    "@nbw/thumbnail/@types/bun/bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+    "@nbw/thumbnail/@types/bun/bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
     "@nbw/thumbnail/jest/@jest/core": ["@jest/core@29.7.0", "", { "dependencies": { "@jest/console": "^29.7.0", "@jest/reporters": "^29.7.0", "@jest/test-result": "^29.7.0", "@jest/transform": "^29.7.0", "@jest/types": "^29.6.3", "@types/node": "*", "ansi-escapes": "^4.2.1", "chalk": "^4.0.0", "ci-info": "^3.2.0", "exit": "^0.1.2", "graceful-fs": "^4.2.9", "jest-changed-files": "^29.7.0", "jest-config": "^29.7.0", "jest-haste-map": "^29.7.0", "jest-message-util": "^29.7.0", "jest-regex-util": "^29.6.3", "jest-resolve": "^29.7.0", "jest-resolve-dependencies": "^29.7.0", "jest-runner": "^29.7.0", "jest-runtime": "^29.7.0", "jest-snapshot": "^29.7.0", "jest-util": "^29.7.0", "jest-validate": "^29.7.0", "jest-watcher": "^29.7.0", "micromatch": "^4.0.4", "pretty-format": "^29.7.0", "slash": "^3.0.0", "strip-ansi": "^6.0.0" }, "peerDependencies": { "node-notifier": "^8.0.1 || ^9.0.0 || ^10.0.0" }, "optionalPeers": ["node-notifier"] }, "sha512-n7aeXWKMnGtDA48y8TLWJPJmLmmZ642Ceo78cYWEpiD7FzDgmNDV/GCVRorPABdXLJZ/9wzzgZAlHjXjxDHGsg=="],
 

From 9d3b8919813f868b2caa8de5c8d09a88fffd6d70 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 16 Jan 2026 13:38:49 -0300
Subject: [PATCH 074/111] fix: properly upgrade project to Tailwind CSS v4

- Applied all changes described in the page below, through a combination of the automatic upgrade tool (`$ bunx @tailwindcss/upgrade`) and manual revision
https://tailwindcss.com/docs/upgrade-guide

- Simplified arbitrary values syntax in many cases (e.g. `w-[4.25rem]` `w-17`)

Fixes subtle differences from current production version regarding:

- kerning;
- font size (the font appears to be the same, but it seems to be slightly stretched in the vertical axis);
- breakpoints (behavior didn't break, but the same screen size yields different layouts in production vs. development version);
- border radius;
- spacing (margins, padding);
- line height;
- etc.
---
 apps/frontend/src/app/(content)/(info)/about/page.tsx     | 2 +-
 apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx | 4 ++--
 apps/frontend/src/app/(content)/(info)/blog/page.tsx      | 6 +++---
 apps/frontend/src/app/(content)/(info)/contact/page.tsx   | 2 +-
 apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx | 2 +-
 apps/frontend/src/app/(content)/(info)/help/page.tsx      | 4 ++--
 apps/frontend/src/app/(external)/layout.tsx               | 2 +-
 apps/frontend/src/app/layout.tsx                          | 2 +-
 apps/frontend/src/app/not-found.tsx                       | 6 +++---
 apps/frontend/src/modules/auth/components/loginPage.tsx   | 4 ++--
 .../src/modules/auth/components/loginWithEmailPage.tsx    | 4 ++--
 apps/frontend/src/modules/browse/EventBanner.tsx          | 4 ++--
 apps/frontend/src/modules/browse/WelcomeBanner.tsx        | 4 ++--
 .../src/modules/browse/components/HomePageComponent.tsx   | 2 +-
 apps/frontend/src/modules/browse/components/SongCard.tsx  | 8 ++++----
 .../src/modules/my-songs/components/client/SongRow.tsx    | 2 +-
 .../src/modules/shared/components/CustomMarkdown.tsx      | 2 +-
 .../src/modules/shared/components/NoteBlockWorldLogo.tsx  | 6 +++---
 .../src/modules/shared/components/client/Carousel.tsx     | 2 +-
 .../src/modules/shared/components/client/Command.tsx      | 6 +++---
 .../src/modules/shared/components/client/CookieBanner.tsx | 4 ++--
 .../src/modules/shared/components/client/ErrorBox.tsx     | 2 +-
 .../src/modules/shared/components/client/FormElements.tsx | 6 +++---
 .../src/modules/shared/components/client/Popover.tsx      | 2 +-
 .../src/modules/shared/components/client/ads/AdSlots.tsx  | 4 ++--
 .../modules/shared/components/layout/DocumentLayout.tsx   | 2 +-
 .../src/modules/shared/components/layout/Footer.tsx       | 8 ++++----
 .../src/modules/shared/components/layout/Header.tsx       | 4 ++--
 .../src/modules/shared/components/layout/NavbarLayout.tsx | 2 +-
 .../src/modules/shared/components/layout/SearchBar.tsx    | 2 +-
 .../modules/shared/components/layout/SongThumbnail.tsx    | 2 +-
 .../src/modules/shared/components/layout/UserMenu.tsx     | 2 +-
 .../src/modules/shared/components/layout/UserMenuLink.tsx | 2 +-
 .../src/modules/shared/components/layout/popover.tsx      | 2 +-
 apps/frontend/src/modules/shared/components/ui/badge.tsx  | 2 +-
 .../frontend/src/modules/shared/components/ui/command.tsx | 8 ++++----
 .../src/modules/shared/components/ui/dualRangeSlider.tsx  | 2 +-
 .../shared/components/ui/multipleSelectorProps.tsx        | 6 +++---
 apps/frontend/src/modules/shared/components/ui/select.tsx | 8 ++++----
 apps/frontend/src/modules/shared/components/ui/slider.tsx | 2 +-
 apps/frontend/src/modules/song-search/SearchSongPage.tsx  | 8 ++++----
 .../song-upload/components/client/UploadCompleteModal.tsx | 2 +-
 apps/frontend/src/modules/song/components/SongDetails.tsx | 2 +-
 apps/frontend/src/modules/song/components/SongPage.tsx    | 2 +-
 .../modules/song/components/client/DownloadSongModal.tsx  | 2 +-
 .../src/modules/song/components/client/FileDisplay.tsx    | 4 ++--
 .../modules/song/components/client/InstrumentPicker.tsx   | 4 ++--
 .../src/modules/song/components/client/ShareModal.tsx     | 2 +-
 .../src/modules/song/components/client/SongCanvas.tsx     | 2 +-
 .../src/modules/song/components/client/SongSelector.tsx   | 4 ++--
 .../modules/song/components/client/SongThumbnailInput.tsx | 2 +-
 .../modules/song/components/client/ThumbnailRenderer.tsx  | 5 +----
 52 files changed, 91 insertions(+), 94 deletions(-)

diff --git a/apps/frontend/src/app/(content)/(info)/about/page.tsx b/apps/frontend/src/app/(content)/(info)/about/page.tsx
index 37916161..d7e9ceea 100644
--- a/apps/frontend/src/app/(content)/(info)/about/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/about/page.tsx
@@ -12,7 +12,7 @@ export const metadata: Metadata = {
 const AboutPage = () => {
   return (
     <>
-      <article className='max-w-screen-md mx-auto mb-36'>
+      <article className='max-w-(--breakpoint-md) mx-auto mb-36'>
         <NoteBlockWorldLogo
           size={112}
           orientation='horizontal'
diff --git a/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx b/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx
index 5773f799..a0e90d94 100644
--- a/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/blog/[id]/page.tsx
@@ -50,12 +50,12 @@ const BlogPost = async ({ params }: BlogPageProps) => {
         <Image
           src={post.image}
           alt=''
-          className='w-full h-[30vh] md:h-[50vh] object-cover mb-8 mt-[-2.5rem] rounded-xl'
+          className='w-full h-[30vh] md:h-[50vh] object-cover mb-8 -mt-10 rounded-xl'
           width={1920}
           height={1080}
         />
       )}
-      <article className='max-w-screen-md mx-auto mb-36'>
+      <article className='max-w-(--breakpoint-md) mx-auto mb-36'>
         <Link
           href='/blog'
           className='text-zinc-500 hover:text-zinc-400 text-sm'
diff --git a/apps/frontend/src/app/(content)/(info)/blog/page.tsx b/apps/frontend/src/app/(content)/(info)/blog/page.tsx
index bcadb92c..4cdab16b 100644
--- a/apps/frontend/src/app/(content)/(info)/blog/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/blog/page.tsx
@@ -33,7 +33,7 @@ const BlogPageComponent = ({ posts }: { posts: PostType[] }) => {
         {"See what we've been working on!"}
       </h2>
 
-      <section className='grid grid-auto-fit-xl max-w-screen-md mx-auto justify-center w-full items-center gap-8'>
+      <section className='grid grid-auto-fit-xl max-w-(--breakpoint-md) mx-auto justify-center w-full items-center gap-8'>
         {posts.map((post, i) => (
           <Link
             key={i}
@@ -46,10 +46,10 @@ const BlogPageComponent = ({ posts }: { posts: PostType[] }) => {
                 width={480}
                 height={360}
                 alt=''
-                className='rounded-md aspect-[16/9] w-full object-cover transition-all duration-300 mb-2'
+                className='rounded-md aspect-video w-full object-cover transition-all duration-300 mb-2'
               />
 
-              <h3 className='text-lg font-bold text-opacity-50 mb-2 leading-6 flex-grow'>
+              <h3 className='text-lg font-bold mb-2 leading-6 grow'>
                 {post.title}
               </h3>
               <p className='text-zinc-300 tracking-wide text-sm mb-2'>
diff --git a/apps/frontend/src/app/(content)/(info)/contact/page.tsx b/apps/frontend/src/app/(content)/(info)/contact/page.tsx
index ebd20a1a..18f5728d 100644
--- a/apps/frontend/src/app/(content)/(info)/contact/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/contact/page.tsx
@@ -11,7 +11,7 @@ export const metadata: Metadata = {
 const AboutPage = () => {
   return (
     <>
-      <article className='max-w-screen-md mx-auto mb-36'>
+      <article className='max-w-(--breakpoint-md) mx-auto mb-36'>
         <BackButton className='text-zinc-500 hover:text-zinc-400 text-sm'>
           {'< Back'}
         </BackButton>
diff --git a/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx b/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
index d776871e..5c372fbc 100644
--- a/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/help/[id]/page.tsx
@@ -46,7 +46,7 @@ const HelpPost = async ({ params }: HelpPageProps) => {
 
   return (
     <>
-      <article className='max-w-screen-md mx-auto mb-36'>
+      <article className='max-w-(--breakpoint-md) mx-auto mb-36'>
         <Link
           href='/help'
           className='text-zinc-500 hover:text-zinc-400 text-sm'
diff --git a/apps/frontend/src/app/(content)/(info)/help/page.tsx b/apps/frontend/src/app/(content)/(info)/help/page.tsx
index f0984c24..83805466 100644
--- a/apps/frontend/src/app/(content)/(info)/help/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/help/page.tsx
@@ -45,11 +45,11 @@ const HelpPageComponent = ({ posts }: { posts: PostType[] }) => {
                 width={480}
                 height={360}
                 alt={post.title}
-                className='rounded-2xl aspect-[3/2] object-cover brightness-150 transition-all duration-300'
+                className='rounded-2xl aspect-3/2 object-cover brightness-150 transition-all duration-300'
               />
 
               {/* Gradient over the image */}
-              <div className='absolute top-0 left-0 w-full h-full hover:bg-white/20 transition-all duration-300 bg-gradient-to-b from-transparent to-black/80 rounded-2xl'>
+              <div className='absolute top-0 left-0 w-full h-full hover:bg-white/20 transition-all duration-300 bg-linear-to-b from-transparent to-black/80 rounded-2xl'>
                 <h3 className='relative w-full h-full p-3 sm:p-6 flex justify-center items-end text-xl text-opacity-50'>
                   {post.shortTitle || post.title}
                 </h3>
diff --git a/apps/frontend/src/app/(external)/layout.tsx b/apps/frontend/src/app/(external)/layout.tsx
index aa9d1eb1..36d17c19 100644
--- a/apps/frontend/src/app/(external)/layout.tsx
+++ b/apps/frontend/src/app/(external)/layout.tsx
@@ -10,7 +10,7 @@ export default async function LoginLayout({
   return (
     <>
       <div
-        className="fixed z-[-1] w-full h-full bg-center bg-repeat grayscale-[50%] before:content-[''] before:absolute before:w-full before:h-full before:bg-gradient-to-b before:from-black/20 before:to-black/90"
+        className="fixed z-[-1] w-full h-full bg-center bg-repeat grayscale-50 before:content-[''] before:absolute before:w-full before:h-full before:bg-linear-to-b before:from-black/20 before:to-black/90"
         style={{
           backgroundImage: "url('/background-tile-flat.png')",
         }}
diff --git a/apps/frontend/src/app/layout.tsx b/apps/frontend/src/app/layout.tsx
index 6e9f65ae..95c5f561 100644
--- a/apps/frontend/src/app/layout.tsx
+++ b/apps/frontend/src/app/layout.tsx
@@ -102,7 +102,7 @@ export default function RootLayout({
           <Toaster
             position='bottom-center'
             toastOptions={{
-              className: '!bg-zinc-700 !text-white !max-w-fit',
+              className: 'bg-zinc-700! text-white! max-w-fit!',
               duration: 4000,
             }}
           />
diff --git a/apps/frontend/src/app/not-found.tsx b/apps/frontend/src/app/not-found.tsx
index 618e98f6..e6544d41 100644
--- a/apps/frontend/src/app/not-found.tsx
+++ b/apps/frontend/src/app/not-found.tsx
@@ -40,13 +40,13 @@ export default function NotFound() {
   return (
     <>
       <div
-        className="fixed w-full h-full bg-center bg-repeat grayscale brightness-50 opacity-30 before:content-[''] before:absolute before:w-full before:h-full before:bg-gradient-to-b before:from-black/20 before:to-black/80"
+        className="fixed w-full h-full bg-center bg-repeat grayscale brightness-50 opacity-30 before:content-[''] before:absolute before:w-full before:h-full before:bg-linear-to-b before:from-black/20 before:to-black/80"
         style={{
           backgroundImage: "url('/background-tile-flat.png')",
         }}
       ></div>
 
-      <main className='w-full h-screen text-center [&>*]:z-[2] p-2 bg-zinc-900 flex flex-col items-center justify-center gap-8'>
+      <main className='w-full h-screen text-center *:z-2 p-2 bg-zinc-900 flex flex-col items-center justify-center gap-8'>
         {/* Background image */}
 
         <p className='font-light text-zinc-400 text-5xl'>Oops...</p>
@@ -57,7 +57,7 @@ export default function NotFound() {
             width={400}
             height={400}
             quality={95}
-            className='object-contain relative md:left-8 top-8 w-64 md:w-full z-[2]'
+            className='object-contain relative md:left-8 top-8 w-64 md:w-full z-2'
           />
           <h1 className='leading-none font-black text-[10rem] md:text-[18rem] z-1 text-zinc-600/30 relative bottom-8 md:right-12 md:bottom-16'>
             404
diff --git a/apps/frontend/src/modules/auth/components/loginPage.tsx b/apps/frontend/src/modules/auth/components/loginPage.tsx
index 5551d6d3..ab799c13 100644
--- a/apps/frontend/src/modules/auth/components/loginPage.tsx
+++ b/apps/frontend/src/modules/auth/components/loginPage.tsx
@@ -51,9 +51,9 @@ export const LoginPage = () => {
         <NoteBlockWorldLogo glow={true} orientation='adaptive' size={128} />
 
         {/* Vertical divider (mobile) */}
-        <div className='w-[1px] min-h-full hidden sm:block bg-zinc-600'></div>
+        <div className='w-px min-h-full hidden sm:block bg-zinc-600'></div>
         {/* Horizontal divider (desktop) */}
-        <div className='h-[1px] min-w-full block sm:hidden bg-zinc-600'></div>
+        <div className='h-px min-w-full block sm:hidden bg-zinc-600'></div>
 
         {/* Right half */}
         <div className='flex flex-col justify-center items-center gap-5'>
diff --git a/apps/frontend/src/modules/auth/components/loginWithEmailPage.tsx b/apps/frontend/src/modules/auth/components/loginWithEmailPage.tsx
index 06367fd3..9607bdec 100644
--- a/apps/frontend/src/modules/auth/components/loginWithEmailPage.tsx
+++ b/apps/frontend/src/modules/auth/components/loginWithEmailPage.tsx
@@ -14,9 +14,9 @@ export const LoginWithEmailPage = () => {
         <NoteBlockWorldLogo glow={true} orientation='adaptive' size={128} />
 
         {/* Vertical divider (mobile) */}
-        <div className='w-[1px] min-h-full hidden sm:block bg-zinc-600'></div>
+        <div className='w-px min-h-full hidden sm:block bg-zinc-600'></div>
         {/* Horizontal divider (desktop) */}
-        <div className='h-[1px] min-w-full block sm:hidden bg-zinc-600'></div>
+        <div className='h-px min-w-full block sm:hidden bg-zinc-600'></div>
 
         {/* Right half */}
         <div className='flex flex-col justify-center items-center gap-5'>
diff --git a/apps/frontend/src/modules/browse/EventBanner.tsx b/apps/frontend/src/modules/browse/EventBanner.tsx
index 496b0791..81f864fc 100644
--- a/apps/frontend/src/modules/browse/EventBanner.tsx
+++ b/apps/frontend/src/modules/browse/EventBanner.tsx
@@ -32,7 +32,7 @@ export const EventBanner = () => {
   };
 
   return (
-    <div className='flex flex-row mx-auto w-fit justify-between items-center text-pretty gap-6 py-4 px-2 sm:px-8 text-md rounded-xl mb-10 bg-top backdrop-filter backdrop-blur-lg bg-opacity-50 bg-gradient-to-br from-15% from-pink-800 via-rose-900 to-85% to-red-900 relative'>
+    <div className='flex flex-row mx-auto w-fit justify-between items-center text-pretty gap-6 py-4 px-2 sm:px-8 text-md rounded-xl mb-10 bg-top backdrop-filter backdrop-blur-lg bg-linear-to-br from-15% from-pink-800/50 via-rose-900/50 to-85% to-red-900/50 relative'>
       <div
         className='absolute h-full w-full top-0 left-0 z-[-1] rounded-xl opacity-50 brightness-[0.3]'
         style={{
@@ -43,7 +43,7 @@ export const EventBanner = () => {
       ></div>
       <Image src='/img/event/maestro-icon.png' alt='' width={64} height={64} />
 
-      <div className='flex-1 leading-tight max-w-screen-md w-fit'>
+      <div className='flex-1 leading-tight max-w-(--breakpoint-md) w-fit'>
         <p className='uppercase text-md font-bold tracking-wider text-yellow-300 mb-1 w-fit'>
           <FontAwesomeIcon icon={faExclamationCircle} />{' '}
           {timeLeft === 0 ? (
diff --git a/apps/frontend/src/modules/browse/WelcomeBanner.tsx b/apps/frontend/src/modules/browse/WelcomeBanner.tsx
index ba489bc2..63f3e264 100644
--- a/apps/frontend/src/modules/browse/WelcomeBanner.tsx
+++ b/apps/frontend/src/modules/browse/WelcomeBanner.tsx
@@ -3,7 +3,7 @@ import Link from 'next/link';
 
 export const WelcomeBanner = () => {
   return (
-    <div className='flex flex-col md:flex-row mx-auto w-fit justify-between items-center text-center text-balance gap-1 py-4 px-2 sm:px-8 text-sm rounded-xl mb-10 bg-top backdrop-filter backdrop-blur-lg bg-opacity-50 bg-gradient-to-br from-15% from-green-700 via-cyan-800 to-85% to-blue-900 border-2 border-white/20'>
+    <div className='flex flex-col md:flex-row mx-auto w-fit justify-between items-center text-center text-balance gap-1 py-4 px-2 sm:px-8 text-sm rounded-xl mb-10 bg-top backdrop-filter backdrop-blur-lg bg-linear-to-br from-15% from-green-700/50 via-cyan-800/50 to-85% to-blue-900/50 border-2 border-white/20'>
       <div
         className='absolute h-full w-full top-0 left-0 z-[-1] rounded-xl opacity-20 brightness-50 hue-rotate-90'
         style={{
@@ -19,7 +19,7 @@ export const WelcomeBanner = () => {
         width={100}
         height={100}
       />
-      <div className='flex-1 leading-tight max-w-screen-md'>
+      <div className='flex-1 leading-tight max-w-(--breakpoint-md)'>
         <h1 className='text-lg font-bold mb-1 text-green-400'>
           Welcome to <strong className='text-teal-300'>Note Block World</strong>
           !
diff --git a/apps/frontend/src/modules/browse/components/HomePageComponent.tsx b/apps/frontend/src/modules/browse/components/HomePageComponent.tsx
index 9edcd140..0f9d3ccf 100644
--- a/apps/frontend/src/modules/browse/components/HomePageComponent.tsx
+++ b/apps/frontend/src/modules/browse/components/HomePageComponent.tsx
@@ -82,7 +82,7 @@ export const HomePageComponent = () => {
 
       {/* RECENT SONGS */}
       <div className='flex flex-row flex-wrap justify-between items-center gap-4 mb-2'>
-        <h2 className='text-xl uppercase z-[2]'>Recent songs</h2>
+        <h2 className='text-xl uppercase z-2'>Recent songs</h2>
         <CategoryButtonGroup />
       </div>
       <div className='h-6' />
diff --git a/apps/frontend/src/modules/browse/components/SongCard.tsx b/apps/frontend/src/modules/browse/components/SongCard.tsx
index e2e3d4ac..5910abbc 100644
--- a/apps/frontend/src/modules/browse/components/SongCard.tsx
+++ b/apps/frontend/src/modules/browse/components/SongCard.tsx
@@ -17,7 +17,7 @@ const SongDataDisplay = ({ song }: { song: SongPreviewDtoType | null }) => {
       <div className='relative'>
         {!song ? (
           <Skeleton
-            className='w-full h-full rounded-lg aspect-[5/3] object-cover'
+            className='w-full h-full rounded-lg aspect-5/3 object-cover'
             containerClassName='block leading-none'
           />
         ) : (
@@ -33,9 +33,9 @@ const SongDataDisplay = ({ song }: { song: SongPreviewDtoType | null }) => {
       </div>
 
       {/* Song info */}
-      <div className='flex flex-row justify-between px-4 pt-0.5 text-pretty flex-grow'>
+      <div className='flex flex-row justify-between px-4 pt-0.5 text-pretty grow'>
         {/* Song title */}
-        <h3 className='text-md font-semibold leading-tight w-full h-10 flex-grow line-clamp-2'>
+        <h3 className='text-md font-semibold leading-tight w-full h-10 grow line-clamp-2'>
           {song?.title || <Skeleton count={2} />}
         </h3>
       </div>
@@ -51,7 +51,7 @@ const SongDataDisplay = ({ song }: { song: SongPreviewDtoType | null }) => {
           )}
         </p>
         {/* Play icon & count */}
-        <div className='text-md flex items-center gap-1 flex-shrink'>
+        <div className='text-md flex items-center gap-1 shrink'>
           {!song ? (
             <Skeleton className='min-w-16' />
           ) : (
diff --git a/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx b/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx
index 418e8f38..9333cb9b 100644
--- a/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx
+++ b/apps/frontend/src/modules/my-songs/components/client/SongRow.tsx
@@ -41,7 +41,7 @@ export const SongRow = ({ song }: { song?: SongPreviewDtoType | null }) => {
     >
       {/* Thumbnail */}
       <div className='col-span-1'>
-        <div className='aspect-[5/3] w-full object-cover rounded-lg relative block leading-none'>
+        <div className='aspect-5/3 w-full object-cover rounded-lg relative block leading-none'>
           {!song ? (
             <Skeleton className='w-full h-full' />
           ) : (
diff --git a/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx b/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx
index fdad1fec..523597ee 100644
--- a/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx
+++ b/apps/frontend/src/modules/shared/components/CustomMarkdown.tsx
@@ -105,7 +105,7 @@ const code = ({
   return (
     <code
       {...props}
-      className='bg-zinc-950/50 text-green-400 rounded-md outline outline-1 outline-zinc-600 text-sm font-mono px-1 py-0.5 mx-0.5'
+      className='bg-zinc-950/50 text-green-400 rounded-md outline-1 outline-zinc-600 text-sm font-mono px-1 py-0.5 mx-0.5'
     />
   );
 };
diff --git a/apps/frontend/src/modules/shared/components/NoteBlockWorldLogo.tsx b/apps/frontend/src/modules/shared/components/NoteBlockWorldLogo.tsx
index 4b83afe1..e302ef18 100644
--- a/apps/frontend/src/modules/shared/components/NoteBlockWorldLogo.tsx
+++ b/apps/frontend/src/modules/shared/components/NoteBlockWorldLogo.tsx
@@ -16,13 +16,13 @@ export const NoteBlockWorldLogo = ({
   let flexConfig, marginConfig;
 
   if (orientation === 'horizontal') {
-    flexConfig = 'flex-row mr-[-2rem]';
+    flexConfig = 'flex-row -mr-8';
     marginConfig = 'right-8';
   } else if (orientation === 'vertical') {
-    flexConfig = 'flex-col mb-[-2.5rem]';
+    flexConfig = 'flex-col -mb-10';
     marginConfig = 'bottom-10';
   } else {
-    flexConfig = 'flex-row sm:flex-col mr-[-2rem] sm:mr-0 sm:mb-[-2.5rem]';
+    flexConfig = 'flex-row sm:flex-col -mr-8 sm:mr-0 sm:-mb-10';
     marginConfig = 'right-8 sm:right-0 sm:bottom-10';
   }
 
diff --git a/apps/frontend/src/modules/shared/components/client/Carousel.tsx b/apps/frontend/src/modules/shared/components/client/Carousel.tsx
index e28ad30c..add8b9e3 100644
--- a/apps/frontend/src/modules/shared/components/client/Carousel.tsx
+++ b/apps/frontend/src/modules/shared/components/client/Carousel.tsx
@@ -181,7 +181,7 @@ export const CarouselContent = forwardRef<
   const { carouselRef } = useCarousel();
 
   return (
-    <div ref={carouselRef} className='overflow-hidden p-4 m-[-1rem]'>
+    <div ref={carouselRef} className='overflow-hidden p-4 -m-4'>
       <div ref={ref} className={cn('flex', className)} {...props} />
     </div>
   );
diff --git a/apps/frontend/src/modules/shared/components/client/Command.tsx b/apps/frontend/src/modules/shared/components/client/Command.tsx
index a8c20b3f..05134107 100644
--- a/apps/frontend/src/modules/shared/components/client/Command.tsx
+++ b/apps/frontend/src/modules/shared/components/client/Command.tsx
@@ -39,7 +39,7 @@ const CommandInput = React.forwardRef<
     <CommandPrimitive.Input
       ref={ref}
       className={cn(
-        'flex h-11 w-full rounded-md bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
+        'flex h-11 w-full rounded-md bg-transparent py-3 text-sm outline-hidden placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
         className,
       )}
       {...props}
@@ -82,7 +82,7 @@ const CommandGroup = React.forwardRef<
   <CommandPrimitive.Group
     ref={ref}
     className={cn(
-      'overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground',
+      'overflow-hidden p-1 text-foreground **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground',
       className,
     )}
     {...props}
@@ -111,7 +111,7 @@ const CommandItem = React.forwardRef<
   <CommandPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center rounded-md px-2 py-1.5 text-sm outline-none hover:bg-blue-600 transition-colors duration-100 data-[disabled=true]:pointer-events-none data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50',
+      'relative flex cursor-default select-none items-center rounded-md px-2 py-1.5 text-sm outline-hidden hover:bg-blue-600 transition-colors duration-100 data-[disabled=true]:pointer-events-none data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50',
       className,
     )}
     {...props}
diff --git a/apps/frontend/src/modules/shared/components/client/CookieBanner.tsx b/apps/frontend/src/modules/shared/components/client/CookieBanner.tsx
index 527dae0e..f20ab2a4 100644
--- a/apps/frontend/src/modules/shared/components/client/CookieBanner.tsx
+++ b/apps/frontend/src/modules/shared/components/client/CookieBanner.tsx
@@ -25,11 +25,11 @@ export const CookieBanner = () => {
 
   return (
     <div className='fixed bottom-0 w-full min-h-32 z-10 flex justify-center bg-blue-900/80 border-t-blue-500/80 border-t-4 border-zinc-700 backdrop-blur-md py-4'>
-      <div className='relative w-[1280px] max-w-screen-xl px-6 sm:px-10'>
+      <div className='relative w-(--breakpoint-xl) max-w-(--breakpoint-xl) px-6 sm:px-10'>
         {/* Close button */}
         <button
           onClick={handleAccept}
-          className='absolute top-[-0.5rem] right-12 text-lg text-zinc-400 hover:text-zinc-300'
+          className='absolute -top-2 right-12 text-lg text-zinc-400 hover:text-zinc-300'
         >
           <FontAwesomeIcon icon={faClose} />
         </button>
diff --git a/apps/frontend/src/modules/shared/components/client/ErrorBox.tsx b/apps/frontend/src/modules/shared/components/client/ErrorBox.tsx
index b5d2619a..ac56739f 100644
--- a/apps/frontend/src/modules/shared/components/client/ErrorBox.tsx
+++ b/apps/frontend/src/modules/shared/components/client/ErrorBox.tsx
@@ -3,7 +3,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 
 export const ErrorBox = ({ message }: { message: string }) => {
   return (
-    <div className='outline outline-2 text-center text-balance outline-red-500 bg-red-800 p-2 rounded-lg'>
+    <div className='outline-2 text-center text-balance outline-red-500 bg-red-800 p-2 rounded-lg'>
       <FontAwesomeIcon icon={faWarning} className='mr-2 h-4' />
       {message}
     </div>
diff --git a/apps/frontend/src/modules/shared/components/client/FormElements.tsx b/apps/frontend/src/modules/shared/components/client/FormElements.tsx
index 614fcbbc..fc7f7baf 100644
--- a/apps/frontend/src/modules/shared/components/client/FormElements.tsx
+++ b/apps/frontend/src/modules/shared/components/client/FormElements.tsx
@@ -20,7 +20,7 @@ export const Label = forwardRef<
   const { id, label } = props;
 
   return (
-    <label htmlFor={id} ref={ref} className='text-sm text-zinc-300'>
+    <label htmlFor={id} ref={ref} className='text-zinc-300 text-[14px]'>
       {label}
     </label>
   );
@@ -49,7 +49,7 @@ export const Area = ({
       ) : (
         <div
           className={cn(
-            'flex justify-center w-full rounded-lg outline-none border-2 border-zinc-500 p-8 mb-4',
+            'flex justify-center w-full rounded-lg outline-hidden border-2 border-zinc-500 p-8 mb-4',
             className,
           )}
         >
@@ -245,7 +245,7 @@ export const Slider = forwardRef<
     <SliderPrimitive.Track className='relative h-2 w-full grow overflow-hidden rounded-full bg-secondary'>
       <SliderPrimitive.Range className='absolute h-full bg-primary' />
     </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className='block h-5 w-5 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50' />
+    <SliderPrimitive.Thumb className='block h-5 w-5 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50' />
   </SliderPrimitive.Root>
 ));
 Slider.displayName = SliderPrimitive.Root.displayName;
diff --git a/apps/frontend/src/modules/shared/components/client/Popover.tsx b/apps/frontend/src/modules/shared/components/client/Popover.tsx
index 7f15c4be..82437a7a 100644
--- a/apps/frontend/src/modules/shared/components/client/Popover.tsx
+++ b/apps/frontend/src/modules/shared/components/client/Popover.tsx
@@ -19,7 +19,7 @@ const PopoverContent = React.forwardRef<
       align={align}
       sideOffset={sideOffset}
       className={cn(
-        'z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        'z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-hidden data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
         className,
       )}
       {...props}
diff --git a/apps/frontend/src/modules/shared/components/client/ads/AdSlots.tsx b/apps/frontend/src/modules/shared/components/client/ads/AdSlots.tsx
index c55eee35..d626e2a1 100644
--- a/apps/frontend/src/modules/shared/components/client/ads/AdSlots.tsx
+++ b/apps/frontend/src/modules/shared/components/client/ads/AdSlots.tsx
@@ -14,7 +14,7 @@ const HideAdButton = ({
 }: {
   setIsHidden: (hidden: boolean) => void;
 }) => (
-  <div className='absolute w-0 h-0 top-full right-[0.75rem]'>
+  <div className='absolute w-0 h-0 top-full right-3'>
     <button
       className='h-6 w-3'
       onClick={() => {
@@ -208,7 +208,7 @@ export const InterSectionAdSlot = ({ className }: { className?: string }) => {
       adSlot='4046918224'
       adFormat='auto'
       fullWidthResponsive='true'
-      hiddenClassName='!hidden'
+      hiddenClassName='hidden!'
     />
   );
 };
diff --git a/apps/frontend/src/modules/shared/components/layout/DocumentLayout.tsx b/apps/frontend/src/modules/shared/components/layout/DocumentLayout.tsx
index bee4d004..3be7ce12 100644
--- a/apps/frontend/src/modules/shared/components/layout/DocumentLayout.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/DocumentLayout.tsx
@@ -9,7 +9,7 @@ import { CopyrightFooter } from './CopyrightFooter';
 const DocumentLayout = ({ children }: { children: React.ReactNode }) => {
   return (
     <main className='sm:p-4 flex flex-col items-center justify-between'>
-      <div className='md:px-10 lg:px-20 py-8 mx-auto sm:my-[8rem] max-w-screen-lg sm:rounded-3xl bg-zinc-950/50 backdrop-blur-[10px]'>
+      <div className='md:px-10 lg:px-20 py-8 mx-auto sm:my-32 max-w-(--breakpoint-lg) sm:rounded-3xl bg-zinc-950/50 backdrop-blur-[10px]'>
         <BackButton className='px-8 text-zinc-500 hover:text-zinc-400 text-sm'>
           {'< Back'}
         </BackButton>
diff --git a/apps/frontend/src/modules/shared/components/layout/Footer.tsx b/apps/frontend/src/modules/shared/components/layout/Footer.tsx
index b7bb7eb7..899ae1d7 100644
--- a/apps/frontend/src/modules/shared/components/layout/Footer.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/Footer.tsx
@@ -21,9 +21,9 @@ const FooterIcon = ({ icon, href }: { href: string; icon: IconDefinition }) => (
 export function Footer() {
   return (
     <footer className='flex items-center justify-center w-full h-fit min-h-12 py-4 z-10 border-t border-zinc-700 text-sm text-zinc-400'>
-      <div className='flex-1 flex flex-col sm:flex-row gap-2 justify-around items-center max-w-screen-xl px-6 sm:px-10'>
+      <div className='flex-1 flex flex-col sm:flex-row gap-2 justify-around items-center max-w-(--breakpoint-xl) px-6 sm:px-10'>
         {/* Social links */}
-        <div className='flex-grow flex flex-row gap-2'>
+        <div className='grow flex flex-row gap-2'>
           <FooterIcon icon={faTwitter} href='https://twitter.com/OpenNBS' />
           <FooterIcon icon={faYoutube} href='https://youtube.com/@OpenNBS' />
           <FooterIcon icon={faGithub} href='https://github.com/OpenNBS' />
@@ -39,7 +39,7 @@ export function Footer() {
           />
         </div>
 
-        <div className='flex-shrink'>
+        <div className='shrink'>
           <p>
             © {new Date().getFullYear()}{' '}
             <Link href='https://opennbs.org/' className='hover:underline'>
@@ -48,7 +48,7 @@ export function Footer() {
           </p>
         </div>
 
-        <div className='flex-grow flex justify-end'>
+        <div className='grow flex justify-end'>
           <Link href='/terms' className='hover:underline'>
             Terms
           </Link>
diff --git a/apps/frontend/src/modules/shared/components/layout/Header.tsx b/apps/frontend/src/modules/shared/components/layout/Header.tsx
index 1998f73a..c51710ed 100644
--- a/apps/frontend/src/modules/shared/components/layout/Header.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/Header.tsx
@@ -31,9 +31,9 @@ export async function Header() {
   }
 
   return (
-    <header className='fixed w-[calc(100vw_-_16px)] h-14 flex flex-row justify-center items-center bg-zinc-900 border-b border-zinc-700 py-2 z-10'>
+    <header className='fixed w-[calc(100vw-16px)] h-14 flex flex-row justify-center items-center bg-zinc-900 border-b border-zinc-700 py-2 z-10'>
       {/* Navbar */}
-      <nav className='w-full flex flex-row justify-between items-center gap-8 md:gap-12 max-w-screen-xl px-6 sm:px-10 overflow-x-auto [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden'>
+      <nav className='w-full flex flex-row justify-between items-center gap-8 md:gap-12 max-w-(--breakpoint-xl) px-6 sm:px-10 overflow-x-auto [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden'>
         {/* Icon */}
         <div className='flex-0 flex justify-start lg:justify-center min-w-fit'>
           <Link href='/'>
diff --git a/apps/frontend/src/modules/shared/components/layout/NavbarLayout.tsx b/apps/frontend/src/modules/shared/components/layout/NavbarLayout.tsx
index e9e225f0..b72418f5 100644
--- a/apps/frontend/src/modules/shared/components/layout/NavbarLayout.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/NavbarLayout.tsx
@@ -17,7 +17,7 @@ async function Layout({ children }: TNavbarLayoutProps) {
         {/* Main content */}
         <div className='flex flex-row justify-around w-full pt-24 pb-10'>
           <SideRailAdSlot />
-          <main className='flex-1 w-full max-w-screen-xl px-6 sm:px-10 mb-8'>
+          <main className='flex-1 w-full max-w-(--breakpoint-xl) px-6 sm:px-10 mb-8'>
             {children}
           </main>
           <SideRailAdSlot />
diff --git a/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx b/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx
index 73ebec00..e194d804 100644
--- a/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx
@@ -40,7 +40,7 @@ export function SearchBar() {
         autoCorrect='off'
         autoCapitalize='none'
         spellCheck={false}
-        className='flex-1 px-3 py-2 pr-1 bg-transparent border border-zinc-700 rounded-l-full text-sm text-white placeholder-zinc-500 focus:outline-none focus:border-blue-500'
+        className='flex-1 px-3 py-2 pr-1 bg-transparent border border-zinc-700 rounded-l-full text-sm text-white placeholder-zinc-500 focus:outline-hidden focus:border-blue-500'
       />
       <button
         type='submit'
diff --git a/apps/frontend/src/modules/shared/components/layout/SongThumbnail.tsx b/apps/frontend/src/modules/shared/components/layout/SongThumbnail.tsx
index fea41dfb..fbb116f0 100644
--- a/apps/frontend/src/modules/shared/components/layout/SongThumbnail.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/SongThumbnail.tsx
@@ -29,7 +29,7 @@ const SongThumbnail = ({
     <Image
       unoptimized={isLocalhost} // Disable optimization for localhost to avoid private IP errors
       src={src}
-      className='w-full h-full rounded-lg aspect-[5/3] object-cover'
+      className='w-full h-full rounded-lg aspect-5/3 object-cover'
       width={640}
       height={384}
       alt=''
diff --git a/apps/frontend/src/modules/shared/components/layout/UserMenu.tsx b/apps/frontend/src/modules/shared/components/layout/UserMenu.tsx
index d7adf1fe..3f17ffc3 100644
--- a/apps/frontend/src/modules/shared/components/layout/UserMenu.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/UserMenu.tsx
@@ -124,7 +124,7 @@ export const UserMenu = ({ userData }: { userData: LoggedUserData }) => {
                 className='rounded-full'
               />
             </div>
-            <div className='flex-shrink min-w-0 flex flex-col leading-tight'>
+            <div className='shrink min-w-0 flex flex-col leading-tight'>
               <div className='flex justify-start items-center gap-2'>
                 {!isEditingUsername ? (
                   <>
diff --git a/apps/frontend/src/modules/shared/components/layout/UserMenuLink.tsx b/apps/frontend/src/modules/shared/components/layout/UserMenuLink.tsx
index 4a248ad6..7062cdd1 100644
--- a/apps/frontend/src/modules/shared/components/layout/UserMenuLink.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/UserMenuLink.tsx
@@ -35,7 +35,7 @@ const UserMenuLink = ({
         <div className='h-8 w-8 flex items-center justify-center'>
           <FontAwesomeIcon icon={icon} size='lg' className={textColor} />
         </div>
-        <p className={`flex-grow text-left ${textColor}`}>{label}</p>
+        <p className={`grow text-left ${textColor}`}>{label}</p>
         {external && (
           <div className='h-5 w-5 text-zinc-500 flex items-center'>
             <FontAwesomeIcon
diff --git a/apps/frontend/src/modules/shared/components/layout/popover.tsx b/apps/frontend/src/modules/shared/components/layout/popover.tsx
index 4e334bfd..504b782e 100644
--- a/apps/frontend/src/modules/shared/components/layout/popover.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/popover.tsx
@@ -21,7 +21,7 @@ export const PopoverContent = React.forwardRef<
       align={align}
       sideOffset={sideOffset}
       className={cn(
-        'z-50 w-72 rounded-md p-4 outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        'z-50 w-72 rounded-md p-4 outline-hidden data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
         className,
       )}
       {...props}
diff --git a/apps/frontend/src/modules/shared/components/ui/badge.tsx b/apps/frontend/src/modules/shared/components/ui/badge.tsx
index 82b6841c..3be72376 100644
--- a/apps/frontend/src/modules/shared/components/ui/badge.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/badge.tsx
@@ -4,7 +4,7 @@ import * as React from 'react';
 import { cn } from '@web/lib/utils';
 
 const badgeVariants = cva(
-  'inline-flex items-center rounded-md border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+  'inline-flex items-center rounded-md border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2',
   {
     variants: {
       variant: {
diff --git a/apps/frontend/src/modules/shared/components/ui/command.tsx b/apps/frontend/src/modules/shared/components/ui/command.tsx
index e5743a60..c2a86db6 100644
--- a/apps/frontend/src/modules/shared/components/ui/command.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/command.tsx
@@ -30,7 +30,7 @@ const CommandDialog = ({ children, ...props }: DialogProps) => {
   return (
     <Dialog {...props}>
       <DialogContent className='overflow-hidden p-0'>
-        <Command className='[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5'>
+        <Command className='**:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 **:[[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 **:[[cmdk-input]]:h-12 **:[[cmdk-item]]:px-2 **:[[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5'>
           {children}
         </Command>
       </DialogContent>
@@ -47,7 +47,7 @@ const CommandInput = React.forwardRef<
     <CommandPrimitive.Input
       ref={ref}
       className={cn(
-        'flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
+        'flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-hidden placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
         className,
       )}
       {...props}
@@ -90,7 +90,7 @@ const CommandGroup = React.forwardRef<
   <CommandPrimitive.Group
     ref={ref}
     className={cn(
-      'overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground',
+      'overflow-hidden p-1 text-foreground **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground',
       className,
     )}
     {...props}
@@ -118,7 +118,7 @@ const CommandItem = React.forwardRef<
   <CommandPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex cursor-default gap-2 select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none data-[disabled=true]:pointer-events-none data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      'relative flex cursor-default gap-2 select-none items-center rounded-xs px-2 py-1.5 text-sm outline-hidden data-[disabled=true]:pointer-events-none data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
       className,
     )}
     {...props}
diff --git a/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx b/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx
index 8b900555..76f92f0a 100644
--- a/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx
@@ -33,7 +33,7 @@ const DualRangeSlider = React.forwardRef<
       </SliderPrimitive.Track>
       {initialValue.map((value, index) => (
         <React.Fragment key={index}>
-          <SliderPrimitive.Thumb className='relative block h-4 w-4 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50'>
+          <SliderPrimitive.Thumb className='relative block h-4 w-4 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50'>
             {label && (
               <span
                 className={cn(
diff --git a/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx b/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx
index de5740a2..b37c0745 100644
--- a/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx
@@ -486,7 +486,7 @@ const MultipleSelector = React.forwardRef<
                   <button
                     type='button'
                     className={cn(
-                      'ml-1 rounded-full outline-none ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-2',
+                      'ml-1 rounded-full outline-hidden ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-2',
                       (disabled || option.fixed) && 'hidden',
                     )}
                     onKeyDown={(e) => {
@@ -531,7 +531,7 @@ const MultipleSelector = React.forwardRef<
                   : placeholder
               }
               className={cn(
-                'flex-1 self-baseline bg-transparent outline-none placeholder:text-muted-foreground',
+                'flex-1 self-baseline bg-transparent outline-hidden placeholder:text-muted-foreground',
                 {
                   'w-full': hidePlaceholderWhenSelected,
                   'ml-1': selected.length !== 0,
@@ -571,7 +571,7 @@ const MultipleSelector = React.forwardRef<
         <div className='relative'>
           {open && (
             <CommandList
-              className='absolute top-1 z-10 w-full rounded-md border bg-popover text-popover-foreground shadow-md outline-none animate-in'
+              className='absolute top-1 z-10 w-full rounded-md border bg-popover text-popover-foreground shadow-md outline-hidden animate-in'
               onMouseLeave={() => {
                 setOnScrollbar(false);
               }}
diff --git a/apps/frontend/src/modules/shared/components/ui/select.tsx b/apps/frontend/src/modules/shared/components/ui/select.tsx
index 52f6abef..f54ca1e1 100644
--- a/apps/frontend/src/modules/shared/components/ui/select.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/select.tsx
@@ -19,7 +19,7 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      'flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background data-[placeholder]:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
+      'flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-xs ring-offset-background data-[placeholder]:text-muted-foreground focus:outline-hidden focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
       className,
     )}
     {...props}
@@ -75,7 +75,7 @@ const SelectContent = React.forwardRef<
     <SelectPrimitive.Content
       ref={ref}
       className={cn(
-        'relative z-50 max-h-[--radix-select-content-available-height] min-w-[8rem] overflow-y-auto overflow-x-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-select-content-transform-origin]',
+        'relative z-50 max-h-(--radix-select-content-available-height) min-w-32 overflow-y-auto overflow-x-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-(--radix-select-content-transform-origin)',
         position === 'popper' &&
           'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
         className,
@@ -88,7 +88,7 @@ const SelectContent = React.forwardRef<
         className={cn(
           'p-1',
           position === 'popper' &&
-            'h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]',
+            'h-(--radix-select-trigger-height) w-full min-w-(--radix-select-trigger-width)',
         )}
       >
         {children}
@@ -118,7 +118,7 @@ const SelectItem = React.forwardRef<
   <SelectPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      'relative flex w-full cursor-default select-none items-center rounded-xs py-1.5 pl-2 pr-8 text-sm outline-hidden focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50',
       className,
     )}
     {...props}
diff --git a/apps/frontend/src/modules/shared/components/ui/slider.tsx b/apps/frontend/src/modules/shared/components/ui/slider.tsx
index 48804c64..92807a4b 100644
--- a/apps/frontend/src/modules/shared/components/ui/slider.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/slider.tsx
@@ -20,7 +20,7 @@ const Slider = React.forwardRef<
     <SliderPrimitive.Track className='relative h-1.5 w-full grow overflow-hidden rounded-full bg-zinc-700'>
       <SliderPrimitive.Range className='absolute h-full bg-zinc-500' />
     </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className='block h-4 w-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50' />
+    <SliderPrimitive.Thumb className='block h-4 w-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50' />
   </SliderPrimitive.Root>
 ));
 Slider.displayName = SliderPrimitive.Root.displayName;
diff --git a/apps/frontend/src/modules/song-search/SearchSongPage.tsx b/apps/frontend/src/modules/song-search/SearchSongPage.tsx
index 67919c1a..c9811060 100644
--- a/apps/frontend/src/modules/song-search/SearchSongPage.tsx
+++ b/apps/frontend/src/modules/song-search/SearchSongPage.tsx
@@ -320,7 +320,7 @@ const SearchFilters = ({ filters, onFilterChange }: SearchFiltersProps) => {
             options={Object.entries(UPLOAD_CONSTANTS.categories).map(
               ([key, value]) => ({ value: key, label: value }),
             )}
-            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
+            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-hidden p-2 transition-colors'
           />
         </div>
 
@@ -341,7 +341,7 @@ const SearchFilters = ({ filters, onFilterChange }: SearchFiltersProps) => {
               value: value,
               label: key,
             }))}
-            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
+            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-hidden p-2 transition-colors'
           />
         </div>
 
@@ -362,7 +362,7 @@ const SearchFilters = ({ filters, onFilterChange }: SearchFiltersProps) => {
               value: value,
               label: key,
             }))}
-            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-none p-2 transition-colors'
+            className='block w-full h-fit rounded-lg bg-zinc-900 border-2 border-zinc-600 hover:border-zinc-500 focus:border-blue-500 focus:outline-hidden p-2 transition-colors'
           />
         </div>
       </div>
@@ -562,7 +562,7 @@ export const SearchSongPage = () => {
                   value={sort}
                   onChange={(e) => handleSortChange(e.target.value)}
                   disabled={loading}
-                  className='h-10 w-48 rounded-md bg-zinc-900 border-2 border-zinc-600 hover:enabled:border-zinc-500 disabled:opacity-50 focus:border-blue-500 focus:outline-none px-1.5 text-sm transition-colors'
+                  className='h-10 w-48 rounded-md bg-zinc-900 border-2 border-zinc-600 hover:enabled:border-zinc-500 disabled:opacity-50 focus:border-blue-500 focus:outline-hidden px-1.5 text-sm transition-colors'
                 >
                   <option value={SongSortType.RECENT}>Recent</option>
                   <option value={SongSortType.PLAY_COUNT}>Popular</option>
diff --git a/apps/frontend/src/modules/song-upload/components/client/UploadCompleteModal.tsx b/apps/frontend/src/modules/song-upload/components/client/UploadCompleteModal.tsx
index 66e72bbb..f89f755f 100644
--- a/apps/frontend/src/modules/song-upload/components/client/UploadCompleteModal.tsx
+++ b/apps/frontend/src/modules/song-upload/components/client/UploadCompleteModal.tsx
@@ -64,7 +64,7 @@ export default function UploadCompleteModal({
         <button
           type='button'
           disabled={isCopied}
-          className='rounded-md h-full px-2 w-[4.25rem] text-nowrap bg-zinc-700 text-white enabled:hover:bg-zinc-600 disabled:opacity-50 disabled:cursor-default disabled:text-xs'
+          className='rounded-md h-full px-2 w-17 text-nowrap bg-zinc-700 text-white enabled:hover:bg-zinc-600 disabled:opacity-50 disabled:cursor-default disabled:text-xs'
           onClick={handleCopy()}
         >
           {isCopied ? 'Copied!' : 'Copy'}
diff --git a/apps/frontend/src/modules/song/components/SongDetails.tsx b/apps/frontend/src/modules/song/components/SongDetails.tsx
index 8b46defc..5059f10b 100644
--- a/apps/frontend/src/modules/song/components/SongDetails.tsx
+++ b/apps/frontend/src/modules/song/components/SongDetails.tsx
@@ -22,7 +22,7 @@ const SongDetailsRow = ({ children }: { children: React.ReactNode }) => {
 
 const SongDetailsCell = ({ children }: { children: React.ReactNode }) => {
   return (
-    <td className='first:w-[40%] last:max-w-0 p-2 py-[10px] break-words align-top first:text-zinc-400 first:text-right last:font-bold'>
+    <td className='first:w-[40%] last:max-w-0 p-2 py-[10px] wrap-break-word align-top first:text-zinc-400 first:text-right last:font-bold'>
       {children}
     </td>
   );
diff --git a/apps/frontend/src/modules/song/components/SongPage.tsx b/apps/frontend/src/modules/song/components/SongPage.tsx
index ec4168f7..eca3878c 100644
--- a/apps/frontend/src/modules/song/components/SongPage.tsx
+++ b/apps/frontend/src/modules/song/components/SongPage.tsx
@@ -109,7 +109,7 @@ export async function SongPage({ id }: { id: string }) {
           <div className='flex flex-row flex-wrap justify-start items-center gap-8 w-full'>
             <UploaderBadge user={song.uploader} />
             {/* <FollowButton /> */}
-            <div className='flex-grow'></div>
+            <div className='grow'></div>
             <div className='flex flex-row gap-4 overflow-x-auto'>
               {/* <LikeButton /> */}
               {song.visibility !== 'private' && (
diff --git a/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx b/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx
index b1b75efa..c6533a9b 100644
--- a/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx
+++ b/apps/frontend/src/modules/song/components/client/DownloadSongModal.tsx
@@ -57,7 +57,7 @@ export default function DownloadSongModal({
         <button
           type='button'
           disabled={isCopied}
-          className='rounded-md h-8 px-2 w-[4.25rem] text-nowrap bg-zinc-700 text-white enabled:hover:bg-zinc-600 disabled:opacity-50 disabled:cursor-default disabled:text-xs'
+          className='rounded-md h-8 px-2 w-17 text-nowrap bg-zinc-700 text-white enabled:hover:bg-zinc-600 disabled:opacity-50 disabled:cursor-default disabled:text-xs'
           onClick={handleCopy()}
         >
           {isCopied ? 'Copied!' : 'Copy'}
diff --git a/apps/frontend/src/modules/song/components/client/FileDisplay.tsx b/apps/frontend/src/modules/song/components/client/FileDisplay.tsx
index dc716444..908bd25a 100644
--- a/apps/frontend/src/modules/song/components/client/FileDisplay.tsx
+++ b/apps/frontend/src/modules/song/components/client/FileDisplay.tsx
@@ -22,9 +22,9 @@ export const FileDisplay = ({
       className,
     )}
   >
-    <div className='flex-shrink min-w-0 max-w-96 flex flex-row gap-2 items-center'>
+    <div className='shrink min-w-0 max-w-96 flex flex-row gap-2 items-center'>
       <FontAwesomeIcon icon={faFile} size='lg' />
-      <p className='text-md flex-shrink min-w-0 text-wrap line-clamp-2 leading-tight'>
+      <p className='text-md shrink min-w-0 text-wrap line-clamp-2 leading-tight'>
         {fileName}
       </p>
     </div>
diff --git a/apps/frontend/src/modules/song/components/client/InstrumentPicker.tsx b/apps/frontend/src/modules/song/components/client/InstrumentPicker.tsx
index 863b4fe8..d22e1e9f 100644
--- a/apps/frontend/src/modules/song/components/client/InstrumentPicker.tsx
+++ b/apps/frontend/src/modules/song/components/client/InstrumentPicker.tsx
@@ -105,7 +105,7 @@ const InstrumentTable = ({ type }: { type: 'upload' | 'edit' }) => {
   return (
     <div className='flex flex-col w-full'>
       {/* Header */}
-      <div className='flex-shrink grid grid-cols-8'>
+      <div className='shrink grid grid-cols-8'>
         <InstrumentTableHeader className='text-right'>#</InstrumentTableHeader>
         <InstrumentTableHeader className='col-span-3'>
           Instrument
@@ -119,7 +119,7 @@ const InstrumentTable = ({ type }: { type: 'upload' | 'edit' }) => {
       </div>
 
       {/* Instruments */}
-      <div className='overflow-y-scroll max-h-72 flex flex-col mr-[-1rem]'>
+      <div className='overflow-y-scroll max-h-72 flex flex-col -mr-4'>
         {song?.instruments.map((instrument, i) => (
           <InstrumentTableRow
             key={i}
diff --git a/apps/frontend/src/modules/song/components/client/ShareModal.tsx b/apps/frontend/src/modules/song/components/client/ShareModal.tsx
index 057d80de..664be7cd 100644
--- a/apps/frontend/src/modules/song/components/client/ShareModal.tsx
+++ b/apps/frontend/src/modules/song/components/client/ShareModal.tsx
@@ -55,7 +55,7 @@ export default function ShareModal({
         <button
           type='button'
           disabled={isCopied}
-          className='rounded-md h-full px-2 w-[4.25rem] text-nowrap bg-zinc-700 text-white enabled:hover:bg-zinc-600 disabled:opacity-50 disabled:cursor-default disabled:text-xs'
+          className='rounded-md h-full px-2 w-17 text-nowrap bg-zinc-700 text-white enabled:hover:bg-zinc-600 disabled:opacity-50 disabled:cursor-default disabled:text-xs'
           onClick={handleCopy()}
         >
           {isCopied ? 'Copied!' : 'Copy'}
diff --git a/apps/frontend/src/modules/song/components/client/SongCanvas.tsx b/apps/frontend/src/modules/song/components/client/SongCanvas.tsx
index 07e34e6d..cac049d6 100644
--- a/apps/frontend/src/modules/song/components/client/SongCanvas.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongCanvas.tsx
@@ -121,7 +121,7 @@ export const SongCanvas = ({ song }: { song: SongViewDtoType }) => {
     <div
       ref={canvasContainerRef}
       id='song-renderer-container'
-      className='bg-zinc-800 aspect-[5/3] rounded-xl'
+      className='bg-zinc-800 aspect-5/3 rounded-xl'
     >
       <canvas
         id='song-renderer'
diff --git a/apps/frontend/src/modules/song/components/client/SongSelector.tsx b/apps/frontend/src/modules/song/components/client/SongSelector.tsx
index f8f23af5..20b5d946 100644
--- a/apps/frontend/src/modules/song/components/client/SongSelector.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongSelector.tsx
@@ -55,12 +55,12 @@ export const SongSelector = () => {
           icon={faFile}
           className={`${
             isDragActive ? 'text-blue-400 scale-105' : 'text-zinc-600'
-          } transition-all duration-250 ease-in-out !h-20 text-7xl`}
+          } transition-all duration-250 ease-in-out h-20! text-7xl`}
         />
 
         <FontAwesomeIcon
           icon={faMusic}
-          className={`absolute translate-y-9 !h-8 !w-8 text-zinc-900 ${
+          className={`absolute translate-y-9 h-8! w-8! text-zinc-900 ${
             isDragActive ? 'scale-105' : ''
           } transition-all duration-250 ease-in-out`}
         />
diff --git a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
index 40acb09b..25efc660 100644
--- a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
@@ -127,7 +127,7 @@ const ColorButton: React.FC<ColorButtonProps> = ({
         type='button'
         className={cn(
           'w-6 h-6 rounded-full flex-none border-2 border-zinc-200/30 disabled:opacity-30',
-          active && 'outline outline-2 outline-zinc-200',
+          active && 'outline-2 outline-zinc-200',
         )}
         style={{ backgroundColor: color }}
         disabled={disabled}
diff --git a/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx b/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
index 6cd0da89..c7d77afa 100644
--- a/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
+++ b/apps/frontend/src/modules/song/components/client/ThumbnailRenderer.tsx
@@ -82,10 +82,7 @@ export const ThumbnailRendererCanvas = ({
 
   return (
     <div className='relative w-full'>
-      <canvas
-        ref={canvasRef}
-        className='w-full h-full aspect-[5/3] rounded-lg'
-      />
+      <canvas ref={canvasRef} className='w-full h-full aspect-5/3 rounded-lg' />
       {loading && (
         <div className='absolute top-0 flex items-center justify-center bg-black w-full h-full rounded-lg opacity-80'>
           Loading...

From 29bfcf7e72ce2f48360f7292003c64217c6e3c15 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 16 Jan 2026 17:00:57 -0300
Subject: [PATCH 075/111] fix: prevent FontAwesome from injecting CSS after
 load

Fixes icons being huge during page load.
---
 apps/frontend/src/app/layout.tsx | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/apps/frontend/src/app/layout.tsx b/apps/frontend/src/app/layout.tsx
index 95c5f561..526f2497 100644
--- a/apps/frontend/src/app/layout.tsx
+++ b/apps/frontend/src/app/layout.tsx
@@ -1,3 +1,4 @@
+import { config } from '@fortawesome/fontawesome-svg-core';
 import { GoogleAnalytics } from '@next/third-parties/google';
 import type { Metadata } from 'next';
 import { Lato } from 'next/font/google';
@@ -14,6 +15,13 @@ import DetectAdBlock from '../modules/shared/components/client/ads/DetectAdBlock
 import GoogleAdSense from '../modules/shared/components/GoogleAdSense';
 import { TooltipProvider } from '../modules/shared/components/tooltip';
 
+// Pre-import FontAwesome CSS to avoid FOUC
+// See: https://fontawesome.com/docs/web/use-with/react/use-with#nextjs
+import '@fortawesome/fontawesome-svg-core/styles.css';
+
+// Prevent FontAwesome from injecting CSS after initial render
+config.autoAddCss = false;
+
 const lato = Lato({
   subsets: ['latin'],
   weight: ['100', '300', '400', '700', '900'],

From 7a575481ba97ef27c9f58be1061546db978a8909 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Fri, 16 Jan 2026 17:08:26 -0300
Subject: [PATCH 076/111] fix: apply Lato font to theme via CSS variable

---
 apps/frontend/src/app/globals.css | 6 ++++++
 apps/frontend/src/app/layout.tsx  | 1 +
 2 files changed, 7 insertions(+)

diff --git a/apps/frontend/src/app/globals.css b/apps/frontend/src/app/globals.css
index b5e385a9..aa407bf3 100644
--- a/apps/frontend/src/app/globals.css
+++ b/apps/frontend/src/app/globals.css
@@ -4,6 +4,12 @@
 /*---break---*/
 @custom-variant dark (&:is(.dark *));
 
+@layer theme {
+  :root {
+    --font-sans: var(--font-lato);
+  }
+}
+
 /************** Scrollbar **************/
 
 html {
diff --git a/apps/frontend/src/app/layout.tsx b/apps/frontend/src/app/layout.tsx
index 526f2497..749a9d75 100644
--- a/apps/frontend/src/app/layout.tsx
+++ b/apps/frontend/src/app/layout.tsx
@@ -25,6 +25,7 @@ config.autoAddCss = false;
 const lato = Lato({
   subsets: ['latin'],
   weight: ['100', '300', '400', '700', '900'],
+  variable: '--font-lato',
 });
 
 export const metadata: Metadata = {

From b521ae62caa6069fe8676e3331396b2273ede2bd Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:06:07 -0300
Subject: [PATCH 077/111] fix: make buttons use pointer cursor

Tailwind CSS v4 removed that as the default.
---
 apps/frontend/src/app/globals.css | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/apps/frontend/src/app/globals.css b/apps/frontend/src/app/globals.css
index aa407bf3..609cc830 100644
--- a/apps/frontend/src/app/globals.css
+++ b/apps/frontend/src/app/globals.css
@@ -1,7 +1,7 @@
 @import 'tailwindcss';
-/*---break---*/
+
 @plugin "tailwindcss-animate";
-/*---break---*/
+
 @custom-variant dark (&:is(.dark *));
 
 @layer theme {
@@ -308,3 +308,12 @@ ins.adsbygoogle[data-ad-status='unfilled'] {
   }
 }
 */
+
+/* Make buttons use pointer cursor */
+/* See: https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor */
+@layer base {
+  button:not(:disabled),
+  [role='button']:not(:disabled) {
+    cursor: pointer;
+  }
+}

From 98fa6ac2732f862fdf998da08f7c008e4467a07b Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:07:41 -0300
Subject: [PATCH 078/111] chore: delete tailwind.config.js

No longer used in v4, replaced in favor of CSS-first configuration. See:
https://tailwindcss.com/blog/tailwindcss-v4#css-first-configuration
---
 apps/frontend/tailwind.config.js | 12 ------------
 1 file changed, 12 deletions(-)
 delete mode 100644 apps/frontend/tailwind.config.js

diff --git a/apps/frontend/tailwind.config.js b/apps/frontend/tailwind.config.js
deleted file mode 100644
index 1094916c..00000000
--- a/apps/frontend/tailwind.config.js
+++ /dev/null
@@ -1,12 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: ['./src/**/*.{ts,tsx}'],
-  theme: {
-    extend: {
-      transitionTimingFunction: {
-        'out-back': 'cubic-bezier(0.34, 1.56, 0.51, 1.2)',
-      },
-    },
-  },
-  plugins: [require('@shrutibalasa/tailwind-grid-auto-fit')],
-};

From a8e11d9f8d1c8509fb5e0ddf82c6eafcf8a3cda4 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:18:38 -0300
Subject: [PATCH 079/111] chore: remove `autoprefixer` from PostCSS config

no longer needed with v4's parser:
https://tailwindcss.com/docs/installation/framework-guides/nextjs
---
 apps/frontend/postcss.config.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/apps/frontend/postcss.config.js b/apps/frontend/postcss.config.js
index b4bee663..e5640725 100644
--- a/apps/frontend/postcss.config.js
+++ b/apps/frontend/postcss.config.js
@@ -1,6 +1,5 @@
 module.exports = {
   plugins: {
     '@tailwindcss/postcss': {},
-    autoprefixer: {},
   },
 };

From f19d1f9e2654c8035770894c78d39ec9ef6fc0b5 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:19:27 -0300
Subject: [PATCH 080/111] chore: change `postcss.config.js` extension to `.mjs`

---
 apps/frontend/{postcss.config.js => postcss.config.mjs} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename apps/frontend/{postcss.config.js => postcss.config.mjs} (100%)

diff --git a/apps/frontend/postcss.config.js b/apps/frontend/postcss.config.mjs
similarity index 100%
rename from apps/frontend/postcss.config.js
rename to apps/frontend/postcss.config.mjs

From 9e93de844bb802ab14bad7d03f25d9d34a951b00 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:20:48 -0300
Subject: [PATCH 081/111] refactor: use modern export syntax in PostCSS config

---
 apps/frontend/postcss.config.mjs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/apps/frontend/postcss.config.mjs b/apps/frontend/postcss.config.mjs
index e5640725..297374d8 100644
--- a/apps/frontend/postcss.config.mjs
+++ b/apps/frontend/postcss.config.mjs
@@ -1,5 +1,7 @@
-module.exports = {
+const config = {
   plugins: {
     '@tailwindcss/postcss': {},
   },
 };
+
+export default config;

From da7f5f6c772720f77429de5bc9fb97e4b51b93f5 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:21:40 -0300
Subject: [PATCH 082/111] chore: remove `@shrutibalasa/tailwind-grid-auto-fit`
 dependency

---
 apps/frontend/package.json | 1 -
 bun.lock                   | 4 ----
 2 files changed, 5 deletions(-)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index 2af666cd..2b406af5 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -67,7 +67,6 @@
     "zustand": "^5.0.9"
   },
   "devDependencies": {
-    "@shrutibalasa/tailwind-grid-auto-fit": "^1.1.0",
     "@tailwindcss/postcss": "^4.1.18",
     "@types/mdx": "^2.0.13",
     "@types/react-modal": "^3.16.3",
diff --git a/bun.lock b/bun.lock
index 327d539b..20afc225 100644
--- a/bun.lock
+++ b/bun.lock
@@ -7,7 +7,6 @@
       "dependencies": {
         "@nbw/sounds": "workspace:*",
         "@types/jest": "^30.0.0",
-        "tailwindcss": "^4.1.18",
       },
       "devDependencies": {
         "@eslint/js": "^9.36.0",
@@ -166,7 +165,6 @@
         "zustand": "^5.0.9",
       },
       "devDependencies": {
-        "@shrutibalasa/tailwind-grid-auto-fit": "^1.1.0",
         "@tailwindcss/postcss": "^4.1.18",
         "@types/mdx": "^2.0.13",
         "@types/react-modal": "^3.16.3",
@@ -845,8 +843,6 @@
 
     "@selderee/plugin-htmlparser2": ["@selderee/plugin-htmlparser2@0.11.0", "", { "dependencies": { "domhandler": "^5.0.3", "selderee": "^0.11.0" } }, "sha512-P33hHGdldxGabLFjPPpaTxVolMrzrcegejx+0GxjrIb9Zv48D8yAIA/QTDR2dFl7Uz7urX8aX6+5bCZslr+gWQ=="],
 
-    "@shrutibalasa/tailwind-grid-auto-fit": ["@shrutibalasa/tailwind-grid-auto-fit@1.1.0", "", {}, "sha512-sh/Vmdz/xTVziUF9ZYDb5YpECApdK85KXSRIJY58GzmdUuum5QBE3jqDeNMjICEVaVOSrOnp+gqUWx8A9dmZjA=="],
-
     "@sinclair/typebox": ["@sinclair/typebox@0.34.41", "", {}, "sha512-6gS8pZzSXdyRHTIqoqSVknxolr1kzfy4/CeDnrzsVz8TTIWUbOBr6gnzOmTYJ3eXQNh4IYHIGi5aIL7sOZ2G/g=="],
 
     "@sinonjs/commons": ["@sinonjs/commons@3.0.1", "", { "dependencies": { "type-detect": "4.0.8" } }, "sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ=="],

From d2e349fd14844f8ab0e7592a4ea2e42c14b96ec2 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:26:32 -0300
Subject: [PATCH 083/111] fix: change font definition from `@layer theme` to
 `@theme` directive

This is the Tailwind v4 CSS-first way to define design tokens. Tailwind uses these values to set `--font-sans` at `:root`.
---
 apps/frontend/src/app/globals.css | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/apps/frontend/src/app/globals.css b/apps/frontend/src/app/globals.css
index 609cc830..ab693295 100644
--- a/apps/frontend/src/app/globals.css
+++ b/apps/frontend/src/app/globals.css
@@ -4,10 +4,8 @@
 
 @custom-variant dark (&:is(.dark *));
 
-@layer theme {
-  :root {
-    --font-sans: var(--font-lato);
-  }
+@theme {
+  --font-sans: var(--font-lato);
 }
 
 /************** Scrollbar **************/

From 5dbf95efda1bdc08417b48d6ac48fb5930f99297 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:27:59 -0300
Subject: [PATCH 084/111] fix: re-add `ease-out-back` CSS transition defition

---
 apps/frontend/src/app/globals.css | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/frontend/src/app/globals.css b/apps/frontend/src/app/globals.css
index ab693295..31e01209 100644
--- a/apps/frontend/src/app/globals.css
+++ b/apps/frontend/src/app/globals.css
@@ -6,6 +6,7 @@
 
 @theme {
   --font-sans: var(--font-lato);
+  --ease-out-back: cubic-bezier(0.34, 1.56, 0.51, 1.2);
 }
 
 /************** Scrollbar **************/

From 5e47d3dad7dd5775e695a27a2275d2489c5de248 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:28:40 -0300
Subject: [PATCH 085/111] fix: change icon set from `lucide` to `fontawesome`
 in @shadcn/ui config

---
 apps/frontend/components.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/components.json b/apps/frontend/components.json
index d09c9490..b9835b61 100644
--- a/apps/frontend/components.json
+++ b/apps/frontend/components.json
@@ -12,7 +12,7 @@
     "rsc": true,
     "tsx": true
   },
-  "iconLibrary": "lucide",
+  "iconLibrary": "fontawesome",
   "aliases": {
     "components": "@web/modules/shared/components",
     "utils": "@web/lib/utils",

From c9c690c53a30891493577d509802bc1f026536bb Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:37:05 -0300
Subject: [PATCH 086/111] fix: re-add grid auto-fit utility classes

Replaces `tailwindcss-grid-auto-fit` plugin with inline utility definitions.
---
 apps/frontend/src/app/globals.css | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/apps/frontend/src/app/globals.css b/apps/frontend/src/app/globals.css
index 31e01209..b4a005fa 100644
--- a/apps/frontend/src/app/globals.css
+++ b/apps/frontend/src/app/globals.css
@@ -9,6 +9,32 @@
   --ease-out-back: cubic-bezier(0.34, 1.56, 0.51, 1.2);
 }
 
+/************** Grid utilities **************/
+
+@utility grid-auto-fit {
+  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+}
+
+@utility grid-auto-fit-xs {
+  grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+}
+
+@utility grid-auto-fit-sm {
+  grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr));
+}
+
+@utility grid-auto-fit-md {
+  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+}
+
+@utility grid-auto-fit-lg {
+  grid-template-columns: repeat(auto-fit, minmax(18rem, 1fr));
+}
+
+@utility grid-auto-fit-xl {
+  grid-template-columns: repeat(auto-fit, minmax(20rem, 1fr));
+}
+
 /************** Scrollbar **************/
 
 html {

From ea0cb6bab2b8212424b5aae6e831976ba3aa74e0 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 19 Jan 2026 13:39:58 -0300
Subject: [PATCH 087/111] fix: mismatched icon size on social login provider
 icons

---
 apps/frontend/src/modules/auth/components/loginPage.tsx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/frontend/src/modules/auth/components/loginPage.tsx b/apps/frontend/src/modules/auth/components/loginPage.tsx
index ab799c13..75a1f05e 100644
--- a/apps/frontend/src/modules/auth/components/loginPage.tsx
+++ b/apps/frontend/src/modules/auth/components/loginPage.tsx
@@ -87,6 +87,7 @@ export const LoginPage = () => {
               <FontAwesomeIcon
                 icon={faGoogle}
                 className='align-middle mr-2 h-5'
+                size='lg'
               />
               <span className='flex-1 text-nowrap'>Log in with Google</span>
             </Link>
@@ -99,6 +100,7 @@ export const LoginPage = () => {
               <FontAwesomeIcon
                 icon={faGithub}
                 className='align-middle mr-2 h-5'
+                size='lg'
               />
               <span className='flex-1'>Log in with GitHub</span>
             </Link>
@@ -111,6 +113,7 @@ export const LoginPage = () => {
               <FontAwesomeIcon
                 icon={faDiscord}
                 className='align-middle mr-2 h-5'
+                size='lg'
               />
               <span className='flex-1 text-nowrap'>Log in with Discord</span>
             </Link>

From 3004290dfee51c58567002107aae7820f5613ca4 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 21 Jan 2026 22:54:35 -0300
Subject: [PATCH 088/111] chore: enable suggestions inside strings on VS Code
 settings

As recommended by the Tailwind CSS Intellisense extension:
https://github.com/tailwindlabs/tailwindcss-intellisense#editorquicksuggestions
---
 .vscode/settings.json | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 76a9c3a4..60902421 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -13,6 +13,11 @@
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "always"
   },
+  // Enable suggestions inside strings for Tailwind CSS class names
+  // https://github.com/tailwindlabs/tailwindcss-intellisense#editorquicksuggestions
+  "editor.quickSuggestions": {
+    "strings": "on"
+  },
   "files.associations": {
     ".css": "tailwindcss",
     "*.scss": "tailwindcss"

From 0bbc25915386afd88034954583bb4b177cb053cb Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 21 Jan 2026 22:55:37 -0300
Subject: [PATCH 089/111] chore: add `globals.css` as config file for Tailwind
 CSS extension

See: https://stackoverflow.com/a/79433860/9045426
---
 .vscode/settings.json | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 60902421..5e67e7c6 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -18,6 +18,9 @@
   "editor.quickSuggestions": {
     "strings": "on"
   },
+  "tailwindCSS.experimental.configFile": {
+    "apps/frontend/src/app/globals.css": "apps/frontend/src/**"
+  },
   "files.associations": {
     ".css": "tailwindcss",
     "*.scss": "tailwindcss"

From bff61378c0eecfd3584b7b23df6682a9748a71a3 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 21 Jan 2026 22:57:04 -0300
Subject: [PATCH 090/111] chore: enable Tailwind CSS Intellisense inside
 utility functions

---
 .vscode/settings.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 5e67e7c6..d90d6c9c 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -21,6 +21,7 @@
   "tailwindCSS.experimental.configFile": {
     "apps/frontend/src/app/globals.css": "apps/frontend/src/**"
   },
+  "tailwindCSS.classFunctions": ["tw", "clsx", "cn"],
   "files.associations": {
     ".css": "tailwindcss",
     "*.scss": "tailwindcss"

From 6a53b7d1e395bc2d140df971a3fad7250d46f450 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Wed, 21 Jan 2026 23:32:07 -0300
Subject: [PATCH 091/111] fix: add Lato font variable to root html element

---
 apps/frontend/src/app/layout.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/app/layout.tsx b/apps/frontend/src/app/layout.tsx
index 749a9d75..9e25cfbf 100644
--- a/apps/frontend/src/app/layout.tsx
+++ b/apps/frontend/src/app/layout.tsx
@@ -59,7 +59,7 @@ export default function RootLayout({
 }) {
   return (
     <ReCaptchaProvider useEnterprise>
-      <html lang='en'>
+      <html lang='en' className={lato.variable}>
         <head>
           <GoogleAdSense pId={process.env.NEXT_PUBLIC_ADSENSE_CLIENT} />
           {/* https://nextjs.org/docs/app/building-your-application/optimizing/metadata#json-ld */}

From 1e544640c449042f68a16466cbf678b9de57bc3d Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 22 Jan 2026 02:12:40 -0300
Subject: [PATCH 092/111] fix: revert to old slider component in thumbnail
 editor

The new components from @shadcn/ui, loaded at the `src/modules/shared/components/ui` aren't up to standard yet:

- They're using a different color syntax (variations such as `primary`, `secondary`, `destructive` as opposed to directly color references), which we need to properly implement support for before migrating components to it.
- They're using the Lucide icon pack instead of FontAwesome, which we use throughout the project.

As such, this commit reverts the reference change from the new element to the old one, co-lated with the other form elements in `shared/components/client/FormElements`. A future refactoring will reoganize the frontend's path structure and also implement theme variations properly.
---
 .../src/modules/song/components/client/SongThumbnailInput.tsx   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
index 25efc660..868b7b03 100644
--- a/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
+++ b/apps/frontend/src/modules/song/components/client/SongThumbnailInput.tsx
@@ -3,12 +3,12 @@ import { UseFormReturn } from 'react-hook-form';
 
 import { BG_COLORS, THUMBNAIL_CONSTANTS } from '@nbw/config';
 import { cn } from '@web/lib/utils';
+import { Slider } from '@web/modules/shared/components/client/FormElements';
 import {
   Tooltip,
   TooltipContent,
   TooltipTrigger,
 } from '@web/modules/shared/components/tooltip';
-import { Slider } from '@web/modules/shared/components/ui/slider';
 
 import { useSongProvider } from './context/Song.context';
 import { EditSongFormInput, UploadSongFormInput } from './SongForm.zod';

From 673ac51b67ad1f33409393c26266438328cdf474 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Thu, 22 Jan 2026 02:25:59 -0300
Subject: [PATCH 093/111] fix: adjust custom slider element appearance

- Adds `hover` and `active` state changes
- Sets color, thickness, and focus based onsurrounding style
- Fixes broken
---
 apps/frontend/src/modules/shared/components/ui/slider.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/frontend/src/modules/shared/components/ui/slider.tsx b/apps/frontend/src/modules/shared/components/ui/slider.tsx
index 92807a4b..fd178577 100644
--- a/apps/frontend/src/modules/shared/components/ui/slider.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/slider.tsx
@@ -12,15 +12,15 @@ const Slider = React.forwardRef<
   <SliderPrimitive.Root
     ref={ref}
     className={cn(
-      'relative flex w-full touch-none select-none items-center',
+      'group relative flex w-full touch-none select-none items-center transition-colors',
       className,
     )}
     {...props}
   >
-    <SliderPrimitive.Track className='relative h-1.5 w-full grow overflow-hidden rounded-full bg-zinc-700'>
-      <SliderPrimitive.Range className='absolute h-full bg-zinc-500' />
+    <SliderPrimitive.Track className='relative h-2 w-full grow overflow-hidden rounded-full bg-zinc-600'>
+      <SliderPrimitive.Range className='absolute h-full bg-blue-500 group-hover:bg-blue-600 group-active:bg-blue-400' />
     </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className='block h-4 w-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50' />
+    <SliderPrimitive.Thumb className='block h-4 w-4 rounded-full bg-blue-500 group-hover:bg-blue-600 group-active:bg-blue-400 shadow focus-visible:outline-hidden focus-visible:ring-1 disabled:pointer-events-none disabled:opacity-50' />
   </SliderPrimitive.Root>
 ));
 Slider.displayName = SliderPrimitive.Root.displayName;

From 29a343cbc1409a18ca6360d95c85f5aa06914878 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 20:37:24 -0300
Subject: [PATCH 094/111] fix: adjust form elements' slider appearance

That is the one we're using on the song edit form - not the one in `ui/`. This will be reviewed later.
---
 .../shared/components/client/FormElements.tsx      | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/apps/frontend/src/modules/shared/components/client/FormElements.tsx b/apps/frontend/src/modules/shared/components/client/FormElements.tsx
index fc7f7baf..0e81c5b1 100644
--- a/apps/frontend/src/modules/shared/components/client/FormElements.tsx
+++ b/apps/frontend/src/modules/shared/components/client/FormElements.tsx
@@ -1,7 +1,7 @@
 import { faQuestionCircle } from '@fortawesome/free-solid-svg-icons';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import * as SliderPrimitive from '@radix-ui/react-slider';
-import { ComponentPropsWithoutRef, ElementRef, forwardRef } from 'react';
+import { forwardRef } from 'react';
 import Skeleton from 'react-loading-skeleton';
 import Markdown from 'react-markdown';
 
@@ -231,21 +231,21 @@ export const Option = forwardRef<
 Option.displayName = 'Option';
 
 export const Slider = forwardRef<
-  ElementRef<typeof SliderPrimitive.Root>,
-  ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
+  React.ElementRef<typeof SliderPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
 >(({ className, ...props }, ref) => (
   <SliderPrimitive.Root
     ref={ref}
     className={cn(
-      'relative flex w-full touch-none select-none items-center',
+      'group relative flex w-full touch-none select-none items-center transition-colors',
       className,
     )}
     {...props}
   >
-    <SliderPrimitive.Track className='relative h-2 w-full grow overflow-hidden rounded-full bg-secondary'>
-      <SliderPrimitive.Range className='absolute h-full bg-primary' />
+    <SliderPrimitive.Track className='relative h-2 w-full grow overflow-hidden rounded-full bg-zinc-600'>
+      <SliderPrimitive.Range className='absolute h-full bg-blue-500 group-hover:bg-blue-600 group-active:bg-blue-400' />
     </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className='block h-5 w-5 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50' />
+    <SliderPrimitive.Thumb className='block h-4 w-4 rounded-full bg-blue-500 group-hover:bg-blue-600 group-active:bg-blue-400 shadow focus-visible:outline-hidden focus-visible:ring-1 disabled:pointer-events-none disabled:opacity-50' />
   </SliderPrimitive.Root>
 ));
 Slider.displayName = SliderPrimitive.Root.displayName;

From afbaa7972085e64ae2a8798ee68dc55490ec288e Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 20:40:15 -0300
Subject: [PATCH 095/111] refactor: replace unused `size` param in
 `SongCardGroup` with auto-fit

Commit 0de0449433615d31017d20f4066a3eeba279eae5 made this change as a workaround for the `grid-auto-fit-<size>` utilities having broken. They have been re-introduced in c9c690c53a30891493577d509802bc1f026536bb, so this change can be reverted as it simplifies the component; besides, the `size` parameter wasn't used anywhere in the codebase.
---
 .../browse/components/SongCardGroup.tsx       | 23 ++-----------------
 1 file changed, 2 insertions(+), 21 deletions(-)

diff --git a/apps/frontend/src/modules/browse/components/SongCardGroup.tsx b/apps/frontend/src/modules/browse/components/SongCardGroup.tsx
index c247d636..1d62d49e 100644
--- a/apps/frontend/src/modules/browse/components/SongCardGroup.tsx
+++ b/apps/frontend/src/modules/browse/components/SongCardGroup.tsx
@@ -1,25 +1,6 @@
-const SongCardGroup = ({
-  children,
-  size = 'md',
-}: {
-  children: React.ReactNode;
-  size?: 'sm' | 'md' | 'lg' | 'xl';
-}) => {
-  // Define min column widths for each size
-  const minWidths = {
-    sm: '200px',
-    md: '280px',
-    lg: '320px',
-    xl: '400px',
-  };
-
+const SongCardGroup = ({ children }: { children: React.ReactNode }) => {
   return (
-    <div
-      className='grid w-full items-center gap-4'
-      style={{
-        gridTemplateColumns: `repeat(auto-fit, minmax(${minWidths[size]}, 1fr))`,
-      }}
-    >
+    <div className='grid grid-auto-fit-md w-full items-center gap-4'>
       {children}
     </div>
   );

From a3308b3abd1754ed07e5724dd2db48d7a6099d93 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 20:50:28 -0300
Subject: [PATCH 096/111] chore: add TODOs related to component standardization

---
 apps/frontend/src/modules/shared/components/ui/badge.tsx       | 3 +++
 apps/frontend/src/modules/shared/components/ui/command.tsx     | 2 ++
 apps/frontend/src/modules/shared/components/ui/dialog.tsx      | 2 ++
 .../src/modules/shared/components/ui/dualRangeSlider.tsx       | 3 +++
 .../src/modules/shared/components/ui/multipleSelectorProps.tsx | 2 ++
 apps/frontend/src/modules/shared/components/ui/select.tsx      | 2 ++
 6 files changed, 14 insertions(+)

diff --git a/apps/frontend/src/modules/shared/components/ui/badge.tsx b/apps/frontend/src/modules/shared/components/ui/badge.tsx
index 3be72376..9d7d46f4 100644
--- a/apps/frontend/src/modules/shared/components/ui/badge.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/badge.tsx
@@ -1,3 +1,6 @@
+// TODO: this component uses bg-primary etc. instead of bg-blue-500 as the rest of the project.
+// We must either standardize the color scheme (preferably) or make this component use the same color scheme.
+
 import { cva, type VariantProps } from 'class-variance-authority';
 import * as React from 'react';
 
diff --git a/apps/frontend/src/modules/shared/components/ui/command.tsx b/apps/frontend/src/modules/shared/components/ui/command.tsx
index c2a86db6..f2026a0c 100644
--- a/apps/frontend/src/modules/shared/components/ui/command.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/command.tsx
@@ -1,3 +1,5 @@
+// TODO: use FontAwesome icons instead of lucide-react
+
 'use client';
 
 import { type DialogProps } from '@radix-ui/react-dialog';
diff --git a/apps/frontend/src/modules/shared/components/ui/dialog.tsx b/apps/frontend/src/modules/shared/components/ui/dialog.tsx
index 5ec5215a..44f6dbf0 100644
--- a/apps/frontend/src/modules/shared/components/ui/dialog.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/dialog.tsx
@@ -1,3 +1,5 @@
+// TODO: use FontAwesome icons instead of lucide-react
+
 'use client';
 
 import * as DialogPrimitive from '@radix-ui/react-dialog';
diff --git a/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx b/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx
index 76f92f0a..a5bfd164 100644
--- a/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/dualRangeSlider.tsx
@@ -1,3 +1,6 @@
+// TODO: this component uses bg-primary etc. instead of bg-blue-500 as the rest of the project.
+// We must either standardize the color scheme (preferably) or make this component use the same color scheme.
+
 'use client';
 
 import * as SliderPrimitive from '@radix-ui/react-slider';
diff --git a/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx b/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx
index b37c0745..919d1881 100644
--- a/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/multipleSelectorProps.tsx
@@ -1,3 +1,5 @@
+// TODO: use FontAwesome icons instead of lucide-react
+
 'use client';
 
 import { Command as CommandPrimitive, useCommandState } from 'cmdk';
diff --git a/apps/frontend/src/modules/shared/components/ui/select.tsx b/apps/frontend/src/modules/shared/components/ui/select.tsx
index f54ca1e1..b7678c53 100644
--- a/apps/frontend/src/modules/shared/components/ui/select.tsx
+++ b/apps/frontend/src/modules/shared/components/ui/select.tsx
@@ -1,3 +1,5 @@
+// TODO: use FontAwesome icons instead of lucide-react
+
 'use client';
 
 import * as SelectPrimitive from '@radix-ui/react-select';

From 730041f8825e3792645cdc52e7011fbfcd1aee8e Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 21:35:45 -0300
Subject: [PATCH 097/111] fix: simplify form label's font size definition

Added as a test to fix the label font looking slightly stretched vertically in comparison to the current production version. This change did not manage to fix the issue, but ended up making it in with the batch of changes in 9d3b8919813f868b2caa8de5c8d09a88fffd6d70.
---
 .../src/modules/shared/components/client/FormElements.tsx       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/shared/components/client/FormElements.tsx b/apps/frontend/src/modules/shared/components/client/FormElements.tsx
index 0e81c5b1..e96218ef 100644
--- a/apps/frontend/src/modules/shared/components/client/FormElements.tsx
+++ b/apps/frontend/src/modules/shared/components/client/FormElements.tsx
@@ -20,7 +20,7 @@ export const Label = forwardRef<
   const { id, label } = props;
 
   return (
-    <label htmlFor={id} ref={ref} className='text-zinc-300 text-[14px]'>
+    <label htmlFor={id} ref={ref} className='text-zinc-300 text-sm'>
       {label}
     </label>
   );

From 83b6438db8706a8b64719bcb6fdd2a0633504d4c Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 22:04:38 -0300
Subject: [PATCH 098/111] chore: add `remove-markdown` to frontend dependencies

---
 apps/frontend/package.json | 1 +
 bun.lock                   | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/apps/frontend/package.json b/apps/frontend/package.json
index 2b406af5..f1e4c2a1 100644
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -56,6 +56,7 @@
     "react-infinite-scroll-component": "^6.1.1",
     "react-loading-skeleton": "^3.5.0",
     "react-markdown": "^10.1.0",
+    "remove-markdown": "^0.6.3",
     "schema-dts": "^1.1.5",
     "sharp": "^0.34.5",
     "tailwind-merge": "^3.4.0",
diff --git a/bun.lock b/bun.lock
index 20afc225..c2a2b35b 100644
--- a/bun.lock
+++ b/bun.lock
@@ -154,6 +154,7 @@
         "react-infinite-scroll-component": "^6.1.1",
         "react-loading-skeleton": "^3.5.0",
         "react-markdown": "^10.1.0",
+        "remove-markdown": "^0.6.3",
         "schema-dts": "^1.1.5",
         "sharp": "^0.34.5",
         "tailwind-merge": "^3.4.0",
@@ -2771,6 +2772,8 @@
 
     "remark-stringify": ["remark-stringify@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-to-markdown": "^2.0.0", "unified": "^11.0.0" } }, "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw=="],
 
+    "remove-markdown": ["remove-markdown@0.6.3", "", {}, "sha512-Qvp2p0Q1irE7AaJO7QemJe04HdObHylJrG+q4hszvPlYp7q4EvfINpEIaIEFdB+3XTDp1h6fiyT60ae00gmRow=="],
+
     "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
 
     "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],

From 7683a3123ef09dbe3584b4eed3ec0362422893b7 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 22:04:55 -0300
Subject: [PATCH 099/111] fix: strip markdown syntax from blog post preview

---
 apps/frontend/src/app/(content)/(info)/blog/page.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/frontend/src/app/(content)/(info)/blog/page.tsx b/apps/frontend/src/app/(content)/(info)/blog/page.tsx
index 4cdab16b..6896fd1c 100644
--- a/apps/frontend/src/app/(content)/(info)/blog/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/blog/page.tsx
@@ -3,6 +3,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import { Metadata } from 'next';
 import Image from 'next/image';
 import Link from 'next/link';
+import removeMarkdown from 'remove-markdown';
 
 import { getSortedPostsData } from '@web/lib/posts';
 import type { PostType } from '@web/lib/posts';
@@ -58,7 +59,7 @@ const BlogPageComponent = ({ posts }: { posts: PostType[] }) => {
                   .replace(/\//g, '.')}
               </p>
               <p className='self-end line-clamp-3 text-sm text-zinc-400 leading-[1.3]'>
-                {post.content.slice(0, 200)}
+                {removeMarkdown(post.content).slice(0, 200)}
               </p>
             </article>
           </Link>

From 77ba23096fadda08fec4afa6849afdbd246c26c8 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Sun, 25 Jan 2026 22:14:03 -0300
Subject: [PATCH 100/111] fix: increase blog post preview excerpt's length

Make sure there's enough text to fill the line's length, accounting for the removal of Markdown syntax.
---
 apps/frontend/src/app/(content)/(info)/blog/page.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/frontend/src/app/(content)/(info)/blog/page.tsx b/apps/frontend/src/app/(content)/(info)/blog/page.tsx
index 6896fd1c..a9855f94 100644
--- a/apps/frontend/src/app/(content)/(info)/blog/page.tsx
+++ b/apps/frontend/src/app/(content)/(info)/blog/page.tsx
@@ -59,7 +59,7 @@ const BlogPageComponent = ({ posts }: { posts: PostType[] }) => {
                   .replace(/\//g, '.')}
               </p>
               <p className='self-end line-clamp-3 text-sm text-zinc-400 leading-[1.3]'>
-                {removeMarkdown(post.content).slice(0, 200)}
+                {removeMarkdown(post.content).slice(0, 250)}
               </p>
             </article>
           </Link>

From 134aa10305f507fbfca1e407ef6b289f3d482267 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 26 Jan 2026 00:32:09 -0300
Subject: [PATCH 101/111] chore: add section comments on VS Code settings file

---
 .vscode/settings.json | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index d90d6c9c..98703614 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,4 +1,7 @@
 {
+  /***********************************
+  Linting and formatting settings
+  **********************************/
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.formatOnSave": true,
   "eslint.validate": [
@@ -13,6 +16,10 @@
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "always"
   },
+
+  /***********************************
+  Tailwind CSS IntelliSense settings
+  ***********************************/
   // Enable suggestions inside strings for Tailwind CSS class names
   // https://github.com/tailwindlabs/tailwindcss-intellisense#editorquicksuggestions
   "editor.quickSuggestions": {
@@ -26,6 +33,10 @@
     ".css": "tailwindcss",
     "*.scss": "tailwindcss"
   },
+
+  /***********************************
+  Use the workspace version of TypeScript
+  ***********************************/
   "typescript.tsdk": "./node_modules/typescript/lib",
   "typescript.enablePromptUseWorkspaceTsdk": true
 }

From 3f249322a16eb531805f111730917f5d4151efa8 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 26 Jan 2026 00:32:19 -0300
Subject: [PATCH 102/111] chore(lint): remove test files from ESLint config

---
 eslint.config.mjs | 2 --
 1 file changed, 2 deletions(-)

diff --git a/eslint.config.mjs b/eslint.config.mjs
index dedf562d..41124abc 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -18,8 +18,6 @@ export default defineConfig(
       '**/.next/**',
       '**/coverage/**',
       '**/generated/**',
-      '**/*.spec.ts',
-      '**/*.test.ts',
     ],
   },
 

From 45081d2d6cd9e4e6c24b194ba7ad7b6fbc40d160 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 2 Feb 2026 21:19:02 -0300
Subject: [PATCH 103/111] fix(ui): add translucent glass effect to navbar and
 search bar

---
 apps/frontend/src/modules/shared/components/layout/Header.tsx   | 2 +-
 .../frontend/src/modules/shared/components/layout/SearchBar.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/frontend/src/modules/shared/components/layout/Header.tsx b/apps/frontend/src/modules/shared/components/layout/Header.tsx
index c51710ed..94675ee6 100644
--- a/apps/frontend/src/modules/shared/components/layout/Header.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/Header.tsx
@@ -31,7 +31,7 @@ export async function Header() {
   }
 
   return (
-    <header className='fixed w-[calc(100vw-16px)] h-14 flex flex-row justify-center items-center bg-zinc-900 border-b border-zinc-700 py-2 z-10'>
+    <header className='fixed w-[calc(100vw-16px)] h-14 flex flex-row justify-center items-center bg-zinc-900/70 backdrop-blur-md border-b border-zinc-700 py-2 z-10'>
       {/* Navbar */}
       <nav className='w-full flex flex-row justify-between items-center gap-8 md:gap-12 max-w-(--breakpoint-xl) px-6 sm:px-10 overflow-x-auto [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden'>
         {/* Icon */}
diff --git a/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx b/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx
index e194d804..ca6e9230 100644
--- a/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx
+++ b/apps/frontend/src/modules/shared/components/layout/SearchBar.tsx
@@ -40,7 +40,7 @@ export function SearchBar() {
         autoCorrect='off'
         autoCapitalize='none'
         spellCheck={false}
-        className='flex-1 px-3 py-2 pr-1 bg-transparent border border-zinc-700 rounded-l-full text-sm text-white placeholder-zinc-500 focus:outline-hidden focus:border-blue-500'
+        className='flex-1 px-3 py-2 pr-1 bg-zinc-900/40 backdrop-blur-xs border border-zinc-700 rounded-l-full text-sm text-white placeholder-zinc-500 focus:outline-hidden focus:border-blue-500'
       />
       <button
         type='submit'

From 88bfbeb83020d89163704e9b5dae02a8d11cf6ca Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 2 Feb 2026 21:20:43 -0300
Subject: [PATCH 104/111] fix(ui): pad song card grid to always display minimum
 number of columns

---
 .../src/modules/browse/components/SongCardGroup.tsx  | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/frontend/src/modules/browse/components/SongCardGroup.tsx b/apps/frontend/src/modules/browse/components/SongCardGroup.tsx
index 1d62d49e..6eedd04a 100644
--- a/apps/frontend/src/modules/browse/components/SongCardGroup.tsx
+++ b/apps/frontend/src/modules/browse/components/SongCardGroup.tsx
@@ -1,7 +1,17 @@
 const SongCardGroup = ({ children }: { children: React.ReactNode }) => {
+  // Ensure at least 4 items in the grid to prevent single cards from taking up full width
+  const childrenArray = Array.isArray(children) ? children : [children];
+  const itemsToDisplay = Math.max(childrenArray.length, 4);
+  const paddedSongs = [
+    ...childrenArray,
+    ...Array.from({ length: itemsToDisplay - childrenArray.length }, (_, i) => (
+      <div key={`placeholder-${i}`} aria-hidden='true' />
+    )),
+  ];
+
   return (
     <div className='grid grid-auto-fit-md w-full items-center gap-4'>
-      {children}
+      {paddedSongs}
     </div>
   );
 };

From 879121093f06ff6419995a62abb47c3811a8f53b Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 2 Feb 2026 22:15:41 -0300
Subject: [PATCH 105/111] fix: don't proxy downloaded songs through backend
 server

Partially revert commit 173b8706c1075929f84834eb66d35ddb25062973.
---
 apps/backend/src/song/song.controller.spec.ts | 30 +++------
 apps/backend/src/song/song.controller.ts      | 38 +++---------
 apps/backend/src/song/song.service.ts         | 51 ----------------
 .../client/context/EditSong.context.tsx       | 61 +++++--------------
 .../src/modules/song/util/downloadSong.ts     | 36 +++++------
 5 files changed, 52 insertions(+), 164 deletions(-)

diff --git a/apps/backend/src/song/song.controller.spec.ts b/apps/backend/src/song/song.controller.spec.ts
index 158ca27a..b44b4162 100644
--- a/apps/backend/src/song/song.controller.spec.ts
+++ b/apps/backend/src/song/song.controller.spec.ts
@@ -31,7 +31,6 @@ const mockSongService = {
   getSongEdit: jest.fn(),
   patchSong: jest.fn(),
   getSongDownloadUrl: jest.fn(),
-  getSongFileBuffer: jest.fn(),
   deleteSong: jest.fn(),
   uploadSong: jest.fn(),
   getRandomSongs: jest.fn(),
@@ -803,40 +802,31 @@ describe('SongController', () => {
   });
 
   describe('getSongFile', () => {
-    it('should get song .nbs file', async () => {
+    it('should redirect to download URL', async () => {
       const id = 'test-id';
       const src = 'test-src';
       const user: UserDocument = {
         _id: 'test-user-id',
       } as unknown as UserDocument;
+      const downloadUrl = 'https://example.com/download/song.nbs';
 
       const res = {
         set: jest.fn(),
-        send: jest.fn(),
+        redirect: jest.fn(),
       } as unknown as Response;
 
-      const buffer = Buffer.from('test-song-data');
-      const filename = 'test-song.nbs';
-
-      mockSongService.getSongFileBuffer.mockResolvedValueOnce({
-        buffer,
-        filename,
-      });
+      mockSongService.getSongDownloadUrl.mockResolvedValueOnce(downloadUrl);
 
       await songController.getSongFile(id, src, user, res);
 
       expect(res.set).toHaveBeenCalledWith({
-        'Content-Type': 'application/octet-stream',
-        'Content-Disposition': `attachment; filename="${filename.replace(
-          /[/"]/g,
-          '_',
-        )}"`,
+        'Content-Disposition': 'attachment; filename="song.nbs"',
         'Access-Control-Expose-Headers': 'Content-Disposition',
       });
 
-      expect(res.send).toHaveBeenCalledWith(Buffer.from(buffer));
+      expect(res.redirect).toHaveBeenCalledWith(HttpStatus.FOUND, downloadUrl);
 
-      expect(songService.getSongFileBuffer).toHaveBeenCalledWith(
+      expect(songService.getSongDownloadUrl).toHaveBeenCalledWith(
         id,
         user,
         src,
@@ -853,16 +843,16 @@ describe('SongController', () => {
 
       const res = {
         set: jest.fn(),
-        send: jest.fn(),
+        redirect: jest.fn(),
       } as unknown as Response;
 
-      mockSongService.getSongFileBuffer.mockRejectedValueOnce(
+      mockSongService.getSongDownloadUrl.mockRejectedValueOnce(
         new Error('Error'),
       );
 
       await expect(
         songController.getSongFile(id, src, user, res),
-      ).rejects.toThrow('An error occurred while retrieving the song file');
+      ).rejects.toThrow('Error');
     });
   });
 
diff --git a/apps/backend/src/song/song.controller.ts b/apps/backend/src/song/song.controller.ts
index c1005d66..a6e8410d 100644
--- a/apps/backend/src/song/song.controller.ts
+++ b/apps/backend/src/song/song.controller.ts
@@ -321,37 +321,15 @@ export class SongController {
   ): Promise<void> {
     user = validateUser(user);
 
-    try {
-      // Get file directly from S3/MinIO and proxy it to avoid CORS issues
-      // This bypasses presigned URLs and CORS entirely
-      const { buffer, filename } = await this.songService.getSongFileBuffer(
-        id,
-        user,
-        src,
-        false,
-      );
-
-      // Set headers and send file
-      res.set({
-        'Content-Type': 'application/octet-stream',
-        'Content-Disposition': `attachment; filename="${filename.replace(
-          /[/"]/g,
-          '_',
-        )}"`,
-        'Access-Control-Expose-Headers': 'Content-Disposition',
-      });
+    // TODO: no longer used
+    res.set({
+      'Content-Disposition': 'attachment; filename="song.nbs"',
+      // Expose the Content-Disposition header to the client
+      'Access-Control-Expose-Headers': 'Content-Disposition',
+    });
 
-      res.send(Buffer.from(buffer));
-    } catch (error) {
-      this.logger.error('Error downloading song file:', error);
-      if (error instanceof HttpException) {
-        throw error;
-      }
-      throw new HttpException(
-        'An error occurred while retrieving the song file',
-        HttpStatus.INTERNAL_SERVER_ERROR,
-      );
-    }
+    const url = await this.songService.getSongDownloadUrl(id, user, src, false);
+    res.redirect(HttpStatus.FOUND, url);
   }
 
   @Get('/:id/open')
diff --git a/apps/backend/src/song/song.service.ts b/apps/backend/src/song/song.service.ts
index 546d4a35..82da03f8 100644
--- a/apps/backend/src/song/song.service.ts
+++ b/apps/backend/src/song/song.service.ts
@@ -393,57 +393,6 @@ export class SongService {
     }
   }
 
-  public async getSongFileBuffer(
-    publicId: string,
-    user: UserDocument | null,
-    src?: string,
-    packed: boolean = false,
-  ): Promise<{ buffer: ArrayBuffer; filename: string }> {
-    const foundSong = await this.songModel.findOne({ publicId: publicId });
-
-    if (!foundSong) {
-      throw new HttpException('Song not found with ID', HttpStatus.NOT_FOUND);
-    }
-
-    if (foundSong.visibility !== 'public') {
-      if (!user || foundSong.uploader.toString() !== user._id.toString()) {
-        throw new HttpException(
-          'This song is private',
-          HttpStatus.UNAUTHORIZED,
-        );
-      }
-    }
-
-    if (!packed && !foundSong.allowDownload) {
-      throw new HttpException(
-        'The uploader has disabled downloads of this song',
-        HttpStatus.UNAUTHORIZED,
-      );
-    }
-
-    const fileKey = packed ? foundSong.packedSongUrl : foundSong.nbsFileUrl;
-    const fileExt = packed ? '.zip' : '.nbs';
-    const fileName = `${foundSong.title}${fileExt}`;
-
-    try {
-      const fileBuffer = await this.fileService.getSongFile(fileKey);
-
-      // increment download count
-      if (!packed && src === 'downloadButton') {
-        foundSong.downloadCount++;
-        await foundSong.save();
-      }
-
-      return { buffer: fileBuffer, filename: fileName };
-    } catch (e) {
-      this.logger.error('Error getting song file', e);
-      throw new HttpException(
-        'An error occurred while retrieving the song file',
-        HttpStatus.INTERNAL_SERVER_ERROR,
-      );
-    }
-  }
-
   public async getMySongsPage({
     query,
     user,
diff --git a/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx b/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
index cd3d0329..914aeca1 100644
--- a/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
+++ b/apps/frontend/src/modules/song-edit/components/client/context/EditSong.context.tsx
@@ -241,56 +241,25 @@ export const EditSongProvider = ({
       // fetch song
       const token = getTokenLocal();
 
-      try {
-        // Backend now proxies the file directly, avoiding CORS issues
-        const response = await axiosInstance.get(`/song/${id}/download`, {
+      const songFile = (
+        await axiosInstance.get(`/song/${id}/download`, {
           params: {
             src: 'edit',
           },
+          responseType: 'arraybuffer',
           headers: { authorization: `Bearer ${token}` },
-          responseType: 'arraybuffer', // Get as ArrayBuffer for parsing
-        });
-
-        const songFile = response.data;
-
-        // convert to song
-        const song = await parseSongFromBuffer(songFile);
-
-        // set instruments array
-        const songInstruments = songData.customInstruments;
-        setInstrumentSounds(songInstruments);
-        formMethods.setValue('customInstruments', songInstruments);
-
-        setSong(song);
-      } catch (error: unknown) {
-        let errorMessage = 'An unknown error occurred while loading the song!';
-        if (error instanceof AxiosError) {
-          if (error.response) {
-            // Server responded with an error status
-            errorMessage =
-              error.response.data?.message ||
-              (error.response.data?.error
-                ? Object.values(error.response.data.error)[0]
-                : null) ||
-              `Failed to load song: ${error.response.status}`;
-          } else if (error.request) {
-            // Request was made but no response received (network error)
-            errorMessage =
-              'Network error: Unable to connect to the server. Please check your internet connection and try again.';
-          } else {
-            // Something else happened (including fetch errors)
-            errorMessage = error.message || errorMessage;
-          }
-
-          setSendError(errorMessage);
-          toaster.error(errorMessage);
-          throw error; // Re-throw to allow caller to handle if needed
-        } else {
-          setSendError(errorMessage);
-          toaster.error(errorMessage);
-          throw error;
-        }
-      }
+        })
+      ).data as ArrayBuffer;
+
+      // convert to song
+      const song = await parseSongFromBuffer(songFile);
+
+      // set instruments array
+      const songInstruments = songData.customInstruments;
+      setInstrumentSounds(songInstruments);
+      formMethods.setValue('customInstruments', songInstruments);
+
+      setSong(song);
     },
     [formMethods, setSong],
   );
diff --git a/apps/frontend/src/modules/song/util/downloadSong.ts b/apps/frontend/src/modules/song/util/downloadSong.ts
index 38df926d..6012e43f 100644
--- a/apps/frontend/src/modules/song/util/downloadSong.ts
+++ b/apps/frontend/src/modules/song/util/downloadSong.ts
@@ -11,9 +11,8 @@ export const downloadSongFile = async (song: {
 }) => {
   const token = getTokenLocal();
 
-  try {
-    // Backend now proxies the file directly, avoiding CORS issues
-    const response = await axios.get(`/song/${song.publicId}/download`, {
+  axios
+    .get(`/song/${song.publicId}/download`, {
       params: {
         src: 'downloadButton',
       },
@@ -21,22 +20,25 @@ export const downloadSongFile = async (song: {
         authorization: `Bearer ${token}`,
       },
       responseType: 'blob',
-    });
+      withCredentials: true,
+    })
+    .then((res) => {
+      const url = window.URL.createObjectURL(res.data);
+      const link = document.createElement('a');
+      link.href = url;
 
-    const url = window.URL.createObjectURL(response.data);
-    const link = document.createElement('a');
-    link.href = url;
-    link.setAttribute('download', `${song.title}.nbs`);
-    document.body.appendChild(link);
-    link.click();
+      link.setAttribute('download', `${song.title}.nbs`);
+      document.body.appendChild(link);
+      link.click();
 
-    // Clean up
-    link.remove();
-    window.URL.revokeObjectURL(url);
-  } catch (error) {
-    console.error('Error downloading song:', error);
-    toast.error('Failed to download song');
-  }
+      // Clean up
+      link.remove();
+      window.URL.revokeObjectURL(url);
+    })
+    .catch((error) => {
+      console.error('Error downloading song:', error);
+      toast.error('Failed to download song');
+    });
 };
 
 export const openSongInNBS = async (song: { publicId: string }) => {

From d7899b1ed40e702ca2356e400830e78b459c34a1 Mon Sep 17 00:00:00 2001
From: Bentroen <29354120+Bentroen@users.noreply.github.com>
Date: Mon, 2 Feb 2026 22:16:08 -0300
Subject: [PATCH 106/111] build: fix missing single quote in `start:server`
 command

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 6d8e442f..3f66ddb0 100644
--- a/package.json
+++ b/package.json
@@ -48,7 +48,7 @@
     "build:all": "bun run build:packages && bun run build:apps",
     "docker": "docker-compose -f docker-compose-dev.yml up -d && bun run dev && docker-compose down",
     "start:apps": "bun run --filter './apps/*' start",
-    "start:server": "bun run --filter '@nbw/backend start",
+    "start:server": "bun run --filter '@nbw/backend' start",
     "start:web": "bun run --filter '@nbw/frontend' start",
     "dev:server": "bun run --filter '@nbw/backend' start:dev",
     "dev:web": "bun run --filter '@nbw/frontend' dev",

From cd3ad18b8ecd3b0fd8f4921a4626b637a57af37a Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Fri, 6 Feb 2026 22:57:08 -0300
Subject: [PATCH 107/111] feat(auth): enhance cookie handling and trust proxy
 settings

- Added trust proxy configuration for Express to handle X-Forwarded-* headers correctly.
- Improved cookie options by conditionally setting the domain attribute to prevent browser blocking of invalid domains.
---
 apps/backend/src/auth/auth.service.ts | 31 ++++++++++++++++++++-------
 apps/backend/src/main.ts              |  5 +++++
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index 53237ea1..2c7ce302 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -199,18 +199,33 @@ export class AuthService {
     });
 
     const frontEndURL = this.FRONTEND_URL;
-    const domain = this.APP_DOMAIN;
     const maxAge = ms(this.COOKIE_EXPIRES_IN) * 1000;
 
-    res.cookie('token', token.access_token, {
-      domain: domain,
+    // Build cookie options with conditional domain
+    // Only include domain if it's set and not empty (avoids browser blocking invalid domains)
+    const cookieOptions: {
+      maxAge: number;
+      sameSite: 'none' | 'lax' | 'strict';
+      secure: boolean;
+      httpOnly: boolean;
+      path: string;
+      domain?: string;
+    } = {
       maxAge: maxAge,
-    });
+      sameSite: 'none', // Required for cross-site cookies
+      secure: true, // Required when sameSite is 'none'
+      httpOnly: true, // Prevents JavaScript access (security best practice)
+      path: '/', // Make cookies available site-wide
+    };
 
-    res.cookie('refresh_token', token.refresh_token, {
-      domain: domain,
-      maxAge: maxAge,
-    });
+    // Only set domain if APP_DOMAIN is provided and not empty
+    // This prevents browser from blocking cookies with invalid domain attributes
+    if (this.APP_DOMAIN && this.APP_DOMAIN.trim() !== '') {
+      cookieOptions.domain = this.APP_DOMAIN;
+    }
+
+    res.cookie('token', token.access_token, cookieOptions);
+    res.cookie('refresh_token', token.refresh_token, cookieOptions);
 
     res.redirect(frontEndURL + '/');
   }
diff --git a/apps/backend/src/main.ts b/apps/backend/src/main.ts
index 389ee3c0..2fd6a1ed 100644
--- a/apps/backend/src/main.ts
+++ b/apps/backend/src/main.ts
@@ -28,6 +28,11 @@ async function bootstrap() {
   app.use(express.json({ limit: '50mb' }));
   app.use(express.urlencoded({ extended: true, limit: '50mb' }));
 
+  // Trust proxy for Railway reverse proxy
+  // This ensures Express properly handles X-Forwarded-* headers
+  const expressApp = app.getHttpAdapter().getInstance();
+  expressApp.set('trust proxy', 1);
+
   if (process.env.NODE_ENV === 'development') {
     initializeSwagger(app);
   }

From fdfb10596af0cdd6721522553c6f5399777b54a8 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 7 Feb 2026 10:35:08 -0300
Subject: [PATCH 108/111] fix(auth): update cookie security settings to allow
 JavaScript access

---
 apps/backend/src/auth/auth.service.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index 2c7ce302..09a33dae 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -214,7 +214,7 @@ export class AuthService {
       maxAge: maxAge,
       sameSite: 'none', // Required for cross-site cookies
       secure: true, // Required when sameSite is 'none'
-      httpOnly: true, // Prevents JavaScript access (security best practice)
+      httpOnly: false, // Prevents JavaScript access (security best practice)
       path: '/', // Make cookies available site-wide
     };
 

From dab5c43812195691af3b50fbdd5eabf5bf7b9620 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 7 Feb 2026 20:11:17 -0300
Subject: [PATCH 109/111] fix(auth): refine cookie options for improved
 security and compatibility

- Updated cookie options to use the CookieOptions type from Express.
- Ensured the domain attribute is set correctly for cross-site cookies.
- Removed conditional domain setting to streamline cookie handling.
---
 apps/backend/src/auth/auth.service.ts | 28 ++++++---------------------
 1 file changed, 6 insertions(+), 22 deletions(-)

diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index 09a33dae..c3a7e2d6 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -1,7 +1,7 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 import axios from 'axios';
-import type { Request, Response } from 'express';
+import type { CookieOptions, Request, Response } from 'express';
 import ms from 'ms';
 
 import { CreateUser } from '@nbw/database';
@@ -190,7 +190,7 @@ export class AuthService {
 
   private async GenTokenRedirect(
     user_registered: UserDocument,
-    res: Response<any, Record<string, any>>,
+    res: Response<unknown, Record<string, unknown>>,
   ): Promise<void> {
     const token = await this.createJwtPayload({
       id: user_registered._id.toString(),
@@ -201,29 +201,13 @@ export class AuthService {
     const frontEndURL = this.FRONTEND_URL;
     const maxAge = ms(this.COOKIE_EXPIRES_IN) * 1000;
 
-    // Build cookie options with conditional domain
-    // Only include domain if it's set and not empty (avoids browser blocking invalid domains)
-    const cookieOptions: {
-      maxAge: number;
-      sameSite: 'none' | 'lax' | 'strict';
-      secure: boolean;
-      httpOnly: boolean;
-      path: string;
-      domain?: string;
-    } = {
+    const cookieOptions: CookieOptions = {
       maxAge: maxAge,
-      sameSite: 'none', // Required for cross-site cookies
-      secure: true, // Required when sameSite is 'none'
-      httpOnly: false, // Prevents JavaScript access (security best practice)
-      path: '/', // Make cookies available site-wide
+      domain: this.APP_DOMAIN,
+      sameSite: 'none',
+      path: '/',
     };
 
-    // Only set domain if APP_DOMAIN is provided and not empty
-    // This prevents browser from blocking cookies with invalid domain attributes
-    if (this.APP_DOMAIN && this.APP_DOMAIN.trim() !== '') {
-      cookieOptions.domain = this.APP_DOMAIN;
-    }
-
     res.cookie('token', token.access_token, cookieOptions);
     res.cookie('refresh_token', token.refresh_token, cookieOptions);
 

From cb06c193372d66f2a43de4eb5bfac1805a54c8a6 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Sat, 7 Feb 2026 20:36:26 -0300
Subject: [PATCH 110/111] fix(auth): remove sameSite attribute from cookie
 options for compatibility

---
 apps/backend/src/auth/auth.service.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/apps/backend/src/auth/auth.service.ts b/apps/backend/src/auth/auth.service.ts
index c3a7e2d6..ae96220a 100644
--- a/apps/backend/src/auth/auth.service.ts
+++ b/apps/backend/src/auth/auth.service.ts
@@ -204,7 +204,6 @@ export class AuthService {
     const cookieOptions: CookieOptions = {
       maxAge: maxAge,
       domain: this.APP_DOMAIN,
-      sameSite: 'none',
       path: '/',
     };
 

From 34d834c39a744756d451bfe697509766665098d8 Mon Sep 17 00:00:00 2001
From: tomast1337 <vycasnicolas@gmail.com>
Date: Wed, 18 Feb 2026 22:07:15 -0300
Subject: [PATCH 111/111] fix(auth): add path option to cookie settings for
 proper routing

---
 apps/backend/src/auth/auth.service.spec.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/backend/src/auth/auth.service.spec.ts b/apps/backend/src/auth/auth.service.spec.ts
index 2fb54343..add4d1dc 100644
--- a/apps/backend/src/auth/auth.service.spec.ts
+++ b/apps/backend/src/auth/auth.service.spec.ts
@@ -253,6 +253,7 @@ describe('AuthService', () => {
       expect(res.cookie).toHaveBeenCalledWith('token', 'access-token', {
         domain: '.test.com',
         maxAge: 3600000,
+        path: '/',
       });
 
       expect(res.cookie).toHaveBeenCalledWith(
@@ -261,6 +262,7 @@ describe('AuthService', () => {
         {
           domain: '.test.com',
           maxAge: 3600000,
+          path: '/',
         },
       );