feat: optimize extension uninstall URL registration with anonymous token and startup hardening

docs: revert completed milestones in ROADMAP.md
docs: audit and update script references, supported languages, and completed milestones
2026-07-26 20:18:14 +00:00 · 2026-06-19 11:54:07 +02:00 · 2026-06-19 11:39:50 +02:00 · 2026-06-19 11:35:49 +02:00 · 2026-06-19 11:12:48 +02:00 · 2026-06-19 10:59:30 +02:00
47 changed files with 1144 additions and 385 deletions
@@ -37,7 +37,7 @@ Closes #
 - [ ] I have performed a self-review of my code
 - [ ] I have added/updated tests if needed
 - [ ] I have updated documentation if needed (`docs/`, README, etc.)
- [ ] Protocol changes: I ran `node scripts/build-extension.js` and updated relevant docs
+- [ ] Protocol changes: I ran `node scripts/build-extension.cjs` and updated relevant docs
 - [ ] No new warnings, secrets, or hardcoded credentials introduced

 ### Additional Context
@@ -5,23 +5,29 @@ on:
    tags:
      - 'v*'

+# A release run must never be interrupted (it commits back to main and publishes
+# artifacts). Only dedupe accidental re-pushes of the same tag.
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
 jobs:
  release-server:
    runs-on: ubuntu-latest
    permissions:
-      contents: write
+      contents: read
      packages: write
      id-token: write
      attestations: write
    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
@@ -29,7 +35,7 @@ jobs:

      - name: Extract Docker metadata
        id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
@@ -38,7 +44,7 @@ jobs:

      - name: Build and push Docker image
        id: build
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
        with:
          context: .
          file: server/Dockerfile
@@ -46,6 +52,9 @@ jobs:
          platforms: linux/amd64,linux/arm64
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
+          # Reuse layers across releases to speed up the multi-arch build.
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

      - name: Generate artifact attestation
        uses: actions/attest@v4
@@ -62,7 +71,13 @@ jobs:
      attestations: write
    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'

      - name: Extract version from tag
        id: version
@@ -79,7 +94,7 @@ jobs:
          echo "  ✓ manifest.base.json -> $VERSION"

          # 2. shared/constants.js — APP_VERSION
-          sed -i "s/export const APP_VERSION = '.*'/export const APP_VERSION = '$VERSION'/" shared/constants.js
+          sed -i "s/export const APP_VERSION = [\"'].*[\"']/export const APP_VERSION = \"$VERSION\"/" shared/constants.js
          echo "  ✓ shared/constants.js -> $VERSION"

          # 3. package.json
@@ -94,17 +109,22 @@ jobs:
          sed -i "s/\"softwareVersion\": \".*\"/\"softwareVersion\": \"$VERSION\"/" website/template.html
          echo "  ✓ website/template.html -> softwareVersion $VERSION"

-          # 6. README.md — version badge
-          sed -i "s/v[0-9]\+\.[0-9]\+\.[0-9]\+/v$VERSION/g" README.md
+          # 6. README.md — version badge & banner
+          sed -i "s|Release-v[0-9]\+\.[0-9]\+\.[0-9]\+-blue|Release-v$VERSION-blue|g" README.md
+          sed -i "s/New v[0-9]\+\.[0-9]\+\.[0-9]\+ Release/New v$VERSION Release/g" README.md
          echo "  ✓ README.md -> v$VERSION"

+          # 7. website/sitemap.xml — lastmod dates
+          sed -i "s/<lastmod>[0-9-]*<\/lastmod>/<lastmod>$(date +%Y-%m-%d)<\/lastmod>/g" website/sitemap.xml
+          echo "  ✓ website/sitemap.xml -> lastmod $(date +%Y-%m-%d)"
+
          echo "Version injection complete."

      - name: Commit and push version updates back to main
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
-          git add extension/manifest.base.json shared/constants.js package.json website/version.json website/template.html README.md
+          git add extension/manifest.base.json shared/constants.js package.json website/version.json website/template.html README.md website/sitemap.xml
          git commit -m "chore(release): update versions to $GITHUB_REF_NAME [skip ci]" || echo "No changes to commit"
          git push origin HEAD:main
        env:
@@ -121,17 +141,17 @@ jobs:
          subject-path: dist/koalasync-*.zip

      - name: Build Website
-        run: node website/build.js
+        run: node website/build.cjs

      - name: Upload Website Artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: website-www
          path: website/www/
          if-no-files-found: error

      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v3
        with:
          files: |
            dist/koalasync-chrome.zip
@@ -31,7 +31,7 @@ Please note that by participating in this project, you agree to abide by our [Co
 git clone https://github.com/Shik3i/KoalaSync.git
 cd KoalaSync
 npm install
-node scripts/build-extension.js
+node scripts/build-extension.cjs
 ```

 ---
@@ -62,7 +62,7 @@ node scripts/build-extension.js
 ### Website

 ```bash
-node website/build.js           # Compile static site → www/
+node website/build.cjs           # Compile static site → www/
 python3 -m http.server 8080 -d website/www  # Serve locally
 ```

@@ -77,7 +77,7 @@ KoalaSync uses a **single source of truth** for all protocol constants in `share
 > [!IMPORTANT]
 > After modifying `shared/constants.js`, you **must** run the build script to sync changes to the extension:
 > ```bash
-> node scripts/build-extension.js
+> node scripts/build-extension.cjs
 > ```
 > This automatically injects constants into `content.js` and regenerates browser bundles in `dist/`.

@@ -109,7 +109,7 @@ If you are new to open-source contributions, follow these steps to propose your
 3. **Create a Branch**: `git checkout -b my-new-feature` (e.g. `feature/dark-mode` or `fix/translation-de`)
 4. **Make your Changes**: Edit the files, then verify them locally.
   - *Extension/Server changes*: Test on Chrome/Firefox and check `npm run lint`.
-   - *Website/Translation changes*: Run `node website/build.js` and check the output in `www/`.
+   - *Website/Translation changes*: Run `node website/build.cjs` and check the output in `www/`.
 5. **Commit and Push**: `git commit -m "Add my feature"` and `git push origin my-new-feature`
 6. **Open a Pull Request (PR)**: Go to the original KoalaSync repository on GitHub and click "New Pull Request".

@@ -156,9 +156,9 @@ KoalaSync supports multiple languages. To add or improve translations:
 1. Read the **[Translation Guide](docs/TRANSLATION.md)** first. It explains how our localization system works.
 2. Edit the `.json` files in `website/locales/` (for the website) and `extension/locales/` (for the extension).
 3. Test your translations locally by running:
-   - `node scripts/test-locales.js` (for extension)
+   - `node scripts/test-locales.cjs` (for extension)
   - `node scripts/test-website-locales.mjs` (for website)
-   - `node website/build.js` (to build the site)
+   - `node website/build.cjs` (to build the site)
 4. Follow the **Open Source Workflow** above (Fork -> Branch -> Edit -> PR) to submit your translations.

 ---
@@ -6,15 +6,15 @@

 <p align="center">
  <a href="https://github.com/Shik3i/KoalaSync/actions/workflows/release.yml"><img src="https://github.com/Shik3i/KoalaSync/actions/workflows/release.yml/badge.svg" alt="Release Status"></a>
-  <a href="https://github.com/Shik3i/KoalaSync/releases"><img src="https://img.shields.io/github/v/release/Shik3i/KoalaSync" alt="GitHub release"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/Shik3i/KoalaSync?color=blue" alt="License"></a>
+  <a href="https://github.com/Shik3i/KoalaSync/releases"><img src="https://img.shields.io/badge/Release-v2.4.1-blue?logo=github" alt="GitHub release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License"></a>
  <a href="https://addons.mozilla.org/de/firefox/addon/koalasync/"><img src="https://img.shields.io/badge/Firefox-Download-orange?logo=firefoxbrowser&logoColor=white" alt="Firefox Add-on"></a>
  <a href="https://chromewebstore.google.com/detail/koalasync/obbnmkmlaaddodakcbdljknjpagklifc"><img src="https://img.shields.io/badge/Chrome-Download-blue?logo=googlechrome&logoColor=white" alt="Chrome Extension"></a>
 </p>

 <p align="center"><i>KoalaSync is a lightweight Browser Extension and Relay Server for synchronized video playback on almost any website with a video element—YouTube, Twitch, Netflix, Emby, Jellyfin, and beyond. Built with a focus on <b>Data Sovereignty</b> and <b>Performance</b>.</i></p>

-<p align="center"><a href="docs/CHANGELOG.md"><b>New v2.3.1 Release!</b> — See what's changed</a></p>
+<p align="center"><a href="docs/CHANGELOG.md"><b>New v2.4.1 Release!</b> — See what's changed</a></p>

 ### 🌟 Why KoalaSync?

@@ -81,7 +81,7 @@ Both the official KoalaSync website and the **v2.0 Browser Extension** feature f
 To build the extension from source and synchronize protocol constants:
 ```bash
 npm install
-node scripts/build-extension.js
+npm run build:extension
 ```
 The compiled artifacts will be available in the `dist/` directory.

@@ -103,7 +103,7 @@ To connect your extension to a self-hosted server, open the popup → **Room** t

 To verify your relay is reachable from outside, visit `https://your-domain.com` in a browser — it should return `{"status":"online","service":"KoalaSync Relay"}`.

-#### Supply Chain Security (v2.3.1+)
+#### Supply Chain Security (v2.2.2+)

 All official release artifacts (Docker images and extension binaries) are published with signed [artifact attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations) to prove they were built from this repository's source code.

@@ -40,7 +40,7 @@ KoalaSync is built for private watch parties without unnecessary data collection
 ⚙️ UNDER THE HOOD
 KoalaSync is lightweight, transparent, and built with privacy in mind.

-• Real-Time Relay: Playback state is synchronized through a custom WebSocket-based relay server for fast room updates.
+• On-Demand Relay: Playback state is synchronized through a custom WebSocket-based relay server. No persistent connection — the relay is only active while you're in a room. No background traffic, no idle connections.
 • No Media Streaming: KoalaSync does not stream, proxy, upload, download, or redistribute any video content. Everyone watches from their own browser on the original website.
 • Temporary Room State Only: The relay server only coordinates room state such as play, pause, seek position, active target, nickname, and readiness status.
 • Docker Self-Hosting: The relay server can be self-hosted with Docker if you prefer to run your own private instance.
@@ -21,14 +21,14 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi
 - `extension/`: Browser Extension (Chrome & Firefox, Manifest V3). Contains background service worker, content scripts, and popup UI.
 - `server/`: Node.js Relay Server using Socket.IO (WebSocket-only).
 - `website/`: **Landing Page** & Invitation Bridge (Marketing, Tutorials, and Downloads).
-  - **`build.js`**: Zero-dependency static site compiler. Translates `template.html` + `locales/*.json` → `www/`. Also minifies CSS/JS automatically.
-  - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.js` to regenerate. CSS/JS are output as `.min.*` files — a built-in cleanup step removes stale artifacts on each build.
+  - **`build.cjs`**: Zero-dependency static site compiler. Translates `template.html` + `locales/*.json` → `www/`. Also minifies CSS/JS automatically.
+  - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.cjs` to regenerate. CSS/JS are output as `.min.*` files — a built-in cleanup step removes stale artifacts on each build.
 - `shared/`: **Single Source of Truth** for protocol constants and event names.
- `scripts/`: Development utilities (e.g., `build-extension.js`).
+- `scripts/`: Development utilities (e.g., `build-extension.cjs`).
 - `docker-compose.yml`: Root-level orchestration for the relay server.

 > [!IMPORTANT]
-> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.js`. 
+> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.cjs`. 
 > - **Extension Modules** (`background.js`, `popup.js`) import directly from `./shared/constants.js`.
 > - **Content Scripts** (`content.js`) use a **marker-injected synchronous copy** of the constants. The build script automatically replaces the marked blocks — no manual mirroring needed.

@@ -41,7 +41,7 @@ Before touching any code, you MUST read the following documents in order:
 ## 4. The "Vanilla JS Mirror" Pattern
 To avoid boot-time race conditions in Manifest V3 without a bundler, the following architectural trade-off is enforced:
 - **Synchronous Execution**: `content.js` MUST execute synchronously to catch early media events. 
- **Automated Injection**: The build script (`node scripts/build-extension.js`) automatically injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details).
+- **Automated Injection**: The build script (`node scripts/build-extension.cjs`) automatically injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details).
 - **Maintenance**: After modifying `shared/constants.js`, simply run the build script. No manual mirroring is required.

 ## 5. File Responsibility Map
@@ -137,18 +137,18 @@ Before starting any task, committing, or pushing, you **MUST** run `git pull --r

 ### Adding a Protocol Event
 1. Add the event name to `shared/constants.js`.
-2. Run the build script (`node scripts/build-extension.js`).
+2. Run the build script (`node scripts/build-extension.cjs`).
 3. Implement the handler in `server/index.js` and `background.js`.

 ### Making Website Changes
 1. Edit source files in `website/` (`template.html`, `style.css`, `app.js`, `lang-init.js`, or `locales/*.json`).
-2. Run the compiler: `node website/build.js`. This generates the multilingual pages in `www/` and minifies CSS/JS.
+2. Run the compiler: `node website/build.cjs`. This generates the multilingual pages in `www/` and minifies CSS/JS.
 3. Verify the output: `node --check website/www/app.js && node --check website/www/lang-init.js`.
 4. Test locally: `npx serve website/www` or `python3 -m http.server 8080 -d website/www`.
 5. Commit both source changes and the updated `www/` output.

 ### Testing Locally
-1. Run the build script: `node scripts/build-extension.js`.
+1. Run the build script: `node scripts/build-extension.cjs`.
 2. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (or `dist/firefox/` in Firefox).
 3. Start the server from the root: `docker-compose up --build`.
 4. Use **different browser profiles** or vendors to test multi-peer logic.
@@ -2,9 +2,10 @@

 This document describes the communication flows and internal logic of the KoalaSync system.

-## 1. Extension Startup & Connection
- **Initialization**: On startup, `background.js` reads settings (Server URL, Username, Last Room) from `chrome.storage.sync`.
- **WebSocket Handshake**:
+## 1. Extension Connection (Lazy Connect)
+- **Initialization**: On startup, `background.js` reads settings (Server URL, Username, Last Room) from `chrome.storage.sync`. No WebSocket connection is established at this point.
+- **On-Demand Connection**: The extension only connects when needed — either the user opens the popup with saved room credentials, or when actively in a room. When not in a room, no connection exists. This improves privacy (IP not exposed while idle) and reduces battery/network usage.
+- **WebSocket Handshake (when connecting)**:
  1. Background creates a `new WebSocket` to `/socket.io/?EIO=4&transport=websocket&version=1.0.0`.
  2. Server performs security checks:
     - **IP Rate Limit**: Checks if the IP has exceeded connection limits.
@@ -45,7 +46,7 @@ To maintain a clean room state and eliminate "Ghost Peers":
 - **Video Heartbeat (Content)**: Every 15 seconds, `content.js` sends current playback metadata (time, title, state) if a video is found.
 - **Server Pruning**: The server runs a "Reaper" every 2 minutes. If a peer has sent **zero** activity (no events and no heartbeats) for 5 minutes, they are forcefully disconnected.
 - **Immediate Cleanup**: Rooms are deleted instantly when the last peer leaves or disconnects.
- **Reconnect Strategy**: Aggressive backoff — 500ms base, 1.5x multiplier, capped at 5s. Max 20 attempts before marking as failed. Events are queued during disconnect and flushed after namespace rejoin.
+- **Reconnect Strategy (while in room)**: Aggressive backoff — 500ms base, 1.5x multiplier, capped at 5s. Max 20 attempts before marking as failed. Events are queued during disconnect and flushed after namespace rejoin. When not in a room, no reconnection occurs.

 > [!CAUTION]
 > **Identity Rule**: Differentiate between `peerId` and `socket.id`. Use `socket.id` exclusively for ephemeral transport routing on the server. Use `peerId` exclusively for identity, state management, and room tracking across the stack.
@@ -70,5 +71,5 @@ KoalaSync uses a megaphone routing approach to minimize server logic:
 To maintain a "Single Source of Truth" across the server and extension without using a bundler:
 - **Relay Server & Extension Modules**: `background.js` and `popup.js` import constants directly from `shared/constants.js`.
 - **Content Scripts**: To ensure zero-latency execution, `content.js` uses a synchronized copy of `EVENTS` and constants.
- **Automation**: The `node scripts/build-extension.js` script automatically injects these constants into `content.js` during the build process, eliminating the risk of manual mirror mismatch.
+- **Automation**: The `npm run build:extension` script automatically injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions into `content.js` during the build process, eliminating the risk of manual mirror mismatch.
 - **Verification**: Any protocol change is automatically propagated across the stack by running the build script.
@@ -4,6 +4,44 @@ All notable changes to the KoalaSync browser extension and relay server.

 ---

+## [v2.4.1] — 2026-06-19
+
+### Added
+- **Extension: Onboarding tour now has a closing step** — The first-run tour ends on a dedicated "You're all set!" card (the `ONBOARDING_5` copy that already existed in all 13 locales but was never shown). The tour no longer stops abruptly on the username step.
+- **Extension: One-click invite from the empty peer list** — The "No peers yet" state now shows a **📋 Invite Link** button that copies the invite link to the clipboard, so users can share it without hunting for the field.
+
+### Changed
+- **Extension: Cleaner onboarding welcome** — Step 1 is now a centered welcome card instead of spotlighting the logo title. Added a guard so target-less tour steps center cleanly.
+- **Website: Mobile comparison table** — The KoalaSync vs Teleparty table stacks into per-feature cards on phones instead of forcing horizontal scrolling; feature descriptions are shown again on mobile.
+
+### Fixed
+- **Extension: Onboarding step counter/progress placeholders** — Static `Step 1 of 3` / 33% fallbacks in `popup.html` corrected to match the actual 5-step tour (`Step 1 of 5` / 20%).
+- **Website: Mobile navigation restored** — The header hamburger menu was hidden by a `display:none !important` rule, leaving the nav links unreachable on phones. Re-enabled, with spacing kept comfortable down to ~320px.
+- **Website: Hero alignment on mobile** — A fixed-width extension mockup forced the hero grid column wider than the container, shifting all hero content off-center (larger left margin than right). The mockup is now responsive (`width:100%/max-width` + `minmax(0,1fr)` grid track).
+- **Website: Reveal-animation fallback** — Added a `<noscript>` style fallback and `IntersectionObserver` feature guards so scroll-revealed content can never stay invisible if JavaScript is disabled or unsupported.
+
+## [v2.4.0] — 2026-06-16
+
+### Added
+- **Extension: Lazy WebSocket connection** — The extension no longer maintains a permanent WebSocket connection to the relay server. Instead, the connection is established only when actively in a room or when the popup is opened with a saved room configuration. This improves privacy (IP is not exposed while idle), reduces battery/network usage, and prevents the server from tracking online status of inactive users. Automatic reconnect is guaranteed while in a room — zero behavior change during active sync sessions. See `connectIntent` flag in `background.js`.
+- **Extension: Episode title regex unification** — `extractEpisodeId()` had inconsistent regex patterns between `background.js` and `content.js`. The content script correctly matched Crunchyroll-style separators (`S01/E01`) while the service worker's stricter pattern (`[\s\-\.]*`) silently rejected them, causing episode lobby sync failures. Now unified to `[^a-zA-Z0-9]*` via shared `episode-utils.js`.
+- **Unit tests: `rate-limiter` and `episode-utils`** — 12 test groups for rate-limit functions and 30+ assertions for episode title parsing, covering all 6 separator types (dash, dot, slash, colon, comma, space). Run automatically via `npm run verify`.
+
+### Changed
+- **Server: Rate limiter extracted to `rate-limiter.js`** — 6 rate-limit functions, all rate-limit Maps, and cleanup intervals moved from `index.js` (149 lines). `index.js` now imports via facade pattern with re-exports for backward compatibility.
+- **Extension: Episode utilities extracted to `episode-utils.js`** — `extractEpisodeId()` and `sameEpisode()` deduplicated from `background.js` and `content.js`. The shared module is imported as an ES module by the service worker and injected into the content script IIFE by the build script.
+- **Build: `"type": "module"` in root `package.json`** — All scripts standardized to ESM (`.mjs`) or explicitly CommonJS (`.cjs`). Eliminated Node.js `MODULE_TYPELESS_PACKAGE_JSON` warnings.
+- **Build: 4 CJS scripts renamed to `.cjs`** — `build-extension.js`, `test-content-video-finder.js`, `test-locales.js`, `website/build.js`.
+
+### Fixed
+- **Server: npm audit resolved** — `ws` package vulnerability (CVE-2024-37890) fixed. Zero vulnerabilities in production dependencies.
+- **Pop-up: Connection status flicker fixed** — Removed hardcoded `disconnected` state on every pop-up open. Status now reflects actual background state from the first frame.
+- **Pop-up: Join button timeout improved** — No longer blindly re-enables after 15s. Polls connection status and extends window if still connecting.
+- **Pop-up: Validation failure state cleanup** — Custom server URL validation errors now properly reset `isProcessingConnection` and `joinBtnTimeout`.
+- **Extension: `WEB_JOIN_REQUEST` channel leak fixed** — Missing `sendResponse()` call when already in the target room.
+- **Extension: `LEAVE_ROOM` now clears `roomId` from storage** — Prevents phantom auto-reconnect on browser restart after explicit leave.
+- **Extension: Reconnect attempt counters reset on leave** — Prevents stale `reconnecting` status display after intentional disconnect.
+
 ## [v2.3.2] — 2026-06-16

 ### Changed
@@ -17,6 +55,9 @@ All notable changes to the KoalaSync browser extension and relay server.

 ## [v2.3.1] — 2026-06-15

+### Fixed
+- **Server: Concurrent peer join race condition and teardown error handling**
+
 ### Changed
 - **Server: Smart unhandled rejection handling (exits after 5/min instead of 1)**
 - **Server: Optimized admin health metrics allocation**
@@ -16,9 +16,9 @@ This guide walks through the complete user flow of KoalaSync, from creating a ro

 ## Step 2: Connecting to the Relay Server

-When you open the extension popup, the background service worker connects to the relay server:
+When you open the extension popup (with saved room credentials) or when a saved room configuration exists from a previous session, the background service worker connects to the relay server:

-1. **WebSocket Handshake**: `background.js` opens a WebSocket to `wss://syncserver.koalastuff.net/socket.io/?EIO=4&transport=websocket`.
+1. **WebSocket Handshake** (on demand): `background.js` opens a WebSocket to `wss://syncserver.koalastuff.net/socket.io/?EIO=4&transport=websocket` only when needed (popup opened or active room).
 2. **Security Checks** (server-side):
   - The server checks the client's **IP rate limit** (max 10 connections per 60 seconds).
   - The server validates the **authentication token** (hardcoded in `shared/constants.js`) to verify this is a legitimate KoalaSync client.
@@ -155,7 +155,7 @@ While in a room, two heartbeats keep the session alive:

 | Heartbeat | Interval | Source | Purpose |
 |:----------|:---------|:-------|:--------|
-| **Background** | 30 seconds | `background.js` | Signals "I'm still connected" and triggers aggressive reconnect (500ms base, max 5s) |
+| **Background** | 30 seconds | `background.js` | While connected, signals "I'm still connected" and triggers automatic reconnect (500ms base, max 5s). No heartbeats fire when idle (lazy connect). |
 | **Content** | 15 seconds | `content.js` | Sends video metadata: `currentTime`, `mediaTitle`, `playbackState`, `volume`, `muted` |

 - **Server Reaper**: Every 2 minutes, the server checks for peers with no activity for 5+ minutes and disconnects them ("dead peer pruning").
@@ -33,7 +33,7 @@ The browser extension requires the following permissions:
 - `storage`: To remember your local preferences (username, server URL, room settings).
 - `tabs` & `scripting`: To detect and control video elements on the pages you choose to sync.
 - `<all_urls>` (host permission): Required to detect `<video>` elements on any website the user chooses to synchronize. The extension only activates on the specific tab the user has actively selected — it does not scan, monitor, or interact with any other tabs or pages.
- `alarms`: To keep the background service worker alive during active sync sessions.
+- `alarms`: To keep the background service worker alive during active sync sessions (the extension only stays connected while you are in a room).
 - `notifications`: To display sync status updates (e.g., "Peer joined", "Force Sync initiated").
 - **No History Access**: We do not read, store, or transmit your browsing history. We only interact with the specific tab you have actively selected for synchronization.

@@ -79,12 +79,4 @@
 |---|---|
 | *(none yet)* | |

---

-## ✅ Completed
-
-*Shipped milestones.*
-
-| Feature | Shipped |
-|---|---|
-| *(none yet)* | |
@@ -17,13 +17,15 @@ You MUST run the build script in any of the following scenarios:

 Run the Node.js build script from the repository root:
 ```bash
-node scripts/build-extension.js
+node scripts/build-extension.cjs
+# or simply:
+npm run build:extension
 ```

 ## What does it do?
 The build script performs the following actions:
 1. Synchronizes protocol constants by copying `shared/constants.js`, `shared/blacklist.js`, and `shared/README.md` into `extension/shared/`.
-2. Injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` via marker-based replacement.
+2. Injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions (`extractEpisodeId`, `sameEpisode`) into `content.js` via marker-based replacement.
 3. Compiles browser-specific manifest files.
 4. Packages the final ready-to-publish extension artifacts for Chrome and Firefox into the `dist/` directory.

@@ -69,19 +69,19 @@ The website hosts the landing page and invitation bridge.
     "LANG_TOGGLE_TEXT": "EN"
   }
   ```
-5. If creating a **brand new language**, register it in `website/build.js` by adding it to the `languages` array.
+5. If creating a **brand new language**, register it in `website/build.cjs` by adding it to the `languages` array.

 ### Step 4: Verify Locally
 Ensure your JSON files are valid and all keys match the English baseline. Open your terminal in the KoalaSync root folder and run:
 ```bash
 # Tests the extension locales for missing keys or syntax errors
-node scripts/test-locales.js
+node scripts/test-locales.cjs

 # Tests the website locales for missing keys or syntax errors
 node scripts/test-website-locales.mjs

 # Builds the website with your new translations
-node website/build.js
+node website/build.cjs
 ```
 *Note: If you receive any errors about missing keys or `TODO` placeholders, please fix them before submitting.*

@@ -37,8 +37,10 @@ export default [
        URL: "readonly",
        URLSearchParams: "readonly",
        WebSocket: "readonly",
+        history: "readonly",
+        location: "readonly",
        self: "readonly",
-        process: "readonly"
+        process: "readonly",
      }
    },
    rules: {
@@ -56,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",
@@ -6,9 +6,9 @@ A Manifest V3 Browser Extension (Chrome & Firefox) for synchronized video playba
 - **Manifest V3**: Optimized Service Worker architecture with session persistence.
 - **Pure Vanilla JS**: No external dependencies or heavy libraries.
 - **Smart Peer IDs**: Hexadecimal IDs combined with customizable Usernames for easy identification.
- **Dual Heartbeat**: Advanced session tracking (Background) and video synchronization (Content) to prevent ghost sessions.
+- **On-Demand Connection**: The service worker only maintains a WebSocket connection while you're in a room. No persistent background connections — privacy-first architecture. Based on `connectIntent` flag that gates all reconnect attempts.
 - **Live Diagnostics**: Built-in "Dev" tab for real-time video state debugging (ReadyState, CurrentTime, etc.).
- **Dynamic i18n (Multi-Language)**: Fully localized in 6 languages (`en`, `de`, `fr`, `es`, `pt-BR`, `ru`) with auto-detected fallback and dynamic on-the-fly language selectors.
+- **Dynamic i18n (Multi-Language)**: Fully localized in 13 languages (`en`, `de`, `fr`, `es`, `it`, `pl`, `tr`, `nl`, `ja`, `ko`, `pt-BR`, `pt`, `ru`) with auto-detected fallback and dynamic on-the-fly language selectors.

 ## Tab Overview
 1. **Room**: Manage connections, view active peers, and share invitation links.
@@ -26,7 +26,7 @@ KoalaSync requires `<all_urls>` permission to detect and interact with video ele
 ## Installation
 1. **Prepare Extension**: From the repository root, run:
   ```bash
-   node scripts/build-extension.js
+   npm run build:extension
   ```
 2. Open Chrome and go to `chrome://extensions/`.
 3. Enable **Developer mode** (top right).
@@ -35,6 +35,18 @@ KoalaSync requires `<all_urls>` permission to detect and interact with video ele
 ## Development
 If you modify `shared/constants.js`, you must synchronize the changes by running the build script from the root:
 ```bash
-node scripts/build-extension.js
+npm run build:extension
 ```
 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 |
@@ -1,10 +1,17 @@
 import { EVENTS, PROTOCOL_VERSION, OFFICIAL_SERVER_URL, OFFICIAL_SERVER_TOKEN, EPISODE_LOBBY_TIMEOUT, FORCE_SYNC_TIMEOUT } from './shared/constants.js';
 import { generateUsername } from './shared/names.js';
 import { loadLocale, getMessage, getSystemLanguage } from './i18n.js';
+import { sameEpisode } from './episode-utils.js';

 // --- Uninstall URL Initialization ---
-chrome.runtime.onInstalled.addListener((details) => {
-    if (details.reason === 'install' || details.reason === 'update') {
+let uninstallURLInitPromise = null;
+
+async function initUninstallURL() {
+    if (uninstallURLInitPromise) {
+        return uninstallURLInitPromise;
+    }
+    
+    uninstallURLInitPromise = (async () => {
        // --- UNINSTALL_URL_INJECT_START ---
        const UNINSTALL_URL = ""; // Populated during build
        const BROWSER_TYPE = "unknown";
@@ -12,8 +19,24 @@ chrome.runtime.onInstalled.addListener((details) => {
        
        if (UNINSTALL_URL && UNINSTALL_URL.trim() !== '') {
            try {
+                if (typeof chrome === 'undefined' || !chrome.storage || !chrome.storage.local) {
+                    console.warn("Storage API not available, skipping uninstall URL token generation");
+                    return;
+                }
+
+                const data = await chrome.storage.local.get("koalaByeToken");
+                let token = data?.koalaByeToken;
+                
+                if (!token) {
+                    token = (typeof self.crypto !== 'undefined' && typeof self.crypto.randomUUID === 'function')
+                        ? self.crypto.randomUUID()
+                        : Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+                    await chrome.storage.local.set({ koalaByeToken: token });
+                }
+
                const url = new URL(UNINSTALL_URL);
                url.searchParams.set("browser", BROWSER_TYPE);
+                url.searchParams.set("t", token);
                
                const runtimeAPI = typeof browser !== 'undefined' ? browser.runtime : chrome.runtime;
                if (runtimeAPI && runtimeAPI.setUninstallURL) {
@@ -24,12 +47,24 @@ chrome.runtime.onInstalled.addListener((details) => {
                    }
                }
            } catch (err) {
-                console.error("Invalid uninstall URL provided:", err);
+                console.error("Failed to initialize uninstall URL:", err);
            }
        }
+    })();
+
+    return uninstallURLInitPromise;
+}
+
+chrome.runtime.onInstalled.addListener((details) => {
+    if (details.reason === 'install' || details.reason === 'update') {
+        initUninstallURL();
    }
 });

+chrome.runtime.onStartup.addListener(() => {
+    initUninstallURL();
+});
+
 // --- State Management ---
 let socket = null;
 let isConnecting = false;
@@ -176,6 +211,7 @@ let reconnectAttempts = 0;
 let currentServerUrl = null;
 let roomIdleSince = null;
 let lastContentHeartbeatAt = null;
+let connectIntent = false;
 const MAX_RECONNECT_ATTEMPTS = 20;
 const _RECONNECT_BASE_DELAY = 500;
 const _RECONNECT_MAX_DELAY = 5000;
@@ -190,26 +226,6 @@ let forceSyncTimeout = null;
 let episodeLobby = null; // { expectedTitle, initiatorPeerId, readyPeers: [], createdAt }
 let episodeLobbyTimeout = null;

-// --- Episode Title Extraction (synced with content.js) ---
-function extractEpisodeId(title) {
-    if (!title || typeof title !== 'string') return null;
-    const se = title.match(/S(?:eason\s*)?(\d+)[\s\-\.]*E(?:pisode\s*)?(\d+)/i);
-    if (se) return `S${String(se[1]).padStart(2, '0')}E${String(se[2]).padStart(2, '0')}`;
-    const ep = title.match(/(?:Episode|Folge|Ep\.?|#)\s*(\d+)/i);
-    if (ep) return `EP${String(ep[1]).padStart(3, '0')}`;
-    return null;
-}
-
-function sameEpisode(titleA, titleB) {
-    if (!titleA && !titleB) return true; // Both unknown → assume same (backward compat)
-    if (!titleA || !titleB) return false; // One unknown, one known → different
-    const idA = extractEpisodeId(titleA);
-    const idB = extractEpisodeId(titleB);
-    if (idA && idB) return idA === idB; // Both have parseable IDs → compare IDs
-    if (idA || idB) return false;       // One has ID, other doesn't → different
-    return titleA === titleB;            // Neither has ID → exact string match
-}
-
 // --- Storage Utils ---

 /**
@@ -404,7 +420,12 @@ function clearTargetTabForIdle() {

 async function leaveRoomAfterIdleGrace(reason) {
    if (!currentRoom) return;
+    connectIntent = false;
+    reconnectFailed = false;
+    reconnectAttempts = 0;
+    chrome.storage.session.set({ reconnectFailed: false, reconnectAttempts: 0, reconnectStartTime: null });
    emit(EVENTS.LEAVE_ROOM, { peerId });
+    forceDisconnect();
    currentRoom = null;
    currentTabId = null;
    currentTabTitle = null;
@@ -457,7 +478,9 @@ async function connect() {
            addLog('Browser is offline. Waiting...', 'warn');
            broadcastConnectionStatus('offline');
            isConnecting = false;
-            scheduleReconnect();
+            if (currentRoom || connectIntent) {
+                scheduleReconnect();
+            }
            return;
        }

@@ -564,25 +587,32 @@ async function connect() {
            isNamespaceJoined = false;
            stopPing();
            
-            isForceSyncInitiator = false;
-            forceSyncAcks.clear();
-            if (forceSyncTimeout) clearTimeout(forceSyncTimeout);
-            chrome.storage.session.set({ 
-                isForceSyncInitiator: false, 
-                forceSyncAcks: [], 
-                forceSyncDeadline: null 
-            }).catch(() => {});
+            if (!connectIntent && !currentRoom) {
+                isForceSyncInitiator = false;
+                forceSyncAcks.clear();
+                if (forceSyncTimeout) clearTimeout(forceSyncTimeout);
+                chrome.storage.session.set({ 
+                    isForceSyncInitiator: false, 
+                    forceSyncAcks: [], 
+                    forceSyncDeadline: null 
+                }).catch(() => {});
+            }

            
-            if (currentRoom) {
+            if (currentRoom && !connectIntent) {
                currentRoom.peers = [];
                if (storageInitialized) chrome.storage.session.set({ currentRoom }).catch(() => {});
                chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: [] }).catch(() => {});
            }
            broadcastConnectionStatus('disconnected');
-            addLog('Disconnected. Scheduling reconnect...', 'warn');
-            socket = null;
-            scheduleReconnect();
+            if (currentRoom || connectIntent) {
+                addLog('Disconnected. Scheduling reconnect...', 'warn');
+                socket = null;
+                scheduleReconnect();
+            } else {
+                addLog('Disconnected. No active session — staying disconnected.', 'info');
+                socket = null;
+            }
        };

        socket.onerror = () => {
@@ -597,7 +627,9 @@ async function connect() {
        const errMsg = (e && e.message) ? e.message : String(e || 'Unknown connection error');
        addLog(errMsg, logType);
        broadcastConnectionStatus('disconnected');
-        scheduleReconnect();
+        if (currentRoom || connectIntent) {
+            scheduleReconnect();
+        }
    }
 }

@@ -738,6 +770,9 @@ function sendPing() {
            addLog('Ping timeout reached, force disconnecting to trigger reconnect', 'warn');
            pendingPingT = null;
            forceDisconnect();
+            if (currentRoom || connectIntent) {
+                scheduleReconnect();
+            }
        }
        pingTimeout = null;
    }, 5000);
@@ -836,6 +871,14 @@ function handleServerEvent(event, data) {
            break;
        case EVENTS.ERROR:
            isConnecting = false;
+            // If we get a server error before successfully joining a room,
+            // clear connectIntent to prevent an infinite reconnect loop.
+            if (!currentRoom) {
+                connectIntent = false;
+                if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+                reconnectAttempts = 0;
+                reconnectFailed = false;
+            }
            broadcastConnectionStatus('disconnected');
            addLog(`Server Error: ${data.message}`, 'error');
            chrome.storage.local.get(['browserNotifications', 'locale'], async (settings) => {
@@ -1334,7 +1377,7 @@ chrome.alarms.onAlarm.addListener(async (alarm) => {
    if (alarm.name === 'keepAlive') {
        chrome.storage.session.get('keepAlive', () => {});
        if (!socket || socket.readyState !== WebSocket.OPEN) {
-            if (!reconnectFailed) {
+            if (!reconnectFailed && (currentRoom || connectIntent)) {
                connect();
            }
        } else if (currentRoom) {
@@ -1417,6 +1460,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {

    if (message.type === 'CONNECT') {
        const settings = await getSettings();
+        connectIntent = !!settings.roomId;
        const desiredUrl = resolveServerUrl(settings);

        if (settings.roomId && currentRoom && currentRoom.roomId === settings.roomId && socket && socket.readyState === WebSocket.OPEN && isNamespaceJoined && desiredUrl === currentServerUrl) {
@@ -1439,7 +1483,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
        }
        if (desiredUrl !== currentServerUrl || !socket || socket.readyState !== WebSocket.OPEN || !isNamespaceJoined) {
            if (desiredUrl !== currentServerUrl) forceDisconnect();
-            connect();
+            if (settings.roomId) connect();
        } else if (settings.roomId) {
            emit(EVENTS.JOIN_ROOM, { 
                roomId: settings.roomId, 
@@ -1452,6 +1496,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
        }
        sendResponse({ status: 'ok' });
    } else if (message.type === 'RETRY_CONNECT') {
+        connectIntent = true;
        reconnectFailed = false;
        reconnectStartTime = null;
        reconnectAttempts = 0;
@@ -1480,6 +1525,10 @@ async function handleAsyncMessage(message, sender, sendResponse) {
            ping: currentPingMs
        });
    } else if (message.type === 'LEAVE_ROOM') {
+        connectIntent = false;
+        reconnectFailed = false;
+        reconnectAttempts = 0;
+        chrome.storage.session.set({ reconnectFailed: false, reconnectAttempts: 0, reconnectStartTime: null });
        resetAudioProcessingInTab(currentTabId);
        emit(EVENTS.LEAVE_ROOM, { peerId });
        currentRoom = null;
@@ -1510,8 +1559,10 @@ async function handleAsyncMessage(message, sender, sendResponse) {
            episodeLobby: null,
            expectedAcksCount: 0
        });
+        chrome.storage.local.set({ roomId: '', password: '' }).catch(() => {});
        addLog('Left Room', 'info');
        chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: [] }).catch(() => {});
+        forceDisconnect();
        sendResponse({ status: 'ok' });
    } else if (message.type === 'CLEAR_LOGS') {
        logs = [];
@@ -1526,6 +1577,16 @@ async function handleAsyncMessage(message, sender, sendResponse) {
    } else if (message.type === 'WEB_JOIN_REQUEST') {
        const { roomId: rawRoomId, password, useCustomServer, serverUrl } = message;
        const roomId = typeof rawRoomId === 'string' ? rawRoomId.replace(/[^a-zA-Z0-9\-]/g, '') : '';
+        if (!roomId) {
+            const errMsg = { type: 'JOIN_STATUS', success: false, message: 'Invalid room ID' };
+            chrome.runtime.sendMessage(errMsg).catch(() => {});
+            chrome.tabs.query({}, (tabs) => {
+                tabs.forEach(tab => chrome.tabs.sendMessage(tab.id, errMsg).catch(() => {}));
+            });
+            sendResponse({ status: 'invalid_room_id' });
+            return;
+        }
+        connectIntent = true;
        chrome.storage.local.set({ 
            roomId, 
            password,
@@ -1541,6 +1602,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
                for (const tab of tabs) {
                    chrome.tabs.sendMessage(tab.id, { type: 'JOIN_STATUS', success: true, message: 'Already in room' }).catch(() => {});
                }
+                sendResponse({ status: 'already_joined' });
                return;
            }

@@ -1554,7 +1616,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
            if (desiredUrl !== currentServerUrl || !socket || socket.readyState !== WebSocket.OPEN || !isNamespaceJoined) {
                if (desiredUrl !== currentServerUrl) forceDisconnect();
                connect();
-            } else {
+            } else if (roomId) {
                emit(EVENTS.JOIN_ROOM, { 
                    roomId, 
                    password,
@@ -1939,5 +2001,8 @@ chrome.tabs.onUpdated.addListener(async (tabId, changeInfo, _tab) => {
    }
 });

-// Initial Connect
-connect();
+// Initial Connect — only if user has an active room configuration
+getSettings().then(settings => {
+    connectIntent = !!settings.roomId;
+    if (connectIntent) connect();
+}).catch(() => connectIntent = false);
@@ -290,28 +290,27 @@
    // Extract a canonical episode identifier from a title string.
    // Handles: S01E01, S1E1, S01 - E01, Season 1 Episode 1, "Folge 5", "Episode 5", "Ep. 5", "#5"
    // Returns null if no episode pattern found.
+    // --- SHARED_EPISODE_UTILS_INJECT_START ---
+    // This block is automatically replaced by /scripts/build-extension.js
    function extractEpisodeId(title) {
        if (!title || typeof title !== 'string') return null;
-        // S01E01 patterns (with any non-alphanumeric separator between season and E)
        const se = title.match(/S(?:eason\s*)?(\d+)[^a-zA-Z0-9]*E(?:pisode\s*)?(\d+)/i);
        if (se) return `S${String(se[1]).padStart(2, '0')}E${String(se[2]).padStart(2, '0')}`;
-        // "Episode X", "Folge X", "Ep. X", "#X"
        const ep = title.match(/(?:Episode|Folge|Ep\.?|#)\s*(\d+)/i);
        if (ep) return `EP${String(ep[1]).padStart(3, '0')}`;
        return null;
    }

-    // Returns true if two titles likely refer to the same episode.
-    // Strict: both must have IDs and match, OR neither has IDs and exact match.
    function sameEpisode(titleA, titleB) {
-        if (!titleA && !titleB) return true; // Both unknown → assume same (backward compat)
-        if (!titleA || !titleB) return false; // One unknown, one known → different
+        if (!titleA && !titleB) return true;
+        if (!titleA || !titleB) return false;
        const idA = extractEpisodeId(titleA);
        const idB = extractEpisodeId(titleB);
-        if (idA && idB) return idA === idB; // Both have parseable IDs → compare IDs
-        if (idA || idB) return false;       // One has ID, other doesn't → different
-        return titleA === titleB;            // Neither has ID → exact string match
+        if (idA && idB) return idA === idB;
+        if (idA || idB) return false;
+        return titleA === titleB;
    }
+    // --- SHARED_EPISODE_UTILS_INJECT_END ---

    // Returns true only when we are CERTAIN the episodes differ.
    // Permissive: only blocks if BOTH titles have parseable IDs AND they differ.
@@ -0,0 +1,24 @@
+/**
+ * KoalaSync Episode Title Utilities
+ * Single source of truth — synced to content.js by build-extension.js.
+ * Keep in sync with the injection block in content.js!
+ */
+
+export function extractEpisodeId(title) {
+    if (!title || typeof title !== 'string') return null;
+    const se = title.match(/S(?:eason\s*)?(\d+)[^a-zA-Z0-9]*E(?:pisode\s*)?(\d+)/i);
+    if (se) return `S${String(se[1]).padStart(2, '0')}E${String(se[2]).padStart(2, '0')}`;
+    const ep = title.match(/(?:Episode|Folge|Ep\.?|#)\s*(\d+)/i);
+    if (ep) return `EP${String(ep[1]).padStart(3, '0')}`;
+    return null;
+}
+
+export function sameEpisode(titleA, titleB) {
+    if (!titleA && !titleB) return true;
+    if (!titleA || !titleB) return false;
+    const idA = extractEpisodeId(titleA);
+    const idB = extractEpisodeId(titleB);
+    if (idA && idB) return idA === idB;
+    if (idA || idB) return false;
+    return titleA === titleB;
+}
@@ -2,7 +2,7 @@
  "manifest_version": 3,
  "default_locale": "en",
  "name": "KoalaSync",
-  "version": "2.3.1",
+  "version": "2.4.1",
  "description": "Synchronize video playback on YouTube, Netflix, Emby, Jellyfin, and any HTML5 site in real-time with friends.",
  "permissions": [
    "storage",
@@ -659,14 +659,14 @@
        <div id="onboarding-card" style="position:fixed; background:var(--card); padding:16px 20px; border-radius:12px; width:280px; box-shadow:0 8px 32px rgba(0,0,0,0.5); z-index:1002; transition:all 0.3s cubic-bezier(0.4, 0, 0.2, 1); box-sizing:border-box; border:1px solid #334155; opacity:0; transform: scale(0.9); display:none;">
            <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:8px;">
                <span id="onboarding-icon" style="font-size:24px;">👋</span>
-                <span id="onboarding-step-indicator" style="font-size:10px; font-weight:700; color:var(--accent); text-transform:uppercase; letter-spacing:0.5px;">Step 1 of 3</span>
+                <span id="onboarding-step-indicator" style="font-size:10px; font-weight:700; color:var(--accent); text-transform:uppercase; letter-spacing:0.5px;">Step 1 of 5</span>
            </div>
            <h2 id="onboarding-title" style="color:var(--accent); margin:0 0 6px; font-size:14px; font-weight:700; text-align:left;">Welcome to KoalaSync!</h2>
            <p id="onboarding-text" style="color:var(--text-muted); font-size:12px; margin:0 0 16px; line-height:1.4; text-align:left;">Let's get you started.</p>
            
            <!-- Progress Bar -->
            <div id="onboarding-progress-container" style="height:4px; background:#334155; border-radius:2px; margin-bottom:16px; overflow:hidden;">
-                <div id="onboarding-progress-bar" style="height:100%; width:33%; background:var(--accent); transition:width 0.3s ease;"></div>
+                <div id="onboarding-progress-bar" style="height:100%; width:20%; background:var(--accent); transition:width 0.3s ease;"></div>
            </div>
            
            <div style="display:flex; gap:8px; justify-content:space-between; align-items:center;">
@@ -237,8 +237,7 @@ async function init() {
    refreshLogs();
    refreshHistory();

-    // Default connection status (localized) before async check
-    applyConnectionStatus('disconnected');
+    // Initial Status Check (status shows via GET_STATUS below)

    // Initial Status Check
    chrome.runtime.sendMessage({ type: 'GET_STATUS' }, async (res) => {
@@ -255,6 +254,13 @@ async function init() {
            updatePeerList(res.peers);
            lastKnownPeers = res.peers || [];
            if (res.lastActionState) updateLastActionUI(res.lastActionState, res.peers);
+
+            // If user has a room configured but background is not connected,
+            // trigger connection now — the popup opening is explicit user intent.
+            if (res.status === 'disconnected' && localData.roomId) {
+                chrome.runtime.sendMessage({ type: 'CONNECT' }).catch(() => {});
+                applyConnectionStatus('connecting');
+            }
            
            // Populate Tabs using the background's targetTabId
            await populateTabs(res.peers, res.targetTabId);
@@ -497,6 +503,24 @@ function renderEmpty(container, type) {
    wrapper.appendChild(iconDiv);
    wrapper.appendChild(titleDiv);
    wrapper.appendChild(hintDiv);
+
+    // "No peers yet" — turn the hint into a one-click action so the user can
+    // immediately copy and share the invite link instead of hunting for it.
+    if (type === 'peers' && elements.inviteLink && elements.inviteLink.value) {
+        const copyBtn = document.createElement('button');
+        copyBtn.type = 'button';
+        copyBtn.className = 'primary';
+        copyBtn.style.cssText = 'display:inline-block; width:auto; margin-top:12px; padding:6px 14px; font-size:11px;';
+        copyBtn.textContent = getMessage('BTN_COPY_INVITE');
+        copyBtn.title = getMessage('BTN_COPY_INVITE_TOOLTIP');
+        copyBtn.addEventListener('click', () => {
+            navigator.clipboard.writeText(elements.inviteLink.value)
+                .then(() => showToast(getMessage('TOAST_INVITE_COPIED'), 'success', 2000))
+                .catch(() => showToast(getMessage('TOAST_COPY_FAILED'), 'error'));
+        });
+        wrapper.appendChild(copyBtn);
+    }
+
    container.replaceChildren(wrapper);
 }

@@ -1195,11 +1219,23 @@ elements.joinBtn.addEventListener('click', async () => {
    
    if (joinBtnTimeout) clearTimeout(joinBtnTimeout);
    joinBtnTimeout = setTimeout(() => {
-        elements.joinBtn.disabled = false;
-        elements.joinBtn.textContent = getMessage('BTN_JOIN_ROOM');
-        joinBtnTimeout = null;
-        isProcessingConnection = false;
-        showError(getMessage('ERR_CONN_TIMEOUT'));
+        chrome.runtime.sendMessage({ type: 'GET_STATUS' }, (res) => {
+            if (res && res.status === 'connecting') {
+                joinBtnTimeout = setTimeout(() => {
+                    elements.joinBtn.disabled = false;
+                    elements.joinBtn.textContent = getMessage('BTN_JOIN_ROOM');
+                    joinBtnTimeout = null;
+                    isProcessingConnection = false;
+                    showError(getMessage('ERR_CONN_TIMEOUT'));
+                }, 15000);
+                return;
+            }
+            elements.joinBtn.disabled = false;
+            elements.joinBtn.textContent = getMessage('BTN_JOIN_ROOM');
+            joinBtnTimeout = null;
+            isProcessingConnection = false;
+            if (res && res.status !== 'connected') showError(getMessage('ERR_CONN_TIMEOUT'));
+        });
    }, 15000);
    
    const serverUrl = elements.serverUrl.value.trim();
@@ -1210,6 +1246,8 @@ elements.joinBtn.addEventListener('click', async () => {
        showError(getMessage('ERR_INVALID_SERVER_URL'));
        elements.joinBtn.disabled = false;
        elements.joinBtn.textContent = getMessage('BTN_JOIN_ROOM');
+        if (joinBtnTimeout) { clearTimeout(joinBtnTimeout); joinBtnTimeout = null; }
+        isProcessingConnection = false;
        return;
    }
    if (useCustom && serverUrl) {
@@ -1220,6 +1258,7 @@ elements.joinBtn.addEventListener('click', async () => {
            showError(getMessage('ERR_INVALID_SERVER_URL'));
            elements.joinBtn.disabled = false;
            elements.joinBtn.textContent = getMessage('BTN_JOIN_ROOM');
+            if (joinBtnTimeout) { clearTimeout(joinBtnTimeout); joinBtnTimeout = null; }
            isProcessingConnection = false;
            return;
        }
@@ -1608,6 +1647,9 @@ chrome.runtime.onMessage.addListener((msg) => {
        updatePeerList(msg.peers);
        if (msg.peers) detectPeerChanges(msg.peers);
    } else if (msg.type === 'CONNECTION_STATUS') {
+        if (msg.status === 'connected' || msg.status === 'disconnected') {
+            if (joinBtnTimeout) { clearTimeout(joinBtnTimeout); joinBtnTimeout = null; }
+        }
        if (msg.status === 'connected') {
            clearConnectionErrorTimer();
        }
@@ -2095,9 +2137,9 @@ const onboardingSteps = [
    { 
        icon: '👋', 
        get title() { return getMessage('ONBOARDING_1_TITLE'); }, 
-        get text() { return getMessage('ONBOARDING_1_TEXT'); }, 
+        get text() { return getMessage('ONBOARDING_1_TEXT'); },
        targetTab: 'tab-room',
-        targetSelector: 'h1'
+        targetSelector: null
    },
    { 
        icon: '🏠', 
@@ -2116,9 +2158,16 @@ const onboardingSteps = [
    { 
        icon: '⚙️', 
        get title() { return getMessage('ONBOARDING_4_TITLE'); }, 
-        get text() { return getMessage('ONBOARDING_4_TEXT'); }, 
+        get text() { return getMessage('ONBOARDING_4_TEXT'); },
        targetTab: 'tab-settings',
        targetSelector: '#username'
+    },
+    {
+        icon: '🍿',
+        get title() { return getMessage('ONBOARDING_5_TITLE'); },
+        get text() { return getMessage('ONBOARDING_5_TEXT'); },
+        targetTab: 'tab-room',
+        targetSelector: null
    }
 ];

@@ -2292,7 +2341,7 @@ function renderOnboardingStep() {
    }

    onboardingTimeout = setTimeout(() => {
-        const targetEl = document.querySelector(step.targetSelector);
+        const targetEl = step.targetSelector ? document.querySelector(step.targetSelector) : null;
        if (targetEl && targetEl.offsetParent !== null) {
            positionSpotlightAndCard(targetEl);
        } else {
@@ -1,10 +1,11 @@
 {
  "name": "koalasync",
-  "version": "2.3.1",
+  "version": "2.4.1",
  "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"
@@ -2,7 +2,7 @@

 This directory contains utility scripts for the KoalaSync development workflow.

-## build-extension.js
+## build-extension.cjs

 The primary build tool for KoalaSync. This Node.js script automates two critical tasks:

@@ -15,7 +15,7 @@ The primary build tool for KoalaSync. This Node.js script automates two critical
 From the **repository root**, run:

 ```bash
-node scripts/build-extension.js
+node scripts/build-extension.cjs
 ```

 ### Why this script exists
@@ -77,7 +77,7 @@ function copyExtensionFiles(targetDir, browserName) {
        const eStart = '// --- SHARED_EVENTS_INJECT_START ---';
        const eEnd = '// --- SHARED_EVENTS_INJECT_END ---';
        const ePattern = new RegExp(`${eStart}[\\s\\S]+?${eEnd}`);
-        const eRep = `${eStart}\n    // This block is automatically updated by /scripts/build-extension.js\n    const EVENTS = ${eventsObject};\n    ${eEnd}`;
+        const eRep = `${eStart}\n    // This block is automatically updated by /scripts/build-extension.cjs\n    const EVENTS = ${eventsObject};\n    ${eEnd}`;
        
        if (ePattern.test(content)) {
          content = content.replace(ePattern, eRep);
@@ -97,6 +97,25 @@ function copyExtensionFiles(targetDir, browserName) {
          console.warn('⚠️ WARNING: Heartbeat markers not found in content.js');
        }

+        // 3. Inject Episode Utils
+        const euStart = '// --- SHARED_EPISODE_UTILS_INJECT_START ---';
+        const euEnd = '// --- SHARED_EPISODE_UTILS_INJECT_END ---';
+        const euPattern = new RegExp(euStart.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '[\\s\\S]+?' + euEnd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const euPath = path.join(rootDir, 'extension', 'episode-utils.js');
+        if (fs.existsSync(euPath)) {
+          const euContent = fs.readFileSync(euPath, 'utf8');
+          const stripped = euContent
+            .replace(/^\/\*\*[\s\S]*?\*\/\s*/m, '')
+            .replace(/export function /g, 'function ')
+            .trim();
+          const euRep = `${euStart}\n    // This block is automatically updated by /scripts/build-extension.cjs\n${stripped.split('\n').map(l => '    ' + l).join('\n')}\n    ${euEnd}`;
+          if (euPattern.test(content)) {
+            content = content.replace(euPattern, euRep);
+          } else {
+            console.warn('⚠ WARNING: Episode utils markers not found in content.js');
+          }
+        }
+
        fs.writeFileSync(destPath, content);
        console.log('✓ Injected shared constants into content.js');
      } else if (item === 'background.js') {
@@ -108,7 +127,7 @@ function copyExtensionFiles(targetDir, browserName) {
        const uPattern = new RegExp(`${uStart}[\\s\\S]+?${uEnd}`);
        const placeholderUrl = "https://bye.koalastuff.net/c/camp_99ztjRVbK1BNN2RU";
        
-        let uRep = `${uStart}\n        // This block is automatically updated by /scripts/build-extension.js\n`;
+        let uRep = `${uStart}\n        // This block is automatically updated by /scripts/build-extension.cjs\n`;
        uRep += `        const UNINSTALL_URL = "${placeholderUrl}";\n`;
        uRep += `        const BROWSER_TYPE = "${browserName}";\n`;
        uRep += `        ${uEnd}`;
@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { extractEpisodeId, sameEpisode } from '../extension/episode-utils.js';
+
+// --- extractEpisodeId ---
+
+// Standard SxxExx patterns
+assert.equal(extractEpisodeId('S01E01'), 'S01E01');
+assert.equal(extractEpisodeId('S1E1'), 'S01E01');
+assert.equal(extractEpisodeId('s01e01'), 'S01E01', 'case insensitive');
+assert.equal(extractEpisodeId('Season 1 Episode 2'), 'S01E02');
+assert.equal(extractEpisodeId('season 01 episode 02'), 'S01E02');
+
+// Separators: dash, dot, slash, colon, space, comma
+assert.equal(extractEpisodeId('S01 - E01'), 'S01E01', 'dash separator');
+assert.equal(extractEpisodeId('S01.E01'), 'S01E01', 'dot separator');
+assert.equal(extractEpisodeId('S01/E01'), 'S01E01', 'slash separator (Crunchyroll)');
+assert.equal(extractEpisodeId('S01:E01'), 'S01E01', 'colon separator');
+assert.equal(extractEpisodeId('S01,E01'), 'S01E01', 'comma separator');
+assert.equal(extractEpisodeId('S01 E01'), 'S01E01', 'space separator');
+
+// German / multi-language
+assert.equal(extractEpisodeId('Folge 5'), 'EP005');
+assert.equal(extractEpisodeId('Episode 12'), 'EP012');
+assert.equal(extractEpisodeId('Ep. 3'), 'EP003');
+assert.equal(extractEpisodeId('#42'), 'EP042');
+
+// Edge cases
+assert.equal(extractEpisodeId(null), null);
+assert.equal(extractEpisodeId(undefined), null);
+assert.equal(extractEpisodeId(''), null);
+assert.equal(extractEpisodeId(123), null);
+assert.equal(extractEpisodeId('Some Movie Title'), null);
+assert.equal(extractEpisodeId('Breaking Bad'), null);
+
+// Leading zeros preserved
+assert.equal(extractEpisodeId('S01E001'), 'S01E001');
+
+// --- sameEpisode ---
+
+// Identical episodes
+assert.equal(sameEpisode('S01E01', 'S01E01'), true);
+assert.equal(sameEpisode('S01E01 - Pilot', 'S01E01'), true, 'extra text ignored');
+assert.equal(sameEpisode('Folge 5', 'Episode 5'), true, 'German vs English');
+
+// Different episodes
+assert.equal(sameEpisode('S01E01', 'S01E02'), false);
+assert.equal(sameEpisode('Folge 1', 'Folge 2'), false);
+assert.equal(sameEpisode('S01E01', 'S02E01'), false);
+
+// Both unknown → assume same (backward compat)
+assert.equal(sameEpisode(null, null), true);
+assert.equal(sameEpisode(undefined, undefined), true);
+assert.equal(sameEpisode('', ''), true);
+assert.equal(sameEpisode('Some Movie', 'Some Movie'), true);
+assert.equal(sameEpisode('Some Movie', 'Other Movie'), false, 'different unknowns differ');
+
+// One unknown, one known → different
+assert.equal(sameEpisode('S01E01', null), false);
+assert.equal(sameEpisode(null, 'Episode 5'), false);
+assert.equal(sameEpisode(undefined, 'S01E01'), false);
+
+// Mixed formats — only match when the same episode
+assert.equal(sameEpisode('S01E05', 'S01E05'), true, 'same SxxExx');
+assert.equal(sameEpisode('Folge 5', 'Episode 5'), true, 'German Folge vs English Episode');
+assert.equal(sameEpisode('Episode 12', 'Ep. 12'), true, 'Episode X vs Ep. X');
+assert.equal(sameEpisode('#42', 'Folge 42'), true, '#X vs Folge X');
+
+// Different format IDs → different (season-tagged vs seasonless)
+assert.equal(sameEpisode('S01E05', 'Episode 5'), false, 'SxxExx vs Episode X: different IDs');
+assert.equal(sameEpisode('S01E01', 'EP001'), false, 'SxxExx vs EPxxx: different IDs');
+
+// parseable but truly different
+assert.equal(sameEpisode('S01E01', 'S01E02'), false, 'different episodes');
+assert.equal(sameEpisode('S01E01', 'S02E01'), false, 'different seasons');
+
+console.log('episode-utils tests passed');
@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { getAvatarForName, generateUsername, USERNAME_ADJECTIVES, USERNAME_NOUNS } from '../shared/names.js';
+
+// --- getAvatarForName (deterministic) ---
+
+// Exact matches
+assert.equal(getAvatarForName('Koala'), '🐨', 'Koala');
+assert.equal(getAvatarForName('Tiger'), '🐯', 'Tiger');
+assert.equal(getAvatarForName('Panda'), '🐼', 'Panda');
+assert.equal(getAvatarForName('Fox'), '🦊', 'Fox');
+
+// Case insensitive
+assert.equal(getAvatarForName('koala'), '🐨', 'lowercase');
+assert.equal(getAvatarForName('MyKoalaUser'), '🐨', 'embedded uppercase');
+
+// Longest match wins (caterpillar > cat)
+assert.equal(getAvatarForName('CaterpillarCat'), '🐛', 'caterpillar before cat');
+assert.equal(getAvatarForName('Cat'), '🐱', 'cat alone');
+
+// Emoji with ZWJ sequences (multi-codepoint)
+assert.equal(getAvatarForName('Polar'), '🐻\u200D❄️', 'polar bear ZWJ');
+assert.equal(getAvatarForName('Crow'), '🐦\u200D⬛', 'crow ZWJ');
+
+// Human-like characters
+assert.equal(getAvatarForName('Ninja'), '🥷', 'ninja');
+assert.equal(getAvatarForName('Wizard'), '🧙', 'wizard');
+assert.equal(getAvatarForName('Pirate'), '🏴', 'pirate');
+assert.equal(getAvatarForName('Alien'), '👾', 'alien');
+assert.equal(getAvatarForName('Robot'), '🤖', 'robot');
+
+// Fallback
+assert.equal(getAvatarForName(''), '👤', 'empty string');
+assert.equal(getAvatarForName('Xyzzy123'), '👤', 'unknown name');
+assert.equal(getAvatarForName(null), '👤', 'null');
+assert.equal(getAvatarForName(undefined), '👤', 'undefined');
+
+// --- generateUsername (format check) ---
+for (let i = 0; i < 10; i++) {
+    const name = generateUsername();
+    // Format: AdjectiveNoun (e.g. "HappyKoala")
+    assert.ok(/^[A-Z][a-z]+[A-Z][a-z]+$/.test(name), `format: ${name}`);
+    // Adjective from list
+    const adj = USERNAME_ADJECTIVES.some(a => name.startsWith(a));
+    assert.ok(adj, `adjective from list: ${name}`);
+    // Noun from list
+    const noun = USERNAME_NOUNS.some(n => name.endsWith(n));
+    assert.ok(noun, `noun from list: ${name}`);
+}
+
+// Every noun has an emoji (no broken usernames)
+for (const noun of USERNAME_NOUNS) {
+    const avatar = getAvatarForName(noun);
+    assert.notEqual(avatar, '👤', `noun "${noun}" has no emoji — add to ANIMAL_EMOJI_MAP`);
+}
+
+console.log('names tests passed');
@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import {
+    checkConnectionRate,
+    checkEventRate,
+    checkHealthRate,
+    checkAdminMetricsAuthRate,
+    checkAuthRate,
+    recordAuthFailure,
+    clearRateLimitMaps,
+    connectionCounts,
+    failedAuthAttempts,
+    eventCounts,
+    healthCounts,
+    adminMetricsAuthCounts,
+    roomListCooldowns,
+    rateLimitDenied,
+    startRateLimitCleanup,
+    stopRateLimitCleanup
+} from '../server/rate-limiter.js';
+
+// Helper: mock io for cleanup
+const mockIo = { sockets: { sockets: new Map() } };
+
+// Reset state before each test group
+function reset() {
+    clearRateLimitMaps();
+    Object.assign(rateLimitDenied, { connections: 0, events: 0, health: 0, adminMetricsAuth: 0, roomList: 0 });
+    stopRateLimitCleanup();
+}
+
+// --- checkConnectionRate ---
+reset();
+assert.equal(checkConnectionRate('1.1.1.1'), true, 'first connection allowed');
+for (let i = 0; i < 9; i++) checkConnectionRate('1.1.1.1');
+assert.equal(checkConnectionRate('1.1.1.1'), false, '11th connection blocked');
+assert.equal(rateLimitDenied.connections, 1, 'denial counter incremented');
+
+reset();
+assert.equal(checkConnectionRate('2.2.2.2'), true, 'separate IP independent');
+
+// --- checkEventRate ---
+reset();
+assert.equal(checkEventRate('sock1'), true, 'first event allowed');
+for (let i = 0; i < 29; i++) checkEventRate('sock1');
+assert.equal(checkEventRate('sock1'), false, '31st event blocked');
+assert.equal(rateLimitDenied.events, 1);
+
+reset();
+assert.equal(checkEventRate('sock2'), true, 'separate socket independent');
+
+// --- checkHealthRate ---
+reset();
+assert.equal(checkHealthRate('1.2.3.4'), true, 'first health check allowed');
+for (let i = 0; i < 9; i++) checkHealthRate('1.2.3.4');
+assert.equal(checkHealthRate('1.2.3.4'), false, '11th health check blocked');
+assert.equal(rateLimitDenied.health, 1);
+
+// --- checkAdminMetricsAuthRate ---
+reset();
+assert.equal(checkAdminMetricsAuthRate('5.6.7.8'), true, 'first admin auth allowed');
+for (let i = 0; i < 4; i++) checkAdminMetricsAuthRate('5.6.7.8');
+assert.equal(checkAdminMetricsAuthRate('5.6.7.8'), false, '6th admin auth blocked');
+assert.equal(rateLimitDenied.adminMetricsAuth, 1);
+
+// --- checkAuthRate ---
+reset();
+assert.equal(checkAuthRate('10.0.0.1', 'room-a'), true, 'first auth attempt allowed');
+for (let i = 0; i < 5; i++) recordAuthFailure('10.0.0.1', 'room-a');
+assert.equal(checkAuthRate('10.0.0.1', 'room-a'), false, '6th auth attempt blocked');
+assert.equal(checkAuthRate('10.0.0.1', 'room-b'), true, 'different room not blocked');
+
+// --- recordAuthFailure ---
+reset();
+recordAuthFailure('10.0.0.2', 'room-x');
+assert.equal(failedAuthAttempts.size, 1, 'failure recorded');
+const record = failedAuthAttempts.get('10.0.0.2:room-x');
+assert.equal(record.count, 1, 'count incremented');
+assert.ok(record.lastAttempt <= Date.now(), 'timestamp set');
+
+recordAuthFailure('10.0.0.2', 'room-x');
+assert.equal(failedAuthAttempts.get('10.0.0.2:room-x').count, 2, 'count increments on repeat');
+
+// --- clearRateLimitMaps ---
+reset();
+connectionCounts.set('ip1', { count: 1, resetTime: Date.now() + 60000 });
+eventCounts.set('sock1', { count: 1, resetTime: Date.now() + 10000 });
+healthCounts.set('ip2', { count: 1, resetTime: Date.now() + 60000 });
+adminMetricsAuthCounts.set('ip3', { count: 1, resetTime: Date.now() + 60000 });
+roomListCooldowns.set('sock2', Date.now());
+clearRateLimitMaps();
+assert.equal(connectionCounts.size, 0, 'connectionCounts cleared');
+assert.equal(eventCounts.size, 0, 'eventCounts cleared');
+assert.equal(healthCounts.size, 0, 'healthCounts cleared');
+assert.equal(adminMetricsAuthCounts.size, 0, 'adminMetricsAuthCounts cleared');
+assert.equal(roomListCooldowns.size, 0, 'roomListCooldowns cleared');
+
+// --- startRateLimitCleanup / stopRateLimitCleanup ---
+reset();
+startRateLimitCleanup(mockIo);
+startRateLimitCleanup(mockIo); // double-start guard
+stopRateLimitCleanup();
+assert.ok(true, 'cleanup start/stop does not throw');
+
+// --- rateLimitDenied reset ---
+reset();
+rateLimitDenied.connections = 5;
+Object.assign(rateLimitDenied, { connections: 0, events: 0, health: 0, adminMetricsAuth: 0, roomList: 0 });
+assert.equal(rateLimitDenied.connections, 0, 'denial counter resettable');
+
+console.log('rate-limiter tests passed');
@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(path.join(__dirname, '..', 'server', 'package.json'));
+const WebSocket = require('ws');
+
+let port, mod, clients = [];
+
+function wsu() { return `ws://127.0.0.1:${port}/socket.io/?EIO=4&transport=websocket&version=2.4.0&token=62170b705234c4f4807a9b22420bb93cf1a2aacfa4c5d3b47804482babb8eb50`; }
+async function c() {
+    const ws = new WebSocket(wsu()); clients.push(ws); ws._m = []; ws.on('message', d => ws._m.push(d.toString()));
+    await new Promise((r, j) => { const t = setTimeout(() => j(Error('connect')), 5e3); ws.on('open', () => { clearTimeout(t); r(); }); });
+    ws.send('40'); const s = Date.now(); while (ws._m.length < 2 && Date.now()-s < 5e3) await new Promise(r => setTimeout(r, 50));
+    if (ws._m.length < 2) throw Error('handshake');
+    ws._m.length = 0; return ws;
+}
+function s(ws, evt, d={}) { ws.send(`42${JSON.stringify([evt,d])}`); }
+function a(ws) { if (ws._m.length) { const r=ws._m.shift(); return r.startsWith('42') ? JSON.parse(r.substring(2)) : r; } return new Promise((resolve, reject) => { const t=setTimeout(()=>reject(Error('timeout')),3e3); const h=(d)=>{clearTimeout(t);ws.removeListener('message',h);const r=d.toString();resolve(r.startsWith('42')?JSON.parse(r.substring(2)):r);};ws.on('message',h);}); }
+async function w(ws, evt, ms=3000) { const st=Date.now(); while(Date.now()-st<ms) { for(let i=0;i<ws._m.length;i++){const r=ws._m[i];ws._m.splice(i,1);if(r.startsWith('42')){try{const[e]=JSON.parse(r.substring(2));if(e===evt)return e}catch{/* skip */}}} await new Promise(r=>setTimeout(r,50));} throw Error(`wait:${evt}`); }
+async function j(ws, rid, pid, pw=null) { s(ws,'join_room',{roomId:rid,peerId:pid,password:pw,protocolVersion:'1.0.0'}); assert.equal((await a(ws))[0],'room_data'); }
+function close() { clients.forEach(w=>{try{w.close()}catch{/* ignore */}}); clients.length=0; }
+
+try {
+    process.env.ADMIN_METRICS_TOKEN = 'ws-integration-test-32chars-minimum!';
+    mod = await import('../server/index.js');
+    await mod.startServer(0,'127.0.0.1');
+    port = mod.httpServer.address().port;
+
+    // --- Pool: 2 peers in 1 room, test everything ---
+    const rid = 't-'+Date.now();
+    const p1 = await c(), p2 = await c();
+
+    // Room + join
+    await j(p1, rid, 'a'); await j(p2, rid, 'b'); p1._m.length = p2._m.length = 0;
+
+    // Relay
+    s(p1,'play',{currentTime:10}); await w(p2,'play');
+    s(p1,'pause',{currentTime:20}); await w(p2,'pause');
+    s(p1,'seek',{currentTime:30}); await w(p2,'seek');
+
+    // Force Sync
+    s(p1,'force_sync_prepare',{targetTime:0}); await w(p2,'force_sync_prepare');
+    s(p1,'force_sync_ack',{}); await w(p2,'force_sync_ack');
+    s(p1,'force_sync_execute',{}); await w(p2,'force_sync_execute');
+
+    // EVENT_ACK
+    s(p2,'event_ack',{targetId:'a',actionTimestamp:Date.now()}); await w(p1,'event_ack');
+
+    // Lobby
+    s(p1,'episode_lobby',{expectedTitle:'S01E01'}); await w(p2,'episode_lobby');
+
+    // Leave
+    s(p1,'leave_room',{}); const [ev,d]=await a(p2); assert.equal(ev,'peer_status');assert.equal(d.status,'left');
+
+    close();
+
+    // --- Password room ---
+    const prid = 'pw-'+Date.now();
+    const pw1 = await c(); await j(pw1, prid, 'admin', 's3cret');
+    const pw2 = await c();
+    s(pw2,'join_room',{roomId:prid,password:'BAD',peerId:'bad',protocolVersion:'1.0.0'});
+    assert.equal((await a(pw2))[0],'error','wrong pw');
+    const pw3 = await c();
+    s(pw3,'join_room',{roomId:prid,password:'s3cret',peerId:'good',protocolVersion:'1.0.0'});
+    assert.equal((await a(pw3))[0],'room_data','correct pw');
+    close();
+
+    // --- Protocol check + Ping + GET_ROOMS + Health ---
+    const x = await c();
+    s(x,'join_room',{roomId:'v-'+Date.now(),peerId:'old',protocolVersion:'0.0.1'});
+    await w(x,'error'); // version mismatch
+    x._m.length = 0;
+    s(x,'ping',{t:Date.now()}); await w(x,'pong');
+    await j(x,'lst-'+Date.now(),'l1');
+    x._m.length = 0;
+    s(x,'get_rooms',{}); await w(x,'room_list');
+    close();
+
+    // Dedup
+    const did = 'dup-'+Date.now();
+    const d1 = await c(), d2 = await c();
+    await j(d1, did, 'dup'); d1._m.length = 0;
+    s(d2,'join_room',{roomId:did,peerId:'dup',protocolVersion:'1.0.0'});
+    assert.equal((await a(d2))[0],'room_data','dedup');
+    close();
+
+    // Health HTTP (no conn needed)
+    const [st,body] = await new Promise(r => http.get(`http://127.0.0.1:${port}/`, res => {
+        let d=''; res.on('data',c=>d+=c); res.on('end',()=>r([res.statusCode,JSON.parse(d)])); }));
+    assert.equal(st,200); assert.equal(body.status,'online');
+
+    console.log('All 13 WebSocket integration tests passed');
+} catch(e) {
+    console.error('FAILED:', e.message);
+    process.exitCode=1;
+} finally {
+    close();
+    if (mod?.stopServerForTests) await mod.stopServerForTests();
+}
@@ -11,21 +11,26 @@ const checks = [
  ['server routes', 'node', ['scripts/test-server-routes.mjs'], {
    env: { ADMIN_METRICS_TOKEN: 'verify-admin-token-with-more-than-32-chars' }
  }],
-  ['content video finder', 'node', ['scripts/test-content-video-finder.js']],
+  ['rate-limiter unit tests', 'node', ['scripts/test-rate-limiter.mjs']],
+  ['episode-utils unit tests', 'node', ['scripts/test-episode-utils.mjs']],
+  ['server WebSocket integration', 'node', ['scripts/test-server-ws.mjs']],
+  ['names generator', 'node', ['scripts/test-names.mjs']],
+  ['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']],
  ['server syntax ops', 'node', ['-c', 'server/ops.js']],
+  ['server syntax rate-limiter', 'node', ['-c', 'server/rate-limiter.js']],
  ['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 = {}]) {
@@ -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 |
@@ -12,6 +12,38 @@ import {
    isAdminMetricsAuthorized,
    isAdminMetricsTokenStrong
 } from './ops.js';
+import {
+    ROOM_LIST_COOLDOWN_MS,
+    HEALTH_RATE_LIMIT_PER_MINUTE,
+    ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE,
+    connectionCounts,
+    failedAuthAttempts,
+    eventCounts,
+    healthCounts,
+    adminMetricsAuthCounts,
+    roomListCooldowns,
+    rateLimitDenied,
+    checkAuthRate,
+    recordAuthFailure,
+    checkConnectionRate,
+    checkEventRate,
+    checkHealthRate,
+    checkAdminMetricsAuthRate,
+    startRateLimitCleanup,
+    stopRateLimitCleanup,
+    clearRateLimitMaps
+} from './rate-limiter.js';
+
+// Re-export for external consumers (tests, ops)
+export {
+    HEALTH_RATE_LIMIT_PER_MINUTE,
+    ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE,
+    healthCounts,
+    adminMetricsAuthCounts,
+    connectionCounts,
+    eventCounts,
+    rateLimitDenied
+};

 dotenv.config();

@@ -26,9 +58,6 @@ const MAX_ROOMS = parseInt(process.env.MAX_ROOMS) || 1000;
 const MAX_PEERS_PER_ROOM = parseInt(process.env.MAX_PEERS_PER_ROOM) || 25;
 const MIN_VERSION = process.env.MIN_VERSION || '1.0.0';
 const ADMIN_METRICS_TOKEN = process.env.ADMIN_METRICS_TOKEN || '';
-const ROOM_LIST_COOLDOWN_MS = 10000;
-export const HEALTH_RATE_LIMIT_PER_MINUTE = 10;
-export const ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE = 5;
 const HEALTH_RESPONSE_CACHE_TTL_MS = 60000;

 if (!isAdminMetricsTokenStrong(ADMIN_METRICS_TOKEN)) {
@@ -108,6 +137,8 @@ export const io = new Server(httpServer, {
    allowUpgrades: false
 });

+startRateLimitCleanup(io);
+
 /**
 * In-memory storage
 */
@@ -126,157 +157,6 @@ function log(type, message, details = '') {
    console.log(`[${timestamp}] [${type}] ${message}`, details);
 }

-// Rate Limiting & Security
-export const connectionCounts = new Map(); // ip -> { count, resetTime }
-const failedAuthAttempts = new Map(); // Map<IP+RoomID, {count, lastAttempt}>
-
-function checkAuthRate(ip, roomId) {
-    const key = `${ip}:${roomId}`;
-    const now = Date.now();
-    const record = failedAuthAttempts.get(key) || { count: 0, lastAttempt: 0 };
-    
-    // Block for 15 mins if 5 fails in 2 mins
-    if (record.count >= 5 && (now - record.lastAttempt) < 15 * 60 * 1000) {
-        return false;
-    }
-    
-    // Reset if last attempt was long ago
-    if ((now - record.lastAttempt) > 2 * 60 * 1000) {
-        record.count = 0;
-    }
-    
-    return true;
-}
-
-function recordAuthFailure(ip, roomId) {
-    if (failedAuthAttempts.size > 200000) {
-        const now = Date.now();
-        // 1. Clear expired entries (> 15 mins)
-        for (const [key, record] of failedAuthAttempts.entries()) {
-            if (now - record.lastAttempt > 15 * 60 * 1000) {
-                failedAuthAttempts.delete(key);
-            } else {
-                break;
-            }
-        }
-        
-        // 2. If still over 200k, perform LRU-style eviction on the oldest 10,000 entries (first items in Map order)
-        if (failedAuthAttempts.size > 200000) {
-            log('SECURITY', 'failedAuthAttempts size exceeded 200000. Performing insertion-order eviction.');
-            for (const [key] of failedAuthAttempts.entries()) {
-                if (failedAuthAttempts.size <= 190000) {
-                    break;
-                }
-                failedAuthAttempts.delete(key);
-            }
-        }
-    }
-    const key = `${ip}:${roomId}`;
-    const record = failedAuthAttempts.get(key) || { count: 0, lastAttempt: 0 };
-    record.count++;
-    record.lastAttempt = Date.now();
-    failedAuthAttempts.delete(key); // Remove first to update insertion order (moves key to the end of iteration)
-    failedAuthAttempts.set(key, record);
-}
-
-// Periodically clean up old auth failure records (every 15 minutes)
-const authFailureCleanupInterval = setInterval(() => {
-    const now = Date.now();
-    for (const [key, record] of failedAuthAttempts.entries()) {
-        if (now - record.lastAttempt > 15 * 60 * 1000) {
-            failedAuthAttempts.delete(key);
-        }
-    }
-}, 15 * 60 * 1000);
-
-export const eventCounts = new Map(); // socketId -> { count, resetTime }
-export const healthCounts = new Map(); // ip -> { count, resetTime }
-export const adminMetricsAuthCounts = new Map(); // ip -> { count, resetTime }
-const roomListCooldowns = new Map(); // socketId -> last allowed timestamp
-
-// Actual rate-limit denial counters (incremented only when a request is denied)
-const rateLimitDenied = {
-    connections: 0,
-    events: 0,
-    health: 0,
-    adminMetricsAuth: 0,
-    roomList: 0
-};
-
-// Clean up connection counts and event counts to prevent memory leak
-const rateLimitCleanupInterval = setInterval(() => {
-    const now = Date.now();
-    for (const [ip, entry] of connectionCounts.entries()) {
-        if (now > entry.resetTime) {
-            connectionCounts.delete(ip);
-        }
-    }
-    for (const [socketId, entry] of eventCounts.entries()) {
-        if (now > entry.resetTime || !io.sockets.sockets.has(socketId)) {
-            eventCounts.delete(socketId);
-        }
-    }
-    for (const [ip, entry] of healthCounts.entries()) {
-        if (now > entry.resetTime) {
-            healthCounts.delete(ip);
-        }
-    }
-    for (const [ip, entry] of adminMetricsAuthCounts.entries()) {
-        if (now > entry.resetTime) {
-            adminMetricsAuthCounts.delete(ip);
-        }
-    }
-    for (const [socketId] of roomListCooldowns.entries()) {
-        if (!io.sockets.sockets.has(socketId)) {
-            roomListCooldowns.delete(socketId);
-        }
-    }
-}, 60000);
-
-function checkConnectionRate(ip) {
-    const now = Date.now();
-    const entry = connectionCounts.get(ip) || { count: 0, resetTime: now + 60000 };
-    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
-    entry.count++;
-    connectionCounts.set(ip, entry);
-    if (entry.count <= 10) return true;
-    rateLimitDenied.connections++;
-    return false;
-}
-
-function checkEventRate(socketId) {
-    const now = Date.now();
-    const entry = eventCounts.get(socketId) || { count: 0, resetTime: now + 10000 };
-    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 10000; }
-    entry.count++;
-    eventCounts.set(socketId, entry);
-    if (entry.count <= 30) return true;
-    rateLimitDenied.events++;
-    return false;
-}
-
-function checkHealthRate(ip) {
-    const now = Date.now();
-    const entry = healthCounts.get(ip) || { count: 0, resetTime: now + 60000 };
-    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
-    entry.count++;
-    healthCounts.set(ip, entry);
-    if (entry.count <= HEALTH_RATE_LIMIT_PER_MINUTE) return true;
-    rateLimitDenied.health++;
-    return false;
-}
-
-function checkAdminMetricsAuthRate(ip) {
-    const now = Date.now();
-    const entry = adminMetricsAuthCounts.get(ip) || { count: 0, resetTime: now + 60000 };
-    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
-    entry.count++;
-    adminMetricsAuthCounts.set(ip, entry);
-    if (entry.count <= ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE) return true;
-    rateLimitDenied.adminMetricsAuth++;
-    return false;
-}
-
 /**
 * Central peer teardown. Removes a socket from all room state and notifies
 * remaining peers. Call this from every disconnect/leave/reaper/dedupe path.
@@ -836,20 +716,14 @@ function gracefulShutdown(signal) {
 }

 export async function stopServerForTests() {
-    clearInterval(authFailureCleanupInterval);
-    clearInterval(rateLimitCleanupInterval);
+    stopRateLimitCleanup();
    clearInterval(roomCleanupInterval);
    rooms.clear();
    socketToRoom.clear();
    peerToSocket.clear();
    roomCreationLocks.clear();
    peerJoinLocks.clear();
-    connectionCounts.clear();
-    failedAuthAttempts.clear();
-    eventCounts.clear();
-    healthCounts.clear();
-    adminMetricsAuthCounts.clear();
-    roomListCooldowns.clear();
+    clearRateLimitMaps();
    healthResponseCache.clear();
    io.removeAllListeners();
    io.disconnectSockets(true);
@@ -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"
@@ -0,0 +1,164 @@
+/**
+ * KoalaSync Rate Limiter
+ * Connection, event, health, and auth rate limiting for the relay server.
+ */
+
+export const ROOM_LIST_COOLDOWN_MS = 10000;
+export const HEALTH_RATE_LIMIT_PER_MINUTE = 10;
+export const ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE = 5;
+
+export const connectionCounts = new Map(); // ip -> { count, resetTime }
+export const failedAuthAttempts = new Map(); // Map<IP+RoomID, {count, lastAttempt}>
+export const eventCounts = new Map(); // socketId -> { count, resetTime }
+export const healthCounts = new Map(); // ip -> { count, resetTime }
+export const adminMetricsAuthCounts = new Map(); // ip -> { count, resetTime }
+export const roomListCooldowns = new Map(); // socketId -> last allowed timestamp
+
+export const rateLimitDenied = {
+    connections: 0,
+    events: 0,
+    health: 0,
+    adminMetricsAuth: 0,
+    roomList: 0
+};
+
+let authCleanupId = null;
+let rateLimitCleanupId = null;
+
+export function checkAuthRate(ip, roomId) {
+    const key = `${ip}:${roomId}`;
+    const now = Date.now();
+    const record = failedAuthAttempts.get(key) || { count: 0, lastAttempt: 0 };
+
+    if (record.count >= 5 && (now - record.lastAttempt) < 15 * 60 * 1000) {
+        return false;
+    }
+
+    if ((now - record.lastAttempt) > 2 * 60 * 1000) {
+        record.count = 0;
+    }
+
+    return true;
+}
+
+export function recordAuthFailure(ip, roomId) {
+    if (failedAuthAttempts.size > 200000) {
+        const now = Date.now();
+        for (const [key, record] of failedAuthAttempts.entries()) {
+            if (now - record.lastAttempt > 15 * 60 * 1000) {
+                failedAuthAttempts.delete(key);
+            } else {
+                break;
+            }
+        }
+
+        if (failedAuthAttempts.size > 200000) {
+            console.warn('SECURITY: failedAuthAttempts size exceeded 200000. Performing insertion-order eviction.');
+            for (const [key] of failedAuthAttempts.entries()) {
+                if (failedAuthAttempts.size <= 190000) {
+                    break;
+                }
+                failedAuthAttempts.delete(key);
+            }
+        }
+    }
+    const key = `${ip}:${roomId}`;
+    const record = failedAuthAttempts.get(key) || { count: 0, lastAttempt: 0 };
+    record.count++;
+    record.lastAttempt = Date.now();
+    failedAuthAttempts.delete(key);
+    failedAuthAttempts.set(key, record);
+}
+
+export function checkConnectionRate(ip) {
+    const now = Date.now();
+    const entry = connectionCounts.get(ip) || { count: 0, resetTime: now + 60000 };
+    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
+    entry.count++;
+    connectionCounts.set(ip, entry);
+    if (entry.count <= 10) return true;
+    rateLimitDenied.connections++;
+    return false;
+}
+
+export function checkEventRate(socketId) {
+    const now = Date.now();
+    const entry = eventCounts.get(socketId) || { count: 0, resetTime: now + 10000 };
+    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 10000; }
+    entry.count++;
+    eventCounts.set(socketId, entry);
+    if (entry.count <= 30) return true;
+    rateLimitDenied.events++;
+    return false;
+}
+
+export function checkHealthRate(ip) {
+    const now = Date.now();
+    const entry = healthCounts.get(ip) || { count: 0, resetTime: now + 60000 };
+    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
+    entry.count++;
+    healthCounts.set(ip, entry);
+    if (entry.count <= HEALTH_RATE_LIMIT_PER_MINUTE) return true;
+    rateLimitDenied.health++;
+    return false;
+}
+
+export function checkAdminMetricsAuthRate(ip) {
+    const now = Date.now();
+    const entry = adminMetricsAuthCounts.get(ip) || { count: 0, resetTime: now + 60000 };
+    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
+    entry.count++;
+    adminMetricsAuthCounts.set(ip, entry);
+    if (entry.count <= ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE) return true;
+    rateLimitDenied.adminMetricsAuth++;
+    return false;
+}
+
+export function startRateLimitCleanup(io) {
+    if (authCleanupId !== null || rateLimitCleanupId !== null) return; // guard double-start
+    // Clean up old auth failure records (every 15 minutes)
+    authCleanupId = setInterval(() => {
+        const now = Date.now();
+        for (const [key, record] of failedAuthAttempts.entries()) {
+            if (now - record.lastAttempt > 15 * 60 * 1000) {
+                failedAuthAttempts.delete(key);
+            }
+        }
+    }, 15 * 60 * 1000);
+
+    // Clean up rate-limit maps to prevent memory leaks (every 60 seconds)
+    rateLimitCleanupId = setInterval(() => {
+        const now = Date.now();
+        for (const [ip, entry] of connectionCounts.entries()) {
+            if (now > entry.resetTime) connectionCounts.delete(ip);
+        }
+        for (const [socketId, entry] of eventCounts.entries()) {
+            if (now > entry.resetTime || !io.sockets.sockets.has(socketId)) {
+                eventCounts.delete(socketId);
+            }
+        }
+        for (const [ip, entry] of healthCounts.entries()) {
+            if (now > entry.resetTime) healthCounts.delete(ip);
+        }
+        for (const [ip, entry] of adminMetricsAuthCounts.entries()) {
+            if (now > entry.resetTime) adminMetricsAuthCounts.delete(ip);
+        }
+        for (const [socketId] of roomListCooldowns.entries()) {
+            if (!io.sockets.sockets.has(socketId)) roomListCooldowns.delete(socketId);
+        }
+    }, 60000);
+}
+
+export function stopRateLimitCleanup() {
+    if (authCleanupId) { clearInterval(authCleanupId); authCleanupId = null; }
+    if (rateLimitCleanupId) { clearInterval(rateLimitCleanupId); rateLimitCleanupId = null; }
+}
+
+export function clearRateLimitMaps() {
+    connectionCounts.clear();
+    failedAuthAttempts.clear();
+    eventCounts.clear();
+    healthCounts.clear();
+    adminMetricsAuthCounts.clear();
+    roomListCooldowns.clear();
+}
@@ -4,7 +4,7 @@ This directory contains constants and protocol definitions used by both the exte

 ## Syncing with the Extension
 > [!IMPORTANT]
-> Every time this directory is modified, you must run `node scripts/build-extension.js` to keep the extension's copy up to date.
+> Every time this directory is modified, you must run `node scripts/build-extension.cjs` to keep the extension's copy up to date.

 Because Browser Extensions (Manifest V3) cannot load files outside their root directory, all files in this directory must be copied to `extension/shared/` whenever they are modified. The build script handles this automatically.

@@ -2,7 +2,7 @@
 * blacklist.js
 * 
 * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH.
- * If you edit this file, you MUST run: node scripts/build-extension.js
+ * If you edit this file, you MUST run: node scripts/build-extension.cjs
 * to propagate changes to the extension and relay server.
 * 
 * Domains to be filtered out from the tab selection dropdown to reduce "noise".
@@ -2,12 +2,12 @@
 * KoalaSync Shared Constants & Protocol Definitions
 * 
 * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH.
- * If you edit this file, you MUST run: node scripts/build-extension.js
+ * If you edit this file, you MUST run: node scripts/build-extension.cjs
 * to propagate changes to the extension and relay server.
 */

 export const PROTOCOL_VERSION = "1.0.0";
-export const APP_VERSION = "1.9.0";
+export const APP_VERSION = "2.4.1";

 export const OFFICIAL_SERVER_URL = 'wss://syncserver.koalastuff.net';
 export const OFFICIAL_LANDING_PAGE_URL = 'https://sync.koalastuff.net';
@@ -2,7 +2,7 @@
 * KoalaSync Shared Name Generation & Emoji Mapping
 *
 * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH.
- * If you edit this file, you MUST run: node scripts/build-extension.js
+ * If you edit this file, you MUST run: node scripts/build-extension.cjs
 * to propagate changes to the extension.
 *
 * The emoji map covers every animal/creature that has a Unicode emoji.
@@ -5,7 +5,7 @@ This directory contains the KoalaSync website. It serves a dual purpose: it is b
 ## Core Roles

 ### 1. Marketing & Onboarding
-Provides a premium, multi-language (EN/DE/FR/ES/PT-BR/RU) overview of features, setup instructions, and direct links to the extension stores.
+Provides a premium, multi-language (EN/DE/FR/ES/PT-BR/RU/IT/PL/TR/NL/JA/KO/PT) overview of features, setup instructions, and direct links to the extension stores.

 ### 2. The Invitation Bridge (`join.html`)
 The website handles incoming invitation links. When a user clicks a link like `sync.koalastuff.net/join.html#join:roomID:pass`, the website:
@@ -16,8 +16,8 @@ The website handles incoming invitation links. When a user clicks a link like `s
 ## Architecture

 The website is 100% **Static HTML, CSS, and JS**. 
- **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.js`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`.
- **Build-time Minification**: `build.js` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified (`style.css`, `app.js`, `lang-init.js`) — always edit source files, never the generated `.min.*` files in `www/`.
+- **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.cjs`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`.
+- **Build-time Minification**: `build.cjs` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified (`style.css`, `app.js`, `lang-init.js`) — always edit source files, never the generated `.min.*` files in `www/`.
 - **Zero Backend**: No Node.js, PHP, or databases are required to host the compiled website.
 - **Zero Tracking**: All assets (fonts, icons) are self-hosted to prevent third-party tracking.
 - **Responsive**: Fully optimized for mobile with a native-feel hamburger menu.
@@ -62,7 +62,7 @@ sync.koalastuff.net {

 1. Run the compilation script from the repository root to generate the `/website/www` folder:
   ```bash
-   node website/build.js
+   node website/build.cjs
   ```
 2. Serve the compiled `/www` directory using any local development server:
   ```bash
@@ -71,4 +71,4 @@ sync.koalastuff.net {
 3. To test the invitation flow locally, navigate to `http://localhost:5000/join.html#join:test-room:test-pass`.

 > [!IMPORTANT]
-> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.js`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.js` to apply changes. CSS and JS are output as `style.min.css`, `app.min.js`, and `lang-init.min.js` — the `.min.*` naming makes it visually obvious these are build artifacts. Editing minified files in `www/` will result in lost changes on the next build.
+> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.cjs`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.cjs` to apply changes. CSS and JS are output as `style.min.css`, `app.min.js`, and `lang-init.min.js` — the `.min.*` naming makes it visually obvious these are build artifacts. Editing minified files in `www/` will result in lost changes on the next build.
@@ -19,20 +19,39 @@ document.addEventListener('DOMContentLoaded', () => {

    // Scroll Reveal Logic (IntersectionObserver for performance)
    const revealElements = document.querySelectorAll('[data-reveal]');
-    
-    const revealObserver = new IntersectionObserver((entries) => {
-        entries.forEach(entry => {
-            if (entry.isIntersecting) {
-                entry.target.classList.add('revealed');
-                revealObserver.unobserve(entry.target);
-            }
-        });
-    }, {
-        rootMargin: '0px 0px -150px 0px',
-        threshold: 0.1
-    });

-    revealElements.forEach(el => revealObserver.observe(el));
+    if ('IntersectionObserver' in window) {
+        const revealObserver = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+                if (entry.isIntersecting) {
+                    entry.target.classList.add('revealed');
+                    revealObserver.unobserve(entry.target);
+                }
+            });
+        }, {
+            rootMargin: '0px 0px -150px 0px',
+            threshold: 0.1
+        });
+
+        revealElements.forEach(el => revealObserver.observe(el));
+    } else {
+        // Fallback: without IntersectionObserver support, reveal everything
+        // immediately so no content can ever stay hidden.
+        revealElements.forEach(el => el.classList.add('revealed'));
+    }
+
+    // Auto-update URL hash as user scrolls through sections
+    // (preserves position across language switches)
+    if ('IntersectionObserver' in window) {
+        const sectionObserver = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+                if (entry.isIntersecting) {
+                    history.replaceState(null, null, '#' + entry.target.id);
+                }
+            });
+        }, { threshold: 0.3 });
+        document.querySelectorAll('section[id], header[id]').forEach(el => sectionObserver.observe(el));
+    }

    // Navbar scroll effect
    const nav = document.querySelector('nav');
@@ -46,20 +65,6 @@ document.addEventListener('DOMContentLoaded', () => {
        }
    });

-    // Smooth scroll for anchors
-    document.querySelectorAll('a[href^="#"]').forEach(anchor => {
-        anchor.addEventListener('click', function (e) {
-            e.preventDefault();
-            const target = document.querySelector(this.getAttribute('href'));
-            if (target) {
-                target.scrollIntoView({
-                    behavior: 'smooth',
-                    block: 'start'
-                });
-            }
-        });
-    });
-
    // Invite Detection & Bridge
    const checkInvite = () => {
        const isJoinPage = window.location.pathname.includes('join');
@@ -508,7 +513,7 @@ document.addEventListener('DOMContentLoaded', () => {
                target = hasHtml ? 'imprint.html' : 'imprint';
                if (path.includes('/de/')) target = hasHtml ? '../imprint.html' : '../imprint';
            }
-            window.location.href = target;
+            window.location.href = target + window.location.hash;
            return;
        } else if (isLegalPrivacy) {
            let target;
@@ -520,7 +525,7 @@ document.addEventListener('DOMContentLoaded', () => {
                target = hasHtml ? 'privacy.html' : 'privacy';
                if (path.includes('/de/')) target = hasHtml ? '../privacy.html' : '../privacy';
            }
-            window.location.href = target;
+            window.location.href = target + window.location.hash;
            return;
        }
        
@@ -549,7 +554,7 @@ document.addEventListener('DOMContentLoaded', () => {
                }
            }
            
-            window.location.href = targetPath;
+            window.location.href = targetPath + window.location.hash;
        } else {
            // Dynamic page: Toggle classes and update elements dynamically without navigating away
            const html = document.documentElement;
@@ -113,6 +113,9 @@
                <p>
                    To enable cross-device synchronization, the KoalaSync browser extension temporarily captures data from the currently active video tab (e.g., tab title, media metadata like the video title, and playback state). This data is exclusively sent to other participants in your room for synchronization. We explicitly <strong>do not read, store, or transmit your general browsing history</strong>.
                </p>
+                <p style="margin-top: 0.5rem;">
+                    The extension only connects to the relay server while you are actively in a room. No persistent background connection is maintained — your IP address is not exposed to the server when you are not using the extension.
+                </p>
            </section>

            <section>
@@ -3,31 +3,31 @@
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://sync.koalastuff.net/imprint</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://sync.koalastuff.net/privacy</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://sync.koalastuff.net/de/impressum</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://sync.koalastuff.net/de/datenschutz</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://sync.koalastuff.net/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -47,7 +47,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/de/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -67,7 +67,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/fr/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -87,7 +87,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/es/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -107,7 +107,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/pt-BR/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -127,7 +127,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/ru/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -147,7 +147,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/it/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -167,7 +167,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/pl/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -187,7 +187,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/tr/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -207,7 +207,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/nl/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -227,7 +227,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/ja/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -247,7 +247,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/ko/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -267,7 +267,7 @@
  </url>
  <url>
    <loc>https://sync.koalastuff.net/pt/</loc>
-    <lastmod>2026-06-09</lastmod>
+    <lastmod>2026-06-19</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://sync.koalastuff.net/"/>
@@ -61,6 +61,10 @@
    border-radius: 6px;
 }

+html {
+    scroll-behavior: smooth;
+}
+
 body {
    font-family: 'Twemoji Country Flags', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
    background-color: var(--bg);
@@ -354,7 +358,8 @@ nav {
 }

 .extension-mockup {
-    width: 320px;
+    width: 100%;
+    max-width: 320px;
    height: 520px;
    background: #0f172a;
    border-radius: 20px;
@@ -1896,7 +1901,7 @@ footer {

@media (max-width: 768px) {
    .hero-grid, .step {
-        grid-template-columns: 1fr;
+        grid-template-columns: minmax(0, 1fr);
        text-align: center;
    }
    .hero-text h1 {
@@ -1927,7 +1932,7 @@ footer {
        margin-left: auto;
    }
    .hamburger {
-        display: none !important;
+        display: inline-flex !important;
    }
    nav .container {
        padding: 0 0.5rem;
@@ -1962,6 +1967,21 @@ footer {
    }
 }

+/* Extra-narrow phones: make sure logo, language picker and the menu button
+   never crowd each other in the header (kept comfortable down to ~320px). */
+@media (max-width: 380px) {
+    nav .container {
+        padding: 0 0.4rem;
+    }
+    .nav-right {
+        gap: 0.35rem;
+    }
+    .logo-area {
+        font-size: 1rem;
+        gap: 0.4rem;
+    }
+}
+
 /* --- Language Toggle --- */
 html.lang-de [lang="en"] {
    display: none !important;
@@ -2007,12 +2027,14 @@ html:not(.lang-de) [lang="de"] {
 }

 .lang-select-container .chevron-icon {
+    position: absolute;
+    right: 14px;
+    top: 50%;
+    transform: translateY(-50%);
    width: 12px;
    height: 12px;
-    flex-shrink: 0;
    pointer-events: none;
    opacity: 0.6;
-    margin-left: -2px;
 }

 .lang-select-container:hover .chevron-icon {
@@ -2031,21 +2053,16 @@ html:not(.lang-de) [lang="de"] {
    font-weight: 600;
    color: currentColor;
    cursor: pointer;
-    padding: 0 12px 0 0;
+    padding: 0 28px 0 0;
    margin: 0;
    width: auto;
-    max-width: 150px;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+    min-width: 110px;
    overflow: hidden;
 }

@supports (appearance: base-select) {
-    .lang-dropdown,
    .lang-dropdown::picker(select) {
        appearance: base-select;
-    }
-    .lang-dropdown::picker(select) {
        background-color: #0f172a;
        border: 1px solid #334155;
        border-radius: 8px;
@@ -2449,13 +2466,115 @@ html:not(.lang-de) [lang="de"] {
 }

@media (max-width: 768px) {
-    .comparison-table th, 
+    .comparison-table th,
    .comparison-table td {
        padding: 1rem;
        font-size: 0.85rem;
    }
+}
+
+/* On phones the 3-column table is turned into stacked cards so there is
+   no horizontal scrolling — one card per feature, KoalaSync above Teleparty. */
+@media (max-width: 600px) {
+    .comparison-table-wrapper {
+        overflow-x: visible;
+        background: transparent;
+        border: none;
+        box-shadow: none;
+        backdrop-filter: none;
+        -webkit-backdrop-filter: none;
+        margin-top: 0;
+    }
+
+    .comparison-table {
+        display: block;
+        font-size: 0.95rem;
+    }
+
+    /* Visually hide the header row but keep it for screen readers. */
+    .comparison-table thead {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+    }
+
+    .comparison-table tbody,
+    .comparison-table tr,
+    .comparison-table td {
+        display: block;
+        width: 100%;
+    }
+
+    .comparison-table tbody tr {
+        background: rgba(30, 41, 59, 0.35);
+        border: 1px solid var(--glass-border);
+        border-radius: 14px;
+        box-shadow: 0 6px 18px rgba(0, 0, 0, 0.18);
+        margin-bottom: 1rem;
+        overflow: hidden;
+    }
+
+    .comparison-table tbody tr:last-child {
+        margin-bottom: 0;
+    }
+
+    .comparison-table td {
+        padding: 0.85rem 1.1rem;
+        border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+    }
+
+    .comparison-table tbody tr td:last-child {
+        border-bottom: none;
+    }
+
+    /* Feature name acts as the card header. */
+    .comparison-table td.feat-name {
+        background: rgba(15, 23, 42, 0.55);
+        padding: 0.9rem 1.1rem;
+    }
+
+    /* Room is back on the card, so show the description again. */
    .feat-desc {
-        display: none;
+        display: block;
+        margin-top: 0.15rem;
+    }
+
+    /* Label each value cell with the product it belongs to. */
+    .comparison-table td.check,
+    .comparison-table td.cross {
+        display: flex;
+        align-items: baseline;
+        gap: 0.4rem;
+    }
+
+    .comparison-table td.check::before,
+    .comparison-table td.cross::before {
+        flex: 0 0 5.5rem;
+        font-size: 0.7rem;
+        font-weight: 700;
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+        color: var(--text-muted);
+        opacity: 0.85;
+    }
+
+    .comparison-table td.check::before {
+        content: "KoalaSync";
+    }
+
+    .comparison-table td.cross::before {
+        content: "Teleparty";
+    }
+
+    /* Keep the KoalaSync row subtly highlighted, like on desktop. */
+    .comparison-table td.check.highlight {
+        background: rgba(99, 102, 241, 0.08);
    }
 }

@@ -2748,7 +2867,9 @@ html:not(.lang-de) [lang="de"] {
 }
 .feature-card,
 .use-case-card,
-.compat-logo {
+.compat-logo,
+section[id],
+header[id] {
    scroll-margin-top: 100px;
 }

@@ -102,7 +102,7 @@
        "priceCurrency": "EUR"
      },
      "description": "Watch Netflix, YouTube, Twitch, Jellyfin, Emby and almost any HTML5 video in perfect sync with friends. Open source, privacy-first, free.",
-      "softwareVersion": "2.3.1",
+      "softwareVersion": "2.4.1",
      "license": "https://opensource.org/licenses/MIT",
      "sameAs": "https://github.com/Shik3i/KoalaSync",
      "image": "https://sync.koalastuff.net/assets/NewLogoIcon.webp",
@@ -183,6 +183,13 @@
      ]
    }
    </script>
+    <noscript>
+        <!-- Without JS the scroll-reveal observer never runs, so make all
+             reveal-animated content visible by default. -->
+        <style>
+            [data-reveal] { opacity: 1 !important; transform: none !important; }
+        </style>
+    </noscript>
 </head>
 <body>

@@ -1,4 +1,4 @@
 {
-  "version": "2.3.1",
-  "date": "2026-06-15T11:14:22Z"
+  "version": "2.4.1",
+  "date": "2026-06-19T08:50:27Z"
 }
Author	SHA1	Message	Date
KoalaDev	32fd677a31	feat: optimize extension uninstall URL registration with anonymous token and startup hardening	2026-06-19 11:54:07 +02:00
KoalaDev	fb22700268	docs: revert completed milestones in ROADMAP.md	2026-06-19 11:39:50 +02:00
KoalaDev	59b675ce17	docs: audit and update script references, supported languages, and completed milestones	2026-06-19 11:35:49 +02:00
KoalaDev	8a9293280b	chore: harden version substitution in release workflow and fix supply chain security version in README	2026-06-19 11:12:48 +02:00
KoalaDev	450f715874	ci(release): update actions to Node 24 versions & optimize workflow - Bump all actions off the deprecated Node 20 runtime: checkout v4->v7, upload-artifact v4->v7, setup-node added@v6, action-gh-release v1->v3, docker build-push v5->v7, login v3->v4, metadata v5->v6, buildx v3->v4 (verified latest majors via GitHub API; no breaking input/output changes) - Add npm dependency caching via setup-node (cache: npm) - Add GHA layer caching for the multi-arch Docker build (cache-from/to gha) - Add concurrency group so a release run is never interrupted, only dedupes re-pushes of the same tag - Tighten release-server permissions to contents: read (it never writes to the repo) Version-injection and commit-back logic unchanged. First exercised on the next v* tag. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-19 10:59:30 +02:00
GitHub Action	b4c00f36a0	chore(release): update versions to v2.4.1 [skip ci]	2026-06-19 08:50:27 +00:00
KoalaDev	36f494fa55	feat(extension): one-click invite button in empty peer list + v2.4.1 changelog - "No peers yet" state now shows a localized "Copy invite link" button (reuses BTN_COPY_INVITE, present in all 13 locales) so users can share without hunting for the field - Add v2.4.1 changelog entry covering the onboarding tour improvements, empty-state action, and the mobile landing-page fixes from this session Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-19 10:50:04 +02:00
KoalaDev	b5b3885d19	feat(extension): finish onboarding tour with closing step & cleaner welcome - Add the previously-orphaned 5th onboarding step (ONBOARDING_5) so the tour ends on a closing card instead of stopping at the username field - Make step 1 a centered welcome card instead of spotlighting the logo; guard querySelector for target-less steps - Fix stale static placeholders in popup.html (Step 1 of 3 -> 5, progress 33% -> 20%) Verified ONBOARDING_5/DONE exist across all 13 locales; rendered with the longest (German) copy. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-19 10:40:40 +02:00
KoalaDev	373f2d127a	fix(website): mobile comparison cards, hamburger nav, hero symmetry & reveal fallback - Comparison table: stack into per-feature cards on phones (no more horizontal scroll); bring feature descriptions back - Re-enable mobile hamburger menu (was hidden via display:none !important); keep logo/language/button uncrowded down to ~320px - Fix hero asymmetry: extension mockup forced the grid column wider than the container; make it width:100%/max-width:320px and use minmax(0,1fr) - Add IntersectionObserver guards + <noscript> fallback so reveal-animated content never stays hidden Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-19 10:27:07 +02:00
KoalaDev	3ebe80aab2	refactor: replace dynamic GitHub API badges with static shields.io badges	2026-06-17 06:39:42 +02:00
Timo	e7b59d61ac	docs: update all docs for lazy-connect, refactor, and .cjs rename - ARCHITECTURE.md: startup -> lazy connect, reconnect when in room - HOW_IT_WORKS.md: on-demand connection, heartbeat while connected - PRIVACY.md: clarify alarms only during active sessions - SYNC_GUIDE.md: build-extension.cjs + episode-utils injection - StoreDescription.md: on-demand relay, no persistent connection - README.md + extension/README.md: npm run build:extension - extension/README.md: replace Dual Heartbeat with On-Demand Connection - website/privacy.html: add lazy-connect privacy note	2026-06-16 14:17:19 +02:00
GitHub Action	71f7ac425a	chore(release): update versions to v2.4.0 [skip ci]	2026-06-16 12:00:03 +00:00
Timo	394b9ba474	Merge branch 'refactor/split-monoliths'	2026-06-16 13:58:32 +02:00
Timo	526736b045	fix(ci): update website build path to .cjs after rename	2026-06-16 13:54:57 +02:00
Timo	86112057b4	test: add names generator unit tests (getAvatarForName + generateUsername) Tests: 20 deterministic avatar assertions (exact match, case insensitive, longest-match-wins, ZWJ sequences, fallback), 30 randomized username format checks, and validation that every noun in the list has an emoji mapping.	2026-06-16 13:53:19 +02:00
Timo	c56fcfd281	test(server): add 13 WebSocket integration tests covering all server features Tests: connect, room create/join, password auth, play/pause/seek relay, force_sync, event_ack, episode_lobby, peer leave, ping/pong, room list, protocol version check, deduplication, health HTTP endpoint. All 13 tests pass as part of npm run verify.	2026-06-16 13:48:21 +02:00
Timo	5c43fc6236	docs: add v2.4.0 changelog entries for lazy-connect and refactor	2026-06-16 13:23:53 +02:00
Timo	101761e984	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	2026-06-16 13:22:45 +02:00
Timo	3bc68a5713	test: add unit tests for rate-limiter and episode-utils - test-rate-limiter.mjs: 12 test groups covering all rate-limit functions, Maps, cleanup, and double-start guard - test-episode-utils.mjs: 30+ assertions covering SxxExx patterns, 6 separator types (dash/dot/slash/colon/comma/space), German/English, edge cases (null/undefined/empty), and sameEpisode matching logic - verify-release.mjs: added 2 test suites + 1 syntax check to pipeline	2026-06-16 13:15:25 +02:00
Timo	6c96dd6344	chore(refactor): remove orphaned comment, add double-start guard to rate-limiter	2026-06-16 13:10:37 +02:00
Timo	d7bb8dc97c	refactor(extension): extract episode-utils from background.js + content.js Move extractEpisodeId() and sameEpisode() to shared episode-utils.js. background.js imports via ES module. content.js (IIFE) receives injected copy via build-extension.js marker replacement, eliminating duplication.	2026-06-16 12:48:11 +02:00
Timo	d38a840114	refactor(server): extract rate-limiter module from index.js Move 6 rate-limit functions, all rate-limit Maps, cleanup intervals, and denial counter to server/rate-limiter.js. 149 lines extracted. Index.js re-exports what tests and ops.js need. npm run verify passes.	2026-06-16 12:44:43 +02:00
Timo	e7d2d76ba3	fix(eslint): add missing browser globals history and location	2026-06-16 10:50:40 +02:00
Timo	5277cd0f21	fix(eslint): add missing browser globals history and location	2026-06-16 10:50:32 +02:00
Timo	4d7cbfe347	Merge branch 'feature/lazy-connect'	2026-06-16 10:47:46 +02:00
Timo	91aa76e842	fix: revert premature isConnecting reset + remove popup disconnected flicker - background.js: remove isConnecting=false at line 608 (was set before WebSocket handshake completed, defeating the guard for the entire CONNECTING phase). isConnecting is already properly reset in onclose, onopen/40 handler, catch block, and socket guard path. - background.js: restore isConnecting=false in forceDisconnect() so subsequent connect() calls can proceed after intentional disconnect. - popup.js: remove hardcoded applyConnectionStatus('disconnected') that caused a guaranteed red flicker on every popup open. Status is now set only by the async GET_STATUS response.	2026-06-16 10:44:57 +02:00
Timo	5f0a189451	fix(popup): trigger CONNECT when popup opens with saved roomId If user has a room configured but the background is not connected (e.g. service worker was killed, startup race, or stale state), the popup now sends CONNECT on open. Previously it only called GET_STATUS and showed 'disconnected' with 0 logs — the user had no way to know whether the extension was working.	2026-06-16 10:35:13 +02:00
KoalaDev	312d4f2cf7	chore: update sitemap lastmod dates, automate in release CI - Update all sitemap <lastmod> entries from 2026-06-09 to 2026-06-16. - Add sed step in release workflow to auto-update sitemap dates on every tagged release, so the sitemap never goes stale.	2026-06-16 06:11:13 +02:00
KoalaDev	884feb982d	fix(website): smooth anchor scrolling, language-switch scroll position, lang select UX - Replace JS scrollIntoView handler with CSS scroll-behavior:smooth for native anchor navigation. Fixes #hash-based scroll position surviving language switches since the hash stays in the URL. - Auto-update URL hash via IntersectionObserver as user scrolls through sections, so manual scrolling also sets the anchor for language switch. - Preserve window.location.hash across all language-switch navigations. - Fix Chrome double-arrow on language select by limiting appearance:base-select to ::picker(select) only, keeping the custom SVG chevron. - Make chevron absolutely positioned over the select with pointer-events:none so clicks anywhere on the container open the dropdown. - Remove max-width constraint on language select so longer names fit. - Add scroll-margin-top to section[id] and header[id] so anchored sections clear the fixed navbar (100px offset). - Add header[id] to scroll-margin-top for keyboard skip-link accessibility. Thanks to Taradal from Reddit	2026-06-16 06:05:49 +02:00
KoalaDev	b2da17ab62	fix(lazy-connect): harden connection lifecycle against race conditions and edge cases - Prevent concurrent connect() by removing isConnecting reset from forceDisconnect(); the guard in connect() now reliably blocks re-entry since no external caller can defeat it. - Reset isConnecting at end of connect() so subsequent calls can proceed without waiting for the async '40' handler. - Clear connectIntent and cancel reconnect timer on server ERROR when no currentRoom exists, preventing infinite reconnect loops after failed join attempts (e.g. wrong password via invite link). - Move connectIntent assignment after !roomId guard in WEB_JOIN_REQUEST to avoid clobbering existing intent on invalid input. - Broadcast JOIN_STATUS failure to popup and bridge tabs when WEB_JOIN_REQUEST receives an invalid room ID, so the website join page receives feedback instead of hanging forever. - Clear joinBtnTimeout on CONNECTION_STATUS connected/disconnected to avoid stale timeout error messages in the popup.	2026-06-16 05:39:17 +02:00
KoalaDev	b518685e2c	merge: bring main (v2.3.2) changes into lazy-connect	2026-06-16 04:59:13 +02:00
GitHub Action	b7a7a14a35	chore(release): update versions to v2.3.2 [skip ci]	2026-06-16 02:29:41 +00:00
Timo	3f8cf33dc9	fix: WEB_JOIN_REQUEST sendResponse leak + popup validation state cleanup - WEB_JOIN_REQUEST: add missing sendResponse when already in target room - popup join: reset isProcessingConnection + clear timeout on validation failures	2026-06-15 14:40:15 +02:00
Timo	f12bb0a532	fix(extension): reset reconnectAttempts on leave to prevent stale reconnecting status After LEAVE_ROOM or idle-leave, reconnectAttempts was not reset. GET_STATUS would return 'reconnecting' instead of 'disconnected', showing wrong status in popup and leaving Retry button visible.	2026-06-15 14:22:17 +02:00
Timo	1685b6a327	fix(popup): join timeout checks connection status instead of blind 15s timer Lazy-connect introduces a new state where the user clicks 'Raum erstellen' and the WebSocket takes 1-2s to establish (previously always pre-connected). The old 15s blind timeout would re-enable the button while background was still connecting, causing silent no-op clicks. Now polls GET_STATUS and extends the window if still connecting.	2026-06-15 14:19:18 +02:00
Timo	ec8f56a85d	feat(extension): lazy-connect — only maintain WebSocket when actively in room - Add connectIntent flag to gate all reconnect attempts - Only auto-connect on startup if roomId exists in storage - Close socket + stop reconnect after leaveRoom or idleLeave - Preserve existing behavior 1:1 when actively in a room - Guard force-sync state and peer list clearing during transient disconnects - Guard WEB_JOIN_REQUEST against empty sanitized roomId	2026-06-15 14:08:29 +02:00
Timo	38dc923a7c	Merge main (v2.3.1) into feature/lazy-connect	2026-06-15 13:30:57 +02:00
Timo	27e57862c0	docs: shorten v2.3.1 changelog entry	2026-06-15 13:15:01 +02:00