chore: add type:module, fix npm audit, rename CJS files, document module structure

- package.json: add type: module to silence ESM warnings
- server: npm audit fix (0 vulnerabilities, ws vuln resolved)
- Rename 4 CJS files to .cjs: build-extension, test-content-video-finder,
  test-locales, website/build
- Update eslint.config.mjs for .cjs glob patterns
- extension/README.md + server/README.md: document module structure

eslint.config.mjs

@@ -58,7 +58,7 @@ export default [
     }
   },
   {
-    files: ["server/**/*.js", "scripts/**/*.js", "website/build.js"],
+    files: ["server/**/*.js", "scripts/**/*.js", "scripts/**/*.cjs", "website/build.cjs"],
     languageOptions: {
       globals: {
         require: "readonly",

extension/README.md

@@ -38,3 +38,15 @@ If you modify `shared/constants.js`, you must synchronize the changes by running
 node scripts/build-extension.js
 ```
 This ensures that the `extension/shared` folder is updated with the latest protocol constants.
+
+## Module Structure
+
+| File | Purpose |
+|---|---|
+| `background.js` | Service worker: message routing, tab listeners, startup |
+| `content.js` | Video detection, audio processing, episode transition (IIFE) |
+| `popup.js` | Popup UI: join/create, tabs, status, settings |
+| `bridge.js` | Landing page bridge (injected into sync.koalastuff.net) |
+| `episode-utils.js` | Shared `extractEpisodeId()` / `sameEpisode()` — used by background.js, injected into content.js at build time |
+| `i18n.js` | Translation loader |
+| `shared/` | Constants, blacklist, name generator |

package.json

@@ -3,8 +3,9 @@
   "version": "2.3.2",
   "description": "KoalaSync Build Scripts",
   "private": true,
+  "type": "module",
   "scripts": {
-    "build:extension": "node scripts/build-extension.js",
+    "build:extension": "node scripts/build-extension.cjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "verify": "node scripts/verify-release.mjs"

scripts/verify-release.mjs

@@ -13,7 +13,7 @@ const checks = [
   }],
   ['rate-limiter unit tests', 'node', ['scripts/test-rate-limiter.mjs']],
   ['episode-utils unit tests', 'node', ['scripts/test-episode-utils.mjs']],
-  ['content video finder', 'node', ['scripts/test-content-video-finder.js']],
+  ['content video finder', 'node', ['scripts/test-content-video-finder.cjs']],
   ['audio settings', 'node', ['scripts/test-audio-settings.mjs']],
   ['popup refresh cooldown', 'node', ['scripts/test-popup-refresh-cooldown.mjs']],
   ['server syntax index', 'node', ['-c', 'server/index.js']],
@@ -22,13 +22,13 @@ const checks = [
   ['content syntax', 'node', ['-c', 'extension/content.js']],
   ['popup syntax', 'node', ['-c', 'extension/popup.js']],
   ['background syntax', 'node', ['-c', 'extension/background.js']],
-  ['locale coverage', 'node', ['scripts/test-locales.js']],
+  ['locale coverage', 'node', ['scripts/test-locales.cjs']],
   ['website locale coverage', 'node', ['scripts/test-website-locales.mjs']],
   ['lint', 'npm', ['run', 'lint']],
   ['root production audit', 'npm', ['audit', '--omit=dev']],
   ['server production audit', 'npm', ['audit', '--omit=dev'], { cwd: path.join(repoRoot, 'server') }],
   ['extension build', 'npm', ['run', 'build:extension']],
-  ['website build', 'node', ['website/build.js']]
+  ['website build', 'node', ['website/build.cjs']]
 ];
 
 function runCheck([label, command, args, options = {}]) {

server/README.md

@@ -71,3 +71,11 @@ npm start
 - **Single Source of Truth**: The server imports constants directly from the root `shared/` directory.
 - **In-Memory**: Rooms are automatically pruned after 2 hours of inactivity.
 - **Reverse Proxy Boundary**: The server trusts one reverse proxy hop for client IP detection. Keep the Node port private/firewalled so clients can only reach it through Caddy or another trusted proxy.
+
+## Module Structure
+
+| File | Purpose |
+|---|---|
+| `index.js` | Express + Socket.IO server: room management, relay loop, graceful shutdown |
+| `rate-limiter.js` | Connection, event, health, and auth rate limiting with 6 functions + cleanup intervals |
+| `ops.js` | Health endpoint helpers, metrics payload builder, auth validation |

server/package-lock.json

@@ -256,9 +256,9 @@
       }
     },
     "node_modules/engine.io": {
-      "version": "6.6.8",
-      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.6.8.tgz",
-      "integrity": "sha512-2agL3ueZhqxoVrfmntO8yuVj+uNSlIOnhykYHk3Cq0ShYPdUjjUiSJrQvXjq01I9jAuI0Zl2YO8Evv5Mqytm5g==",
+      "version": "6.6.9",
+      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.6.9.tgz",
+      "integrity": "sha512-clKkw4C7nJ22mGgoVcCg6V/W/TxdNyIOTr89k2ONZu81qqkddPFDF0LXcbAwhzPD8DjkiRCjzuiO6Y+fkpD4vg==",
       "license": "MIT",
       "dependencies": {
         "@types/cors": "^2.8.12",
@@ -270,7 +270,7 @@
         "cors": "~2.8.5",
         "debug": "~4.4.1",
         "engine.io-parser": "~5.2.1",
-        "ws": "~8.20.1"
+        "ws": "~8.21.0"
       },
       "engines": {
         "node": ">=10.2.0"
@@ -941,13 +941,13 @@
       }
     },
     "node_modules/socket.io-adapter": {
-      "version": "2.5.7",
-      "resolved": "https://registry.npmjs.org/socket.io-adapter/-/socket.io-adapter-2.5.7.tgz",
-      "integrity": "sha512-e0LyK91f3cUxTmv95/KzoLg47+zF+s/sbxRGDNsyG4dmIP8ZSX8ax6byOxfJXeNNtS/8AZlfD+uP7gBeR7DLlg==",
+      "version": "2.5.8",
+      "resolved": "https://registry.npmjs.org/socket.io-adapter/-/socket.io-adapter-2.5.8.tgz",
+      "integrity": "sha512-6Oy52pbg+kvdCVvjcN+FnY7BvxZ7cIHNScbvztT/It5d0vbwoJoVZmF2gjJmnV0/4WlXRfG15zc45ySk9Ah8bw==",
       "license": "MIT",
       "dependencies": {
         "debug": "~4.4.1",
-        "ws": "~8.20.1"
+        "ws": "~8.21.0"
       }
     },
     "node_modules/socket.io-parser": {
@@ -1069,9 +1069,9 @@
       "license": "ISC"
     },
     "node_modules/ws": {
-      "version": "8.20.1",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.1.tgz",
-      "integrity": "sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==",
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"