merge: Google Drive and chat fixes for v3.0.1

Prepare v3.0.0: encrypted text chat and runtime updates

.dockerignore

@@ -7,7 +7,5 @@ extension/
 website/
 scripts/
 *.md
-*.bat
-*.sh
 .env
 server/.env

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# These are supported funding model platforms
+ko_fi: koaladev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,56 @@
+---
+name: 🐛 Bug Report
+about: Create a report to help us improve KoalaSync
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+> **⚠️ Required:** Before submitting, open the KoalaSync **Status** tab in the extension popup and click **"Copy Logs"**. Paste the full output below — it contains essential system info, connection state, and debug data needed to diagnose your issue.
+
+<details>
+<summary><b>📋 Copy Logs Output</b></summary>
+
+<!-- Paste the copied logs here -->
+
+</details>
+
+---
+
+### Describe the Bug
+
+A clear and concise description of what the bug is.
+
+### To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+### Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+### Actual Behavior
+
+A clear and concise description of what actually happened.
+
+### Screenshots / Screen Recordings
+
+If applicable, add screenshots or recordings to help explain your problem.
+
+### Environment
+
+- **Browser:** (e.g. Chrome 125, Firefox 128)
+- **Extension Version:** (visible at the bottom of the Settings tab)
+- **OS:** (e.g. Windows 11, macOS 14.5)
+- **Self-Hosted Server?:** (yes / no — if yes, provide server version)
+- **Website/Platform:** (e.g. YouTube, Netflix, Twitch, Jellyfin, Emby)
+
+### Additional Context
+
+Add any other context about the problem here (e.g. network setup, VPN usage, multiple monitors, etc.).

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: 🚀 Feature Request
+about: Suggest a new feature or enhancement for KoalaSync
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+### Problem Description
+
+A clear and concise description of the problem or limitation you're encountering. What's missing or what could be improved?
+
+*As a user, I want to ... so that ...*
+
+### Proposed Solution
+
+Describe the feature you'd like to see. How should it work? Be as specific as possible.
+
+### Use Cases & Benefits
+
+- **When would you use this?** (e.g., specific websites, workflows, setups)
+- **What value does it add?** (e.g., saves time, enables new functionality, improves UX)
+
+### Alternatives Considered
+
+What workarounds or alternative approaches have you tried? Are there other ways to achieve a similar result?
+
+### Additional Context
+
+Add any other context, sketches, mockups, or references (e.g., links to similar features in other projects).

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!--
+Thanks for contributing to KoalaSync!
+
+Please read the CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting.
+By submitting this PR, you agree to abide by our code of conduct.
+
+Use conventional commits for the title: feat:, fix:, docs:, refactor:, chore:
+-->
+
+### Description
+
+<!-- What does this PR do and why? Link to relevant issue or motivation. -->
+
+Closes #
+
+### Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that alters existing behavior)
+- [ ] Refactoring (no functional changes)
+- [ ] Documentation update
+- [ ] Build, dependencies, or CI
+
+### How Has This Been Tested?
+
+<!-- Describe the tests you ran and the environments (browsers, OS, etc.) -->
+
+- [ ] Tested on Chrome
+- [ ] Tested on Firefox
+- [ ] `npm run lint` passes with zero errors and zero warnings
+- [ ] `node -c` passes on all modified `.js` files
+
+### Checklist
+
+- [ ] My code follows the project's style guidelines
+- [ ] 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.cjs` and updated relevant docs
+- [ ] No new warnings, secrets, or hardcoded credentials introduced
+
+### Additional Context
+
+<!-- Screenshots, migration notes, performance data, etc. -->

.github/workflows/beta-server-image.yml

@@ -0,0 +1,96 @@
+name: Beta Server Image
+
+# Publishes the relay server as a Docker image under NON-production tags so a
+# feature branch can be deployed to a staging/backup server and used as a custom
+# server, without ever touching the ':latest' tag the official relay tracks.
+#
+# Tags produced (on ghcr.io/<owner>/<repo>):
+#   - beta                         moving channel pointer to the newest build
+#   - <branch-slug>                e.g. feature-textchat
+#   - sha-<short-commit>           immutable, pin to an exact build
+#   - <custom>                     only on manual run, e.g. chatbeta01
+# Never ':latest' (flavor: latest=false).
+#
+# Remove this workflow once the feature is merged & released the normal way.
+
+on:
+  push:
+    branches:
+      - feature/textchat
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Extra immutable tag for this build (e.g. chatbeta01). Optional.'
+        required: false
+        default: ''
+
+concurrency:
+  group: beta-image-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-beta-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            server/package-lock.json
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Install server dependencies
+        run: npm ci
+        working-directory: server
+
+      - name: Run verification suite
+        run: npm run verify
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          # Never publish ':latest' from a beta build.
+          flavor: |
+            latest=false
+          tags: |
+            type=raw,value=beta
+            type=ref,event=branch
+            type=sha,prefix=sha-
+            type=raw,value=${{ github.event.inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag != '' }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: server/Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+# Runs the full verification suite (lint, unit/integration tests, production
+# audits, extension + website build) on every push to main and every PR, so a
+# regression can never reach main or a release tag unchecked.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+# Cancel superseded runs on the same ref to save CI minutes. Unlike the release
+# workflow, an interrupted CI run has no side effects.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            server/package-lock.json
+
+      - name: Install root dependencies
+        run: npm ci
+
+      # The server test suite (test-server-ws/routes/ops) imports express,
+      # socket.io, and dotenv from server/node_modules, so install them too.
+      - name: Install server dependencies
+        run: npm ci
+        working-directory: server
+
+      - name: Run verification suite
+        run: npm run verify

.github/workflows/release.yml

@@ -5,21 +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 }}
@@ -27,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: |
@@ -35,35 +43,121 @@ jobs:
             type=ref,event=tag
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v5
+        id: build
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: server/Dockerfile
           push: true
+          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
+        with:
+          subject-name: ghcr.io/${{ github.repository }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
 
   release-extension:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
 
-      - name: Sync Protocol Constants
-        run: |
-          chmod +x ./scripts/sync-constants.sh
-          ./scripts/sync-constants.sh
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
 
-      - name: Create Extension Zip
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Inject version into source files
         run: |
-          zip -r koala-sync-extension.zip extension/ -x "*.DS_Store*"
+          VERSION=${{ steps.version.outputs.VERSION }}
+          DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          echo "Injecting version $VERSION from tag $GITHUB_REF_NAME..."
+
+          # 1. extension/manifest.base.json
+          jq --arg v "$VERSION" '.version = $v' extension/manifest.base.json > tmp.json && mv tmp.json extension/manifest.base.json
+          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
+          echo "  ✓ shared/constants.js -> $VERSION"
+
+          # 3. package.json
+          jq --arg v "$VERSION" '.version = $v' package.json > tmp.json && mv tmp.json package.json
+          echo "  ✓ package.json -> $VERSION"
+
+          # 4. website/version.json
+          jq -n --arg v "$VERSION" --arg d "$DATE" '{version: $v, date: $d}' > website/version.json
+          echo "  ✓ website/version.json -> version $VERSION, date $DATE"
+
+          # 5. website/template.html — SoftwareApplication schema
+          sed -i "s/\"softwareVersion\": \".*\"/\"softwareVersion\": \"$VERSION\"/" website/template.html
+          echo "  ✓ website/template.html -> softwareVersion $VERSION"
+
+          # 6. website/llms.txt — machine-readable release metadata
+          sed -i "s/Current website release: .*/Current website release: $VERSION/" website/llms.txt
+          echo "  ✓ website/llms.txt -> $VERSION"
+
+          # 7. 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"
+
+          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 website/llms.txt README.md
+          git commit -m "chore(release): update versions to $GITHUB_REF_NAME [skip ci]" || echo "No changes to commit"
+          git push origin HEAD:main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build Extensions
+        run: |
+          npm ci
+          npm run build:extension
+
+      - name: Generate artifact attestation for extensions
+        uses: actions/attest@v4
+        with:
+          subject-path: dist/koalasync-*.zip
+
+      - name: Build Website
+        run: node website/build.cjs
+
+      - name: Upload Website Artifacts
+        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: koala-sync-extension.zip
+          files: |
+            dist/koalasync-chrome.zip
+            dist/koalasync-firefox.zip
           name: Release ${{ github.ref_name }}
           generate_release_notes: true
           draft: false

.gitignore

@@ -27,6 +27,7 @@ Thumbs.db
 # IDEs
 .vscode/
 .idea/
+.claude/
 *.swp
 *.swo
 
@@ -40,5 +41,24 @@ coverage/
 # the root 'shared/' remains the Single Source of Truth.
 extension/shared/
 
+# Auto-generated website build output
+website/www/
+website/.avif-cache.json
+
 # Temporary scratch files
 scratch/
+
+# AI Assistants and Agents
+.agents/
+.antigravity/
+.gemini/
+.claude/
+.codex/
+.opencode/
+.cursor/
+.cursorrules
+.copilot/
+.cline/
+.clinerules
+.windsurfrules
+.codeium/

AI_INIT.md

@@ -1,98 +0,0 @@
-# KoalaSync AI Onboarding (AI_INIT.md)
-
-Welcome to the KoalaSync project. This file is the primary entry point for any developer or AI agent working on this codebase. It defines the architecture, non-negotiables, and workflows required to maintain the stability and security of the system.
-
-> [!IMPORTANT]
-> **Privacy & Data Sovereignty**: KoalaSync follows a strict **Zero-External-Requests Policy**: The extension and website must not make requests to any third-party domains (Google Fonts, CDNs, etc.). All assets (fonts, icons, scripts) must be self-hosted or use system defaults.
-> - **Font Stack**: Use a modern system font stack (e.g., -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif) to maintain a premium look without external dependencies. Prohibit the use of `@import` or `<link>` for external font services.
-
----
-
-## 1. Project Overview
-KoalaSync is a specialized tool for **synchronized video playback** across multiple remote peers. It supports YouTube, Twitch, and native HTML5 video elements. 
-- **Users**: Friends or groups wanting to watch synchronized content together.
-- **Workflow**: A user creates a room, shares an invitation link, and all peers in that room are synchronized via a Node.js relay server.
-- **Identity**: Users are identified by a unique hex `peerId` combined with a customizable `username`.
-
-## 2. Repository Structure
-- `extension/`: Chrome Extension (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).
-- `shared/`: **Single Source of Truth** for protocol constants and event names.
-- `scripts/`: Utility scripts (e.g., `sync-constants.sh`).
-- `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 `.\scripts\sync-constants.bat` or `./scripts/sync-constants.sh`. 
-> - **Extension Modules** (`background.js`, `popup.js`) import directly from `./shared/constants.js`.
-> - **Content Scripts** (`content.js`) use a **manual synchronous mirror** to prevent race conditions during page load. Always verify parity after sync.
-
-## 3. Mandatory Reading
-Before touching any code, you MUST read the following documents in order:
-1. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
-2. [extension/README.md](extension/README.md) – Extension components, tab structure, and loading process.
-3. [SYNC_GUIDE.md](SYNC_GUIDE.md) – Protocol constants and synchronization requirements.
-
-## 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. 
-- **Manual Mirroring**: `content.js` maintains a manual mirror of the `EVENTS` constants from `shared/constants.js`.
-- **Maintenance**: Developers must ensure that any changes to `shared/constants.js` are manually reflected in `content.js` after running the sync scripts.
-
-## 5. Design Guidelines
-The popup UI follows a strict design system. Do not modify these variables or the layout structure without explicit approval.
-- **Font**: System font stack. **MANDATORY**: No external CDNs or Google Fonts to ensure 100% privacy.
-- **Popup Width**: Fixed at `320px`.
-- **Tab Structure**: Must maintain the **Room**, **Sync**, **Settings**, and **Dev** tabs.
-- **CSS Variables**:
-  | Variable | Value | Purpose |
-  | :--- | :--- | :--- |
-  | `--bg` | `#0f172a` | Main background |
-  | `--card` | `#1e293b` | Form and info cards |
-  | `--accent` | `#6366f1` | Primary actions and branding |
-  | `--success` | `#22c55e` | Success states / Online dot |
-  | `--error` | `#ef4444` | Errors / Offline dot |
-
-## 5. Non-Negotiables (Core Logic)
-The following features are critical and must not be removed or fundamentally altered:
-- **Two-Phase Force Sync**: The `Prepare` → `ACK` → `Execute` flow ensures all peers are buffered before playback resumes.
-- **Dual Heartbeat**: 
-    - **Background Heartbeat (30s)**: Ensures session persistence even without a video element.
-    - **Content Heartbeat (15s)**: Transmits current video metadata (time, title).
-- **Dead Peer Pruning**: Server "Reaper" disconnects peers after 5 minutes of total silence (no heartbeats or events).
-- **Deduplication**: Server kills old sockets if a user re-joins with the same `peerId` to prevent ghosts.
-- **Platform Specifics**: Specialized click-logic for YouTube (`.ytp-play-button`) and Twitch.
-- **pollSeekReady()**: Polling mechanism that checks `video.readyState` before acknowledging sync.
-- **SW Keep-alive**: Use of `chrome.alarms` to prevent the Manifest V3 Service Worker from suspending.
-- **Diagnostics**: The "Dev" tab provides real-time access to the underlying `<video>` state for troubleshooting.
-- **Persistence**: `peerId` and `username` must be stored to remain stable across sessions.
-
-## 6. Technical Constraints
-- **No Bundler**: The extension uses plain ES Modules. Do not introduce build steps or npm packages into the `extension/` folder.
-- **Manual Protocol**: `background.js` implements a subset of the Socket.IO wire protocol natives.
-- **Server Transport**: Restricted to `websocket` only. Polling is disabled.
-- **Docker Context**: The Docker build must run from the **Repo Root**.
-- **Manifest Settings**: `run_at` must remain `document_idle`, and `all_frames` must remain `false`.
-
-## 7. Security & Deployment
-- **Tokens**: Security tokens are intentionally managed via `shared/constants.js` and server `.env`.
-- **Environment**: `.env` is excluded via `.gitignore`. Only `.env.example` should be committed.
-- **Revocation**: `MIN_VERSION` check on the server is used to deprecate old extension versions.
-- **Invitation Links**: Correctly propagate server URLs, Room IDs, and Passwords via the URL hash to the bridge.
-
-## 8. Common Workflows
-
-### Adding a Protocol Event
-1. Add the event name to `shared/constants.js`.
-2. Run the sync script (`.\scripts\sync-constants.bat` or `./scripts/sync-constants.sh`).
-3. Implement the handler in `server/index.js` and `background.js`.
-
-### Testing Locally
-1. Load `extension/` as an "Unpacked Extension" in Chrome.
-2. Start the server from the root: `docker-compose up --build`.
-3. Use **different browser profiles** or vendors to test multi-peer logic.
-4. Use the **Dev tab** to verify real-time video element metadata.
-
-### Locking Old Versions
-1. Increase `APP_VERSION` in `shared/constants.js`.
-2. Update `MIN_VERSION` in the server's `.env` file and restart.

ARCHITECTURE.md

@@ -1,49 +0,0 @@
-# KoalaSync Architecture
-
-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. 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.
-     - **Protocol Version**: Client must match the server's protocol (currently `1.0.0`).
-  3. Server responds with Engine.IO handshake (`0`) and the client joins the namespace (`40`).
-- **Room Join**: Background emits `JOIN_ROOM` containing `roomId`, `password`, `peerId`, and `username`.
-- **Deduplication**: If a user joins with a `peerId` that already has an active socket, the server kills the old socket to prevent "Ghost Peers".
-
-## 2. Media Event Synchronization
-When a user interacts with a video:
-1. **Detection**: `content.js` listens to native events (`play`, `pause`, `seeked`) on the `<video>` element.
-2. **Prevention of Loops**: Uses `lastTargetState` to distinguish between user actions and programmatic actions triggered by the extension.
-3. **Reporting**: `content.js` sends a `CONTENT_EVENT` to `background.js`.
-4. **Relay**: The Server forwards the event to all other peers in the room.
-5. **Execution**: Remote peers receive the command and call `video.play()`, `video.pause()`, or `video.currentTime = targetTime`.
-
-## 3. Two-Phase Force Sync
-Ensures all peers are frame-perfect and buffered before resuming:
-1. **Prepare**: Initiator sends `FORCE_SYNC_PREPARE` with the target timestamp.
-2. **Buffer**: Peers seek and pause. Once buffered (`readyState >= 3`), they send a `FORCE_SYNC_ACK`.
-3. **Execute**: Once the Initiator collects ACKs (or after a 5s timeout), they send `FORCE_SYNC_EXECUTE`.
-4. **Resume**: All peers call `play()` simultaneously.
-
-## 4. Peer Lifecycle & Dual Heartbeat
-To maintain a clean room state and eliminate "Ghost Peers":
-- **Session Heartbeat (Background)**: Every 30 seconds, `background.js` sends an "I'm alive" signal to the server. This keeps you in the room even if no video is playing.
-- **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.
-
-## 5. Security & Stability
-- **Service Worker Lifecycle**: Uses `chrome.alarms` to prevent the Manifest V3 service worker from suspending while in an active room.
-- **Rate Limiting**: Server-side per-socket and per-IP rate limits to prevent sync-spamming or DoS.
-- **Noise Filtering**: Uses a curated blacklist of domains (Search Engines, Social Media) to declutter the "Target Tab" selector in the popup.
-- **Diagnostics**: A "Dev" tab provides real-time access to the underlying `<video>` state (`readyState`, `paused`, `currentTime`) for easier troubleshooting.
-
-## 6. Constant Synchronization & Consistency
-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 manual mirror of `EVENTS`. 
-- **Synchronization**: The `./scripts/sync-constants.sh` script ensures that the `shared/` folder within the `extension/` directory is kept up-to-date with the root `shared/` source.
-- **Verification**: Any protocol change requires a manual verification sweep across all three constant locations (Shared, Server, and Content Script Mirror).

CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at **koalasync@koalastuff.net**.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All project maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Project maintainers will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from project maintainers, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,168 @@
+# Contributing to KoalaSync
+
+Thanks for your interest in improving KoalaSync. All contributions are welcome — from bug reports and translations to core protocol changes.
+
+Please note that by participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## Ways to Contribute
+
+| Area | Description |
+|------|-------------|
+| **Bug Reports** | Found a bug? Open an issue with repro steps (see template below). |
+| **Code** | Fix bugs, add features, or improve the extension / server / website. |
+| **Translations** | Help localize the extension and website into more languages. See [TRANSLATION.md](docs/TRANSLATION.md). |
+| **Documentation** | Improve docs, fix typos, or add missing examples. |
+| **Security** | Found a vulnerability? See [SECURITY.md](SECURITY.md) — do NOT open a public issue. |
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** v20.9+
+- **Docker** (for local relay server testing)
+
+### Quick Start
+
+```bash
+git clone https://github.com/Shik3i/KoalaSync.git
+cd KoalaSync
+npm install
+node scripts/build-extension.cjs
+```
+
+---
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `extension/` | Browser extension (Manifest V3, Chrome & Firefox) |
+| `server/` | Node.js + Socket.IO relay server (Dockerized) |
+| `website/` | Landing page, invitation bridge, and marketing site |
+| `shared/` | Protocol constants — single source of truth |
+| `scripts/` | Build and sync utilities |
+| `docs/` | Architecture, sync protocol, and deep-dive guides |
+
+---
+
+## Testing Locally
+
+### Extension
+
+1. Load `dist/chrome/` as an unpacked extension in Chrome (`chrome://extensions/` → Developer Mode → **Load unpacked**).
+2. For Firefox: load `dist/firefox/` via `about:debugging` → **Load Temporary Add-on**.
+3. Start the relay server: `docker compose up --build`.
+4. Use **two different browser profiles** (or Chrome + Firefox) to test multi-peer sync.
+5. Use the extension's **Dev tab** to inspect real-time video element state (`readyState`, `currentTime`, `paused`).
+
+### Website
+
+```bash
+node website/build.cjs           # Compile static site → www/
+python3 -m http.server 8080 -d website/www  # Serve locally
+```
+
+Then open `http://localhost:8080`. For multi-language testing: `http://localhost:8080/de/`.
+
+---
+
+## Protocol Constants
+
+KoalaSync uses a **single source of truth** for all protocol constants in `shared/constants.js`.
+
+> [!IMPORTANT]
+> After modifying `shared/constants.js`, you **must** run the build script to sync changes to the extension:
+> ```bash
+> node scripts/build-extension.cjs
+> ```
+> This automatically injects constants into `content.js` and regenerates browser bundles in `dist/`.
+
+---
+
+## Code Standards
+
+- **Vanilla JS**: The extension must remain dependency-free. No npm packages in `extension/`.
+- **Privacy-first**: Zero external requests — no CDNs, fonts, analytics, or trackers. All assets self-hosted.
+- **System font stack**: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, ...` — never `@import` external fonts.
+- **Room IDs**: Restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only). Enforced server-side.
+- **Comments**: Document complex sync logic. The codebase uses inline comments for protocol reasoning.
+
+---
+
+## Version Numbers
+
+> [!CAUTION]
+> **Never manually bump version numbers.** The CI pipeline injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json` during release builds. Manual bumps cause conflicts.
+
+---
+
+## Open Source Workflow & Pull Requests
+
+If you are new to open-source contributions, follow these steps to propose your changes:
+
+1. **Fork the Repository**: Click the "Fork" button at the top right of this repository to create your own copy of KoalaSync.
+2. **Clone your Fork**: `git clone https://github.com/YOUR-USERNAME/KoalaSync.git`
+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.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".
+
+### PR Code Requirements
+- **Lint**: Ensure `npm run lint` passes with zero errors and warnings.
+- **Syntax**: Run `node -c` on every modified `.js` file.
+- **Protocol changes**: Update relevant documentation in `docs/`.
+
+---
+
+## Bug Report Template
+
+When filing a bug, the easiest way is to use the **Copy Logs** button in the extension's **Status** tab. It copies a fully formatted Markdown report to your clipboard containing:
+
+- System info (version, protocol, peer ID, browser)
+- Connection status (server, room, peers, reconnect state)
+- Video debug info (playback state, readyState, network state, dimensions, error codes, shadow DOM detection, platform)
+- Action history (last 20 events)
+- Log entries (last 50)
+
+Simply paste the clipboard contents into your GitHub issue and add:
+
+| Field | Example |
+|-------|---------|
+| **Steps to Reproduce** | 1. Create room → 2. Join from second browser → 3. Play video |
+| **Expected Behavior** | Both peers play simultaneously |
+| **Actual Behavior** | Peer B remains paused |
+
+If you cannot access the Status tab, include as much of the following manually:
+
+| Field | Example |
+|-------|---------|
+| **Browser** | Chrome 125, Firefox 128 |
+| **Extension Version** | v1.9.3 (visible at bottom of Settings tab) |
+| **Website/Platform** | Netflix, YouTube, Twitch, Jellyfin, etc.
+
+---
+
+## Translation Contributions (Translators Welcome!)
+
+We welcome native speakers to help translate KoalaSync! You **do not** need deep programming knowledge to contribute translations.
+
+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.cjs` (for extension)
+   - `node scripts/test-website-locales.mjs` (for website)
+   - `node website/build.cjs` (to build the site)
+4. Follow the **Open Source Workflow** above (Fork -> Branch -> Edit -> PR) to submit your translations.
+
+---
+
+## Security
+
+If you discover a security vulnerability, **do not open a public issue**. Report it privately as described in [SECURITY.md](SECURITY.md).

README.md

@@ -1,69 +1,152 @@
-# KoalaSync
+<p align="center">
+  <img src="website/assets/PlatformJuggler_New.webp" width="280" alt="KoalaSync Mascot">
+</p>
 
-KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchronized video playback across any website (YouTube, Twitch, Netflix, and custom HTML5 players).
+<h1 align="center">KoalaSync</h1>
 
-> [!TIP]
-> **New Developers & AI Agents**: Please read [AI_INIT.md](AI_INIT.md) before starting work.
+<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/badge/Release-v3.0.0-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>
 
-## Repository Structure
-- `extension/`: Chrome Extension (Manifest V3, Vanilla JS).
-- `server/`: Node.js + Socket.IO Relay Server (Containerized).
-- `website/`: Marketing landing page & **Invitation Bridge**.
-- `shared/`: Protocol constants and domain blacklist.
-- `scripts/`: Development utilities for protocol synchronization.
+<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>
 
-> [!NOTE]
-> For deep technical dives, see [ARCHITECTURE.md](ARCHITECTURE.md) and [SYNC_GUIDE.md](SYNC_GUIDE.md).
+<p align="center"><a href="docs/CHANGELOG.md"><b>New v3.0.0 Release!</b> — See what's changed</a></p>
+
+### 🌟 Why KoalaSync?
+
+*   **🛡️ Security-First**: Volatile RAM-based relay with built-in brute-force protection and zero-persistence architecture. We keep no logs of your sessions or synchronizations. *We don't track you. We only track our server* (relying on the [aggregated, anonymous, non-personal metrics](https://syncserver.koalastuff.net/health) provided under `/health`).
+*   **📡 Direct Logic**: Manual Socket.IO wire implementation for reliable synchronization.
+*   **🛠️ Clean Build**: Dependency-free extension runtime with no library overhead.
+*   **🌐 Universal**: Works on any website with a `<video>` tag.
+
+---
+
+### ✨ Key Features
 
-## Key Features
 - **Global Synchronization**: Synchronize Play, Pause, and Seeking on any website with a `<video>` tag.
-- **Smart Matching**: Automatically highlights and sorts tabs containing matching video titles.
-- **Noise Filtering**: Built-in domain blacklist to hide non-video sites from selection.
-- **Smart Identity**: Customizable usernames combined with unique hexadecimal peer IDs.
+- **Episode Auto-Sync**: Perfectly sync series binges. All peers wait until everyone has loaded the next episode before starting together.
+- **Host Control & Co-Hosts**: Room hosts can lock playback control to trusted controllers while guests keep watching in sync.
+- **Smart Matching**: Automatically highlights tabs containing matching video titles.
 - **Dual Heartbeat Architecture**: Robust session tracking that prevents ghost rooms and stale connections.
-- **Zero-Latency Relay**: Custom Socket.IO wire protocol implementation for maximum performance.
-- **Integrated Diagnostics**: A dedicated "Dev" tab for real-time video state debugging.
-- **Seamless Invitations**: Smart invitation links that automatically configure the server and room credentials for your friends.
+- **Efficient Relay**: Minimal overhead WebSocket message forwarding.
+- **Seamless Invitations**: Smart links that automatically configure server and room credentials for your friends.
+- **Smart Audio Compressor**: Tired of constantly riding the volume? Automatically balance out whispering dialogue and deafening explosions with simple presets, or fully customize the audio to your liking.
 
-## Setup Instructions
+---
 
-### 1. Relay Server (Docker)
-The server runs on Node.js using Socket.IO, containerized for easy deployment.
+### 🚀 Quick Start
 
+#### For Users (Installation & Usage)
+The easiest and safest way to install KoalaSync is directly through the official browser stores:
+
+<p>
+  <a href="https://chromewebstore.google.com/detail/koalasync/obbnmkmlaaddodakcbdljknjpagklifc"><img src="https://img.shields.io/badge/Chrome-Download-blue?logo=googlechrome&logoColor=white&style=for-the-badge" alt="Chrome Extension"></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&style=for-the-badge" alt="Firefox Add-on"></a>
+</p>
+
+*(For manual offline installation: Download the latest `.zip` from the [Releases](https://github.com/Shik3i/KoalaSync/releases) page and load it as an "Unpacked Extension" in Developer Mode).*
+
+**How to use:**
+1. **Create a Room:** Click the Koala icon in your browser and hit `+ Create New Room`.
+2. **Invite Friends:** Share the auto-copied invite link. Once they click it, they automatically join.
+3. **Pick a Video:** Navigate to the Sync Tab, select the tab playing your video, and grab some popcorn! 🍿
+
+---
+
+### 🌐 Localization & Translations
+
+Both the official KoalaSync website and the browser extension feature dynamic localization:
+- **Available Languages**: Support is included for 15 languages: English (`en`), German (`de`), French (`fr`), Spanish (`es`), Portuguese (Brazil) (`pt-BR`), Russian (`ru`), Italian (`it`), Polish (`pl`), Turkish (`tr`), Dutch (`nl`), Japanese (`ja`), Korean (`ko`), Chinese (Simplified) (`zh`), Ukrainian (`uk`), and European Portuguese (`pt`).
+- **Real-Time Extension Localization**: Inside the extension Settings panel, users can swap languages instantly. The entire interface, notifications, Empty States, and onboarding guides re-translate dynamically in real-time.
+- **Contributing**: We welcome community translations for both the website and the extension! Please refer directly to the [TRANSLATION.md](docs/TRANSLATION.md) guide for step-by-step instructions on how to audit, refine, or add new languages.
+
+
+---
+
+### 🛠️ For Developers & Self-Hosters
+
+#### 📂 Repository Structure
+
+- `extension/`: Browser Extension (Chrome & Firefox).
+- `server/`: Node.js + Socket.IO Relay Server (Containerized).
+- `website/`: Marketing landing page & Invitation Bridge.
+- `shared/`: **Single Source of Truth** for protocol constants.
+- `scripts/`: Automated build and synchronization utilities.
+- `docs/`: Technical deep-dives ([Architecture](docs/ARCHITECTURE.md), [Sync Guide](docs/SYNC_GUIDE.md)).
+
+#### Building from Source
+To build the extension from source and synchronize protocol constants:
 ```bash
-# From the root directory
-docker-compose up -d --build
+npm install
+npm run build:extension
 ```
-The server will be available at `ws://localhost:3000`.
+The compiled artifacts will be available in the `dist/` directory.
 
-### 2. Chrome Extension
-1. **Synchronize Protocol**: From the root directory, run the sync script to copy the master constants to the extension folder:
-   ```bash
-   ./scripts/sync-constants.sh
-   ```
-2. Open Chrome and go to `chrome://extensions/`.
-3. Enable **Developer mode** (top right).
-4. Click **Load unpacked**.
-5. Select the `extension/` folder.
+#### For Self-Hosting (Docker)
+For local development or a simple private relay, use the root Compose file:
+```bash
+cp server/.env.example server/.env
+# Edit server/.env and set SERVER_SALT to a unique random value:
+# openssl rand -base64 32
+docker compose up -d --build
+```
+The local relay will be available at `ws://localhost:3000`.
 
-## Usage
-1. Open the extension and go to the **Settings** tab to set your **Username**.
-2. Go to the **Room** tab, enter your Server URL (default: `ws://localhost:3000`), and click **Join / Create Room**.
-3. In the **Sync** tab, select the tab containing the video you want to sync.
-4. Share the **Invite Link** from the Room tab. When your friends click it, they will automatically join your room and server.
-5. Use **Force Sync** to perfectly align everyone to your current timestamp.
+For production, use the official image and one of the ready-to-edit examples:
+- [Docker network compose](examples/docker-compose.caddy.example.yml): for a Caddy or reverse-proxy network. This file does not publish `localhost:3000`; Caddy routes traffic to the container.
+- [Static IP compose](examples/docker-compose.ip.example.yml): for a pre-existing Docker network with a fixed container IP.
 
-## Technical Details
-- **Manifest V3**: Uses a persistent Service Worker with Alarm-based keep-alive.
-- **Manual Socket.IO Protocol**: The extension implements the Socket.IO v4 wire protocol natively for extreme performance and zero dependencies.
-- **Dead Peer Pruning**: The server automatically prunes peers after 5 minutes of total inactivity (detected via dual heartbeats).
-- **Two-Phase Sync**: Ensures all peers are buffered (`readyState >= 3`) before resuming playback.
+In every real deployment, set a unique `SERVER_SALT`. Without it the relay still starts, but it warns that room-password hashes are using the public fallback salt from the repository.
 
-## Security & Privacy
-> [!IMPORTANT]
-> **Privacy First**: KoalaSync stores no data on disk. All room states exist only in RAM and are purged immediately when empty. There is zero telemetry, tracking, or analytics.
+To connect your extension to a self-hosted server, open the popup → **Room** tab → select **Custom Server** → enter your server's WebSocket URL (e.g., `ws://localhost:3000`).
 
-## Troubleshooting
-- **Logs**: Check the **Dev** tab in the extension popup for live connection logs and video state diagnostics.
-- **Handshake**: Verify you see `Joined Namespace /` in the logs.
-- **Permissions**: Ensure the target site hasn't blocked script injection (rare for most video sites).
+> **⚠️ Note**: `ws://` only works for `localhost`. If you deploy to a real domain, you **must** use `wss://` (e.g., `wss://sync.yourdomain.com`). This requires a TLS-terminating reverse proxy (e.g., Caddy, Nginx, or Traefik) in front of the relay server. See [Caddyfile.example](examples/Caddyfile.example) for a production-ready template.
+
+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.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.
+
+**Verify a Docker image:**
+```bash
+gh attestation verify oci://ghcr.io/shik3i/koalasync:latest \
+  -R Shik3i/KoalaSync
+```
+
+**Verify an extension binary:**
+```bash
+gh attestation verify dist/koalasync-chrome.zip \
+  -R Shik3i/KoalaSync
+```
+
+---
+
+### 📖 Documentation & Links
+
+- **[CHANGELOG.md](docs/CHANGELOG.md)**: Full version history for the extension and relay server.
+- **[TESTED_SERVICES.md](docs/TESTED_SERVICES.md)**: Detailed compatibility matrix of tested streaming platforms and known limitations.
+- **[TRANSLATION.md](docs/TRANSLATION.md)**: Translation and localization guide for contributors.
+- **[PRIVACY.md](docs/PRIVACY.md)**: Data Handling and Privacy Policy.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)**: How to help make KoalaSync better.
+- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**: Our community standards and expectations.
+- **[HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**: Step-by-step walkthrough of the complete user flow.
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Deep-dive into the two-phase sync and heartbeat logic.
+- **[PROTOCOL.md](docs/PROTOCOL.md)**: WebSocket protocol specification and event reference.
+- **[ROADMAP.md](docs/ROADMAP.md)**: Planned features, backlog, and rejected ideas.
+- **[SECURITY.md](SECURITY.md)**: Disclosure policy and security practices.
+- **[AI_INIT.md](docs/AI_INIT.md)**: Maintainer and agent onboarding notes for safe code changes.
+- **[Caddyfile.example](examples/Caddyfile.example)**: Production Caddy configuration for website and relay.
+
+---
+
+<div align="center">
+  <sub><a href="https://support.koalastuff.net"><img src="https://img.shields.io/badge/Support-KoalaSync-FF5E5B" alt="Support KoalaSync"></a></sub>
+  <sub><a href="https://gitgem.org/github/Shik3i/KoalaSync"><img src="https://gitgem.org/api/badge/github/Shik3i/KoalaSync.svg" alt="GitGem Badge" /></a></sub>
+
+  <sub>Built with ❤️ by <a href="https://github.com/Shik3i">Shik3i</a>. KoalaSync is Open Source under the <a href="LICENSE">MIT License</a>.</sub>
+</div>

SECURITY.md

@@ -0,0 +1,102 @@
+# Security Policy
+
+KoalaSync is built on a **zero-persistence, privacy-first** architecture. We take security seriously and appreciate responsible disclosure of vulnerabilities.
+
+---
+
+## Supported Versions
+
+Only the latest stable release receives security patches.
+
+| Version | Supported |
+|---------|-----------|
+| Latest release | :white_check_mark: Active |
+| Older versions | :x: Unsupported |
+
+Users on older versions are encouraged to update. The server enforces a minimum client version via `MIN_VERSION`.
+
+---
+
+## Scope
+
+The following components are within scope for security reports:
+
+| Component | Examples |
+|-----------|----------|
+| **Relay Server** (`server/`) | Authentication bypass, rate-limit evasion, room hijacking, DoS vectors |
+| **Browser Extension** (`extension/`) | XSS via content scripts, privilege escalation, data exfiltration, tab snooping |
+| **WebSocket Protocol** | Message injection, replay attacks, man-in-the-middle (WSS bypass) |
+| **Website** (`website/`) | XSS, CSP bypass, invitation-hash leaks |
+
+### Out of Scope
+
+- Theoretical attacks requiring physical device access
+- Social engineering or phishing
+- Denial of service via resource exhaustion on self-hosted instances
+- Vulnerabilities in third-party browser extensions or websites
+
+---
+
+## Reporting a Vulnerability
+
+> [!CAUTION]
+> **Do NOT open a public GitHub issue for security vulnerabilities.** Public disclosure before a patch is available puts users at risk.
+
+Instead, email the project maintainer privately:
+
+**`koalasync@koalastuff.net`**
+
+Encrypt sensitive findings with our PGP key (available on request).
+
+### What to Include
+
+- **Affected component**: Server / Extension / Website / Protocol
+- **Steps to reproduce**: Clear, minimal steps to trigger the vulnerability
+- **Impact**: What an attacker could achieve (data access, privilege escalation, etc.)
+- **Environment**: Browser version, extension version, server configuration
+- **Suggested fix** (optional): If you have ideas for a patch
+
+### What to Expect
+
+| Timeline | Action |
+|----------|--------|
+| **Within 48 hours** | Acknowledgment of your report |
+| **Within 7 days** | Initial assessment and severity confirmation |
+| **As needed** | Collaborative discussion for clarification |
+| **After patch** | Notification that the fix is deployed |
+| **After rollout** | Public acknowledgment in release notes (or anonymity if preferred) |
+
+---
+
+## Architecture & Threat Model
+
+KoalaSync's security is grounded in its architecture:
+
+- **RAM-only relay**: No database, no persistent logs. All session data evaporates on disconnect.
+- **Keyed SHA-256 room password hashes**: Plaintext passwords are never stored. Room passwords are held only as in-memory HMAC-SHA256 hashes for the short room lifetime, with brute-force protection: 5 attempts → 15-minute IP lockout.
+- **Rate limiting**: Connection rate (IP-based, 60s window), health endpoint rate (10 requests/minute/IP), wrong admin-metrics bearer attempts (5 requests/minute/IP), and event rate (per-socket, 10s window). Health-style JSON responses are cached server-side for 60 seconds and refreshed lazily on request.
+- **Reverse proxy boundary**: The relay trusts one proxy hop for client IP detection. In production, keep the Node server reachable only through Caddy or another trusted reverse proxy.
+- **URL-hash credential isolation**: Invitation credentials live in the URL fragment (`#join:...`) — never sent to the web server.
+- **Strict CSP**: `default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'`.
+- **No third-party requests**: Zero CDNs, fonts, analytics, or external scripts.
+
+If you find a way to bypass any of these protections, we want to know about it.
+
+> [!NOTE]
+> Some frequently-reported "issues" are **intentional and out of scope** for our
+> threat model (ephemeral, account-less rooms of invited participants) — e.g. an
+> unauthenticated `peerId` or non-constant-time room-password compare. Before
+> reporting, please read **[`docs/KNOWN_LIMITATIONS.md`](docs/KNOWN_LIMITATIONS.md)**.
+
+---
+
+## Responsible Disclosure
+
+We follow the principle of **coordinated vulnerability disclosure**:
+
+1. You report privately.
+2. We investigate and develop a patch.
+3. We deploy to the Chrome Web Store, Firefox Add-ons, and Docker registry.
+4. We credit you publicly (unless you prefer to remain anonymous).
+
+We do not pursue legal action against researchers who act in good faith and follow this disclosure process.

SYNC_GUIDE.md

@@ -1,43 +0,0 @@
-# KoalaSync Protocol Synchronization Guide
-
-## Why do we need to sync?
-KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the root `shared/` directory. However, Chrome Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**.
-
-To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we maintain a mirrored copy of the shared files within the `extension/shared/` folder.
-
-## When should you run the sync script?
-You MUST run the synchronization script in any of the following scenarios:
-1. **After a fresh `git clone` or `git pull`** (as the synced files are ignored by git).
-2. **After modifying** `shared/constants.js`.
-3. **After modifying** `shared/blacklist.js`.
-4. **Before committing** changes to the repository if any protocol-related files were touched.
-5. **Before deploying** the server or releasing the extension.
-
-## How to sync
-
-### On Windows
-Run the batch script from the repository root:
-```powershell
-.\scripts\sync-constants.bat
-```
-
-### On macOS / Linux
-Run the shell script from the repository root:
-```bash
-./scripts/sync-constants.sh
-```
-
-## What does it do?
-The script performs the following actions:
-1. Ensures the `extension/shared/` directory exists.
-2. Copies `shared/constants.js` to `extension/shared/constants.js`.
-3. Copies `shared/blacklist.js` to `extension/shared/blacklist.js`.
-
-## Protocol Versioning
-As of v1.0.0-RC5, the system enforces a strict `protocolVersion` check during the `JOIN_ROOM` handshake. 
-- The version is defined in `shared/constants.js`.
-- If the extension and server versions mismatch, the server will reject the connection with an `Incompatible protocol version` error.
-- **Always run the sync script** after bumping the version number to ensure both components are updated.
-
-> [!CAUTION]
-> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the sync script is run. Always edit the files in the root `shared/` directory and then run the sync script.

assets/MarketingCopy.md

@@ -0,0 +1,66 @@
+# KoalaSync — Marketing Copy Kit
+
+Ready-to-paste copy for product listings, launch pages, directory submissions, and anywhere else you keep re-typing the same pitch. Three lengths, one consistent message. Pick the one that fits the field limit.
+
+---
+
+## 1. One-Sentence Pitch
+
+> KoalaSync is a privacy-first browser extension that synchronizes video playback across almost any website so you can watch with friends in real time — no accounts, no tracking, and your video never passes through anyone's server but the original site's.
+
+**Shorter alternative** (for tight tagline fields):
+
+> Private, universal watch parties on any website — no accounts, no tracking, no media proxying.
+
+---
+
+## 2. Three-Sentence Overview
+
+> KoalaSync is a lightweight browser extension that keeps you and your friends perfectly in sync on YouTube, Netflix, Twitch, Prime Video, Jellyfin, Emby, and almost any other site with an HTML5 video player — press play once and everyone stays together. It's built privacy-first: no accounts, no telemetry, and the official relay server runs entirely in volatile RAM with zero persistence, so nothing about your sessions is ever stored. Open source under the MIT license and fully self-hostable with a single Docker Compose command, KoalaSync is a transparent watch-party tool that works everywhere and respects your data sovereignty.
+
+---
+
+## 3. Full Description
+
+### Watch together — on any site, on your terms.
+
+Counting down "3, 2, 1, play" over voice chat doesn't scale past two people. KoalaSync fixes that with a tiny browser extension that synchronizes play, pause, and seeking across everyone in the room, on almost any website with a `<video>` element. Create a room, share a link, press play — that's it.
+
+### What makes KoalaSync different
+
+Most watch-party tools fall into one of two traps: they only work on a short allowlist of sites (site-specific extensions that need a separate build for every platform), or they route your video through their own player and servers. KoalaSync was built around three principles that break that mold.
+
+**Universal by design.** If the site has an HTML5 `<video>` element, KoalaSync can usually sync it. YouTube, Netflix, Twitch, Prime Video, Disney+, Jellyfin, Emby, and countless niche sites work out of the box — no per-site integration to wait for, no extension swap when your friends want to switch services.
+
+**Your video never touches our servers.** KoalaSync only relays tiny timing messages — play, pause, seek position, readiness — over a hand-rolled WebSocket protocol. The actual video keeps streaming directly from the original site to each viewer's browser. KoalaSync never proxies, transcodes, uploads, or redistributes a single frame, which also means there is no legal gray zone around redistribution.
+
+**Privacy is the default, not an upgrade.** No accounts, no emails, no telemetry, no analytics, no behavior profiling. The official relay server runs entirely in volatile RAM and keeps zero persistent state — when the room closes, the data is gone. Pick a nickname or let KoalaSync generate one for you and you're in.
+
+### Built for people who actually want to read the code
+
+KoalaSync is MIT-licensed open source, built by a solo developer. Audit it, fork it, change it. The extension is dependency-free with a direct Socket.IO wire implementation — no opaque libraries, no framework bloat, no surprise third-party SDKs. Want full sovereignty? Set a unique `SERVER_SALT` in the supplied Compose file, then start your own relay with a single Docker Compose command and keep all watch-party coordination traffic inside your own infrastructure. The official public relay is there when you don't care, self-hosting is there when you do.
+
+### Little touches you'll notice
+
+- **Episode Auto-Sync** pauses the room when someone loads the next episode and resumes only when everyone is ready — no spoilers, no one left behind on the previous cliffhanger.
+- **Smart Audio Compressor** tames the modern "whisper dialogue, deafening explosion" mix with one click. Three presets or full manual control over threshold, ratio, attack, and release.
+- **One-click invite links** auto-configure the server and room for your friends — they just click the link and they're in. No fumbling with server URLs or room IDs.
+- **Dual-heartbeat architecture** kills ghost rooms and stale connections before they desync your session.
+- **15 languages** fully translated and switchable in real time from the settings panel — English, German, French, Spanish, Portuguese (Brazil + European), Russian, Italian, Polish, Turkish, Dutch, Japanese, Korean, Chinese, Ukrainian.
+
+### Install and start in under a minute
+
+Install KoalaSync from the Chrome Web Store or Firefox Add-ons, click "Create Room," share the invite link, and pick a video. The official relay is ready out of the box — no setup required unless you want to self-host.
+
+- Website: https://sync.koalastuff.net
+- GitHub: https://github.com/Shik3i/KoalaSync
+
+---
+
+## Bonus: Taglines (for hero headlines, social bios, meta descriptions)
+
+- Watch together. Anywhere. Privately.
+- The watch-party tool that works on every site and tracks none of them.
+- Sync play, pause, and seek on any video — no accounts, no logs, no lock-in.
+- Self-hostable, open-source watch parties for the post-"3, 2, 1, play" era.
+- Press play once. Stay together anywhere.

assets/StoreAssets/StoreDescription.md

@@ -0,0 +1,57 @@
+KoalaSync: Private Watch Parties for Emby, Jellyfin, Plex, Netflix & YouTube
+
+Tired of counting down "3, 2, 1, Play" over voice chat? KoalaSync keeps you and your friends perfectly in sync. Whether you are streaming from your own self-hosted media server like Emby, Jellyfin or Plex, or watching on a major platform like Netflix, Prime Video or YouTube, KoalaSync is designed for smooth, browser-based watch parties.
+
+
+✨ CORE FEATURES
+No account required. No tracking. Just create a room, invite your friends, and start watching together.
+
+• Real-Time Video Sync: Play, pause, seek, and watch together with fast synchronized playback across everyone in your room.
+• No Account Needed: Create a room and share the invite link. No emails, no passwords, no sign-ups. Pick a nickname or let KoalaSync generate one for you.
+• Works Almost Everywhere: If the website uses a standard HTML5 video player, KoalaSync can usually sync it. Perfect for streaming sites, self-hosted media servers, and other websites.
+• Smart Binge-Watching: When a new episode loads, KoalaSync automatically pauses the lobby until everyone is ready. No spoilers, no one left behind.
+• Smart Audio Compressor: Tired of quiet dialogue and suddenly loud action scenes? Balance whispering, explosions, and music with a single click while you watch.
+• One-Click Invites: Send a smart invite link to your friends. When they open it, KoalaSync automatically configures the room so they can join instantly.
+• 15 Languages: Enjoy a native experience in English, German, French, Spanish, Brazilian and European Portuguese, Russian, Italian, Polish, Turkish, Dutch, Japanese, Korean, Simplified Chinese, and Ukrainian.
+
+
+
+🛡️ PRIVACY & SECURITY
+KoalaSync is built for private watch parties without unnecessary data collection.
+
+• No Tracking: Zero analytics, zero telemetry, and absolutely no behavior profiling.
+• Anonymous by Design: No accounts needed. Rooms can be joined with a simple nickname.
+• Ready Out of the Box: Install KoalaSync and start watching immediately using the official public relay server. No technical setup required.
+• RAM-Only Public Server: The official relay server operates entirely in volatile RAM. No databases, no stored watch history, no persistent room data. Room data exists only temporarily and disappears when the room closes.
+• Self-Hostable: Want full control? You can run your own private KoalaSync relay server via Docker in seconds. Self-hosting is optional and never required.
+
+
+
+🚀 HOW IT WORKS
+1. Install KoalaSync.
+2. Click "Create Room" to start a private watch party.
+3. Share the invite link with your friends.
+4. Open your favorite streaming site or media server.
+5. Select the active video tab.
+6. Press play. Everyone stays perfectly in sync.
+
+
+
+⚙️ UNDER THE HOOD
+KoalaSync is lightweight, transparent, and built with privacy in mind.
+
+• On-Demand Relay: Playback state is synchronized through a custom WebSocket-based relay server. There is no permanent background connection. The relay connection is maintained only while you're in a room and closes when you leave or automatically after two hours without a selected-video heartbeat.
+• 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.
+• Open Architecture: The project is designed to be inspectable, forkable, and easy to review.
+
+
+
+💻 OPEN SOURCE
+KoalaSync was built by a solo developer who needed a fast, secure way to watch movies with friends. The code is fully transparent under the MIT license: audit it, fork it, improve it, or self-host your own relay server.
+
+Found a bug or have a feature idea? Open an issue on GitHub. Contributions and code reviews are always welcome.
+
+• Website: https://sync.koalastuff.net
+• GitHub: https://github.com/Shik3i/KoalaSync

docker-compose.yml

@@ -1,4 +1,3 @@
-version: '3.8'
 
 services:
   server:

docs/AI_INIT.md

@@ -0,0 +1,161 @@
+# KoalaSync AI Onboarding (AI_INIT.md)
+
+Welcome to the KoalaSync project. This file is the primary entry point for any developer or AI agent working on this codebase. It defines the architecture, non-negotiables, and workflows required to maintain the stability and security of the system.
+
+> [!IMPORTANT]
+> **Privacy & Data Sovereignty**: KoalaSync follows a strict **Zero-External-Requests Policy**: The extension and website must not make requests to any third-party domains (Google Fonts, CDNs, etc.). All assets (fonts, icons, scripts) must be self-hosted or use system defaults.
+> - **Font Stack**: Use a modern system font stack (e.g., -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif) to maintain a premium look without external dependencies. Prohibit the use of `@import` or `<link>` for external font services.
+> 
+> [!IMPORTANT]
+> **Communication Standard**: Be concise, concrete, and professional. Match the user's language when practical, explain risky changes before making them, and report exactly what was changed and verified. Do not use joke protocols or intentionally broken language in contributor-facing work.
+
+---
+
+## 1. Project Overview
+KoalaSync is a specialized tool for **synchronized video playback** across multiple remote peers. It supports YouTube, Twitch, and native HTML5 video elements. 
+- **Users**: Friends or groups wanting to watch synchronized content together.
+- **Workflow**: A user creates a room, shares an invitation link, and all peers in that room are synchronized via a Node.js relay server.
+- **Identity**: Users are identified by a unique hex `peerId` combined with a customizable `username`.
+
+## 2. Repository Structure
+- `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.cjs`**: Static site compiler using the repository's build dependencies. Translates `template.html` + `locales/*.json` → `www/`, generates the sitemap, and minifies HTML/CSS/JS.
+  - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `styles/*.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.cjs` to regenerate. `style.css` is the development manifest; `style.legacy.css` is an unloaded, byte-identical migration reference. Production creates page-specific and render-priority CSS bundles from `styles/*.css`; CSS/JS are output as `.min.*` files and stale generated assets are removed on each build.
+- `shared/`: **Single Source of Truth** for protocol constants, event names, blacklist data, and generated usernames.
+- `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`, `shared/blacklist.js`, and `shared/names.js` are the master shared 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.
+
+## 3. Mandatory Reading
+Before touching any code, you MUST read the following documents in order:
+1. [../README.md](../README.md) – User, developer, and self-hosting overview.
+2. [README.md](README.md) – Documentation map by role.
+3. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
+4. [../extension/README.md](../extension/README.md) – Extension components, tab structure, and loading process.
+5. [SYNC_GUIDE.md](SYNC_GUIDE.md) – Protocol constants and synchronization requirements.
+
+## 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.cjs`) automatically injects `EVENTS`, `HEARTBEAT_INTERVAL`, and episode utility functions into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details).
+- **Maintenance**: After modifying any root `shared/` file, run the build script. No manual mirroring is required.
+
+## 5. File Responsibility Map
+
+| File | Responsibility |
+|:-----|:---------------|
+| `background.js` | WebSocket client, state orchestrator, event router, session persistence |
+| `content.js` | Video element detection, media control, event origin detection (loop prevention) |
+| `popup.js` | UI rendering, user input handling, peer display, invitation link generation |
+| `bridge.js` | Landing page ↔ extension communication for invitation join flow |
+| `episode-utils.js` | Shared episode parsing, imported by background and injected into content |
+| `title-privacy.js` | Tab/media title privacy normalization and sanitization |
+| `page-api-seek-overrides.js` | Page-level seek bridge for site-specific player APIs |
+| `server/index.js` | Room management, message relay, rate limiting, authentication, peer lifecycle |
+
+## 6. Design Guidelines
+The popup UI follows a strict design system. Do not modify these variables or the layout structure without explicit approval.
+- **Font**: System font stack. **MANDATORY**: No external CDNs or Google Fonts to ensure 100% privacy.
+- **Popup Width**: Fixed at `320px`.
+- **Tab Structure**: Must maintain the visible **Room**, **Sync**, **Settings**, and **Status** tabs. The hidden **Dev** tab is available only for developer diagnostics.
+- **Appearance modes**: Preserve `system`, `light`, and `dark` behavior and the Eucalyptus, Cyber, and Graphite palettes.
+- **CSS variables**: Use the semantic tokens defined in `popup.html` (`--bg`, `--card`, `--accent`, `--text`, `--text-muted`, `--success`, `--warning`, and `--error`). Do not hard-code the retired indigo/slate palette or bypass palette-specific token overrides.
+
+## 7. Non-Negotiables (Core Logic)
+The following features are critical and must not be removed or fundamentally altered:
+- **Two-Phase Force Sync**: The `Prepare` → `ACK` → `Execute` flow ensures all peers are buffered before playback resumes.
+- **Episode Auto-Sync**: Ensures series binges stay perfectly synced. A lobby initiates during title transitions, freezing peers until everyone is ready.
+- **Host Control Mode**: In `host-only` rooms, only the host and promoted controllers may initiate room-moving playback events. Both client-side UX and server-side gates must remain intact.
+- **Dual Heartbeat**: 
+    - **Background Heartbeat (1m)**: Ensures session persistence even without a video element.
+    - **Content Heartbeat (15s)**: Transmits current video metadata (time, title).
+- **Dead Peer Pruning**: Server "Reaper" disconnects peers after 5 minutes of total silence (no heartbeats or events).
+- **Deduplication**: Server kills old sockets if a user re-joins with the same `peerId` to prevent ghosts.
+- **Platform Specifics**: Specialized click-logic for YouTube (`.ytp-play-button`) and Twitch.
+- **pollSeekReady()**: Polling mechanism that checks `video.readyState` before acknowledging sync.
+- **SW Keep-alive**: Use of `chrome.alarms` to prevent the Manifest V3 Service Worker from suspending.
+- **Diagnostics**: The visible **Status** tab provides real-time access to connection state, ping, logs, history, and underlying `<video>` state for troubleshooting.
+- **Persistence**: `peerId` and `username` must be stored to remain stable across sessions.
+- **Title Privacy**: Do not accidentally reintroduce tab/media title sharing when users disabled or reduced it.
+- **Room ID Format**: Room IDs are restricted to `[a-zA-Z0-9-]` only (alphanumeric + hyphens). This is enforced server-side.
+
+## 8. Technical Constraints
+- **No Bundler**: The extension uses plain ES Modules. Do not introduce build steps or npm packages into the `extension/` folder.
+- **Manual Protocol**: `background.js` implements a subset of the Socket.IO wire protocol natively.
+- **Server Transport**: Restricted to `websocket` only. Polling is disabled.
+- **Docker Context**: The Docker build must run from the **Repo Root**.
+- **Content Script Scope**: `bridge.js` is the only static content script in the manifest and runs on `https://sync.koalastuff.net/*` at `document_start`. Video control scripts are injected only into the selected tab via `chrome.scripting`; do not add broad persistent video content-script matches.
+- **Self-Hosting Salt**: Production/self-hosted relay examples must include a unique `SERVER_SALT` so room-password hashes are not derived with the public fallback salt.
+- **Strict Backward & Forward Compatibility (Store Delay Rule)**: Browser extensions are distributed through stores (e.g., Chrome Web Store, Firefox Add-ons) which can take up to 2 weeks to approve updates. Therefore, the server MUST NOT reject older extension clients unless a critical protocol version bump is explicitly authorized, and new extension versions MUST remain fully operational when connected to older servers (e.g., by silently falling back if a new feature is not supported). This is a core architectural requirement.
+
+## 9. Security & Deployment
+- **Tokens**: Security tokens are intentionally managed via `shared/constants.js` and server `.env`.
+- **Environment**: `.env` is excluded via `.gitignore`. Only `.env.example` should be committed.
+- **Revocation**: `MIN_VERSION` check on the server is used to deprecate old extension versions.
+- **Invitation Links**: Correctly propagate server URLs, Room IDs, and Passwords via the URL hash to the bridge.
+
+## 10. Common Workflows
+
+## CRITICAL: Git & Release Rules
+
+- **NEVER** push, commit, tag, or release without explicit user instruction.
+- **NEVER** retag or force-push without explicit instruction.
+- **NEVER** create tags for documentation-only or README changes.
+- **NEVER** run `git push`, `git tag`, `git commit` unless the user says "push", "commit", or "tag".
+- Only the user decides when to commit, push, tag, or release.
+- Ask before any git write operation.
+
+### ⚠️ Pre-Session Git Sync (MANDATORY)
+Before starting any task, committing, or pushing, you **MUST** run `git pull --rebase` to ensure your local branch is up-to-date with `origin/main`. CI pipelines and other agents may push commits concurrently. Skipping this step will cause merge conflicts and rejected pushes.
+
+### Releasing a New Version (CRITICAL WORKFLOW FOR AI AGENTS)
+> [!CAUTION]
+> **AI AGENTS MUST FOLLOW THIS EXACT SEQUENCE WHEN RELEASING A NEW VERSION OR TAGGING.**
+> 
+> **🚫 NO MANUAL VERSION BUMPING**: You MUST **NEVER** manually modify the version strings in `package.json`, `extension/manifest.base.json`, or `website/version.json`. The GitHub Actions CI pipeline automatically extracts the version from the git tag (e.g. `v2.0.5` -> `2.0.5`), injects it into all target files, and commits the updates back to `main` with `[skip ci]`. Manual bumps will cause merge conflicts and build failures.
+> - **Website Versioning**: **NEVER** manually modify generated version strings in `website/www/`. The website build injects version data from `website/version.json` into generated output.
+1. **MANDATORY SYNTAX & LINT CHECKS**: Before staging, committing, or pushing any changes, you **MUST** run both checks on every modified JavaScript file:
+   - **Syntax Validation**: Run `node -c` on every single modified JavaScript file (e.g., `node -c extension/background.js` and `node -c extension/content.js`). **NEVER** commit or push code that fails this check.
+   - **ESLint Validation**: Run `npm run lint` (or `npx eslint .`). The output must show **zero errors and zero warnings**. ESLint is configured to catch undefined variables, unused vars, unreachable code, and other semantic issues. **NEVER** commit or push code that fails this check.
+2. Commit all verified code changes and push to `main`.
+3. Create and push a new tag. **MANDATORY**: Tags MUST start with a `v` (e.g., `v1.4.0`). The GitHub Actions release workflow is strictly configured to ignore any tags without the `v` prefix.
+   - **🚫 TAG IMMUTABILITY**: Once a tag is pushed to `origin`, it is **PERMANENT**. You MUST **NEVER** reuse, move, or force-push an existing tag — not even to "fix" a mistake. If a release is missing a fix, increment the version and create a **new** tag (e.g., `v1.7.0` → `v1.7.1`). Tags are immutable identifiers; moving them breaks CI pipelines, corrupts the release history, and causes unreproducible builds.
+   - **🚫 WHEN NOT TO TAG**: Do NOT create a release tag for changes that do NOT affect the shipped extension or server artifacts. Website text changes, documentation updates (`.md` files), and landing page content do NOT require a version tag. Tags trigger the full CI pipeline (Docker build, extension packaging, GitHub Release) — running this for a typo fix wastes CI resources and creates meaningless releases. Only tag when extension code (`extension/`), server code (`server/`), or shared protocol constants (`shared/`) have changed.
+4. The CI will extract the version from the tag (e.g., `v1.4.0` → `1.4.0`), inject it into all source files, build the extension artifacts, publish the Docker image, and create a GitHub Release.
+5. Verify the release builds on GitHub Actions.
+
+### 🚫 Force Push Policy
+> [!CAUTION]
+> **Force pushing (`git push --force` or `git push -f`) is FORBIDDEN without explicit user confirmation.**
+> - If a push is rejected due to a non-fast-forward conflict, you **MUST** run `git pull --rebase` first.
+> - If a force push is absolutely required (e.g., squashed history, amended commits), you **MUST** ask the user for explicit permission with a clear explanation of why it's necessary. Never force-push autonomously.
+> - This applies to both branches (`main`) and **tags** (see Tag Immutability above). Force-pushing tags is doubly destructive. Never do it.
+
+### Adding a Protocol Event
+1. Add the event name to `shared/constants.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`, `styles/*.css`, `app.js`, `lang-init.js`, or `locales/*.json`).
+2. Run the compiler: `node website/build.cjs`. This generates the multilingual pages in `www/` and minifies CSS/JS.
+3. Verify the sources and generated contract: `node --check website/app.js`, `node --check website/lang-init.js`, `node scripts/test-website-locales.mjs`, and `node scripts/test-website-theme.mjs`.
+4. Test locally: `npx serve website/www` or `python3 -m http.server 8080 -d website/www`.
+5. Commit the source changes only. `website/www/` is generated and gitignored.
+
+### Testing Locally
+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.
+5. Use the **Status tab** to verify real-time connection state, logs, and video element metadata.
+
+### Locking Old Versions
+1. Update `MIN_VERSION` in the server's `.env` file to the minimum acceptable version.
+2. Restart the server. Older extensions will be rejected with a "Version too old" error.

docs/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# KoalaSync Architecture
+
+This document describes the communication flows and internal logic of the KoalaSync system.
+
+## 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.
+     - **Protocol Version**: Client must match the server's protocol (currently `1.0.0`).
+  3. Server responds with Engine.IO handshake (`0`) and the client joins the namespace (`40`).
+- **Room Join**: Background emits `JOIN_ROOM` containing `roomId`, `password`, `peerId`, and `username`.
+- **Deduplication**: If a user joins with a `peerId` that already has an active socket, the server kills the old socket to prevent "Ghost Peers". Deduplication re-validates after acquiring the room creation lock to avoid kicking the wrong socket during concurrent joins.
+
+## 2. Media Event Synchronization
+When a user interacts with a video:
+1. **Detection**: `content.js` listens to native events (`play`, `pause`, `seeked`) on the `<video>` element, including videos inside Shadow DOM (YouTube, Netflix, etc.).
+2. **Prevention of Loops**: Uses an `expectedEvents` Set to distinguish between user actions and programmatic actions. Expected events are consumed on match and expire via timeout. Timeout IDs are cleaned up immediately to prevent memory leaks.
+3. **Reporting**: `content.js` sends a `CONTENT_EVENT` to `background.js`.
+4. **Relay**: The Server forwards the event to all other peers in the room.
+5. **Execution**: Remote peers receive the command via `SERVER_COMMAND` (which includes the original `senderId` for correct ACK routing) and call `video.play()`, `video.pause()`, or `video.currentTime = targetTime`.
+6. **ACK Routing**: `content.js` echoes the `commandSenderId` back in `CMD_ACK`, ensuring the `EVENT_ACK` is routed to the correct initiating peer even when multiple commands arrive concurrently.
+
+## 3. Two-Phase Force Sync
+Ensures all peers are buffered and synchronized before resuming:
+1. **Prepare**: Initiator sends `FORCE_SYNC_PREPARE` with the target timestamp.
+2. **Buffer**: Peers seek and pause. Once buffered (`readyState >= 3`), they send a `FORCE_SYNC_ACK`. (Note: `content.js` limits polling to 8000ms).
+3. **Execute**: Once the Initiator collects ACKs (or after an 8.5s timeout), they send `FORCE_SYNC_EXECUTE`.
+   > [!IMPORTANT]
+   > **Network Transit Buffer Rule**: The orchestrator (`background.js`) must always use a timeout at least 500ms longer than the worker (`content.js`) to account for IPC and network transit time. Never align them exactly 1:1, as this will introduce a race condition on slow connections.
+4. **Resume**: All peers call `play()` simultaneously.
+
+## 4. Episode Auto-Sync
+Maintains continuous synchronized viewing when watching series:
+1. **Detection**: `content.js` monitors the Media Session API for title changes.
+2. **Lobby Creation**: When a new title is detected, the peer initiates an `EPISODE_LOBBY` and broadcasts the new title.
+3. **Wait State**: All peers freeze their video until they have also loaded the exact same title.
+4. **Mid-Lobby Joins**: If a new user joins the room during an active lobby, the lobby initiator broadcasts the active lobby state so the newcomer can sync up.
+5. **Resume**: Once all peers report `EPISODE_READY`, the lobby is resolved and playback resumes perfectly.
+
+## 5. Peer Lifecycle & Dual Heartbeat
+To maintain a clean room state and eliminate "Ghost Peers":
+- **Session Heartbeat (Background)**: Every 30 seconds, `background.js` sends an "I'm alive" signal to the server. This keeps you in the room even if no video is playing.
+- **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 (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.
+
+## 6. Broadcast Protocol & Routing
+KoalaSync uses a megaphone routing approach to minimize server logic:
+- **`emit()` Broadcast Behavior**: Any `emit()` from the extension client is unconditionally broadcast to **all other peers in the room**. It is not a direct message. 
+- **Storm Prevention**: When dispatching state updates in response to a new user joining (e.g., an active lobby state), ensure ONLY the initiator (or a designated leader) calls `emit()` to prevent $O(N)$ broadcast storms.
+
+## 7. Security & Stability
+- **Service Worker Lifecycle**: Uses `chrome.alarms` (30s interval) to prevent the Manifest V3 service worker from suspending while in an active room. On wake, runtime state is restored from `chrome.storage.session` via `ensureState()`.
+- **Reconnect Visualization**: Badge shows "..." (orange) during reconnect. Popup displays "Reconnecting..." with attempt counter.
+- **Rate Limiting**: Server-side per-socket and per-IP rate limits to prevent sync-spamming or simple DoS. Public health endpoints are limited to 10 requests/minute/IP and cached server-side for 60 seconds, wrong admin-metrics bearer attempts to 5 requests/minute/IP, and room discovery to one request every 10 seconds per socket. Real client IP is taken from the trusted reverse proxy hop, so the Node port must stay private behind Caddy or another trusted proxy.
+- **Room Creation Lock**: Per-room mutex prevents race conditions when multiple peers join a new room simultaneously.
+- **CORS**: Allows `chrome-extension://` origins for WebSocket fallback compatibility.
+- **Message Buffer**: `maxHttpBufferSize` set to 4KB to accommodate large `JOIN_ROOM` payloads.
+- **Process Guards**: `uncaughtException` and `unhandledRejection` handlers prevent silent server crashes.
+- **Noise Filtering**: Uses a curated blacklist of domains (Search Engines, Social Media) to declutter the "Target Tab" selector in the popup.
+- **Diagnostics**: A "Dev" tab provides real-time access to the underlying `<video>` state (`readyState`, `paused`, `currentTime`) for easier troubleshooting.
+
+## 8. Constant Synchronization & Consistency
+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 `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.

docs/CHANGELOG.md

@@ -0,0 +1,465 @@
+# KoalaSync Changelog
+
+All notable changes to the KoalaSync browser extension and relay server.
+
+---
+
+## [v3.0.1] — 2026-07-26
+
+### Added
+- **Extension: Google Drive workaround** — Detects and controls videos opened on `drive.google.com` through the site-specific embedded-player path.
+- **Extension: Chat event messages** — Optionally shows timestamped room and playback events in chat while keeping chat-message notifications enabled by default and event notifications disabled by default.
+
+### Fixed
+- **Extension: Chat interactions** — Prevents video-player keyboard shortcuts while typing, makes the floating chat draggable, restores left/right docking, updates unread notifications, and keeps chat timestamps visible.
+- **Extension: Embedded-player selection** — Avoids selecting a stale hidden media frame when multiple nested frames are temporarily ambiguous.
+- **Extension: Popup layout** — Moves the video-selection hint lower and reduces its glow.
+- **Website and extension copy** — Corrects malformed translations, separates chat and playback notification labels, removes stale version references and unsupported comparison claims, and accurately documents encrypted live chat and operational logging.
+
+## [v3.0.0] — 2026-07-26
+
+### Added
+- **Extension: Optional encrypted room chat** — Rooms now support live-only, end-to-end encrypted text messages. Chat is disabled and hidden by default and can be enabled explicitly in the extension options.
+- **Extension: Persistent room chat key** — Every room generates and retains a chat key even while chat is disabled, so chat can be enabled later without creating a new room.
+- **Extension: Floating player chat** — When enabled, chat is available from a floating control over the selected player and opens in an overlay without replacing the synchronized video.
+- **Extension: Dedicated chat settings** — Chat now has its own settings section for enablement, left/right/free-floating placement, compact/standard/large/custom sizing, and bubble-versus-open startup behavior.
+
+### Security
+- **Ciphertext-only relay** — The relay receives and forwards encrypted message payloads without storing chat history or accepting client-supplied plaintext, sender identities, timestamps, or message IDs as authoritative.
+- **Backward-compatible rollout** — Versioned `chat-v1` capabilities ensure old non-chat extensions never receive unknown chat events, while current extensions continue to work with older chatless relay versions.
+
+### Changed
+- **Build dependencies** — Updated the supported build and validation toolchain and refreshed compatible transitive dependencies.
+- **Relay container runtime** — Moved the production container from end-of-life Node.js 20 to Node.js 24 LTS and made production dependency installation deterministic with `npm ci --omit=dev`.
+
+## [v2.6.4] — 2026-07-16
+
+### Changed
+- **Extension: Localized store metadata** — Renamed the public extension title to `Watch Party - KoalaSync` and added natural, store-ready descriptions for all 15 supported locales while preserving regional language variants.
+- **Extension: Locale-based manifest metadata** — The extension name and description now resolve through Chrome/Firefox `_locales` messages instead of being hardcoded in the manifest.
+
+### Fixed
+- **Build: Extension metadata validation** — Extension builds now fail clearly for invalid locale JSON, missing metadata, an incorrect extension title, or store titles and descriptions that exceed their character limits.
+
+## [v2.6.3] — 2026-07-15
+
+### Fixed
+- **Extension: Host-access recovery races** — Prevents stale permission grants, reinjection retries, closed tabs, and rapid target changes from reactivating or clearing the wrong video tab.
+- **Extension: Cross-browser host patterns** — Uses Firefox-compatible match patterns for local servers while preserving exact Chromium port scopes.
+- **Extension: Force-sync target integrity** — Keeps sampled playback time and acknowledgements bound to the selected tab during recovery and target changes.
+
+## [v2.6.2] — 2026-07-15
+
+### Added
+- **Website: Site-access recovery guide** — Added an English help page and a localized banner across every landing-page language.
+
+### Fixed
+- **Extension: Withheld website access recovery** — Detects browser-withheld host access, shows a localized allow-access action, requests only the selected website origin, and resumes the selected tab after access is granted.
+- **Extension: Target-tab reliability** — Hardened permission recovery against rapid tab changes, navigation, closed tabs, service-worker restoration, and stale pending state.
+- **Browser compatibility** — Uses Chrome's toolbar access request only when available, with a direct user-gesture permission fallback for Firefox and older Chromium browsers.
+
+---
+
+## [v2.6.1] — 2026-07-15
+
+### Fixed
+- **Extension: Episode Lobby peer list** — Peer names in the lobby are now rendered as text instead of markup. A peer could previously put HTML in their username and have it rendered in everyone else's popup, which allowed loading remote images (leaking viewer IP addresses) and spoofing the readiness badges. Scripts were already blocked by the extension's content security policy.
+
+### Changed
+- **Release checks: AMO validation** — `npm run verify` now runs Mozilla's `addons-linter` against the built Firefox artifact with `--warnings-as-errors`, and ESLint enforces `no-unsanitized`, so upload-blocking issues surface locally instead of at submission time.
+
+---
+
+## [v2.6.0] — 2026-07-15
+
+### Added
+- **Extension: Appearance controls** — Added localized system, light, and dark theme options with an early theme initializer to avoid flashes during popup startup.
+
+### Changed
+- **Extension: Popup and settings redesign** — Unified controls, status surfaces, colors, icons, badges, and accessibility behavior; settings are now organized into mutually exclusive accordion groups.
+
+### Fixed
+- **Extension: Episode Lobby reliability** — Prevented the lobby from remaining stuck in a loading state and stopped episode transitions from triggering on non-episodic media.
+- **Extension: Tab-title normalization** — Notification counters such as `(14)`, `[7]`, and `(99+)` are removed reliably without stripping legitimate large numeric titles.
+
+---
+
+## [v2.5.4] — 2026-07-08
+
+### Changed
+- **Extension: Refined clutter blacklist** — Removed `localhost` and cloud storage providers (`drive.google.com`, `dropbox.com`, `onedrive.live.com`, `icloud.com`) from the domains blacklist so that local web development servers and tabs hosting video files in cloud storage are no longer hidden under "Hide Clutter Tabs".
+
+---
+
+## [v2.5.3] — 2026-07-02
+
+### Fixed
+- **Extension: Disney+ force sync and seeking** — Fixed force sync on Disney+ failing or jumping to wrong positions. The extension now relies solely on accurate player-API time and fails cleanly when it isn't available yet, instead of falling back to unreliable raw video data.
+- **Extension: Force-sync accuracy** — When syncing to the group, peers whose current position isn't known yet (e.g. a Disney+ peer that just loaded) no longer pull the sync target toward the start of the video.
+- **Extension: Disney+ Host Control Mode** — Regular Disney+ content is no longer misclassified as a live stream, which had silently disabled the desync dialog and snap-back for guests in host-controlled rooms. YouTube and Twitch live detection is unchanged.
+- **Extension: Disney+ episode auto-sync** — Episode transitions and the "waiting for peers" lobby flow now work reliably on Disney+ again.
+
+---
+
+## [v2.5.2] — 2026-07-02
+
+### Added
+- **Extension: Privacy title controls** - Advanced users can now disable sending browser tab titles separately from media titles. Media titles can still be sent in full, reduced to detected episode identifiers such as `S01E04`, or hidden entirely. Defaults remain full titles for backwards compatibility.
+- **Relay: Cleaner restart handling** — Connected clients are now disconnected explicitly during relay shutdown so reconnects recover more predictably.
+- **Relay: Stronger abuse protection** — Rapid room-leave spam is now rate-limited.
+- **Extension: Hidden remote seek diagnostics** — KoalaDev can use the hidden Dev tab to simulate remote seeks and inspect precise native/page-API timing while debugging playback integrations.
+
+### Changed
+- **Extension: Shared page-API seek bridge** — Netflix and Disney+ now use a common page-level seek bridge so private player APIs can be invoked from the page context while the default HTML5 path stays unchanged.
+- **Build: Release build timestamp** — Extension builds now inject a build timestamp into the hidden Dev tab for easier local package verification.
+
+### Fixed
+- **Extension: Disney+ precise sync** — Disney+ now reads time and seeks through the real page media-player API, and the temporary DOM timeline/button scraping fallback has been removed.
+- **Extension: Netflix seek reliability** — Netflix seeking keeps using the page player API with a safer session lookup path.
+- **Extension: Tab-title counter cleanup** — Leading browser notification counters such as `(14)` or `[7]` are removed from shared tab titles and matching logic without changing the existing privacy controls.
+- **Extension: Tab navigation reinjection** — Reinjecting the content script after selected-tab navigation now uses the same page-API-aware injection path.
+
+---
+
+## [v2.5.0] — 2026-06-29
+
+### Added
+- **Extension + Relay: Host Control Mode** — Room owners can now switch a room between open playback control and host-controlled playback. In host-only mode, guests stay synchronized but their local play, pause, and seek actions are not rebroadcast to the room.
+- **Backward-compatible Host Control rollout** — The extension only shows Host Control when the connected relay supports it, so users on older self-hosted servers do not see controls that cannot work yet.
+- **Extension: Clear host and guest states** — The popup shows the current control mode, host status, peer roles, and localized guest guidance so participants understand when playback is controlled by the host.
+- **Website: FAQ clarification for streaming access** — The landing page and FAQ structured data now state clearly that KoalaSync does not stream, host, share, or bypass access to video content. Every participant watches locally and needs their own access to services such as Netflix.
+
+### Changed
+- **Playback sync now follows the room's control setting** — When Host Control is enabled, only the host can drive room-wide playback changes; guests can still watch in sync without accidentally changing playback for everyone.
+
+---
+
+## [v2.4.6] — 2026-06-23
+
+### Fixed
+- **Room and settings are no longer stored in `chrome.storage.sync`** — Room ID, password, and username were being resurrected from synced storage on a fresh install (sync survives an uninstall in the user's Google account), which made the extension silently auto-connect to a dead room and appear permanently connected. `getSettings()` and all settings reads are now local-only, and legacy keys are actively purged from sync on install/update/startup. Only `onboardingComplete` and `dismissedHints` remain in sync.
+- **No server traffic while alone in a room** — When you are the only peer, heartbeats, force-sync, and episode auto-sync are now fully suppressed (previously the keepAlive heartbeat, force-sync, and episode lobby were still broadcast to an empty room). The solo state is re-evaluated live on every event — never cached — so the instant another peer joins, syncing resumes immediately, including an instant state push so the newcomer sees your current position without waiting for the next heartbeat.
+
+## [v2.4.4] — 2026-06-23
+
+### Changed
+- **Server: Event rate limit raised 30 → 50 per 10s**, and all connection/event/health rate-limit thresholds and windows extracted into named constants.
+- **Extension: Reconnect backoff tuned and jittered** — capped at ~8 attempts/60s (under the per-IP connection limit) with ±20% jitter to de-synchronize reconnect herds after a server blip.
+- **CI: Added a verification workflow** running lint, tests, audits, and builds on every push/PR; the release build now uses `npm ci`.
+
+### Fixed
+- **Extension: Offline event-queue flush is now paced** (small batches instead of one synchronous burst) so a reconnect after a long outage no longer trips the server event limit and gets disconnected on rejoin.
+- **Extension: Ping liveness tolerates one missed PONG** — a reconnect is forced only after 2 consecutive misses (~20s) instead of a single 5s timeout, avoiding spurious drops under transient load.
+- **Extension: `socket.send()` failures are caught and re-queued** instead of losing the event on a disconnect race.
+
+## [v2.4.3] — 2026-06-19
+
+### Added
+- **Two new languages: Ukrainian (`uk`) and Chinese (`zh`, Simplified)** — added across the extension (UI strings + Chrome `_locales`) and the website (localized pages, hreflang/Open Graph/schema tags, language selector), bringing the total to 15 languages.
+
+### Changed
+- **Play/pause sync coalescing** — The content script now collapses rapid bursts of native play/pause events (source swaps, ABR/quality switches, ad transitions, page teardown) into a single relayed command: the first event is sent instantly and a short 150ms window absorbs the rest. This cuts redundant relay traffic and stops bursts from tripping the server's per-socket event rate limit.
+
+### Fixed
+- **zh/uk translation quality** — Corrected systematic machine-translation word-sense errors in the two new locales (e.g. "Play", "Status", "Leave Room", "Clear", "Open", "peers", and audio compressor terms) and translated the remaining English leftovers.
+- **Relay logging** — An `EVENT_ACK` aimed at a peer that already left is now logged quietly instead of as a `[SECURITY]` cross-room event, so genuine cross-room attempts stand out in the logs.
+
+## [v2.4.2] — 2026-06-19
+
+### Changed
+- **Extension: Optimized uninstall URL registration** — Extracted registration into a reusable, race-condition-protected `initUninstallURL()` helper. It registers the uninstall feedback URL with browser context on both extension installation/update and browser startup to prevent state loss, without storing or sending an installation token.
+
+## [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
+- **Extension: Refined Spanish, Italian, and Portuguese translations**: Complete manual review and improvement of all Spanish (`es`), Italian (`it`), Portuguese — Brazil (`pt-BR`), and Portuguese — Portugal (`pt`) locale files for both the extension UI and the landing website. Thanks to [@Kaia-Alenia](https://github.com/Kaia-Alenia) for the native-quality translations.
+
+### Fixed
+- **Extension: Locale typos and corrupted characters fixed**: Repaired a Korean refresh button label (`Refreschi` → `새로고침`), a corrupted Korean connection status string (`연kel` → `연결`), a Korean character contaminating a Japanese string (`의` → `の`), and a Dutch typo (`cmmuniceren` → `communiceren`).
+- **Server: Admin token length leak fixed (timing side-channel)**: `isAdminMetricsAuthorized()` returned early when the provided buffer had a different length than the expected token, leaking the token length via response timing. Now `crypto.timingSafeEqual` runs in constant time on every attempt regardless of length match. Reported by [@Kaia-Alenia](https://github.com/Kaia-Alenia).
+
+---
+
+## [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**
+
+---
+
+## [v2.3.0] — 2026-06-14
+
+### Added
+- **Extension: New Interactive Onboarding Tour**: A fully redesigned, interactive step-by-step onboarding experience.
+- **Extension: Auto-Switch to Sync Tab**: The UI now intelligently switches to the Sync tab when you join a room to guide video selection.
+- **Extension: Uninstall URL Integration**: Prepared an uninstall URL setup that works natively across Chrome and Firefox, cleanly attaching browser context for analytics.
+
+### Fixed
+- **Extension: Infinite Seek Loop Prevention**: Replaced the fragile time-based seek suppression with an exact target-time verification mechanism, entirely eliminating infinite seek loops on slow buffers.
+- **Extension: Zombie Connections Resolved**: Implemented a forced disconnect upon ping timeouts, ensuring the extension reliably auto-reconnects when the WebSocket hangs in a half-open state.
+- **Extension: Room Switching Architecture**: Joining a new room while already connected now explicitly severs the old connection first, preventing state cross-contamination. 
+- **Extension: Join/Leave Race Conditions**: Added UI locks to prevent users from accidentally sending conflicting connection commands via rapid double-clicking.
+- **Extension: Same-Room Invite Bypass**: Clicking an invite link for the room you are currently in no longer triggers a redundant reconnect, instead instantly confirming the join.
+- **Extension: Audio settings now propagate immediately to video tabs**: Changes made in the audio options page are now instantly applied to the active video tab. Previously, settings saved to `chrome.storage.local` were not picked up by the background listener, which only watched `chrome.storage.sync`.
+- **Extension: Audio compressor now logs enable/disable state and resume failures**: The compressor reports when it is activated or bypassed, and warns if the `AudioContext` cannot be resumed (e.g. browser autoplay policy requires a user gesture on the page first).
+- **Extension: Video heartbeat no longer sent when alone in a room**: The full media metadata `PEER_STATUS` is now only emitted when other peers are present. The session keepalive (background heartbeat) continues to run unaffected, preventing the server reaper from disconnecting idle peers.
+- **Server: Increased `failedAuthAttempts` eviction threshold from 50k to 200k**: Reduces frequency of expensive batch evictions under high auth-failure volumes, smoothing heap usage.
+
+---
+
+## [v2.2.4] — 2026-06-10
+
+### Fixed
+- **Extension: Error notifications now respect `browserNotifications` setting**: Server error events (e.g. "Server is restarting") no longer trigger a browser notification when the user has disabled notifications in the extension settings.
+- **Server: Misleading reconnect message corrected**: The graceful shutdown message no longer tells users to manually reconnect — the extension handles this automatically.
+
+---
+
+## [v2.2.3] — 2026-06-10
+
+### Added
+- **Artifact Attestations (Supply Chain Security)**: All release artifacts (Docker images, extension ZIPs) are now published with signed [SLSA provenance attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations) via `actions/attest@v4`. Anyone can verify that an artifact was built from this repository using `gh attestation verify`.
+- **Admin health: `rateLimits.denied` counters**: New rolling counters track actual rate-limit denials (429 responses), separate from `rateLimits.trackedClients` which reports unique IPs in the tracking window.
+- **Docker HEALTHCHECK**: Container health is now checked every 30s via `GET /health`.
+- **`npm start` script**: Server can now be started with `npm start`.
+
+### Fixed
+- **Server: `activeLobby` no longer silently overwritten**: If a second peer sends `EPISODE_LOBBY` while a lobby is already active, the request is now ignored instead of destroying the first peer's lobby.
+- **CORS log sanitization**: Rejected origin headers are sanitized (`\r\n` stripped) to prevent log injection.
+- **Extension: pagehide resource leak**: `keepAlivePort`, `lobbyPollTimer`, heartbeats, and `MutationObserver` are now properly cleaned up when a tab is hidden or enters bfcache.
+- **Extension: unhandled storage rejections**: `chrome.storage.session.set()` calls in the disconnect handler now have `.catch(() => {})`.
+- **`'Pixel'` duplicate in name generator**: Second occurrence replaced with `'Nitro'` for better name diversity.
+- **`'opposum'` typo**: Corrected to `'opossum'` in the emoji map and added `'Opossum'` to `USERNAME_NOUNS`.
+- **Test reliability**: `test-server-routes.mjs` now sets `ADMIN_METRICS_TOKEN` before importing the server module, fixing standalone test execution.
+- **`MAX_PEERS_PER_ROOM` konsistent**: `.env` auf 25 gesetzt (wie `.env.example`).
+- **pt-BR.json duplicate removed**: Duplicate `FOOTER_DISCLAIMER` key removed from website locale.
+
+### Changed
+- **Admin health: `rateLimitEntries` renamed to `rateLimits.trackedClients`**: The field now accurately describes that it tracks unique clients in the rate-limit window, not denial counts. Update your json_exporter/Grafana config accordingly.
+- **README restructured**: Sections reordered by progressive technical depth. New "Supply Chain Security" subsection under "For Developers & Self-Hosters" with verification commands.
+
+---
+
+## [v2.2.2] — 2026-06-09
+
+### Added
+- **Chrome Web Store i18n Support**: Added `default_locale: "en"` to manifest and created `_locales/*/messages.json` for all 13 supported languages. This unlocks the language selection dropdown in the Chrome Web Store dashboard, allowing translated store listings (title, description) per locale. The extension's own UI translations (`locales/*.json` + `i18n.js`) remain unchanged.
+- **Locale test coverage**: Extended `scripts/test-locales.js` to validate all `_locales/*/messages.json` files (correct format, required keys, no duplicates) and verify `default_locale` is set in the manifest.
+
+### Fixed
+- **Copy Logs button alignment**: Removed stray `margin-top: 8px` inherited from `.secondary` class that pushed the button 8px down in the connection status row.
+
+---
+
+## [v2.2.1] — 2026-06-09
+
+### Added
+- **Server Ping Display**: Measures round-trip latency to the relay server via application-level ping/pong events. The extension sends `PING { t }` every 15 seconds; the server responds with `PONG { t }`. Round-trip time is calculated client-side and displayed in the Status tab, color-coded (<50ms green, 50–150ms yellow, >150ms red). No ping value is shown when disconnected or if the server does not respond within 5 seconds.
+- **Peer Ping Response (Future-Proof)**: The extension can now respond to incoming `PING { t, sender }` events from other peers by sending back `PONG { t, target: sender }`. The relay server forwards `PING` to the target peer and routes `PONG` back to the original sender. Both client and server validate that peers are in the same room before forwarding/routing. Peer-to-peer ping initiation will be activated in a future extension update without requiring a server restart.
+
+---
+
+## [v2.2.0] — 2026-06-08
+
+### Added
+- **Web Audio API Compressor**: Built-in audio dynamic range compression with four presets (Recommended, Dynamic Range, Vocal Enhancement, Smooth) and fully customizable sliders (threshold, ratio, knee, attack, release). Uses dry/wet crossfade (40ms linear ramp) to avoid clicks. Configured via the new Audio Options page accessible from the Settings tab.
+- **Audio Options Page** (`audio-options.html`): Dedicated settings page with master toggle, compressor preset selector, real-time custom sliders, and equalizer placeholder. Dark theme matching the popup design.
+- **Feature Hint System**: Generic `dismissedHints` array in sync storage for announcing new features. First hint highlights the Audio Options entry in Settings. Extensible for future features.
+
+### Changed
+- **Support Links**: Static footer badges on the Settings and Status tabs linking to the developer's support page. README and website footer updated with a Support KoalaSync badge.
+
+### Fixed
+- **Portuguese (PT) locale**: Removed Italian contamination — "sincronizzazione" → "sincronização", "tempo reale" → "tempo real", "Link di Invito" → "Link de Convite", "Sair della Sala" → "Sair da Sala".
+- **Korean locale**: Fixed broken character in `HOWTO_STEP_2_TEXT` (`클rip보드` → `클립보드`).
+- **Website COMP_FEAT_6_KOALA**: Normalized from inconsistent "6 Languages" to "13 Languages" across all locale files (en, de, es, fr, pt-BR, ru).
+- **Debug report showing wrong logs**: Fixed `logs.slice(-50)` and `history.slice(-20)` in the "Copy Debug Report" feature. Since `addLog()` and `addToHistory()` use `unshift` (inserting entries at index 0), the arrays are ordered newest-first. `slice(-N)` took the N **oldest** entries instead of the N **newest**. Changed to `slice(0, N).reverse()` to correctly include the most recent logs and display them chronologically.
+
+---
+
+## [v2.1.2] — 2026-06-06
+
+### Fixed
+- **Episode guard regex**: Fixed `isDifferentEpisode()` not detecting episode changes when the MediaSession title uses `Sxx:Exx` format (colon separator, as used by Jellyfin/Emby). The regex character class `[\s\-\.]` was replaced with `[^a-zA-Z0-9]` to match **any** non-alphanumeric separator between season and episode numbers, preventing play/pause/seek commands from a different episode leaking through and incorrectly manipulating a peer's playback.
+- **Per-device storage isolation**: Migrated `username`, `roomId`, `password`, `serverUrl`, and `useCustomServer` from `chrome.storage.sync` (synced across Google account) to `chrome.storage.local` (per-device). This prevents the extension from automatically joining the same room with the same name on multiple devices. Existing user data is migrated silently on first run; all preferences (`filterNoise`, `autoSyncNextEpisode`, etc.) remain synced.
+
+### Changed
+- Added one-time migration fallback in `getSettings()` and popup `init()` to copy existing user settings from `storage.sync` to `storage.local` on first launch after the update.
+
+---
+
+## [v2.1.0] — 2026-06-04
+
+### Added
+- Added full translation support for 7 new languages to both the browser extension popup settings and landing website: Italian (`it`), Polish (`pl`), Turkish (`tr`), Dutch (`nl`), Japanese (`ja`), Korean (`ko`), and European Portuguese (`pt`).
+- Implemented robust, centralized browser system language detection mapping `pt-BR` to Brazilian Portuguese and other `pt` locales (like `pt-PT`) automatically to European Portuguese.
+- Added flag emojis to language selector dropdowns in both the extension popup and landing/utility web pages for quicker visual identification.
+- Added 181 translation keys parity validation suite checks for the new languages.
+
+### Fixed & Hardened (Extension Audit)
+- Guarded all website `localStorage` interactions to prevent initialization/join flow script failures on privacy-hardened or cookie-blocked browser configurations.
+- Added robust validation null-guards to `chrome.runtime.onMessage` listeners across all extension scripts (`bridge.js`, `content.js`, `background.js`, `popup.js`) to reject unexpected runtime messages.
+- Guarded CustomEvent payload destructuring in `bridge.js` to ensure stability when receiving third-party page events.
+- Wrapped `video.currentTime` seeking adjustments during forced sync in content scripts with exception handling to absorb uninitialized video state DOMExceptions.
+- Added payload validation guards on incoming Socket.IO events within the background script's event handlers to secure against malformed server updates.
+- Prevented noisy browser console exceptions from context invalidation in target tabs by catching promise rejections on extension message dispatches.
+
+### Performance
+- Implemented in-memory language dictionary caching in the background script to completely avoid redundant extension package filesystem reads during translations.
+
+
+---
+
+## [v2.0.8] — 2026-06-03
+
+### Fixed
+- Fixed a bug where switching language inside the extension popup overwrote dynamic fields (such as active room ID, connection status, active server details, and video debug info) with default localized placeholder texts.
+- Fixed a version reporting mismatch where the copied logs (debug reports) and connection handshake parameters incorrectly reported the hardcoded `1.9.0` version instead of the actual installed manifest version.
+
+---
+
+## [v2.0.7] — 2026-06-03
+
+### Added
+- Added a `DEBUG_LOGGING` environment variable to the relay server (defaulting to `"0"` / disabled) to prevent console spam from verbose connection (`CONN`), room activity (`ROOM`, `DEDUPE`), and `CORS` events under load. Critical logs like `SERVER`, `SECURITY`, `AUTH`, and `ERROR` remain enabled at all times.
+
+---
+
+## [v2.0.6] — 2026-06-03
+
+### Performance & Security Hardening
+- Optimized failed authentication attempts cache eviction algorithm to $O(1)$ by exploiting Javascript `Map` insertion-order properties. This completely removes the previous array copying and sorting bottleneck, neutralizing a potential main-thread blocking DoS vector under heavy brute-force password traffic.
+
+---
+
+## [v2.0.5] — 2026-06-03
+
+### Security & Hardening
+- Hardened extension room idle auto-leave detection to correctly recognize when the target tab's video heartbeat goes stale (e.g., after tab navigation or media closure).
+- Exported cleaner graceful shutdown and lifecycle methods (`stopServerForTests`) from the relay server to prevent socket leaks and port-binding conflicts during verify checks.
+
+### Added
+- Added a validation step in `test-locales.js` to ensure the supported language list in `extension/i18n.js` is perfectly synchronized with the actual JSON translation files in the locales directory.
+- Added a robust route verification test suite (`scripts/test-server-routes.mjs`) covering rate limit throttling, caching headers, and admin metrics access control.
+
+---
+
+## [v2.0.4] — 2026-06-03
+
+### Security & Hardening
+- Hardened relay health endpoints against simple flood traffic: `GET /` and `GET /health` are now limited to 10 requests per minute per client IP.
+- Added lazy 60-second server-side caching for `GET /`, basic `/health`, and admin `/health` JSON responses to reduce repeated health-check work under noisy polling.
+- Added stricter brute-force throttling for invalid admin metrics bearer attempts.
+- Added startup warning for short `ADMIN_METRICS_TOKEN` values and documented that production Node ports must stay private behind Caddy or another trusted reverse proxy.
+- Lowered the default maximum peers per room to 25.
+
+### Added
+- Optional privacy-preserving admin metrics on `/health` when `ADMIN_METRICS_TOKEN` is configured and a valid bearer token is supplied. Metrics are aggregate-only and exclude room IDs, peer IDs, usernames, IP addresses, media titles, passwords, and other user-level data.
+
+### Changed
+- Removed `bcryptjs`; temporary room passwords continue to use keyed SHA-256/HMAC hashing as documented.
+- Public room discovery is now rate-limited server-side to one refresh every 10 seconds per socket, with the extension refresh button locked for 11 seconds.
+
+### Fixed
+- Improved Shadow DOM video detection so real embedded players are not hidden by smaller light-DOM preview or placeholder videos.
+- Fixed join-button timeout cleanup after join status responses.
+
+---
+
+## [v2.0.2] — 2026-06-02
+
+### Fixed
+- Peer identity spoofing in relay server: client-supplied `peerId` could be used to impersonate other peers in PEER_STATUS events. Server now always stamps `peerId` with the authenticated sender's identity.
+- Amazon domain detection: replaced broad `includes('amazon.')` substring check with boundary-safe regex that correctly matches all Amazon storefronts (`amazon.com`, `amazon.de`, `amazon.co.uk`, etc.) while rejecting lookalike domains.
+
+---
+
+## [v2.0.1] — 2026-06-01
+
+### Fixed
+- Video detection on Prime Video: `findVideo()` now scores all video elements by size, duration, and mute state instead of picking the first one. Fixes 0×0 placeholder being selected over the actual player.
+- History entries in debug report showing `?` instead of action names.
+- Prime Video status in compatibility matrix updated to reflect partial support.
+
+### Added
+- Multi-video overview table in Copy Debug Report when a page has more than one `<video>` element. Shows resolution, mute state, playback state, readyState, duration, and marks the currently targeted video.
+
+---
+
+## [v2.0.0] — 2026-06-01
+
+### 🌍 Multi-Language Extension (Biggest Feature!)
+- **6-Language UI**: The browser extension is now fully translated into **English, German, French, Spanish, Portuguese (Brazilian), and Russian**. Switch languages instantly in Settings without reload.
+- **Real-Time i18n**: Every label, button, tooltip, toast notification, empty state, and onboarding guide updates dynamically when the language changes.
+
+### New Features
+- **Copy Debug Report (Markdown)**: The *Copy Logs* button in the Status tab now copies a fully formatted Markdown debug report — system info, connection status, video diagnostics, action history, and logs. One click, paste into a GitHub issue, all debugging data ready.
+- **Platform Auto-Detection**: The Dev tab now identifies streaming platforms (YouTube, Netflix, Twitch, Prime Video, Disney+, HBO Max, Vimeo, Dailymotion) and displays the detected platform.
+- **Enhanced Video Debug Info**: 20+ new fields in the Status tab including network state, buffered ranges, dimensions (with 0×0 warning), media error codes, shadow DOM status, seeking/ended/loop flags, volume, playback speed, and data attributes.
+- **No-Video Diagnostic Mode**: When no video is found, the Status tab shows platform, page title, video count, shadow DOM presence, and MediaSession data to help troubleshoot.
+
+### Changed
+- **New TwoPointZero Branding**: Updated extension icons (16/32/48/96/128px).
+- **Larger Popup Logo**: Extension popup icon increased to 48px.
+- **Prime Video Unblocked**: Removed `amazon.` from the tab blacklist so Amazon/Prime Video tabs appear in the video selector.
+- **Improved Debug Report**: Full User-Agent string for accurate browser identification, UTC timestamp, connection details including server URL and room info.
+- **Smart Disconnect**: Improved disconnect handling when leaving rooms.
+- **Human-Readable Room IDs**: Expanded word lists for friendlier room names.
+- **Custom Server Support**: WEB_JOIN_REQUEST and join button for custom server invite flows.
+- **Reconnection Strategy**: Custom server reconnection improvements.
+- **Episode-Aware Sync**: Command sequencing with smarter episode transition detection and echo suppression for smoother series binges.
+- **Sync Status Refinements**: YouTube and Twitch sync behavior improved.
+- **No External Dependencies**: Extension remains dependency-free with no library overhead.
+
+### Fixed
+- Hardcoded strings, missing translation keys, and Service Worker notification race conditions.
+
+---
+
+## Versioning Policy
+
+- **MAJOR** (x.0.0): Breaking protocol changes, architecture rewrites, or major feature milestones.
+- **MINOR** (0.x.0): New features, significant enhancements, new translations, or UI redesigns.
+- **PATCH** (0.0.x): Bug fixes, minor improvements, and documentation updates. PATCH releases may not receive individual changelog entries if bundled with a MINOR release.

docs/CHAT.md

@@ -0,0 +1,85 @@
+# Ephemeral end-to-end encrypted chat
+
+KoalaSync chat is an optional, live-only text channel rendered on the selected
+streaming tab. It is not a messenger and does not add chat UI to the extension
+popup.
+
+## Security boundary
+
+- The relay receives ciphertext only and never receives the chat secret.
+- The relay stores no messages in RAM or on disk and sends no backlog.
+- A late joiner sees only messages sent after joining.
+- Room authentication is unchanged. The room password remains separate from the
+  chat secret and continues to be sent to the relay during `join_room`.
+- Message timing and ciphertext length remain visible to the relay. Same-room
+  replay is accepted by the threat model.
+
+## Invite format and key lifecycle
+
+New invitations use a named fragment format:
+
+```text
+#j2:r=<roomId>&p=<password>&k=<base64url-secret>[&u=<relayUrl>]
+```
+
+The room creator generates 16 random bytes and encodes them as 22 unpadded
+base64url characters. URL fragments are not sent in HTTP requests. The website
+parses the fragment and passes structured fields through `bridge.js` to the
+extension. `chatKey` must never be included in a relay event.
+
+Legacy `#join:` links remain supported and join normally without chat. Manual
+room/password entry also joins without chat. The extension clears any prior chat
+secret when joining without a key, switching rooms, or leaving.
+
+Deployment order is website first, extension second. An old extension ignores the
+additional structured `chatKey` field and continues joining normally.
+
+## Cryptography
+
+- Secret: 16 cryptographically random bytes.
+- KDF: HKDF-SHA256 with `roomId` as salt and a fixed KoalaSync chat info label.
+- Encryption: AES-256-GCM using WebCrypto.
+- IV: fresh random 12-byte value for every message, prepended to the ciphertext.
+- AAD: `${roomId}|${senderId}`.
+- The derived `CryptoKey` is cached once per active room.
+
+The relay stamps `id`, `senderId`, and `timestamp` on the ciphertext envelope.
+Changing `senderId` causes AES-GCM authentication to fail because the receiver uses
+the stamped value as AAD.
+
+## Client policy
+
+- Maximum plaintext length: 500 Unicode code points.
+- Decrypted text is untrusted. Escape HTML before applying the supported limited
+  Markdown formatting.
+- No read receipts and no typing indicators.
+- The local message DOM is bounded; this is presentation state, not server history.
+
+## Overlay behavior
+
+- Default dock: right.
+- Live modes: right, left, and detached.
+- Detached mode is draggable and moderately resizable. Size and position are stored
+  per origin and clamped to the current viewport.
+- The overlay uses a Shadow DOM and never changes host-page layout.
+- On `fullscreenchange`, its host moves into `document.fullscreenElement` and remains
+  visible.
+- It follows all eucalyptus, cyber, and graphite light/dark theme combinations.
+- Without a key, the panel stays closed and a disabled chat control explains that a
+  current invite link is required.
+- Chat display is a local option and defaults to off. Enabling or disabling it never
+  deletes the room chat secret, so it can be enabled later without creating a room.
+- Without the relay `chat` capability, no chat control is shown.
+
+## Mixed-version rollout
+
+- New extensions announce `chat-v1` in `join_room.clientCapabilities`.
+- Old non-chat extensions omit the optional field and receive no `chat_message`
+  events. Their playback and room protocol remains unchanged.
+- The first chat beta omitted the capability. When it sends one valid v1 chat
+  frame, the relay treats that socket as chat-capable for the rest of the
+  connection.
+- New extensions accept the first beta's unversioned server `chat` capability as
+  well as `chat-v1`, so a server-first or extension-first rollout degrades safely.
+
+Peer removal and role management are outside chat scope.

docs/HOW_IT_WORKS.md

@@ -0,0 +1,213 @@
+# KoalaSync — How It Works (Step-by-Step)
+
+This guide walks through the complete user flow of KoalaSync, from creating a room to synchronized playback. It is designed for **store reviewers**, **end-users**, and **manual testers** to understand exactly what happens at each step, what data is sent, and where it goes.
+
+---
+
+## Step 1: Installing the Extension
+
+1. Download the extension from the [Releases](https://github.com/Shik3i/KoalaSync/releases) page (or install from the Chrome Web Store / Firefox Add-ons).
+2. The extension adds a small icon to your browser toolbar.
+3. On first install, a unique 8-character **Peer ID** is generated locally and stored in `chrome.storage.local`. This ID is never sent to any external service — it only travels to the relay server when you join a room.
+
+> **What's stored locally**: `peerId` (8-char hex), `username` (customizable, defaults to a readable adjective-noun pair), `serverUrl`, `filterNoise` preference. All stored via `chrome.storage.sync` and `chrome.storage.local`.
+
+---
+
+## Step 2: Connecting 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** (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.
+   - The server checks the **extension version** against `MIN_VERSION` to reject outdated clients.
+3. **Connection Established**: The server responds with an Engine.IO handshake (`0{...}`), followed by a Socket.IO namespace join (`40`). The connection status dot in the popup turns green.
+
+> **Data sent to server**: `token` (authentication), `version` (e.g., `1.3.1`). No personal data is transmitted during connection.
+
+---
+
+## Step 3: Creating a Room
+
+Click **"Create Room"** in the popup's Room tab:
+
+1. The extension generates a random Room ID (e.g., `happy-koala-42`) and a random 6-character password.
+2. Room IDs are restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only).
+3. The extension emits a `JOIN_ROOM` event to the server.
+
+> **Data sent in `JOIN_ROOM`**:
+> ```json
+> {
+>   "roomId": "happy-koala-42",
+>   "password": "x7k2m9",
+>   "peerId": "a1b2c3d4",
+>   "username": "MyName",
+>   "tabTitle": "YouTube - My Video",
+>   "protocolVersion": "1.0.0"
+> }
+> ```
+
+4. **Server-side processing**:
+   - All fields are **sanitized**: `roomId` is stripped of invalid characters and clamped to 64 chars; `peerId` clamped to 16 chars; `password` clamped to 128 chars; `username` clamped to 30 chars.
+   - The server **hashes the password** with a keyed SHA-256 HMAC and stores only that hash in RAM (the plaintext is never stored).
+   - A new room object is created in memory with the peer's data.
+   - The server responds with `ROOM_DATA` containing the list of peers in the room.
+
+5. **Popup updates**: The Room tab switches to the "Active Room" view, showing your Room ID and an invitation link.
+
+---
+
+## Step 4: Sharing an Invitation Link
+
+Click the **📋 Copy** button next to the invite link:
+
+1. The extension constructs a URL in this format:
+   ```
+   https://sync.koalastuff.net/join.html#join:<roomId>:<password>:<serverFlag>:<encodedServerUrl>
+   ```
+   - `serverFlag`: `0` for official server, `1` for custom server.
+   - `encodedServerUrl`: Only populated if using a custom server.
+   
+2. **Important**: The room credentials are in the **URL hash** (`#`), which means they are **never sent to the web server** — the hash fragment stays entirely in the browser. The landing page server never sees your room ID or password.
+
+3. Send this link to your friend via any messaging app.
+
+---
+
+## Step 5: Your Friend Opens the Invitation Link
+
+When your friend opens the link in their browser:
+
+1. **`join.html` loads** on `sync.koalastuff.net`. The page displays "INVITATION DETECTED" with the Room ID.
+
+2. **Extension detection**: The page checks for `document.documentElement.dataset.koalasyncInstalled`, which is set by `bridge.js` (a content script injected only on `sync.koalastuff.net`).
+
+3. **If the extension IS installed**:
+   - The page shows "Joining room automatically..."
+   - After 500ms, the page dispatches a `KOALASYNC_JOIN_REQUEST` custom DOM event with `{ roomId, password, useCustomServer, serverUrl }`.
+   - `bridge.js` catches this event and forwards it to `background.js` via `chrome.runtime.sendMessage`.
+   - `background.js` stores the credentials in `chrome.storage.sync` and emits `JOIN_ROOM` to the server.
+   - The server validates the password against the stored keyed SHA-256 HMAC hash.
+   - On success, the server responds with `ROOM_DATA` and broadcasts `PEER_STATUS { status: 'joined' }` to all existing peers.
+   - The join page updates to show "✅ Successfully joined!".
+
+4. **If the extension is NOT installed**:
+   - The page shows download links (Chrome Web Store / GitHub).
+   - The user installs the extension, returns to the link, and the flow continues from step 3.
+
+---
+
+## Step 6: Selecting a Video Tab
+
+Both users now need to select which browser tab contains the video to sync:
+
+1. Open a video on any website (YouTube, Twitch, Netflix, etc.).
+2. In the extension popup → **Sync** tab → use the **"Target Tab"** dropdown.
+3. The dropdown lists all open tabs, filtered to exclude noise (search engines, social media — configurable via Settings).
+4. Tabs with a **matching video title** are highlighted with a ⭐ prefix for easy identification.
+5. Selecting a tab causes `background.js` to set `currentTabId` and inject `content.js` into that tab via `chrome.scripting.executeScript`.
+
+> **What `content.js` does on injection**: Finds the first `<video>` element on the page and attaches event listeners for `play`, `pause`, `seeked`, and `loadeddata`. (Time and volume state are tracked via a 15-second heartbeat interval, not continuous event listeners). It uses an `expectedEvents` Set to distinguish between user actions and programmatic actions (loop prevention).
+
+---
+
+## Step 7: Synchronized Playback
+
+When User A presses **Play** on their video:
+
+1. `content.js` detects the native `play` event on the `<video>` element.
+2. It checks the `expectedEvents` Set — if this event was expected (caused by a remote command), it's consumed silently. If not, it's a **user action**.
+3. For user actions, `content.js` sends `{ type: 'CONTENT_EVENT', action: 'play', payload: { currentTime, ... } }` to `background.js`.
+4. `background.js` adds an `actionTimestamp` and emits the `PLAY` event to the server.
+5. **Server relay**: The server sanitizes all fields (strings clamped, numbers validated, booleans type-checked) and constructs a clean `relayPayload` with `senderId` set to User A's `peerId`. The raw client data is never forwarded directly.
+6. The server broadcasts the sanitized payload to all other peers in the room.
+7. User B's `background.js` receives the `PLAY` event and calls `routeToContent()`, which sends a `SERVER_COMMAND` message to User B's `content.js`.
+8. User B's `content.js` adds `'playing'` to its `expectedEvents` Set (so it won't echo the event back), then calls `video.play()`.
+
+> **The same flow applies to Pause and Seek**, with Seek additionally sending `targetTime` for the time position.
+
+---
+
+## Step 8: Force Sync (Two-Phase Protocol)
+
+If videos drift out of sync, either user can click **"Force Sync"**:
+
+### Phase 1 — Prepare
+1. The initiator's `content.js` captures the current `video.currentTime` as the `targetTime`.
+2. `background.js` emits `FORCE_SYNC_PREPARE` with `{ targetTime }` to all peers.
+3. All peers (including the initiator) **pause** their video and **seek** to `targetTime`.
+4. Each peer's `content.js` polls `video.readyState` until it reaches `≥ 3` (buffered enough to play), with an 8-second timeout.
+5. Once buffered, each peer sends `FORCE_SYNC_ACK` back.
+
+### Phase 2 — Execute
+6. Once all ACKs are received (or after 8.5 seconds), the initiator emits `FORCE_SYNC_EXECUTE`.
+7. All peers call `video.play()` simultaneously, achieving synchronized playback.
+
+> **Why two phases?** Without buffering confirmation, peers with slower connections would start playing before they've loaded the target timestamp, causing immediate desync.
+
+---
+
+## Step 9: Heartbeat & Peer Health
+
+While in a room, two heartbeats keep the session alive:
+
+| Heartbeat | Interval | Source | Purpose |
+|:----------|:---------|:-------|:--------|
+| **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`, privacy-filtered `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").
+- **Room Cleanup**: Empty rooms are deleted immediately. Inactive rooms are pruned after 2 hours.
+
+---
+
+## Step 10: Leaving a Room
+
+When a user clicks **"Leave"** or closes their browser:
+
+1. `background.js` emits `LEAVE_ROOM` (or the WebSocket `disconnect` fires automatically).
+2. The server calls `removePeerFromRoom()`, which:
+   - Removes the peer from the room's `peers` Set, `peerIds` Map, and `peerData` Map.
+   - Removes the socket from the global `socketToRoom` and `peerToSocket` maps.
+   - Broadcasts `PEER_STATUS { status: 'left' }` to remaining peers.
+   - If the room is now empty, **deletes the room entirely** — no data persists.
+3. The event rate-limit counter for that socket is also cleaned up.
+
+> **After disconnect, zero data about the user remains on the server.** There is no database, no log file, no analytics record. The session existed only in RAM and is now gone.
+
+---
+
+## Episode Auto-Sync Flow
+
+When watching a series and an episode ends:
+
+1. `content.js` monitors the [Media Session API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API) for title changes.
+2. When a new title is detected, the peer broadcasts `EPISODE_LOBBY` with the expected title after applying the local media title privacy setting. In episode-only mode this is an identifier such as `S01E04`; when media titles are not sent, the client does not create a new episode lobby.
+3. All peers' videos freeze. The UI shows an "Episode Lobby" card with peer readiness status.
+4. Each peer's `content.js` polls for the new title to appear in the `<video>` element's metadata.
+5. Once a peer detects the matching title, they send `EPISODE_READY`.
+6. When all peers report ready, the lobby resolves and playback resumes simultaneously.
+
+---
+
+## Data Flow Summary
+
+```
+┌─────────────┐     WebSocket      ┌──────────────┐     WebSocket      ┌─────────────┐
+│  Extension  │ ←─────────────────→│  Relay Server │←──────────────────→│  Extension  │
+│  (User A)   │   JOIN_ROOM        │  (RAM only)   │   JOIN_ROOM        │  (User B)   │
+│             │   PLAY/PAUSE/SEEK  │               │   PLAY/PAUSE/SEEK  │             │
+│             │   FORCE_SYNC_*     │  Sanitizes &  │   FORCE_SYNC_*     │             │
+│             │   PEER_STATUS      │  relays only  │   PEER_STATUS      │             │
+│             │   EPISODE_*        │               │   EPISODE_*        │             │
+└──────┬──────┘                    └───────────────┘                    └──────┬──────┘
+       │                                                                      │
+  ┌────┴─────┐                                                          ┌─────┴────┐
+  │ content  │  Listens to <video> events                               │ content  │
+  │   .js    │  Controls playback                                       │   .js    │
+  └──────────┘                                                          └──────────┘
+```
+
+> **The relay server is a pure message forwarder.** It never interprets video content, accesses URLs, or stores session history. All media control happens locally inside each user's browser via the `<video>` DOM API.

docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,104 @@
+# Known Limitations & Accepted Non-Issues (NOFIX)
+
+This file records design decisions that are **intentional** and **out of scope** for
+KoalaSync's threat model. They are frequently re-discovered by reviewers, linters, and
+AI agents and re-reported as "bugs" or "vulnerabilities." They are not. Please read the
+threat model below before flagging any of them.
+
+> **For reviewers & agents:** Do **not** re-report the NOFIX items below. They are
+> deliberate. If you think the *threat model itself* should change (e.g. KoalaSync
+> starts handling accounts, payments, or sensitive data), raise **that** discussion
+> first — these items only stand because the threat model holds.
+
+---
+
+## Threat model
+
+KoalaSync is a **privacy-preserving watch-party sync tool**, not a security product.
+
+- **Rooms are ephemeral.** They exist for a few hours and are auto-reaped. There are no
+  accounts, no persistent storage, no money, and no sensitive content on the relay.
+- **The relay is a zero-persistence, in-memory message bus.** It temporarily holds room
+  and peer state while forwarding play/pause/seek between peers who *chose* to watch
+  together and joined via an invite link shared out-of-band.
+- **Participants are invited.** Anyone in a room was let in. The social contract is
+  "we're watching a video together," not "mutually distrusting parties."
+
+### What we DO defend against
+- **Accidental disruption** — the entire point of Host Control Mode.
+- **Spam / DoS** that degrades the relay for everyone — rate limits, 4 KB payload cap,
+  server-side gating, lazy-cached health responses.
+- **Resource exhaustion / memory leaks** — bounded maps, periodic cleanup, room/peer reaping.
+- **Crashes from malformed input** — strict sanitization and clamping of every field.
+- **Genuine boundary breaches** — admin-metrics auth (constant-time), CORS, WSS upgrade,
+  invite-hash isolation, strict CSP. Reports here are very welcome (see `SECURITY.md`).
+
+### What we explicitly DO NOT defend against
+A **determined participant who modifies their own client to misbehave inside a room they
+were invited to.** The worst they achieve is sending playback commands or seizing the
+"host" role in a temporary room they could already disrupt by other means. That is a
+**social** problem, solved socially: kick them, or start a new room. Engineering real
+identity/auth to prevent it would destroy the account-less, frictionless, privacy-first
+design — a bad trade for an ad-hoc movie night.
+
+---
+
+## NOFIX entries
+
+### NOFIX-1 — `peerId` is unauthenticated; a crafted client can impersonate or seize the host
+**Flag:** `peerId` is client-asserted and broadcast to every peer (in `ROOM_DATA` /
+`PEER_STATUS`). A modified client can join with the host's `peerId`, dedupe-kick the real
+host, and become host — controlling or locking `host-only` mode.
+
+**Why NOFIX:** Requires a *modified client* + an *invited* participant + a `peerId` that is
+only meaningful inside that one *temporary* room. The payoff is sending play/pause or
+locking a room the attacker is already in — pure trolling, instantly reversible (kick /
+new room). Cryptographic per-user identity is wildly disproportionate for an ad-hoc,
+account-less, ephemeral watch party. **Out of threat model.**
+Do **not** "fix" with accounts, signed peerIds, or per-user tokens — that breaks the
+core design.
+
+### NOFIX-2 — Room-password comparison is not constant-time
+**Flag:** room password hashes are compared with `!==` (`server/index.js`), so the compare
+is theoretically timing-attackable.
+
+**Why NOFIX:** The compared value is an **HMAC-SHA256 hash that never leaves the server** —
+an attacker cannot observe it to mount a timing attack. Even a hypothetical success only
+lets someone join a *temporary* room to send playback commands. Not worth defending.
+(The admin-metrics bearer token — a real boundary — **does** use `crypto.timingSafeEqual`.
+That is the line we actually guard.)
+
+### NOFIX-3 — `OFFICIAL_SERVER_TOKEN` is public in the repo
+**Flag:** the connection token in `shared/constants.js` is committed, so anyone can connect.
+
+**Why NOFIX:** It is a **coarse filter** to keep random scanners off the relay, **not
+authentication**. The relay is a public message bus by design; rate limits and per-room
+behavior are the real protections.
+
+### NOFIX-4 — Room IDs are enumerable via `GET_ROOMS`
+**Flag:** any connected client can list all room IDs (and whether each has a password).
+
+**Why NOFIX:** This is the intended **"Public Rooms"** feature. Rooms wanting privacy set a
+password; listing the IDs of password-less rooms only lets someone join a watch party —
+the same as being handed the invite link.
+
+### NOFIX-5 — A pause/seek can only be reverted, not prevented
+**Flag:** in `host-only` mode a guest's pause still fires locally before the extension can
+react, so there is a brief flicker before snap-back.
+
+**Why NOFIX:** A content script cannot intercept a `<video>` event before the element
+acts. Reacting (snap-back) is the only option and is by design; the ~½s flicker is
+acceptable. Not a bug.
+
+---
+
+## Not NOFIX — just deferred (may be revisited)
+
+These are *not* accepted-forever; they are scoped out of v1 and tracked separately
+(see the host-control-mode design docs in `docs/`):
+
+- **Host grace on a long disconnect (EC-10).** A brief reconnect/second-tab keeps the host
+  (handled), but a long real disconnect still falls back to `everyone`. A ~30s host-reserve
+  grace could be added later.
+- **Intent-classifier / snap-back tuning.** Thresholds are first-pass; real-device testing
+  may adjust them.

docs/PRIVACY.md

@@ -0,0 +1,51 @@
+# Privacy Policy
+
+**KoalaSync does not collect, store, or sell any personal data.**
+
+*We don't track you. We only track our server* (relying exclusively on aggregated, anonymous, and non-personal system metrics to monitor performance and stability).
+
+KoalaSync is designed with a **Security-First & Volatile** architecture. This means we prioritize keeping your data out of persistent storage, though certain technical data must be processed temporarily to ensure service stability and security.
+
+## 1. Data Processing (In-Memory Only)
+KoalaSync does not use a database. All active session data exists only in the server's RAM and is purged immediately when no longer needed.
+- **Session Data**: To synchronize playback, the server must temporarily hold your `peerId` and `username`. By default, KoalaSync also shares the selected tab title and media title with the room so peers can identify matching videos and coordinate episode transitions. Privacy Settings let you disable sending the tab title separately, and choose whether media titles are sent in full, reduced to a detected episode identifier (for example `S01E04`), or not sent. Playback metadata (`playbackState`, `currentTime`, `volume`, `muted`) is held per peer for the duration of the session. All of this is deleted as soon as you leave the room.
+- **Room Passwords**: If you set a room password, it is stored only as an in-memory **keyed SHA-256 HMAC hash**. The server receives the plaintext password only during join validation, never stores it, and keeps only the hash for the short room lifetime.
+- **Routing Maps**: The server maintains ephemeral lookup tables (`socketToRoom`, `peerToSocket`) to route messages between peers. These contain only transport identifiers and are purged on disconnect.
+
+### Data Retention
+| Data Type | Maximum Retention | Trigger for Deletion |
+|:----------|:------------------|:---------------------|
+| Session data (peerId, username, video metadata) | Duration of session | User leaves room or disconnects |
+| Room state | 2 hours max | Last peer leaves, or inactivity timeout |
+| Auth failure records (lockout after 5 failed attempts) | 15 minutes | Periodic cleanup |
+| Connection rate-limit counters | 60 seconds | Automatic expiry |
+| Event rate-limit counters | 10 seconds | Automatic expiry + periodic cleanup |
+
+## 2. Security & Rate Limiting
+To prevent abuse and brute-force attacks, the following data is processed:
+- **Brute-Force Protection**: If multiple failed password attempts are detected, the server stores the `IP address` and `Room ID` in a temporary RAM-based lockout list for a maximum of 15 minutes.
+- **Connection Rate Limiting**: IP addresses are tracked for 60 seconds to prevent connection-flooding (DoS) attacks.
+- **Event Rate Limiting**: Per-socket event counters are tracked for 10-second windows to prevent event-spamming. These are keyed by ephemeral socket IDs and cleaned up periodically.
+- **Console Logging**: The official relay server (`syncserver.koalastuff.net`) outputs connection events (including IP addresses) to the server console for real-time monitoring. These logs are ephemeral and are not archived, sold, or linked to any persistent user identity.
+
+## 3. Extension Permissions
+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 (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.
+
+## 4. Zero Third-Party Requests
+KoalaSync is completely self-contained:
+- **No CDNs or External Libraries**: All scripts and styles are self-hosted.
+- **No Analytics**: We do not use Google Analytics, tracking pixels, or any third-party telemetry.
+- **No External Fonts**: We use system font stacks to prevent tracking via font services.
+
+## 5. Self-Hosted Instances
+This privacy policy applies to the **official KoalaSync relay server** at `syncserver.koalastuff.net`. If you choose to self-host a relay server using our open-source Docker image, the data handling practices of that instance are the responsibility of the server operator.
+
+---
+
+**Auditable & Open Source**: Because KoalaSync is open source, you can verify these claims by reviewing the [Server Source Code](https://github.com/Shik3i/KoalaSync/blob/main/server/index.js) and the [Extension Logic](https://github.com/Shik3i/KoalaSync/blob/main/extension/content.js).

docs/PROTOCOL.md

@@ -0,0 +1,428 @@
+# WebSocket Protocol Reference
+
+This document describes the relay behavior implemented by `server/index.js` and
+the event names defined in `shared/constants.js`.
+
+## Transport
+
+- The relay uses Socket.IO v4 events over WebSocket.
+- Long-polling is disabled (`transports: ['websocket']`, `allowUpgrades: false`).
+- Messages are Socket.IO event packets whose payload is an event name plus an
+  object payload.
+- The relay caps incoming Socket.IO message size at 4 KB.
+
+## Invite fragments
+
+Current invitations use named URL-fragment fields:
+
+```text
+#j2:r=<roomId>&p=<password>&k=<base64url-chat-secret>[&u=<relayUrl>]
+```
+
+The fragment is parsed by the website and forwarded to the extension as structured
+fields. `k` is client-only and must never appear in a relay payload. Legacy
+`#join:<roomId>:<password>[:1:<relayUrl>]` fragments remain valid but provide no chat
+secret.
+
+## Connection Handshake
+
+The Socket.IO handshake must include:
+
+- `token`: must match `OFFICIAL_SERVER_TOKEN`.
+- `version`: optional app version. If present, it must be a valid semver-like
+  string and not older than `MIN_VERSION` (default `1.0.0`).
+
+If the token is invalid, the relay emits `error` and disconnects the socket.
+If `version` is invalid or too old, the relay emits `error` and disconnects the
+socket.
+
+After the socket is connected, `join_room` must include `protocolVersion`.
+It must equal `PROTOCOL_VERSION` exactly. A mismatch emits `error` and rejects
+the join attempt; it does not currently disconnect the socket.
+
+## Room Join
+
+### `join_room` (client -> server)
+
+Payload:
+
+```json
+{
+  "roomId": "string, sanitized to [A-Za-z0-9-], max 64",
+  "peerId": "string, max 16",
+  "username": "string, max 30",
+  "password": "string, max 128, optional",
+  "tabTitle": "string, max 100, optional",
+  "mediaTitle": "string, max 100, optional",
+  "clientCapabilities": ["chat-v1"],
+  "protocolVersion": "string, max 16"
+}
+```
+
+Behavior:
+
+- Creates the room if it does not exist and capacity allows it.
+- The first peer becomes `hostPeerId`.
+- Rooms may have an optional password hash.
+- Joining with a duplicate `peerId` disconnects the previous socket for that peer.
+- Joining the same room with the same socket and peer is ignored as a no-op.
+- Switching rooms removes the socket from the old room first.
+
+On success, the joining socket receives `room_data`.
+Other room members receive `peer_status` with `status: "joined"`.
+
+### `room_data` (server -> client)
+
+Payload:
+
+```json
+{
+  "roomId": "string",
+  "peers": ["peer state objects"],
+  "activeLobby": "object or null",
+  "hostPeerId": "string or null",
+  "controlMode": "everyone | host-only",
+  "controllers": ["peerId"],
+  "capabilities": ["host-control", "co-host", "chat", "chat-v1"]
+}
+```
+
+`room_data` is sent to the joining socket. It is not the general broadcast used
+for every later room update.
+
+## Ephemeral encrypted chat
+
+Relays advertise chat support with `"chat-v1"` in `room_data.capabilities` and keep
+the initial beta's `"chat"` flag during the transition. New clients announce
+`"chat-v1"` in optional `join_room.clientCapabilities` (at most the first 16 entries
+are inspected; unknown or malformed values are ignored). Old clients omit the field
+and continue using the pre-chat protocol unchanged.
+
+The relay sends `chat_message` only to sockets that announced `"chat-v1"`. As a
+transition for the first chat beta, a socket that sends a valid v1 ciphertext is
+marked capable for the rest of that connection. This prevents old non-chat
+extensions from receiving unknown events while preserving the first beta's send
+path.
+
+### `chat_message`
+
+Client to relay:
+
+```json
+{ "ciphertext": "<unpadded-base64url>" }
+```
+
+`ciphertext` contains a 12-byte AES-GCM IV followed by ciphertext and the 16-byte
+authentication tag. The relay validates only canonical base64url and byte bounds.
+It cannot inspect plaintext.
+
+Relay to every chat-capable current room peer, including the sender:
+
+```json
+{
+  "id": "<server-generated UUID>",
+  "senderId": "<server-stamped peer ID>",
+  "timestamp": 1710000000000,
+  "ciphertext": "<unpadded-base64url>"
+}
+```
+
+Client-provided `id`, `senderId`, `timestamp`, or plaintext fields are discarded.
+The relay keeps no message collection and `room_data` contains no chat history.
+Messages are limited to 10 per socket per 10 seconds in addition to the global event
+budget. There are no typing, read-receipt, history, or chat-specific peer-management
+events.
+
+## Room Leave
+
+### `leave_room` (client -> server)
+
+Payload: none.
+
+Behavior:
+
+- Rate-limited to 10 events per socket per minute.
+- If the socket is mapped to a room, the relay removes it from that room.
+- Remaining room members receive `peer_status` with `status: "left"` when the
+  peer is no longer represented by another socket.
+- Empty rooms are deleted.
+- If the host leaves and peers remain, the relay assigns the next peer as host,
+  falls back to `controlMode: "everyone"`, resets controllers to the new host,
+  and broadcasts `control_mode`.
+
+Exceeding the `leave_room` limit is logged and the socket is disconnected.
+
+## Relayed Room Events
+
+The relay accepts and sanitizes these events, then emits the same event to other
+peers in the room:
+
+- `play`
+- `pause`
+- `seek`
+- `peer_status`
+- `force_sync_prepare`
+- `force_sync_ack`
+- `force_sync_execute`
+- `episode_lobby`
+- `episode_ready`
+- `episode_lobby_cancel`
+
+Relayed payload fields are sanitized and may include:
+
+```json
+{
+  "senderId": "peerId of sender",
+  "seq": "number",
+  "currentTime": "number 0..86400 or null",
+  "targetTime": "number 0..86400",
+  "playbackState": "playing | paused",
+  "username": "string, max 30",
+  "tabTitle": "string, max 100 or null",
+  "mediaTitle": "string, max 100 or null",
+  "volume": "number 0..1",
+  "muted": "boolean",
+  "desynced": "boolean",
+  "peerId": "sender peerId",
+  "status": "string, max 16",
+  "expectedTitle": "string, max 100",
+  "title": "string, max 100",
+  "actionTimestamp": "number"
+}
+```
+
+Undefined fields are removed before relay. Raw client payloads are not forwarded.
+
+## Media Control
+
+### `play`, `pause`, `seek`
+
+These are room-moving actions. In `host-only` mode, the relay drops them unless
+the sender is a controller.
+
+Common payload fields:
+
+- `currentTime` for `play`/`pause`.
+- `targetTime` for `seek`.
+- `seq` and `actionTimestamp` when the extension needs stale-command or ACK
+  handling.
+
+The content script applies additional client-side filtering for noisy native
+player events before it sends these events.
+
+## Peer Status
+
+### `peer_status`
+
+Used for heartbeats and peer state updates. The extension sends it every
+`HEARTBEAT_INTERVAL` while syncing is active.
+
+Typical fields:
+
+- `peerId`
+- `username`
+- `tabTitle`
+- `mediaTitle`
+- `playbackState`
+- `currentTime`
+- `volume`
+- `muted`
+- `desynced`
+- `status`
+
+The relay stores sanitized peer state and relays the sanitized update to other
+peers.
+
+## Force Sync
+
+Force sync coordination is implemented primarily in the extension. The relay
+sanitizes and relays the events.
+
+### `force_sync_prepare`
+
+Payload includes `targetTime`. The initiator waits for ACKs or for
+`FORCE_SYNC_TIMEOUT` before sending `force_sync_execute`.
+
+In `host-only` mode, only controllers may initiate it.
+
+### `force_sync_ack`
+
+The extension sends ACKs with peer identity and sequence data. The relay relays
+them with the same sanitized relay envelope as other room events, including
+`senderId`.
+
+### `force_sync_execute`
+
+Payload includes `targetTime`. In `host-only` mode, only controllers may send it.
+The relay also allows a matching initiator's execute event after that initiator
+started the prepare step, even if their controller state changed before execute.
+
+## Episode Lobby
+
+Episode lobby coordination is implemented primarily in the extension. The relay
+tracks enough state to include `activeLobby` in `room_data` for later joiners.
+
+### `episode_lobby`
+
+Payload uses `expectedTitle`. The relay creates `activeLobby` when this field is
+present and no lobby is already active.
+
+In `host-only` mode, only controllers may initiate it.
+
+### `episode_ready`
+
+Payload may include `title`. The relay adds the sender to the active lobby's
+ready list when a lobby exists.
+
+### `episode_lobby_cancel`
+
+Clears the active lobby and is relayed to peers. In `host-only` mode, only
+controllers may initiate it.
+
+## Host Control Mode
+
+### `set_control_mode` (client -> server)
+
+Payload:
+
+```json
+{
+  "controlMode": "everyone | host-only"
+}
+```
+
+Only the room host may change the mode. Non-host attempts are ignored and the
+sender receives the current `control_mode` snapshot.
+
+Mode changes are debounced per room with `CONTROL_MODE_MIN_INTERVAL_MS` (500 ms).
+
+### `set_peer_role` (client -> server)
+
+Payload:
+
+```json
+{
+  "peerId": "string, max 16",
+  "controller": "boolean"
+}
+```
+
+Only the room host may promote or demote controllers. The host cannot demote
+themself. Role changes use the same 500 ms per-room debounce as mode changes.
+
+### `control_mode` (server -> client)
+
+Payload:
+
+```json
+{
+  "controlMode": "everyone | host-only",
+  "hostPeerId": "string or null",
+  "controllers": ["peerId"]
+}
+```
+
+Sent when mode or controller state changes, when host migration changes room
+authority, and when unauthorized role/mode attempts need to resync the sender.
+
+## Room List
+
+### `get_rooms` (client -> server)
+
+Payload: none.
+
+No admin token is required for this Socket.IO event.
+
+Limits:
+
+- Counts against the per-socket event limit.
+- Also has a 10 second per-socket cooldown.
+
+### `room_list` (server -> client)
+
+Payload:
+
+```json
+{
+  "rooms": [
+    {
+      "id": "room id",
+      "peerCount": 2,
+      "hasPassword": false
+    }
+  ]
+}
+```
+
+## Ping, Pong, and ACK
+
+### `ping`
+
+Payload:
+
+```json
+{
+  "t": 1234567890,
+  "target": "peerId, optional"
+}
+```
+
+If `target` is omitted, the relay responds to the sender with `pong`.
+If `target` is another peer in the same room, the relay sends `ping` to that peer
+with `{ "t": ..., "sender": "senderPeerId" }`.
+
+### `pong`
+
+Payload:
+
+```json
+{
+  "t": 1234567890,
+  "target": "peerId, optional"
+}
+```
+
+If `target` is a peer in the same room, the relay sends `pong` to that peer with
+`{ "t": ... }`.
+
+### `event_ack`
+
+Client payload:
+
+```json
+{
+  "targetId": "peerId",
+  "actionTimestamp": 1234567890
+}
+```
+
+If sender and target are still in the same room, the relay emits:
+
+```json
+{
+  "senderId": "sender peerId",
+  "actionTimestamp": 1234567890
+}
+```
+
+## Rate Limits
+
+- Connections: 10 per IP per minute; excess connections are disconnected.
+- Relayed/events: 50 per socket per 10 seconds; excess disconnects the socket.
+- `get_rooms`: 10 second cooldown per socket plus the event limit.
+- `leave_room`: 10 per socket per minute; excess disconnects the socket.
+- Invalid room passwords: tracked per IP and room. Five recent failures block
+  more password attempts for that room until the failure window ages out.
+- HTTP health and admin-metrics endpoints have their own rate limits outside this
+  Socket.IO protocol.
+
+## Capabilities
+
+`room_data.capabilities` advertises server-backed features:
+
+- `host-control`
+- `co-host`
+- `chat`
+- `chat-v1`
+
+Clients should treat a missing or unknown capabilities list as unsupported.

docs/README.md

@@ -0,0 +1,40 @@
+# Technical Documentation
+
+This directory contains deep-dives into the KoalaSync protocol, architecture, roadmap, and operational guidelines.
+
+## Start Here by Role
+
+- **Users and reviewers**: Start with [HOW_IT_WORKS.md](HOW_IT_WORKS.md), then [PRIVACY.md](PRIVACY.md) and [TESTED_SERVICES.md](TESTED_SERVICES.md).
+- **Self-hosters**: Start with the root [README.md](../README.md), then [devops.md](devops.md), [PROTOCOL.md](PROTOCOL.md), and the examples in `../examples/`.
+- **Contributors**: Start with [../CONTRIBUTING.md](../CONTRIBUTING.md), then [ARCHITECTURE.md](ARCHITECTURE.md), [SYNC_GUIDE.md](SYNC_GUIDE.md), and the README for the subdirectory you are editing.
+- **AI agents**: Start with [AI_INIT.md](AI_INIT.md), then read the relevant subdirectory README before changing files.
+- **Security reviewers**: Start with [SECURITY.md](../SECURITY.md), [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md), [PRIVACY.md](PRIVACY.md), and [PROTOCOL.md](PROTOCOL.md).
+
+## 🏗️ Core Architecture & Design
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)**: Overview of the communication flows, Dual Heartbeat architecture, and synchronization logic.
+- **[HOW_IT_WORKS.md](HOW_IT_WORKS.md)**: Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
+- **[host-control-mode.md](host-control-mode.md)**: Design, requirements, and edge cases of the Host Control feature.
+- **[AI_INIT.md](AI_INIT.md)**: Maintainer and AI-agent onboarding: non-negotiables, workflow order, and safety checks.
+
+## 📡 Protocol & Synchronization
+
+- **[PROTOCOL.md](PROTOCOL.md)**: Low-level message format and payload descriptions for the KoalaSync sync protocol.
+- **[SYNC_GUIDE.md](SYNC_GUIDE.md)**: Guide on keeping protocol constants synchronized across the workspace.
+
+## 📋 Compatibility, Roadmap & Contribution
+
+- **[TESTED_SERVICES.md](TESTED_SERVICES.md)**: Status of compatibility with major streaming services and contribution guidelines for testing new platforms.
+- **[KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md)**: Threat model and accepted design limitations (NOFIX entries) for security audits.
+- **[PRIVACY.md](PRIVACY.md)**: Privacy model and data-handling policy for users, reviewers, and contributors.
+- **[ROADMAP.md](ROADMAP.md)**: Planned features, backlog items, and rejected proposals.
+- **[TRANSLATION.md](TRANSLATION.md)**: Guide for native speakers to contribute and audit dynamic extension/website translations.
+
+## 🚀 DevOps & Releases
+
+- **[devops.md](devops.md)**: Guide on the automated tag-based release pipeline.
+- **[CHANGELOG.md](CHANGELOG.md)**: Detailed history of releases and changes.
+
+---
+
+*For high-level project information and developer setup instructions, refer to the root [README.md](../README.md).*

docs/ROADMAP.md

@@ -0,0 +1,154 @@
+# KoalaSync Roadmap
+
+> Feature priorities, planned work, backlog, and rejected ideas for KoalaSync.
+
+---
+
+## Status Legend
+
+| Badge | Meaning |
+|---|---|
+| 🚧 In Progress | Currently being developed |
+| 📋 Planned | Prioritized for an upcoming phase |
+| 💡 Backlog | Under evaluation, not yet prioritized |
+| ❌ Rejected | Declined (with rationale) |
+| ✅ Completed | Shipped |
+
+---
+
+## 🚧 In Progress
+
+*Currently being worked on.*
+
+| Feature | Priority | Area |
+|---|---|---|
+| *(none yet)* | | |
+
+---
+
+## 📋 Planned
+
+*Prioritized for upcoming phases.*
+
+### v3.0 — Modern Room Chat
+
+- **Release date:** Not scheduled
+- **Priority:** P1
+- **Category:** Social / Communication / Privacy
+- **Status:** Planned. This is a roadmap target, not a release announcement.
+- **Existing foundation:** Opt-in, live-only end-to-end encrypted room chat; a floating
+  chat bubble over the selected player opens a dockable, detachable, resizable overlay.
+  The relay stores no chat history and mixed extension versions use capability-gated
+  delivery.
+
+#### Core experience
+
+- Floating bubble with an accessible unread badge (`1`, `2`, `3`, …, `99+`), cleared
+  only when the chat is actually viewed.
+- Subtle new-message pulse with reduced-motion support; no animation or sound while
+  muted or during Do Not Disturb.
+- Drag-and-snap bubble positioning, remembered per site, with reset-to-default.
+- Dock left/right, detached overlay, compact mode, fullscreen-safe placement, responsive
+  narrow-player layout, and keyboard-only operation.
+- Per-room mute, mention-only mode, notification sound controls, browser notifications,
+  and a visible mute state.
+- Unread state survives overlay close/reopen and tab focus changes, but room messages
+  remain memory-only unless a future storage option is explicitly enabled.
+
+#### Messaging
+
+- Replies with quoted context, emoji reactions, emoji picker, mentions, and typing
+  indicators.
+- Edit and delete own messages with clear local tombstones; no silent mutation.
+- Delivery states (`sending`, `sent`, `failed`, `retry`) with idempotent retries and
+  duplicate suppression after reconnects.
+- Message timestamps, date separators, jump-to-latest, unread divider, search within
+  the current live session, copy, and selectable text.
+- Link detection with safe external opening, explicit scheme allowlist, and no automatic
+  previews or remote-media loading.
+- Optional image/GIF/file sharing only after encrypted size limits, malware-risk UX,
+  relay bandwidth limits, and privacy behavior are designed and tested.
+
+#### Presence, safety, and control
+
+- Online/reconnecting status, join/leave events, and room-member presence without
+  exposing IP addresses or cross-room identity.
+- Local mute/block, host moderation controls, slow mode, spam limits, and configurable
+  maximum message length.
+- Optional read receipts and activity indicators default off; never infer or expose
+  viewing behavior without explicit consent.
+- Clear live-only/no-history explanation, encrypted-chat indicator, room-key fingerprint,
+  and key-rotation/rejoin UX.
+
+#### Reliability and compatibility
+
+- Versioned chat capabilities for every new wire feature; unknown fields/events remain
+  harmless to older extensions and old non-chat clients receive no chat traffic.
+- Server-first and extension-first rollout tests, including current, first-chat-beta,
+  old non-chat, reconnect, duplicate-frame, and malformed-capability clients.
+- Bounded queues, payloads, unread counters, typing events, reactions, and attachment
+  metadata; backpressure and rate limits on both client and relay.
+- Real Chrome and Firefox extension E2E coverage for bubble, unread count, overlay,
+  fullscreen, reconnect, and mixed-version rooms before v3.0 can ship.
+
+#### Accessibility and localization
+
+- Screen-reader announcements that do not read every busy-room message by default.
+- Complete focus management, logical tab order, Escape behavior, high contrast,
+  zoom/reflow, reduced motion, and touch target coverage.
+- All chat UI, notification text, moderation states, and errors localized across every
+  supported locale before release.
+
+#### Explicit non-goals for the first v3.0 release
+
+- No server-readable plaintext.
+- No mandatory accounts, public room directory, advertising, tracking, or presence
+  across rooms.
+- No unencrypted server-side history. Any future encrypted history requires a separate
+  threat model, retention controls, export/delete behavior, and explicit opt-in.
+
+### 2. Invite link with target URL for auto-redirect
+
+- **Priority:** P2
+- **Category:** UX / Ease of Sharing
+- **Background:** The invite link currently only contains the room ID. The invited person has to manually open the page. Ideally, the link would include the shared tab's URL so the invitee gets redirected to the right page and the tab is auto-selected (auto-matching via tab title already exists).
+- **Known challenges:**
+  - Many streaming sites (e.g., Emby, Jellyfin) don't have unique URLs per content — once inside the player, the URL stays the same.
+  - Dozens of such edge cases exist; a generic solution is difficult.
+  - Would likely need site-specific extractor logic (similar to the existing sync service adapters).
+- **Possible approaches:**
+  - Fallback: if no unique URL can be determined, only pass the tab title.
+  - Site-specific URL extraction for known services.
+
+---
+
+## 💡 Backlog
+
+*Ideas and feature requests under evaluation.*
+
+### Cross-frame video detection and control
+
+- **Priority:** P3
+- **Category:** Compatibility / Embedded Players
+- **Background:** KoalaSync currently injects on demand into the selected tab's top frame. This works for normal top-frame players, including current Emby/Jellyfin usage, but does not cover cases where the real `<video>` lives inside a cross-origin iframe or an `about:blank`/`srcdoc` player frame.
+- **Possible approach:** Add an opt-in frame bridge where child frames announce detected videos to the top frame, and the top frame routes remote play/pause/seek commands to the active child video.
+- **Status:** Future compatibility work, not needed for current Emby behavior.
+
+### Local extension E2E smoke tests
+
+- **Priority:** P2
+- **Category:** Testing / Release Confidence
+- **Background:** The release verification covers unit tests, server integration, syntax, lint, audits, and builds, but it does not currently run a real browser extension flow. A small local E2E smoke suite would catch regressions in content-script injection, tab navigation reinjection, remote seek handling, and iframe player support.
+- **Possible approach:** Add a separate local-only Playwright smoke command that loads the unpacked extension, opens two controlled video pages, and verifies play/pause/seek through the actual extension path. Keep it outside `npm run verify` until it is stable enough for CI.
+- **Status:** Backlog, recommended before larger content-script or frame-bridge changes.
+
+---
+
+## ❌ Rejected
+
+*Declined features with rationale — keeps decisions documented so they don't get re-debated.*
+
+| Feature | Reason |
+|---|---|
+| *(none yet)* | |
+

docs/SYNC_GUIDE.md

@@ -0,0 +1,41 @@
+# KoalaSync Protocol Synchronization Guide
+
+## Why do we need to sync?
+KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the root `shared/` directory. However, Browser Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**.
+
+To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we maintain a mirrored copy of the shared files within the `extension/shared/` folder.
+
+## When should you run the build script?
+You MUST run the build script in any of the following scenarios:
+1. **After a fresh `git clone` or `git pull`** (as the synced files are ignored by git).
+2. **After modifying** `shared/constants.js`.
+3. **After modifying** `shared/blacklist.js`.
+4. **After modifying** `shared/names.js`.
+5. **Before committing** changes to the repository if any shared protocol or extension-mirrored files were touched.
+6. **Before deploying** the server or releasing the extension.
+
+## How to sync
+
+Run the Node.js build script from the repository root:
+```bash
+node scripts/build-extension.cjs
+# or simply:
+npm run build:extension
+```
+
+## What does it do?
+The build script performs the following actions:
+1. Synchronizes shared files by copying `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`.
+2. Injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions (`extractEpisodeId`, `sameEpisode`) into `content.js` via marker-based replacement.
+3. Injects browser-specific uninstall URL constants into `background.js` and a build timestamp into `popup.html`.
+4. Compiles browser-specific manifest files.
+5. Packages the final ready-to-publish extension artifacts for Chrome and Firefox into the `dist/` directory.
+
+## Protocol Versioning
+The system enforces a strict `protocolVersion` check during the `JOIN_ROOM` handshake. 
+- The version is defined in `shared/constants.js`.
+- If the extension and server versions mismatch, the server will reject the connection with an `Incompatible protocol version` error.
+- **Never manually bump version numbers**. The CI pipeline automatically injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json` during release builds. Run the build script to synchronize other constant updates.
+
+> [!CAUTION]
+> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the build script is run. Always edit the files in the root `shared/` directory and then run the build script.

docs/TESTED_SERVICES.md

@@ -0,0 +1,66 @@
+# 🎬 Tested Streaming Services & Compatibility
+
+This document tracks which streaming platforms and media servers are supported by the KoalaSync extension. 
+
+> [!TIP]
+> **Contributions are highly welcome!** 🤝 Anyone can easily update this list. If you have tested a streaming service (whether it works, has issues, or is not yet listed), please help the project by submitting a quick Pull Request. See the [How to Contribute](#how-to-contribute) guide below!
+
+---
+
+## Compatibility Matrix
+
+| Service | Sync Works | Media Title | Episode Auto-Sync | Last Tested | Tested By | Extension Version | Notes |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :--- |
+| **YouTube** | ✅ Full | ✅ Full | ❌ N/A | — | — | — | Individual videos, not episodes. |
+| **Twitch** | ✅ Full | ✅ Full | ❌ N/A | — | — | — | Individual streams/VODs. |
+| **Netflix** | ✅ Full | ❌ | ❌ | — | — | — | No media title exposed. |
+| **Emby** | ✅ Full | ✅ Full | ✅ Full | — | — | — | Best-in-class support. |
+| **Jellyfin** | ✅ Full | ✅ Full | ✅ Full | — | — | — | — |
+| **Plex** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Disney+** | ✅ Full | ⚠️ Partial | ❌ | — | — | — | Series title only (e.g. "The Simpsons"), no episode info. |
+| **Prime Video** | ✅ Full  | ✅ Full  | ❌ | — | — | — | — |
+| **HBO Max / Max** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Crunchyroll** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Vimeo** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Dailymotion** | Not tested | Not tested | Not tested | — | — | — | — |
+| **ARD / ZDF Mediathek** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Vix** | ✅ Full | ✅ Full | ✅ Full | — | — | — | Everything works correctly. |
+
+### Legend
+
+| Symbol | Meaning |
+| :---: | :--- |
+| ✅ Full | Works without limitations. |
+| ⚠️ Partial | Works with caveats (see Notes). |
+| ❌ | Not supported / does not work. |
+| ❌ N/A | Not applicable (feature does not exist on the platform). |
+| **Not tested** | Has not been tested yet. |
+
+---
+
+## How to Contribute
+
+Updating this compatibility list is quick and easy! You don't need deep coding skills to contribute:
+
+1. **Fork the Repository**: Click the **Fork** button at the top of the [KoalaSync GitHub Repository](https://github.com/Shik3i/KoalaSync).
+2. **Edit this File**: Open [docs/TESTED_SERVICES.md](TESTED_SERVICES.md) in your fork's browser editor (or clone it locally) and update the table with your testing details.
+3. **Commit & Push**: Commit your changes with a clear message (e.g., `docs: update Netflix compatibility status`).
+4. **Create a Pull Request**: Submit the Pull Request (PR) from your fork to our `main` branch.
+
+> [!NOTE]
+> **Reporting Problems:** If you notice a bug or partial support on a service, please open a [GitHub Issue](https://github.com/Shik3i/KoalaSync/issues) describing the problem, and link it in the **Notes** column of the table. 
+> 
+> _If you are unsure how to create/link an issue, don't worry! Simply submit the PR anyway, and the maintainers will gladly create and link the issue for you._
+
+---
+
+## Technical Background
+
+KoalaSync works on any website with a **standard HTML5 `<video>` element** that allows script injection. 
+
+Limited functionality on certain platforms is typically caused by:
+- **DRM/Copy Protection** (e.g., Widevine on Netflix) which restricts access to media metadata like title and playback state
+- **Shadow DOM encapsulation** that hides video elements from content scripts
+- **Strict Content Security Policies** (CSP) that block script injection
+
+Websites with heavily obfuscated custom players (e.g., complex Shadow DOM, iframe isolation) may require platform-specific workarounds in `content.js`.

docs/TRANSLATION.md

@@ -0,0 +1,121 @@
+# KoalaSync Translation & Localization Guide
+
+Welcome to the **KoalaSync** translation guide. We rely on the open-source community to make KoalaSync accessible to users worldwide.
+
+KoalaSync is split into two independent translation areas. You can translate either one, or both:
+
+1. **The Browser Extension** (`extension/locales/`): The core product that users interact with daily.
+2. **The Website** (`website/locales/`): The landing page and invitation bridge.
+
+---
+
+## Supported Languages Dashboard
+
+We divide supported languages into two tiers: **Core Languages** (fully hand-crafted and audited by native speakers) and **Extended Languages** (auto-generated using translation models to expand initial coverage).
+
+> [!TIP]
+> **Help Us Improve!**
+> We welcome community contributions to audit `Auto-Generated` translations and elevate them to `100% Manually Verified` status.
+
+| Language Code | Language Name | Verification Status | Rationale / Context |
+| :--- | :--- | :--- | :--- |
+| `en` | **English** | `100% Manually Verified` | Global default language (verified by developer) |
+| `de` | **German** | `100% Manually Verified` | Developer's native language |
+| `fr` | **French** | `Auto-Generated` | Needs manual native review and polishing |
+| `es` | **Spanish** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `pt-BR` | **Portuguese (Brazil)** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `ru` | **Russian** | `Auto-Generated` | Needs manual native review and polishing |
+| `it` | **Italian** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `pl` | **Polish** | `Auto-Generated` | Needs manual native review and polishing |
+| `tr` | **Turkish** | `Auto-Generated` | Needs manual native review and polishing |
+| `nl` | **Dutch** | `Auto-Generated` | Needs manual native review and polishing |
+| `ja` | **Japanese** | `Auto-Generated` | Needs manual native review and polishing |
+| `ko` | **Korean** | `Auto-Generated` | Needs manual native review and polishing |
+| `pt` | **European Portuguese** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `zh` | **Chinese (Simplified)** | `Auto-Generated` | Needs manual native review and polishing |
+| `uk` | **Ukrainian** | `Auto-Generated` | Needs manual native review and polishing |
+
+> [!WARNING]
+> **Autogeneration Quality Rule**
+> Any newly contributed languages must be marked as `Auto-Generated` in this table until fully reviewed and signed off by a native speaker in a pull request.
+
+---
+
+## How to Translate KoalaSync
+
+Here is the exact step-by-step process for contributing translations.
+
+### Step 1: Fork and Clone the Repository
+
+If you are an external contributor, start with the standard open-source workflow:
+
+1. Click the "Fork" button on GitHub to create your own copy of the repository.
+2. Clone your fork locally: `git clone https://github.com/YOUR-USERNAME/KoalaSync.git`
+3. Create a branch: `git checkout -b translation/my-language`
+
+### Step 2: Translate the Extension
+
+The browser extension handles real-time syncing, settings, and popups.
+
+1. Navigate to `extension/locales/`.
+2. Edit an existing `[lang].json` or copy `en.json` to create a new one (for example, `it.json`).
+3. Translate all string values. **Do not change the JSON keys.**
+
+### Step 3: Translate the Website
+
+The website hosts the landing page and invitation bridge.
+
+1. Navigate to `website/locales/`.
+2. Edit an existing `[lang].json` or copy `en.json` to create a new one.
+3. Translate all string values. **Do not change the JSON keys.**
+4. If creating a brand new language, configure the metadata at the top of your JSON file:
+
+```json
+{
+  "LANG_CODE": "it",
+  "HTML_CLASS": "lang-it",
+  "CANONICAL_PATH": "it/",
+  "LANG_TOGGLE_URL": "../",
+  "LANG_TOGGLE_TEXT": "EN"
+}
+```
+
+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.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.cjs
+```
+
+If you receive any errors about missing keys or placeholder strings, fix them before submitting.
+
+### Step 5: Commit and Pull Request
+
+1. Open this `TRANSLATION.md` file and add or update your language in the **Supported Languages Dashboard** above. Mark it as `100% Manually Verified` only if it has been reviewed by a native speaker.
+2. Commit your changes: `git commit -m "Update Italian translations"`
+3. Push to your fork: `git push origin translation/my-language`
+4. Open a pull request on the main KoalaSync repository on GitHub.
+
+---
+
+## Strict Legal Exclusion Rule
+
+Our legal pages have strict constraints to protect user privacy and avoid regulatory liabilities.
+
+> [!IMPORTANT]
+> **Do Not Translate Legal Documents**
+> The legal notice (`website/impressum.html`) and privacy policy (`website/datenschutz.html`) **MUST remain exclusively in English and German**.
+>
+> **Rationale:** Legal compliance under the European Union General Data Protection Regulation (GDPR) and the German Digital Services Act (DDG). Offering automated translations of legally binding notices introduces compliance risks due to potential mistranslations of liability limits.
+>
+> **Technical fallback:** Our system automatically falls back to English for legal pages if a user visits them in an unsupported language, so you do not need to translate them.

docs/chat-e2e-prompt.md

@@ -0,0 +1,346 @@
+# E2E-verschlüsselter In-Page-Chat für KoalaSync
+
+## Auftrag
+
+Baue einen privacy-first, Ende-zu-Ende-verschlüsselten Text-Chat, der direkt auf der
+Streaming-Seite neben dem Video sitzt. Neuer Branch von `main`, Vorschlag
+`feature/chat-e2e`.
+
+### Harte Anforderungen
+
+1. **Der Server darf Nachrichten nie lesen können.** Schlüssel nur clientseitig, der
+   Relay sieht ausschließlich Ciphertext.
+2. **Der Server speichert keine Nachrichten.** Reines Live-Relay, kein RAM-Backlog,
+   keine History. Wer zu spät kommt, verpasst den bisherigen Chat. Das ist gewollt.
+3. **Chat läuft auf der Streaming-Seite**, nicht im Extension-Popup.
+4. **Themes werden respektiert** (3 Paletten x light/dark).
+5. **Keine Read Receipts.** Bewusst gestrichen.
+6. **Volle Abwärtskompatibilität**: alte Extensions müssen weiter normal joinen können.
+
+### Bedrohungsmodell (bestimmt alle Krypto-Entscheidungen)
+
+Das hier ist eine Video-Sync-Extension mit optionalem, flüchtigem Chat, **keine
+sicherheitskritische Messenger-App**. Ziel ist: ein bösartiger Betreiber eines
+Custom-Relays soll nicht einfach mitlesen können. Ob etwas mit sehr viel Aufwand
+theoretisch knackbar wäre, ist egal.
+
+Daraus folgt, und das ist bindend:
+- **Usability und Performance haben Vorrang** vor kryptografischer Maximalhärte.
+- Raum-Passwörter sind kurz, zufällig generiert (z.B. `0XUK3C`) und ständig neu. Wer
+  eines knackt, kann trollen (`play`/`pause` senden). Nervig, nicht kritisch. Deshalb
+  nutzt der Server bewusst simples SHA256/HMAC statt bcrypt. **Diese Linie beibehalten,
+  nicht "verbessern".**
+- Der globale `SERVER_SALT` ist bekannt und kein Issue. Räume sind flüchtig, es gibt
+  keine Datenbank.
+
+### Explizite Nicht-Ziele
+
+- Kein Chat-Tab im Popup. Nicht als Fallback, nicht übergangsweise.
+- Keine serverseitige `chatHistory` in irgendeiner Form.
+- **Die Auth nicht anfassen.** Das Klartext-Passwort an den Relay ist bewusst so und
+  wird nicht umgebaut (Begründung unten).
+- `website/` Theme-Redesign auf `main` nicht anfassen.
+
+---
+
+## Krypto-Design (entschieden, nicht neu diskutieren)
+
+### Woher der Schlüssel kommt
+
+Das Raum-Passwort ist **unbrauchbar** als Schlüsselmaterial: der Client sendet es im
+Klartext an den Relay (`join_room` -> `payload.password`, `server/index.js:349`), der
+Server HMACt es erst selbst (`hashPassword`, Zeile 52-55). Der Server könnte jeden
+daraus abgeleiteten Schlüssel mitberechnen.
+
+Es zu ändern würde auch nichts bringen: Raum-Passwörter haben ~31 Bit Entropie
+(6 Zeichen A-Z0-9). Ein bösartiger Server könnte sie offline durchprobieren und den
+Chat-Schlüssel ableiten.
+
+**Lösung: ein eigenes, zufälliges Secret im URL-Fragment.** Fragmente werden nie an
+einen Server gesendet, und das Secret hat volle Entropie per Konstruktion. Der
+Einladungslink transportiert bereits heute das Passwort im Fragment, der Mechanismus
+existiert also schon.
+
+### Primitive
+
+- **16 zufällige Bytes** (128 Bit), base64url, 22 Zeichen. Beispiel:
+  `R5Ti1nxp0crfAFHf3gVncw`
+- Ableitung: **HKDF-SHA256**(secret, salt=roomId) -> AES-256-GCM-Key.
+  **Kein PBKDF2, kein Stretching.** Slow KDFs existieren nur, um schwache
+  Menschen-Passwörter zu strecken. Das Secret ist zufällig mit voller Entropie, HKDF
+  ist ein einziger HMAC (Mikrosekunden). Das ist dieselbe Logik wie sha256-statt-bcrypt
+  beim Server.
+- **Key genau einmal pro Raum ableiten und den `CryptoKey` cachen.** Nicht pro
+  Nachricht neu ableiten oder importieren.
+- Pro Nachricht: **zufälliger 12-Byte-IV**, dem Ciphertext vorangestellt.
+- Alles über **WebCrypto**, keine Fremdabhängigkeit.
+
+### AAD: senderId gegen Umetikettierung binden (Pflicht)
+
+`senderId` wird vom Server gestempelt und liegt damit **außerhalb** des Ciphertexts.
+Ohne Gegenmaßnahme kann ein bösartiger Relay Alices Ciphertext als Bob weiterreichen.
+Das ist exakt der Angreifer, gegen den dieses Feature gebaut wird.
+
+Deshalb: **AES-GCM mit AAD** verschlüsseln.
+```
+AAD = `${roomId}|${senderId}`     // senderId = eigene peerId beim Verschlüsseln,
+                                  // envelope.senderId beim Entschlüsseln
+```
+Etikettiert der Server um, schlägt die Auth-Tag-Prüfung fehl und die Nachricht wird
+verworfen. Kostet null Performance und bindet die Nachricht zusätzlich an den Raum
+(kein Cross-Room-Replay).
+
+Bewusst **nicht** abgedeckt und akzeptiert: Nachrichtenlängen und Timing bleiben für den
+Server sichtbar (kein Padding). Ein Relay kann eine Nachricht innerhalb desselben Raums
+erneut abspielen. Für das Bedrohungsmodell irrelevant.
+
+### Sanitization wandert auf den Client (Pflicht)
+
+Der Server sieht nur noch Ciphertext und **kann Text nicht mehr prüfen**. Die Bedrohung
+verschwindet dadurch nicht, sie verschiebt sich: entschlüsselter Text stammt von einem
+**Peer, der den Key besitzt**.
+
+- Entschlüsselter Text ist **untrusted input**. Vor dem Rendern zwingend durch
+  `escapeChatHtml`/`formatChatText` (escapen, dann Markdown). Niemals rohes `innerHTML`.
+- Die Längengrenze (500 Codepoints) muss der **Client** durchsetzen, vor dem
+  Verschlüsseln. Der Server kann nur noch Bytes zählen.
+- **Bestehende Schranke beachten:** `maxHttpBufferSize: 4096` (`server/index.js:142`)
+  gilt global pro Socket-Nachricht. Nachgerechnet: 500 Codepoints als 4-Byte-Emoji
+  ergeben 2000 B Klartext, +16 B GCM-Tag +12 B IV = 2028 B, base64 = 2704 Zeichen,
+  socket.io-Frame = **2731 B**. Passt, Headroom 1365 B. Bei 700 Codepoints wären es
+  3799 B. Wer die Zeichengrenze anhebt, muss diese Rechnung neu machen, sonst reißt das
+  Limit.
+
+---
+
+## Link-Format und Abwärtskompatibilität (entschieden)
+
+### Warum das alte Format nicht erweiterbar ist
+
+Aktuell (`popup.js:559-563`):
+```
+offiziell:  #join:<roomId>:<password>
+custom:     #join:<roomId>:<password>:1:<encodedUrl>
+```
+
+Der Extension-Parser (`popup.js:1294-1313`) nimmt `roomId` von vorne, das Paar
+`(flag, url)` von hinten, und **alles dazwischen ist das Passwort** (`parts.join(':')`).
+Es gibt keine Position, die er verwirft. Verifiziert durch Ausführen der echten Parser
+gegen echte Links:
+
+| Link | Alte Extension | Alte Website |
+|---|---|---|
+| `#join:SILENT-EAGLE-90:30PXPD:1:wss%3A%2F%2F…` (Kontrolle) | `password:"30PXPD"` OK | `serverFlag:"1"` OK |
+| Key inline: `…:30PXPD:<KEY>:1:wss%3A%2F%2F…` | `password:"30PXPD:R5Ti1nxp…"` **korrumpiert** | `serverFlag:"R5Ti…"`, `serverUrl:"1"` -> **falscher Server** |
+
+Zwei verschiedene, irreführende Fehler aus derselben Zeile. Deshalb: neues Präfix.
+
+### Neues Format
+
+```
+#j2:r=<roomId>&p=<password>&k=<key>[&u=<encodedRelayUrl>]
+```
+
+- `URLSearchParams`, kein positionales Parsen. Behebt nebenbei einen bestehenden Bug:
+  heute zerschießt ein Doppelpunkt im Passwort den Website-Parser (`parts[2]`), während
+  der Extension-Parser (`parts.join(':')`) damit klarkommt.
+- **`s=1` entfällt.** Es existierte nur wegen des positionalen Parsens. Mit benannten
+  Parametern gilt: `u` vorhanden bedeutet Custom Relay.
+- Das Präfix darf `#join:` **nicht als Teilstring enthalten**, sonst greift
+  `includes('#join:')` in alten Extensions doch.
+
+Beispiele:
+```
+offiziell: …/join.html#j2:r=SAPPHIRE-DUCK-49&p=0XUK3C&k=R5Ti1nxp0crfAFHf3gVncw
+custom:    …/join.html#j2:r=SILENT-EAGLE-90&p=30PXPD&k=R5Ti1nxp0crfAFHf3gVncw
+                          &u=wss%3A%2F%2Fsync.shik3i.net
+```
+
+### Warum das alte Extensions nicht bricht
+
+**Die Website ist der Hauptpfad, nicht die Extension.** `website/app.js:452-458` parst
+das Fragment selbst, prüft via `document.documentElement.dataset.koalasyncInstalled`
+(gesetzt von `bridge.js:9`), ob die Extension da ist, und dispatcht dann automatisch
+(`app.js:515-526`, "AUTO-TRIGGER JOIN") ein `KOALASYNC_JOIN_REQUEST` mit fertig
+geparsten, **strukturierten Feldern**. `bridge.js` reicht es als `WEB_JOIN_REQUEST` an
+den background weiter. In diesem Pfad liest die Extension die URL nie an.
+
+Altes `bridge.js` destrukturiert nur, was es kennt:
+```js
+const { roomId, password, useCustomServer, serverUrl } = e.detail;
+```
+Ein zusätzliches `chatKey` fällt dort stillschweigend auf den Boden.
+
+**Daraus folgt die Deploy-Reihenfolge: Website zuerst.** Sie ist die einzige Stelle, die
+das neue Format kennen muss, und sie ist sofort deploybar. Die Extension darf beliebig
+hinterherhinken (Store-Review, Update-Zyklen der Nutzer).
+
+| Kombination | Ergebnis |
+|---|---|
+| Neue Website + neue Ext | Join + Chat |
+| Neue Website + alte Ext | Join normal, kein Chat, `chatKey` ignoriert |
+| Neue Ext + alter `#join:`-Link | Join, kein Key, Chat aus. Legacy-Parser bleibt erhalten |
+| Alte Website + neuer Link | Präfix unbekannt, Join-Seite tot. **Existiert nach dem Website-Deploy nicht mehr** |
+
+`checkInviteLink()` (`popup.js:1289`) ist nur der Komfort-Pfad "Popup auf der Join-Seite
+öffnen und Felder vorausfüllen". Bei `#j2:` greift er in alten Extensions nicht mehr,
+das Feld bleibt leer statt falsch befüllt. Die neue Extension muss dort **beide**
+Formate parsen (`#j2:` und Legacy `#join:`).
+
+**`history.replaceState` auf das Legacy-Format: nicht tun.** Naheliegende Idee, um das
+Autofill alter Extensions zu retten, aber ein Eigentor: es entfernt `k` aus der
+Adressleiste. Nutzer kopieren die URL aus der Adressleiste, um sie weiterzuteilen. Der
+weitergegebene Link joint dann zwar, hat aber stillschweigend keinen Chat mehr. Der
+Fragment-Inhalt muss unangetastet bleiben.
+
+### Lebenszyklus des Keys
+
+- **Erzeugt wird er vom Raum-Ersteller**, einmal, beim Anlegen des Raums. Er lebt im
+  background neben `roomId`/`password` und geht in den Invite-Link.
+- **Er darf niemals in einem Relay-Payload landen.** Nicht in `join_room`, nirgends.
+  Dafür einen Test schreiben, der alle ausgehenden Events gegen den Key prüft.
+- **Krypto gehört in den background**, nicht in den content script. Der Key wird damit
+  gar nicht erst in den Kontext einer fremden Seite ausgeliefert. Das Overlay schickt
+  Klartext an den background und bekommt Klartext zurück, verschlüsselt wird
+  ausschließlich dort.
+- **Kanten, die korrekt fallen müssen:**
+  - Raum-Ersteller hat eine **alte** Extension: es existiert kein Key, niemand chattet.
+    Korrektes Verhalten, kein Fehlerfall.
+  - Ein Peer mit **alter** Extension teilt den Invite aus seinem eigenen Popup: der Link
+    trägt keinen Key. Wer darüber joint, chattet nicht, während die anderen chatten.
+  - Jemand tippt Raum und Passwort **manuell**: kein Key, kein Chat.
+  - Relay **ohne** Chat-Capability: Chat-UI gar nicht erst anzeigen.
+
+---
+
+## Vorgeschichte
+
+Vorgängerbranch `feature/soonTMChat` (Stand `c706513`) ist **verworfen**, bleibt als
+Referenz liegen. Gründe:
+
+- Chat lag nur im Popup. Ein Chrome-Popup schließt beim Fokusverlust, man kann nicht
+  gleichzeitig Video schauen und chatten. Strukturell unbrauchbar.
+- Der Server speicherte bis zu 500 Klartext-Nachrichten pro Raum und schickte jedem
+  Joiner das Backlog.
+- Verifizierter Folgebug: wer einen Raum mit >120 Nachrichten Historie betrat, wurde
+  **rausgeworfen**. `renderChatHistory()` feuerte eine ungebündelte `chat_read`-Quittung
+  pro Nachricht und riss `CHAT_READ_RATE_LIMIT` (120/10s). Reproduziert bei
+  `CHAT_HISTORY_LIMIT=200`, dokumentiert erlaubt sind 500.
+
+**Lehre: kein ungebündeltes Event-pro-Nachricht-Muster. Jedes Client-Verhalten gegen die
+Rate-Limits gegenrechnen, bevor es eingebaut wird.**
+
+### Wiederverwendbar (per `git checkout feature/soonTMChat -- <pfad>`, kritisch prüfen)
+
+| Datei | Was | Einschränkung |
+|---|---|---|
+| `extension/chat.js` | `escapeChatHtml`, `formatChatText`, `insertEmoji`, `createTypingTracker`, `createRemoteTypingTracker` | reine Funktionen, storage-frei, getestet. `createReceiptTracker` weglassen |
+| `extension/chat.test.mjs` | Unit-Tests | Receipt-Tests weg |
+| `extension/locales/*.json` | `CHAT_*`-Keys, 15 Sprachen | Receipt-Keys weg, neue Keys für Overlay nötig |
+| `server/chat.js` | `sanitizeChatUsername`, `canKickPeer` | `sanitizeChatText`/`createChatMessage` greifen auf Klartext zu, bei E2E unmöglich. `parseChatHistoryLimit`, `appendChatHistory`, `canRelayReadReceipt` entfallen |
+| `server/rate-limiter.js` | `checkChatMessageRate` (10/10s) | `checkChatReadRate` entfällt |
+| `shared/constants.js` | `CAPABILITIES.CHAT`, Event-Namen | **muss neu hinzu.** main kennt nur `HOST_CONTROL` und `CO_HOST` (`shared/constants.js:78`, `server/index.js:174`) |
+
+**Server-Design, das überleben soll:** Der Server vergab Message-ID, `senderId` und
+`timestamp` selbst und ignorierte Client-Angaben (Spoofing-Schutz). Bleibt richtig, auch
+wenn der Text jetzt Ciphertext ist.
+
+---
+
+## Technische Randbedingungen
+
+### Overlay-Kontext
+
+- `content.js` wird **programmatisch** injiziert:
+  `chrome.scripting.executeScript({ target: {tabId}, files: ['content.js'] })`
+  (`background.js:1775`). Nicht über `manifest.content_scripts`, dort steht nur
+  `bridge.js` für `https://sync.koalastuff.net/*`.
+- `host_permissions: ["<all_urls>"]`, MV3.
+- Das Overlay lebt im DOM fremder Seiten (Netflix, YouTube, Emby, Jellyfin).
+  **Shadow DOM ist Pflicht**, sonst bluten fremde Styles rein und umgekehrt.
+- Die Theme-Variablen aus `popup.html` existieren im Page-Kontext **nicht** und müssen
+  in den Shadow Root injiziert werden.
+- **Risiko, vorab prüfen:** Netflix-Vollbild ist ein eigener Fullscreen-Element-Kontext.
+  Ein Overlay im normalen DOM verschwindet dort möglicherweise. Das kann die
+  Positionierung grundlegend beeinflussen.
+
+### Performance auf der Host-Seite
+
+Das Video ist das Produkt, der Chat ist Beiwerk. Ein Overlay, das die Wiedergabe ruckeln
+lässt, ist schlechter als kein Overlay.
+
+- Nur im **Ziel-Tab** injizieren (`currentTabId` im background), nicht auf jeder Seite.
+- `position: fixed`, eigener Compositing-Layer, **kein Eingriff in das Layout der
+  Host-Seite**. Kein Layout-Thrashing, keine erzwungenen Reflows während der Wiedergabe.
+- Nachrichtenliste beim Rendern nicht unbegrenzt wachsen lassen (DOM-Knoten deckeln).
+
+### Firefox
+
+`scripts/build-extension.cjs:199` baut ein eigenes **Firefox-Target**, und `bridge.js`
+enthält bereits Firefox-spezifisches `cloneInto`-Handling für CustomEvent-Details
+(isolierte Welten in FF MV3). Overlay, Shadow DOM und WebCrypto müssen dort ebenfalls
+laufen. Neue Website-zu-Extension-Felder (`chatKey`) gehen durch dieselbe
+`cloneInto`-Stelle.
+
+### Theme-System (aus `main`, verbindlich)
+
+- `extension/theme-init.js` setzt auf `<html>`: `data-theme` (`light`/`dark`),
+  `data-palette` (`eucalyptus`/`cyber`/`graphite`), Klasse `theme-light`.
+- Quelle: `chrome.storage.local`, Keys `themeMode` und `themePalette`, plus
+  `chrome.storage.onChanged` für Live-Updates. Das Overlay nutzt denselben Mechanismus
+  im Shadow Root.
+- **Kein `prefers-color-scheme`** für Theme-Farben. Das System ist explizit, nur der
+  Modus `system` liest die OS-Präferenz und das erledigt `theme-init.js`.
+- Tokens: `--bg`, `--card`, `--surface-alt`, `--surface-deep`, `--accent`, `--text`,
+  `--text-muted`, `--border-soft`, `--border-strong`, `--text-on-green`.
+  Text auf `--accent` immer `--text-on-green`, nie `white`.
+- Getönte `oklch`-Schatten sind pro Palette hartcodiert und brauchen
+  `html[data-palette=...]`-Overrides. Neutrale Schwarz-Alpha-Schatten sind
+  palettenunabhängig und der einfachere Weg.
+- Bekannte Alt-Last, nicht Aufgabe dieses Branches: `--text-on-green` auf `--accent`
+  erreicht in eucalyptus/light 3.76 und cyber/dark 4.24, unter WCAG AA.
+
+### Qualitäts-Gates
+
+- `npm run lint`, `npx vitest run`, `npm run verify` müssen grün sein.
+- i18n: alle 15 Sprachen in `extension/locales/`, `en` ist Baseline-Fallback. Keine
+  hartcodierten UI-Strings, `getMessage(key, { placeholder })` aus `i18n.js`.
+- Bei einem Release-Tag: Eintrag in `docs/CHANGELOG.md`.
+- Keine Em-Dashes in nutzersichtbaren Texten.
+
+---
+
+## Offene Punkte (mit dem Nutzer klären, nicht selbst entscheiden)
+
+1. **Overlay-Positionierung**: fest andockbar rechts/links, oder frei verschiebbar?
+   Position pro Seite in `chrome.storage.local` merken? Verhalten im Vollbild?
+2. **Peers ohne Key**: Chat-UI ganz ausblenden mit Hinweis, oder anzeigen und
+   Nachrichten als "nicht lesbar" markieren? (Die Fälle, in denen das eintritt, stehen
+   oben unter Lebenszyklus.)
+3. **Metadaten**: Username bleibt heute für den Server sichtbar (er sanitized ihn).
+   Mitverschlüsseln? Typing-Indikatoren verraten dem Server, wer wann aktiv ist.
+   Behalten, verschlüsseln oder streichen?
+4. **Kick-Funktion**: `canKickPeer` existiert (Host/Controller-Rechte). Behalten?
+5. **Nachrichtenlängen-Limit**: 500 Codepoints beibehalten, oder angesichts des
+   4096-B-Frames anders wählen?
+
+---
+
+## Vorgehen
+
+1. Offene Punkte klären.
+2. Krypto- und Linkformat-Design in `docs/CHAT.md` festhalten. Das bestehende Dokument
+   beschreibt das verworfene Konzept und wird neu geschrieben. Chat-Events in
+   `docs/PROTOCOL.md` ergänzen.
+3. Website-Parser (`#j2:`, Legacy `#join:` weiter unterstützen) und Bridge-Feld
+   `chatKey` zuerst, weil davon die Abwärtskompatibilität hängt.
+4. Dann Relay (reines Relay ohne Storage), dann Krypto im background, dann Overlay, dann
+   i18n, dann Tests.
+5. **Verifizieren, nicht annehmen:**
+   - Overlay auf mindestens zwei echten Seiten in allen 6 Theme-Kombinationen, nicht nur
+     in einer isolierten HTML-Datei.
+   - Chrome **und** Firefox-Build.
+   - Ein Test, der beweist, dass der Key in keinem ausgehenden Relay-Payload vorkommt.
+   - Ein Test, der eine umetikettierte Nachricht (fremde `senderId`) als ungültig
+     zurückweist (AAD-Bindung).
+   - Alte Extension gegen neue Website: Join funktioniert weiter, Chat ist stumm.

docs/devops.md

@@ -0,0 +1,51 @@
+# DevOps Release Workflow
+
+This document describes the deployment and release process for KoalaSync.
+
+## Tag-Based Releases
+
+KoalaSync uses a fully automated release pipeline triggered by Git tags. 
+
+> [!IMPORTANT]
+> **DO NOT** manually bump the version numbers in any files (such as `package.json`, `manifest.base.json`, `shared/constants.js`, etc.) before creating a release. 
+> Bumping versions manually is redundant, leads to conflicts, and is completely handled by the CI/CD pipeline.
+
+### How it Works
+
+When you push a Git tag matching `v*` (e.g., `v2.5.1`), the GitHub Actions release workflow (`.github/workflows/release.yml`) is triggered. The workflow performs the following actions:
+
+1. **Extracts the version** from the tag (e.g., `2.5.1` from `v2.5.1`).
+2. **Injects the version** automatically into the following files:
+   - `extension/manifest.base.json`
+   - `shared/constants.js` (updates `APP_VERSION`)
+   - `package.json`
+   - `website/version.json`
+   - `website/template.html` (updates `softwareVersion` schema)
+   - `README.md` (updates badge and announcement banner)
+   - `website/sitemap.xml` (updates `lastmod` dates)
+3. **Commits and pushes** these version updates back to the `main` branch automatically with the commit message `chore(release): update versions to vX.X.X [skip ci]`.
+4. **Builds the extension** for both Chrome and Firefox and publishes the zipped archives.
+5. **Builds the website** and uploads website artifacts.
+6. **Builds and publishes** the Docker image for the relay server to the GitHub Container Registry (`ghcr.io`).
+
+---
+
+## Steps to Deploy a New Release
+
+To release a new version (e.g., `v2.5.1`), follow these steps:
+
+1. Make sure your local repository is synced on `main`:
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+2. Create a local Git tag:
+   ```bash
+   git tag v2.5.1
+   ```
+3. Push the tag to GitHub:
+   ```bash
+   git push origin v2.5.1
+   ```
+
+The release pipeline will take care of the rest! You can monitor the progress under the **Actions** tab of the GitHub repository.

docs/host-control-mode.md

@@ -0,0 +1,151 @@
+# Host Control Mode
+
+This document describes the Host Control Mode implementation in the relay and
+extension. It only covers behavior implemented in the current codebase.
+
+## Modes
+
+### `everyone`
+
+- Default room mode.
+- Any peer may send room-moving playback events.
+
+### `host-only`
+
+- Only controllers may send room-moving playback events.
+- The host is always a controller.
+- The host can promote additional peers to controllers.
+- Guests can keep watching locally in solo/desynced mode, but their local actions
+  still do not drive the shared room.
+
+Room-moving events are:
+
+- `play`
+- `pause`
+- `seek`
+- `force_sync_prepare`
+- `force_sync_execute`
+- `episode_lobby`
+- `episode_lobby_cancel`
+
+Heartbeats, force-sync ACKs, episode-ready events, ping/pong, and command ACKs
+remain allowed for guests.
+
+## Server State
+
+Rooms store Host Control state in memory:
+
+```js
+{
+  hostPeerId,
+  controlMode,
+  controllers,
+  lastControlModeChangeAt,
+  lastRoleChangeAt,
+  forceSyncInitiator
+}
+```
+
+`controllers` is a `Set` on the server and is serialized as an array in
+`room_data` and `control_mode`.
+
+State is not persisted across relay restarts.
+
+## Authority Rules
+
+### Changing mode
+
+Only `hostPeerId` may send `set_control_mode`.
+
+Valid values:
+
+- `everyone`
+- `host-only`
+
+Invalid values are ignored. Non-host attempts are ignored and the sender receives
+the current `control_mode` snapshot so optimistic UI can revert.
+
+Mode changes are debounced per room for 500 ms.
+
+### Promoting and demoting controllers
+
+Only `hostPeerId` may send `set_peer_role`.
+
+The host cannot demote themself. No-op role changes are ignored. Role changes are
+debounced per room for 500 ms.
+
+### Host leaving
+
+When the host leaves and peers remain:
+
+- the next peer becomes `hostPeerId`;
+- `controlMode` falls back to `everyone`;
+- `controllers` is reset to the new host;
+- the relay broadcasts `control_mode`.
+
+When a non-host controller leaves, the relay removes that peer from
+`controllers` and broadcasts `control_mode`.
+
+## Enforcement
+
+The implementation has two enforcement points:
+
+- The extension background script blocks local guest attempts in `host-only` and
+  sends `HOST_BLOCKED` to the content script for local UX.
+- The relay drops room-moving events from non-controllers in `host-only`, so old
+  or modified clients cannot drive the room.
+
+The relay is the authority for room-wide effects.
+
+## Guest UX
+
+When a guest action is blocked locally, the content script classifies it:
+
+- deliberate user action: show the host-control dialog;
+- likely involuntary player action (buffering, tab refocus, no recent gesture):
+  silently snap back when safe;
+- live/DVR stream: degrade without forcing snap-back.
+
+The dialog offers:
+
+- stay in sync: resync to the host;
+- watch on my own: enter solo/desynced mode.
+
+In solo/desynced mode:
+
+- the guest can control their local video;
+- host room commands are ignored locally, except force-sync preparation is ACKed
+  so the host's flow can continue;
+- the guest can resync to the host.
+
+The extension reports `desynced` in peer status so the host UI can show that a
+guest is watching solo.
+
+## Force Sync Edge Case
+
+The relay tracks `forceSyncInitiator` after a controller sends
+`force_sync_prepare`.
+
+This allows that same initiator's `force_sync_execute` through even if their
+controller role changes before execute arrives. Without this, a demotion in the
+middle of a force-sync flow could leave peers waiting after prepare.
+
+The relay clears `forceSyncInitiator` after execute or when the initiator leaves.
+
+## Capabilities
+
+The relay advertises Host Control support in `room_data.capabilities`:
+
+- `host-control`
+- `co-host`
+
+The extension hides or disables matching UI when capabilities are missing.
+
+## Related Events
+
+See [PROTOCOL.md](PROTOCOL.md) for payloads and relay behavior for:
+
+- `set_control_mode`
+- `control_mode`
+- `set_peer_role`
+- host-only gated relay events

eslint.config.mjs

@@ -0,0 +1,85 @@
+import noUnsanitized from "eslint-plugin-no-unsanitized";
+
+export default [
+  {
+    ignores: ["coverage/**", "dist/**", "node_modules/**", "scratch/**", "website/www/**"]
+  },
+  {
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      globals: {
+        chrome: "readonly",
+        browser: "readonly",
+        window: "readonly",
+        document: "readonly",
+        navigator: "readonly",
+        console: "readonly",
+        localStorage: "readonly",
+        setTimeout: "readonly",
+        setInterval: "readonly",
+        clearTimeout: "readonly",
+        clearInterval: "readonly",
+        requestAnimationFrame: "readonly",
+        cancelAnimationFrame: "readonly",
+        fetch: "readonly",
+        CustomEvent: "readonly",
+        MutationObserver: "readonly",
+        IntersectionObserver: "readonly",
+        Uint32Array: "readonly",
+        Set: "readonly",
+        Map: "readonly",
+        Promise: "readonly",
+        Array: "readonly",
+        Object: "readonly",
+        JSON: "readonly",
+        Math: "readonly",
+        Number: "readonly",
+        String: "readonly",
+        Date: "readonly",
+        Error: "readonly",
+        URL: "readonly",
+        URLSearchParams: "readonly",
+        WebSocket: "readonly",
+        history: "readonly",
+        location: "readonly",
+        self: "readonly",
+        process: "readonly",
+      }
+    },
+    plugins: {
+      "no-unsanitized": noUnsanitized
+    },
+    rules: {
+      // Mirrors the AMO validator's "Unsafe assignment to innerHTML" check, so a
+      // rejection at upload time surfaces here instead.
+      "no-unsanitized/property": "error",
+      "no-unsanitized/method": "error",
+      "no-undef": "error",
+      "no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "caughtErrorsIgnorePattern": "^_" }],
+      "no-unreachable": "error",
+      "no-constant-condition": "error",
+      "no-dupe-keys": "error",
+      "no-duplicate-case": "error",
+      "no-empty": "error",
+      "no-extra-semi": "error",
+      "no-prototype-builtins": "warn",
+      "no-unsafe-optional-chaining": "error",
+      "valid-typeof": "error"
+    }
+  },
+  {
+    files: ["server/**/*.js", "scripts/**/*.js", "scripts/**/*.cjs", "website/build.cjs", "website/**/*.cjs"],
+    languageOptions: {
+      globals: {
+        require: "readonly",
+        __dirname: "readonly",
+        __filename: "readonly",
+        process: "readonly",
+        module: "readonly",
+        exports: "readonly",
+        Buffer: "readonly"
+      }
+    }
+  }
+];

examples/Caddyfile.example

@@ -0,0 +1,99 @@
+# ==============================================================================
+# KoalaSync - Production Caddy Configuration Example
+# ==============================================================================
+# This file provides examples of both a lightweight "Simple" configuration 
+# and a production-hardened "Advanced" configuration.
+# Replace domains, reverse proxy locations, and directories with your actual setup.
+
+# ------------------------------------------------------------------------------
+# OPTION A: Simple Configuration
+# ------------------------------------------------------------------------------
+# Minimal configuration that serves the static website, enables gzip compression,
+# supports extension-less Clean URLs, and reverse proxies the relay server.
+
+# sync.koalastuff.net {
+#     root * /var/www/koalasync/website/www
+#     encode zstd gzip
+#
+#     # Clean URLs support (resolves /join to join.html, etc.)
+#     try_files {path} {path}.html {path}/
+#     file_server
+#
+#     # Serve the themed 404 page for unknown URLs (without this block,
+#     # Caddy returns an empty 404 response)
+#     handle_errors {
+#         @notfound expression {err.status_code} == 404
+#         rewrite @notfound /404.html
+#         file_server
+#     }
+# }
+#
+# syncserver.koalastuff.net {
+#     reverse_proxy localhost:3000
+# }
+
+
+# ------------------------------------------------------------------------------
+# OPTION B: Advanced Configuration (Production-Hardened)
+# ------------------------------------------------------------------------------
+# Highly secure, optimized configuration using advanced HTTP security headers,
+# aggressive static assets caching, server signature concealment, and strict 
+# hardware permission access policies.
+
+(security_headers) {
+	header {
+		# Enable HTTP Strict Transport Security (HSTS)
+		Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+		# Prevent clickjacking attacks (Sameorigin)
+		X-Frame-Options "SAMEORIGIN"
+		# Prevent MIME-sniffing
+		X-Content-Type-Options "nosniff"
+		# Enable browser XSS protection
+		X-XSS-Protection "1; mode=block"
+		# Control referrer information
+		Referrer-Policy "strict-origin-when-cross-origin"
+		# Hide Caddy server stamp signature
+		-Server
+	}
+}
+
+sync.koalastuff.net {
+    encode zstd gzip
+    root * /var/www/koalasync/website/www
+
+    # Clean URLs: Resolves paths without .html in the URL
+    try_files {path} {path}.html {path}/
+    file_server
+
+    # Serve the themed 404 page for unknown URLs (without this block,
+    # Caddy returns an empty 404 response)
+    handle_errors {
+        @notfound expression {err.status_code} == 404
+        rewrite @notfound /404.html
+        file_server
+    }
+
+    # Static Caching for high-performance PageSpeed (1 year with validation)
+    @static {
+        file
+        path *.ico *.css *.js *.png *.svg *.webp *.avif
+    }
+    header @static Cache-Control "public, max-age=31536000, must-revalidate"
+
+    # Security Headers & Content Security Policy (CSP)
+    import security_headers
+    header {
+        # CSP hardened with base-uri and form-action limits
+        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none';"
+        
+        # Modern Permissions Policy (blocks browser hardware access for enhanced privacy)
+        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()"
+    }
+}
+
+syncserver.koalastuff.net {
+	import security_headers
+	encode zstd gzip
+	reverse_proxy KoalaSync:3000
+}
+

examples/docker-compose.caddy.example.yml

@@ -0,0 +1,19 @@
+services:                                                                                # Top-level key defining all containers in this Compose file
+  koala-sync:                                                                              # Name of the KoalaSync service
+    image: ghcr.io/shik3i/koalasync:latest                                                 # Pulls the latest KoalaSync image from GitHub Container Registry
+    container_name: KoalaSync                                                              # Sets a fixed container name instead of an auto-generated one
+    restart: always                                                                        # Always restart the container if it stops or if Docker starts
+    environment:                                                                           # Environment variables passed into the container
+      - TZ=Europe/Berlin                                                                   # Sets the timezone inside the container
+      - PORT=3000                                                                          # Port KoalaSync listens on inside the container
+      - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
+      - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
+      - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
+      - SERVER_SALT=CHANGE_ME_GENERATE_WITH_OPENSSL_RAND_BASE64_32                         # Required: unique random salt for room-password hashes
+      - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
+    pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
+    networks:                                                                              # Attaches the service to the networks listed below
+      - caddy_net                                                                          # Joins the pre-existing Caddy network for reverse proxying
+networks:                                                                                  # Top-level networks definition
+  caddy_net:                                                                                # Network name as referenced by the service
+    external: true                                                                          # Marks the network as managed outside of Compose (created by Caddy)

examples/docker-compose.ip.example.yml

@@ -0,0 +1,23 @@
+services:                                                                                # Top-level key defining all containers in this Compose file
+  koala-sync:                                                                              # Name of the KoalaSync service
+    image: ghcr.io/shik3i/koalasync:latest                                                 # Pulls the latest KoalaSync image from GitHub Container Registry
+    container_name: KoalaSync                                                              # Sets a fixed container name instead of an auto-generated one
+    restart: always                                                                        # Always restart the container if it stops or if Docker starts
+    ports:                                                                                 # Exposes the container port to the host
+      - "3000:3000"                                                                        # Maps host port 3000 to container port 3000
+    environment:                                                                           # Environment variables passed into the container
+      - TZ=Europe/Berlin                                                                   # Sets the timezone inside the container
+      - PORT=3000                                                                          # Port KoalaSync listens on inside the container
+      - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
+      - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
+      - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
+      - SERVER_SALT=CHANGE_ME_GENERATE_WITH_OPENSSL_RAND_BASE64_32                         # Required: unique random salt for room-password hashes
+      - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
+    pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
+    networks:                                                                              # Attaches the service to the networks listed below
+      bond0_network:                                                                       # Network name as referenced by the service
+        ipv4_address: 192.168.1.XXX                                                        # Static IPv4 address for the KoalaSync container
+networks:                                                                                  # Top-level networks definition
+  bond0_network:                                                                          # Network name inside Compose
+    external: true                                                                        # Marks the network as managed outside of Compose
+    name: bond0                                                                           # Name of the pre-existing network on the Docker host

examples/json_exporter.example.yml

@@ -0,0 +1,104 @@
+# Prometheus Community JSON Exporter Configuration Example
+# File: examples/json_exporter.example.yml
+#
+# Use this configuration to map KoalaSync admin health metrics (JSON)
+# to native Prometheus metrics.
+#
+# Usage:
+# 1. Rename this file to json_exporter.yml
+# 2. Replace "YOUR_ADMIN_METRICS_TOKEN" with your actual ADMIN_METRICS_TOKEN env value
+# 3. Mount it to the json-exporter docker container: /config.yml
+
+modules:
+  koalasync:
+    http_client_config:
+      bearer_token: "YOUR_ADMIN_METRICS_TOKEN"
+    metrics:
+      - name: koalasync_uptime_seconds
+        path: '{.uptime}'
+        help: "Uptime of the KoalaSync relay server in seconds"
+
+      - name: koalasync_rooms
+        path: '{.rooms}'
+        help: "Total active rooms"
+
+      - name: koalasync_connections
+        path: '{.connections}'
+        help: "Total active socket connections (sockets)"
+
+      - name: koalasync_peers
+        path: '{.peers}'
+        help: "Total connected peers across all rooms"
+
+      - name: koalasync_rooms_with_lobby
+        path: '{.roomsWithLobby}'
+        help: "Number of rooms waiting in an episode lobby"
+
+      - name: koalasync_avg_peers_per_room
+        path: '{.avgPeersPerRoom}'
+        help: "Average number of peers per room"
+
+      - name: koalasync_max_peers_in_room
+        path: '{.maxPeersInRoom}'
+        help: "Maximum number of peers in a single room"
+
+      - name: koalasync_memory_rss_bytes
+        path: '{.memory.rss}'
+        help: "Resident Set Size (RSS) memory usage in bytes"
+
+      - name: koalasync_memory_heap_used_bytes
+        path: '{.memory.heapUsed}'
+        help: "V8 engine heap used in bytes"
+
+      - name: koalasync_memory_heap_total_bytes
+        path: '{.memory.heapTotal}'
+        help: "V8 engine heap total in bytes"
+
+      # Rate limiter tracking — unique clients currently in each tracking window
+      # (not rate-limit denials; these include legitimate traffic too)
+
+      - name: koalasync_rate_limit_connections
+        path: '{.rateLimits.trackedClients.connections}'
+        help: "Unique clients tracked in the connection rate limiter window"
+
+      - name: koalasync_rate_limit_events
+        path: '{.rateLimits.trackedClients.events}'
+        help: "Unique sockets tracked in the event rate limiter window"
+
+      - name: koalasync_rate_limit_health
+        path: '{.rateLimits.trackedClients.health}'
+        help: "Unique IPs tracked in the health endpoint rate limiter window"
+
+      - name: koalasync_rate_limit_admin_metrics_auth
+        path: '{.rateLimits.trackedClients.adminMetricsAuth}'
+        help: "Unique IPs tracked in the admin metrics auth rate limiter window"
+
+      - name: koalasync_rate_limit_auth_failures
+        path: '{.rateLimits.trackedClients.authFailures}'
+        help: "Unique IPs tracked in the authentication failures cache"
+
+      - name: koalasync_rate_limit_room_list
+        path: '{.rateLimits.trackedClients.roomList}'
+        help: "Unique sockets in the room list cooldown cache"
+
+      # Actual rate-limit denials — incremented only when a 429 is served
+
+      - name: koalasync_rate_limit_denied_connections
+        path: '{.rateLimits.denied.connections}'
+        help: "Total connection attempts denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_events
+        path: '{.rateLimits.denied.events}'
+        help: "Total socket events denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_health
+        path: '{.rateLimits.denied.health}'
+        help: "Total health endpoint requests denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_admin_metrics_auth
+        path: '{.rateLimits.denied.adminMetricsAuth}'
+        help: "Total admin metrics auth attempts denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_room_list
+        path: '{.rateLimits.denied.roomList}'
+        help: "Total room list refresh requests denied by rate limiter"

extension/README.md

@@ -1,33 +1,106 @@
-# KoalaSync Chrome Extension
+# KoalaSync Browser Extension
 
-A Manifest V3 Chrome Extension for synchronized video playback across any website.
+This directory contains the Manifest V3 browser extension for Chrome and Firefox. It owns the popup UI, background service worker, content-script video control, invitation bridge, audio processing, and all browser-local settings.
+
+## Where You Are
+
+- `manifest.base.json` is the source manifest. The build script creates browser-specific `manifest.json` files in `dist/chrome/` and `dist/firefox/`.
+- `background.js` is the long-lived coordinator: WebSocket client, room state, host-control authority, heartbeat, reconnects, tab selection, and content-script injection.
+- `content.js` runs in the selected video tab. It detects video state, applies remote play/pause/seek, handles episode transitions, and applies local audio processing.
+- `popup.html` and `popup.js` implement the visible extension UI.
+- `extension/shared/` is generated by `npm run build:extension` from the root `shared/` directory. Do not edit it directly.
 
 ## Key Features
-- **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.
-- **Live Diagnostics**: Built-in "Dev" tab for real-time video state debugging (ReadyState, CurrentTime, etc.).
+
+- **Manifest V3**: Service-worker architecture with session persistence and explicit keep-alive handling.
+- **Pure Vanilla JS**: No extension runtime dependencies and no bundler inside `extension/`.
+- **On-Demand Connection**: The service worker connects only while the user intends to be in a room.
+- **Host Control & Co-Hosts**: Hosts can switch a room into `host-only` mode and grant controller rights to trusted peers.
+- **Episode Auto-Sync**: Title/episode changes can open a lobby so peers resume together once everyone is ready.
+- **Smart Matching & Title Privacy**: Matching video tabs are highlighted, while tab/media title sharing can be reduced or disabled.
+- **Audio Processing**: Optional local compressor settings live in the dedicated audio options page.
+- **Status Diagnostics**: The Status tab exposes connection state, ping, video debug data, action history, and copyable logs.
+- **Dynamic i18n**: 15 languages are supported: `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `pt`, `pt-BR`, `tr`, `ru`, `ja`, `ko`, `zh`, and `uk`.
 
 ## Tab Overview
-1. **Room**: Manage connections, view active peers, and share invitation links.
-2. **Sync**: Control video playback (Play/Pause/Force Sync) and view recent activity.
-3. **Settings**: Customize your Username and toggle domain-based Noise Filtering.
-4. **Dev**: Monitor connection status and view real-time video element metadata for debugging.
+
+1. **Room**: Select official/custom server, create or join rooms, view peers, share invite links, and manage Host Control when supported by the relay.
+2. **Sync**: Select the video tab, send play/pause/seek/force-sync actions, and view episode lobby state.
+3. **Settings**: Configure username, title sharing, noise filtering, auto episode sync, notifications, language, and audio options.
+4. **Status**: Inspect connection state, latency, video debug info, history, and logs for bug reports.
+5. **Dev**: Hidden developer-only controls shown for the `KoalaDev` username.
 
 ## Privacy & Permissions
-KoalaSync requires `<all_urls>` permission to detect and interact with video elements (`<video>`) on websites.
-- **No Browsing History**: We do not track or store your browsing history.
-- **State Management**: Sensitive data (Room Passwords) is stored locally using `chrome.storage`.
-- **Zero Telemetry**: No analytics or external tracking scripts.
+
+KoalaSync requires `<all_urls>` host permission so it can detect and control `<video>` elements on arbitrary sites.
+
+- No browsing history is collected or uploaded.
+- Room credentials and user settings are stored locally with `chrome.storage`.
+- No analytics, external scripts, external fonts, or tracking libraries are used by the extension.
+- Audio processing is local to the selected tab.
+- Title privacy controls decide whether tab/media titles are shared with room peers.
 
 ## Installation
-1. **Sync Protocol**: Run `./scripts/sync-constants.sh` (macOS/Linux) or `scripts\sync-constants.bat` (Windows) from the root.
-2. Open Chrome and go to `chrome://extensions/`.
-3. Enable **Developer mode** (top right).
-4. Click **Load unpacked** and select the `extension` folder.
+
+From the repository root:
+```bash
+npm install
+npm run build:extension
+```
+
+Then load the generated bundle:
+
+- Chrome/Chromium: open `chrome://extensions/`, enable Developer Mode, and load `dist/chrome`.
+- Firefox: open `about:debugging`, choose **This Firefox**, and load `dist/firefox/manifest.json`.
 
 ## Development
-If you modify `shared/constants.js`, you must synchronize the changes across the extension and server:
-- **Windows**: Run `scripts\sync-constants.bat`
-- **Linux/macOS**: Run `scripts/sync-constants.sh`
+
+Run the build whenever shared protocol files or extension packaging inputs change:
+```bash
+npm run build:extension
+```
+
+The build copies `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`, injects synchronous constants into `content.js`, generates browser manifests, and creates zip artifacts in `dist/`.
+
+Useful focused checks from the repository root:
+```bash
+node -c extension/background.js
+node -c extension/content.js
+node -c extension/popup.js
+node scripts/test-episode-utils.mjs
+node scripts/test-title-privacy.mjs
+node scripts/test-audio-settings.mjs
+node scripts/test-locales.cjs
+```
+
+For the full suite, run:
+```bash
+npm run verify
+```
+
+## Do Not Break
+
+- Keep `content.js` synchronous and IIFE-based; it cannot import ES modules directly.
+- Keep the injection markers used by `scripts/build-extension.cjs`.
+- Keep protocol names in `shared/constants.js` as the source of truth.
+- Keep extension runtime dependencies at zero unless the project explicitly decides to introduce a bundler.
+- Keep all extension assets self-hosted.
+
+## Module Structure
+
+| File | Purpose |
+|---|---|
+| `background.js` | Service worker: WebSocket protocol, room state, host control, tab/content routing, reconnects |
+| `content.js` | Video detection/control, audio processing, episode transition, host-only guest behavior |
+| `popup.js` | Popup UI: room join/create, tabs, settings, peer list, status, diagnostics |
+| `popup.html` | Popup markup, tabs, onboarding, status/debug surfaces |
+| `bridge.js` | Invitation bridge injected into `sync.koalastuff.net` |
+| `episode-utils.js` | Shared episode-title parser imported by background and injected into content at build time |
+| `title-privacy.js` | Tab/media title privacy modes and sanitization helpers |
+| `audio-options.html` / `audio-options.js` / `audio-options.css` | Dedicated local audio-processing settings page |
+| `page-api-seek-overrides.js` | Page-level seek bridge for site-specific player APIs |
+| `modules/tab-manager.js` | Tab lifecycle helper used by the background service worker |
+| `i18n.js` | Dynamic locale loader and DOM translation helper |
+| `locales/` | Runtime popup translations |
+| `_locales/` | Browser-store manifest translations |
+| `shared/` | Generated mirror of root shared constants, blacklist, names, and README |

extension/_locales/de/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Erstelle private Watch Partys und synchronisiere Videos mit Freunden auf YouTube, Netflix, Jellyfin, Emby und fast jeder Website."
+  }
+}

extension/_locales/en/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Create private watch parties and sync videos with friends on YouTube, Netflix, Jellyfin, Emby, and almost any HTML5 website."
+  }
+}

extension/_locales/es/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crea fiestas privadas y sincroniza vídeos con amigos en YouTube, Netflix, Jellyfin, Emby y casi cualquier sitio HTML5."
+  }
+}

extension/_locales/fr/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Créez des watch parties privées et regardez en synchro entre amis sur YouTube, Netflix, Jellyfin, Emby et presque tout site HTML5."
+  }
+}

extension/_locales/it/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crea watch party private e sincronizza i video con gli amici su YouTube, Netflix, Jellyfin, Emby e quasi ogni sito HTML5."
+  }
+}

extension/_locales/ja/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "プライベートなウォッチパーティーを作成し、YouTube、Netflix、Jellyfin、EmbyやほぼすべてのHTML5サイトで友達と動画を同期再生できます。"
+  }
+}

extension/_locales/ko/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "비공개 Watch Party를 만들고 YouTube, Netflix, Jellyfin, Emby 및 거의 모든 HTML5 사이트에서 친구들과 영상을 동기화하세요."
+  }
+}

extension/_locales/nl/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Maak privéwatchparty's en kijk synchroon met vrienden op YouTube, Netflix, Jellyfin, Emby en vrijwel elke HTML5-website."
+  }
+}

extension/_locales/pl/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Twórz prywatne wspólne seanse i synchronizuj filmy ze znajomymi na YouTube, Netflix, Jellyfin, Emby i niemal każdej stronie HTML5."
+  }
+}

extension/_locales/pt_BR/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crie watch parties privadas e sincronize vídeos com amigos no YouTube, Netflix, Jellyfin, Emby e em quase qualquer site HTML5."
+  }
+}

extension/_locales/pt_PT/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crie sessões privadas e veja vídeos sincronizados com amigos no YouTube, Netflix, Jellyfin, Emby e em quase qualquer site HTML5."
+  }
+}

extension/_locales/ru/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Создавайте закрытые Watch Party и смотрите синхронно с друзьями на YouTube, Netflix, Jellyfin, Emby и почти любом сайте HTML5."
+  }
+}

extension/_locales/tr/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Özel izleme partileri kurun; YouTube, Netflix, Jellyfin, Emby ve çoğu HTML5 sitesinde arkadaşlarınızla senkron izleyin."
+  }
+}

extension/_locales/uk/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Створюйте закриті Watch Party й дивіться синхронно з друзями на YouTube, Netflix, Jellyfin, Emby та майже будь-якому сайті HTML5."
+  }
+}

extension/_locales/zh_CN/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "创建私人观影派对，与好友在 YouTube、Netflix、Jellyfin、Emby 及几乎任何 HTML5 视频网站同步观看。"
+  }
+}

extension/audio-options.css

@@ -0,0 +1,284 @@
+:root {
+    /* KoalaSync nature system: forest neutrals, eucalyptus brand, warm supporting accents. */
+    --bg-base: oklch(0.23 0.028 155);
+    --surface: oklch(0.30 0.035 150);
+    --surface-deep: oklch(0.205 0.025 155);
+    --surface-alt: oklch(0.265 0.032 150);
+    --border-soft: oklch(0.88 0.025 145 / 0.09);
+    --border-strong: oklch(0.39 0.038 145);
+    --text-primary: oklch(0.96 0.01 90);
+    --text-secondary: oklch(0.78 0.02 90);
+    --accent-green: oklch(0.73 0.13 155);
+    --accent-green-hover: oklch(0.79 0.12 155);
+    --accent-terracotta: oklch(0.62 0.14 45);
+    --success-green: oklch(0.72 0.14 135);
+    --warning-amber: oklch(0.76 0.14 80);
+    --danger: oklch(0.55 0.15 25);
+    --text-on-green: oklch(0.14 0.02 90);
+
+    --bg: var(--bg-base);
+    --card: var(--surface);
+    --panel: var(--surface-alt);
+    --accent: var(--accent-green);
+    --accent-hover: var(--accent-green-hover);
+    --text: var(--text-primary);
+    --text-muted: var(--text-secondary);
+    --border: var(--border-strong);
+    --radius: 8px;
+    color-scheme: dark;
+}
+
+html.theme-light {
+    --bg-base: oklch(0.965 0.012 105);
+    --surface: oklch(0.995 0.006 100);
+    --surface-deep: oklch(0.935 0.018 110);
+    --surface-alt: oklch(0.91 0.022 115);
+    --border-soft: oklch(0.28 0.035 140 / 0.10);
+    --border-strong: oklch(0.73 0.035 125);
+    --text-primary: oklch(0.21 0.03 140);
+    --text-secondary: oklch(0.43 0.03 135);
+    --accent-green: oklch(0.52 0.13 155);
+    --accent-green-hover: oklch(0.45 0.12 155);
+    --text-on-green: oklch(0.98 0.005 100);
+    color-scheme: light;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    min-height: 100vh;
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    font-size: 14px;
+}
+
+.page-shell {
+    width: min(760px, calc(100vw - 32px));
+    margin: 0 auto;
+    padding: 32px 0;
+}
+
+.page-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 20px;
+    margin-bottom: 18px;
+}
+
+.back-link {
+    display: inline-block;
+    color: var(--text-muted);
+    text-decoration: none;
+    font-size: 12px;
+    margin-bottom: 6px;
+    transition: color 0.2s;
+}
+.back-link:hover {
+    color: var(--accent);
+}
+
+.eyebrow {
+    margin: 0 0 4px;
+    color: var(--text-muted);
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    letter-spacing: 0.04em;
+}
+
+h1,
+h2,
+p {
+    margin: 0;
+}
+
+h1 {
+    color: var(--accent-hover);
+    font-size: 28px;
+    font-weight: 800;
+}
+
+h2 {
+    font-size: 16px;
+}
+
+.panel {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 20px;
+    margin-bottom: 16px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+}
+
+html.theme-light .panel {
+    box-shadow: 0 12px 30px oklch(0.22 0.035 140 / 0.09);
+}
+
+.muted-panel {
+    color: var(--text-muted);
+}
+
+.section-heading,
+.master-toggle,
+.inline-toggle {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+}
+
+.master-toggle,
+.inline-toggle {
+    color: var(--text-muted);
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.01em;
+}
+
+.preset-group {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(148px, 1fr));
+    gap: 10px;
+    margin: 18px 0;
+}
+
+.preset-card {
+    min-height: 44px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 12px;
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text);
+    cursor: pointer;
+    transition: border-color 0.2s, box-shadow 0.2s;
+}
+.preset-card:hover {
+    border-color: color-mix(in oklch, var(--accent), transparent 60%);
+}
+
+.preset-card:has(input:checked) {
+    border-color: var(--accent);
+    box-shadow: 0 0 0 1px color-mix(in oklch, var(--accent), transparent 65%);
+}
+
+.preset-card input {
+    accent-color: var(--accent);
+}
+
+.custom-grid {
+    display: grid;
+    gap: 12px;
+    padding: 16px;
+    background: var(--surface-deep);
+    border: 1px solid var(--border-soft);
+    border-radius: var(--radius);
+    transition: opacity 0.3s;
+}
+
+.control-row {
+    display: grid;
+    grid-template-columns: 110px minmax(160px, 1fr) 78px 30px;
+    align-items: center;
+    gap: 10px;
+}
+
+.control-row label {
+    color: var(--text-muted);
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.01em;
+}
+
+input[type="range"] {
+    width: 100%;
+    accent-color: var(--accent);
+}
+
+input[type="number"] {
+    width: 100%;
+    padding: 8px;
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text);
+    font: inherit;
+    transition: border-color 0.2s;
+}
+input[type="number"]:focus {
+    border-color: var(--accent);
+    outline: none;
+}
+
+.unit {
+    color: var(--text-muted);
+    font-size: 12px;
+}
+
+.toggle-switch {
+    position: relative;
+    display: inline-block;
+    width: 38px;
+    height: 22px;
+    flex: 0 0 auto;
+}
+
+.toggle-switch input {
+    opacity: 0;
+    width: 0;
+    height: 0;
+}
+
+.slider {
+    position: absolute;
+    cursor: pointer;
+    inset: 0;
+    background-color: var(--border-strong);
+    transition: .3s;
+    border-radius: 22px;
+}
+
+.slider:before {
+    position: absolute;
+    content: "";
+    height: 16px;
+    width: 16px;
+    left: 3px;
+    bottom: 3px;
+    background-color: var(--text-secondary);
+    transition: .3s;
+    border-radius: 50%;
+}
+
+input:checked + .slider {
+    background-color: var(--accent);
+}
+
+input:checked + .slider:before {
+    transform: translateX(16px);
+    background-color: white;
+}
+
+@media (max-width: 620px) {
+    .page-header,
+    .section-heading {
+        align-items: flex-start;
+        flex-direction: column;
+    }
+
+    .control-row {
+        grid-template-columns: 1fr 74px 28px;
+    }
+
+    .control-row label {
+        grid-column: 1 / -1;
+    }
+}

extension/audio-options.html

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>KoalaSync Audio Settings</title>
+    <script src="theme-init.js"></script>
+    <link rel="stylesheet" href="audio-options.css">
+</head>
+<body>
+    <main class="page-shell">
+        <header class="page-header">
+            <div>
+                <a id="backLink" href="#" class="back-link" data-i18n="AUDIO_BACK">← Back</a>
+                <p class="eyebrow">KoalaSync</p>
+                <h1 data-i18n="AUDIO_PAGE_TITLE">Audio Settings</h1>
+            </div>
+            <label class="master-toggle">
+                <span data-i18n="AUDIO_MASTER_TOGGLE">Audio Processing</span>
+                <span class="toggle-switch">
+                    <input type="checkbox" id="audioEnabled">
+                    <span class="slider"></span>
+                </span>
+            </label>
+        </header>
+
+        <section class="panel">
+            <div class="section-heading">
+                <h2 data-i18n="AUDIO_COMPRESSOR">Compressor</h2>
+                <label class="inline-toggle">
+                    <span data-i18n="AUDIO_COMPRESSOR_ENABLE">Enabled</span>
+                    <span class="toggle-switch">
+                        <input type="checkbox" id="compressorEnabled">
+                        <span class="slider"></span>
+                    </span>
+                </label>
+            </div>
+
+            <div class="preset-group" role="radiogroup" aria-label="Compressor preset">
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="recommended">
+                    <span data-i18n="AUDIO_PRESET_RECOMMENDED">Recommended</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="dynamicRange">
+                    <span data-i18n="AUDIO_PRESET_DYNAMIC_RANGE">Dynamic Range</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="vocalEnhancement">
+                    <span data-i18n="AUDIO_PRESET_VOCAL_ENHANCEMENT">Vocal Enhancement</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="smooth">
+                    <span data-i18n="AUDIO_PRESET_SMOOTH">Smooth</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="custom">
+                    <span data-i18n="AUDIO_PRESET_CUSTOM">Custom</span>
+                </label>
+            </div>
+
+            <div class="custom-grid" id="customControls">
+                <div class="control-row" data-param="threshold">
+                    <label data-i18n="AUDIO_PARAM_THRESHOLD">Threshold</label>
+                    <input type="range" min="-60" max="0" step="1">
+                    <input type="number" min="-60" max="0" step="1">
+                    <span class="unit">dB</span>
+                </div>
+                <div class="control-row" data-param="knee">
+                    <label data-i18n="AUDIO_PARAM_KNEE">Knee</label>
+                    <input type="range" min="0" max="40" step="1">
+                    <input type="number" min="0" max="40" step="1">
+                    <span class="unit">dB</span>
+                </div>
+                <div class="control-row" data-param="ratio">
+                    <label data-i18n="AUDIO_PARAM_RATIO">Ratio</label>
+                    <input type="range" min="1" max="20" step="0.5">
+                    <input type="number" min="1" max="20" step="0.5">
+                    <span class="unit">:1</span>
+                </div>
+                <div class="control-row" data-param="attack">
+                    <label data-i18n="AUDIO_PARAM_ATTACK">Attack</label>
+                    <input type="range" min="0" max="1" step="0.001">
+                    <input type="number" min="0" max="1000" step="1" data-ms-input="true">
+                    <span class="unit">ms</span>
+                </div>
+                <div class="control-row" data-param="release">
+                    <label data-i18n="AUDIO_PARAM_RELEASE">Release</label>
+                    <input type="range" min="0" max="1" step="0.005">
+                    <input type="number" min="0" max="1000" step="5" data-ms-input="true">
+                    <span class="unit">ms</span>
+                </div>
+            </div>
+        </section>
+
+        <section class="panel muted-panel">
+            <div class="section-heading">
+                <h2 data-i18n="AUDIO_EQUALIZER">Equalizer</h2>
+            </div>
+            <p data-i18n="AUDIO_COMING_SOON">Coming soon</p>
+        </section>
+    </main>
+
+    <script src="audio-options.js" type="module"></script>
+</body>
+</html>

extension/audio-options.js

@@ -0,0 +1,192 @@
+import { loadLocale, translateDOM, getSystemLanguage } from './i18n.js';
+
+const PRESETS = {
+    recommended: { threshold: -24, ratio: 8, attack: 0.010, release: 0.300, knee: 15 },
+    dynamicRange: { threshold: -18, ratio: 4, attack: 0.020, release: 0.200, knee: 10 },
+    vocalEnhancement: { threshold: -12, ratio: 3, attack: 0.015, release: 0.150, knee: 5 },
+    smooth: { threshold: -30, ratio: 1.5, attack: 0.030, release: 0.250, knee: 20 },
+    custom: { threshold: -24, ratio: 12, attack: 0.003, release: 0.250, knee: 30 }
+};
+
+const DEFAULT_AUDIO_SETTINGS = {
+    enabled: false,
+    compressor: {
+        enabled: false,
+        preset: 'recommended',
+        customParams: { ...PRESETS.custom }
+    }
+};
+const PARAM_LIMITS = {
+    threshold: { min: -60, max: 0 },
+    knee: { min: 0, max: 40 },
+    ratio: { min: 1, max: 20 },
+    attack: { min: 0, max: 1 },
+    release: { min: 0, max: 1 }
+};
+
+const elements = {
+    audioEnabled: document.getElementById('audioEnabled'),
+    compressorEnabled: document.getElementById('compressorEnabled'),
+    presetInputs: Array.from(document.querySelectorAll('input[name="preset"]')),
+    controlRows: Array.from(document.querySelectorAll('.control-row')),
+    backLink: document.getElementById('backLink')
+};
+
+let saveTimer = null;
+let isRendering = false;
+
+function cloneDefaultSettings() {
+    return JSON.parse(JSON.stringify(DEFAULT_AUDIO_SETTINGS));
+}
+
+let currentSettings = cloneDefaultSettings();
+
+function mergeAudioSettings(settings = {}) {
+    const safeSettings = settings && typeof settings === 'object' ? settings : {};
+    const defaults = cloneDefaultSettings();
+    return {
+        ...defaults,
+        ...safeSettings,
+        compressor: {
+            ...defaults.compressor,
+            ...(safeSettings.compressor || {}),
+            customParams: {
+                ...defaults.compressor.customParams,
+                ...(safeSettings.compressor?.customParams || {})
+            }
+        }
+    };
+}
+
+function debounceSave() {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+        chrome.storage.local.set({ audioSettings: currentSettings });
+    }, 40);
+}
+
+function getParamValue(param, value, isMsInput = false) {
+    const parsed = Number(value);
+    const candidate = Number.isFinite(parsed)
+        ? (isMsInput ? parsed / 1000 : parsed)
+        : currentSettings.compressor.customParams[param];
+    const limits = PARAM_LIMITS[param];
+    if (!limits) return candidate;
+    return Math.min(limits.max, Math.max(limits.min, candidate));
+}
+
+function formatNumber(value, param, isMsInput = false) {
+    if (isMsInput) return Math.round(value * 1000);
+    if (param === 'ratio') return Number(value).toFixed(1).replace(/\.0$/, '');
+    return value;
+}
+
+function render() {
+    isRendering = true;
+    elements.audioEnabled.checked = currentSettings.enabled === true;
+    elements.compressorEnabled.checked = currentSettings.compressor.enabled === true;
+
+    const selectedPreset = currentSettings.compressor.preset || 'recommended';
+    elements.presetInputs.forEach(input => {
+        input.checked = input.value === selectedPreset;
+    });
+
+    const params = selectedPreset === 'custom'
+        ? currentSettings.compressor.customParams
+        : PRESETS[selectedPreset] || PRESETS.recommended;
+
+    elements.controlRows.forEach(row => {
+        const param = row.dataset.param;
+        const range = row.querySelector('input[type="range"]');
+        const number = row.querySelector('input[type="number"]');
+        const value = params[param];
+        range.value = value;
+        number.value = formatNumber(value, param, number.dataset.msInput === 'true');
+    });
+    isRendering = false;
+}
+
+function setPreset(preset) {
+    currentSettings.compressor.preset = preset;
+    if (preset === 'custom') {
+        currentSettings.compressor.customParams = {
+            ...PRESETS.custom,
+            ...currentSettings.compressor.customParams
+        };
+    }
+    render();
+    debounceSave();
+}
+
+function setCustomParam(param, value) {
+    currentSettings.compressor.preset = 'custom';
+    currentSettings.compressor.customParams[param] = getParamValue(param, value);
+    render();
+    debounceSave();
+}
+
+async function init() {
+    // Local-only: audioSettings/locale are never read from storage.sync.
+    const { audioSettings, locale } = await chrome.storage.local.get(['audioSettings', 'locale']);
+    const lang = locale || getSystemLanguage();
+    await loadLocale(lang);
+    translateDOM();
+
+    currentSettings = mergeAudioSettings(audioSettings);
+    render();
+}
+
+elements.audioEnabled.addEventListener('change', () => {
+    currentSettings.enabled = elements.audioEnabled.checked;
+    if (currentSettings.enabled && !currentSettings.compressor.enabled) {
+        currentSettings.compressor.enabled = true;
+    }
+    render();
+    debounceSave();
+});
+
+elements.compressorEnabled.addEventListener('change', () => {
+    currentSettings.compressor.enabled = elements.compressorEnabled.checked;
+    if (currentSettings.compressor.enabled) currentSettings.enabled = true;
+    render();
+    debounceSave();
+});
+
+elements.presetInputs.forEach(input => {
+    input.addEventListener('change', () => {
+        if (input.checked) setPreset(input.value);
+    });
+});
+
+elements.controlRows.forEach(row => {
+    const param = row.dataset.param;
+    const range = row.querySelector('input[type="range"]');
+    const number = row.querySelector('input[type="number"]');
+
+    range.addEventListener('input', () => {
+        if (isRendering) return;
+        setCustomParam(param, getParamValue(param, range.value));
+    });
+
+    number.addEventListener('input', () => {
+        if (isRendering) return;
+        setCustomParam(param, getParamValue(param, number.value, number.dataset.msInput === 'true'));
+    });
+});
+
+chrome.storage.onChanged.addListener((changes, area) => {
+    if (area !== 'local' || !changes.audioSettings) return;
+    currentSettings = mergeAudioSettings(changes.audioSettings.newValue);
+    render();
+});
+
+if (elements.backLink) {
+    elements.backLink.addEventListener('click', (e) => {
+        e.preventDefault();
+        window.close();
+    });
+}
+
+init().catch(err => {
+    console.error('[AudioOptions] Failed to initialize:', err);
+});

extension/bridge.js

@@ -1,6 +1,7 @@
+/* global cloneInto */
 /**
  * KoalaSync Bridge Script
- * Injected into koalasync.shik3i.net to facilitate communication between 
+ * Injected into sync.koalastuff.net to facilitate communication between 
  * the landing page and the extension.
  */
 
@@ -9,25 +10,31 @@ document.documentElement.dataset.koalasyncInstalled = 'true';
 
 // 2. Listen for Join Requests from the Website
 window.addEventListener('KOALASYNC_JOIN_REQUEST', (e) => {
-    const { roomId, password, useCustomServer, serverUrl } = e.detail;
+    if (!e || !e.detail) return;
+    const { roomId, password, chatKey, useCustomServer, serverUrl } = e.detail;
     chrome.runtime.sendMessage({ 
         type: 'WEB_JOIN_REQUEST', 
         roomId, 
         password,
+        chatKey,
         useCustomServer,
         serverUrl
-    });
+    }).catch(() => {});
 });
 
 // 3. Listen for Status Updates from the Extension and relay to Website
 chrome.runtime.onMessage.addListener((msg) => {
+    if (!msg) return;
     if (msg.type === 'JOIN_STATUS') {
-        const event = new CustomEvent('KOALASYNC_STATUS', { 
-            detail: { 
-                success: msg.success, 
-                message: msg.message 
-            } 
-        });
-        window.dispatchEvent(event);
+        const detail = { success: msg.success, message: msg.message };
+        // Firefox MV3 content scripts run in an isolated world. When dispatching
+        // a CustomEvent with a detail object, Firefox wraps it in an XrayWrapper
+        // that the page's JavaScript cannot destructure (Permission denied).
+        // cloneInto() exposes the object to the page's context correctly.
+        // Chrome doesn't have this issue — cloneInto() is undefined there.
+        const safeDetail = typeof cloneInto === 'function'
+            ? cloneInto(detail, document.defaultView)
+            : detail;
+        window.dispatchEvent(new CustomEvent('KOALASYNC_STATUS', { detail: safeDetail }));
     }
 });

extension/chat-crypto.js

@@ -0,0 +1,122 @@
+const CHAT_INFO = 'KoalaSync E2E Chat v1';
+const SECRET_BYTES = 16;
+const IV_BYTES = 12;
+const MIN_ENCRYPTED_BYTES = 29;
+const MAX_ENCRYPTED_BYTES = 2028;
+
+let cachedKeyPromise = null;
+let cachedRoomId = '';
+let cachedSecret = '';
+let cacheGeneration = 0;
+
+function bytesToBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+function base64UrlToBytes(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value) || value.length % 4 === 1) return null;
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - value.length % 4) % 4);
+    try {
+        const binary = globalThis.atob(padded);
+        const bytes = Uint8Array.from(binary, char => char.charCodeAt(0));
+        return bytesToBase64Url(bytes) === value ? bytes : null;
+    } catch (_) {
+        return null;
+    }
+}
+
+export function generateChatSecret(cryptoImpl = globalThis.crypto) {
+    const bytes = new Uint8Array(SECRET_BYTES);
+    cryptoImpl.getRandomValues(bytes);
+    return bytesToBase64Url(bytes);
+}
+
+export function validateChatSecret(value) {
+    const bytes = base64UrlToBytes(value);
+    return bytes?.length === SECRET_BYTES ? value : '';
+}
+
+export function countCodePoints(value) {
+    return [...String(value ?? '')].length;
+}
+
+export function normalizeOutgoingChatText(value) {
+    if (typeof value !== 'string') throw new TypeError('Chat message must be text');
+    const text = value.trim();
+    if (!text) throw new TypeError('Chat message must not be empty');
+    if (countCodePoints(text) > 500) throw new RangeError('Chat message exceeds 500 Unicode code points');
+    return text;
+}
+
+export function clearChatKeyCache() {
+    cacheGeneration++;
+    cachedKeyPromise = null;
+    cachedRoomId = '';
+    cachedSecret = '';
+}
+
+export async function deriveChatKey(roomId, secret, cryptoImpl = globalThis.crypto) {
+    const validSecret = validateChatSecret(secret);
+    if (!roomId || !validSecret) throw new TypeError('Valid roomId and chat secret are required');
+    if (cachedKeyPromise && cachedRoomId === roomId && cachedSecret === validSecret) return cachedKeyPromise;
+
+    const encoder = new globalThis.TextEncoder();
+    const generation = cacheGeneration;
+    const keyPromise = (async () => {
+        const material = await cryptoImpl.subtle.importKey(
+            'raw', base64UrlToBytes(validSecret), { name: 'HKDF' }, false, ['deriveKey']
+        );
+        return cryptoImpl.subtle.deriveKey({
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: encoder.encode(roomId),
+            info: encoder.encode(CHAT_INFO)
+        }, material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+    })();
+    cachedKeyPromise = keyPromise;
+    cachedRoomId = roomId;
+    cachedSecret = validSecret;
+    try {
+        return await keyPromise;
+    } catch (error) {
+        if (generation === cacheGeneration && cachedKeyPromise === keyPromise) clearChatKeyCache();
+        throw error;
+    }
+}
+
+export async function encryptChatMessage({ text, roomId, senderId, secret }, cryptoImpl = globalThis.crypto) {
+    const plaintext = normalizeOutgoingChatText(text);
+    if (!senderId) throw new TypeError('senderId is required');
+    const key = await deriveChatKey(roomId, secret, cryptoImpl);
+    const encoder = new globalThis.TextEncoder();
+    const iv = new Uint8Array(IV_BYTES);
+    cryptoImpl.getRandomValues(iv);
+    const encrypted = new Uint8Array(await cryptoImpl.subtle.encrypt({
+        name: 'AES-GCM',
+        iv,
+        additionalData: encoder.encode(`${roomId}|${senderId}`)
+    }, key, encoder.encode(plaintext)));
+    const envelope = new Uint8Array(iv.length + encrypted.length);
+    envelope.set(iv);
+    envelope.set(encrypted, iv.length);
+    return bytesToBase64Url(envelope);
+}
+
+export async function decryptChatMessage({ ciphertext, roomId, senderId, secret }, cryptoImpl = globalThis.crypto) {
+    if (!senderId) throw new TypeError('senderId is required');
+    const bytes = base64UrlToBytes(ciphertext);
+    if (!bytes || bytes.length < MIN_ENCRYPTED_BYTES || bytes.length > MAX_ENCRYPTED_BYTES) {
+        throw new TypeError('Invalid chat ciphertext');
+    }
+    const key = await deriveChatKey(roomId, secret, cryptoImpl);
+    const encoder = new globalThis.TextEncoder();
+    const plaintext = await cryptoImpl.subtle.decrypt({
+        name: 'AES-GCM',
+        iv: bytes.slice(0, IV_BYTES),
+        additionalData: encoder.encode(`${roomId}|${senderId}`)
+    }, key, bytes.slice(IV_BYTES));
+    const text = new globalThis.TextDecoder('utf-8', { fatal: true }).decode(plaintext);
+    return normalizeOutgoingChatText(text);
+}

extension/chat-crypto.test.mjs

@@ -0,0 +1,114 @@
+import { webcrypto } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+    clearChatKeyCache,
+    countCodePoints,
+    decryptChatMessage,
+    deriveChatKey,
+    encryptChatMessage,
+    generateChatSecret,
+    normalizeOutgoingChatText,
+    validateChatSecret
+} from './chat-crypto.js';
+
+afterEach(clearChatKeyCache);
+
+describe('chat crypto', () => {
+    it('generates canonical 128-bit secrets', () => {
+        const secret = generateChatSecret(webcrypto);
+        expect(secret).toMatch(/^[A-Za-z0-9_-]{22}$/);
+        expect(validateChatSecret(secret)).toBe(secret);
+        expect(validateChatSecret(`${secret}=`)).toBe('');
+    });
+
+    it('round-trips Unicode with a cached room key and fresh IVs', async () => {
+        const secret = generateChatSecret(webcrypto);
+        const firstKey = await deriveChatKey('ROOM-1', secret, webcrypto);
+        const secondKey = await deriveChatKey('ROOM-1', secret, webcrypto);
+        expect(secondKey).toBe(firstKey);
+
+        const input = { text: 'Hello 🐨 **world**', roomId: 'ROOM-1', senderId: 'alice', secret };
+        const first = await encryptChatMessage(input, webcrypto);
+        const second = await encryptChatMessage(input, webcrypto);
+        expect(second).not.toBe(first);
+        await expect(decryptChatMessage({ ciphertext: first, ...input }, webcrypto)).resolves.toBe(input.text);
+    });
+
+    it('deduplicates in-flight key derivations without restoring a cleared cache', async () => {
+        const secret = generateChatSecret(webcrypto);
+        let deriveCalls = 0;
+        let releaseDerive;
+        const delayedCrypto = {
+            ...webcrypto,
+            subtle: {
+                importKey: (...args) => webcrypto.subtle.importKey(...args),
+                deriveKey: async (...args) => {
+                    deriveCalls++;
+                    await new Promise(resolve => { releaseDerive = resolve; });
+                    return webcrypto.subtle.deriveKey(...args);
+                }
+            }
+        };
+        const first = deriveChatKey('ROOM-1', secret, delayedCrypto);
+        const second = deriveChatKey('ROOM-1', secret, delayedCrypto);
+        await Promise.resolve();
+        expect(deriveCalls).toBe(1);
+        clearChatKeyCache();
+        releaseDerive();
+        await Promise.all([first, second]);
+        const fresh = deriveChatKey('ROOM-1', secret, webcrypto);
+        expect(fresh).not.toBe(first);
+        await fresh;
+    });
+
+    it('rejects relabeling, cross-room replay, and the wrong secret', async () => {
+        const secret = generateChatSecret(webcrypto);
+        const ciphertext = await encryptChatMessage({ text: 'secret', roomId: 'ROOM-1', senderId: 'alice', secret }, webcrypto);
+        clearChatKeyCache();
+        await expect(decryptChatMessage({ ciphertext, roomId: 'ROOM-1', senderId: 'bob', secret }, webcrypto)).rejects.toThrow();
+        clearChatKeyCache();
+        await expect(decryptChatMessage({ ciphertext, roomId: 'ROOM-2', senderId: 'alice', secret }, webcrypto)).rejects.toThrow();
+        clearChatKeyCache();
+        await expect(decryptChatMessage({ ciphertext, roomId: 'ROOM-1', senderId: 'alice', secret: generateChatSecret(webcrypto) }, webcrypto)).rejects.toThrow();
+    });
+
+    it('enforces 500 Unicode code points before encryption', () => {
+        expect(countCodePoints('😀'.repeat(500))).toBe(500);
+        expect(normalizeOutgoingChatText(`  ${'😀'.repeat(500)}  `)).toBe('😀'.repeat(500));
+        expect(() => normalizeOutgoingChatText('😀'.repeat(501))).toThrow(RangeError);
+        expect(() => normalizeOutgoingChatText('   ')).toThrow(TypeError);
+    });
+
+    it('keeps the worst-case 500-codepoint payload within the relay byte bound', async () => {
+        const secret = generateChatSecret(webcrypto);
+        const ciphertext = await encryptChatMessage({
+            text: '😀'.repeat(500), roomId: 'ROOM-1', senderId: 'alice', secret
+        }, webcrypto);
+        const bytes = Buffer.from(ciphertext, 'base64url');
+        expect(bytes).toHaveLength(2028);
+    });
+
+    it('rejects non-canonical plaintext and malformed UTF-8 after authentication', async () => {
+        const secret = generateChatSecret(webcrypto);
+        const roomId = 'ROOM-1';
+        const senderId = 'alice';
+        const key = await deriveChatKey(roomId, secret, webcrypto);
+        const encoder = new globalThis.TextEncoder();
+
+        async function encryptRaw(plaintext) {
+            const iv = webcrypto.getRandomValues(new Uint8Array(12));
+            const encrypted = new Uint8Array(await webcrypto.subtle.encrypt({
+                name: 'AES-GCM',
+                iv,
+                additionalData: encoder.encode(`${roomId}|${senderId}`)
+            }, key, plaintext));
+            return Buffer.concat([Buffer.from(iv), Buffer.from(encrypted)]).toString('base64url');
+        }
+
+        const whitespace = await encryptRaw(encoder.encode('   '));
+        await expect(decryptChatMessage({ ciphertext: whitespace, roomId, senderId, secret }, webcrypto)).rejects.toThrow(TypeError);
+        const malformed = await encryptRaw(Uint8Array.of(0xff));
+        await expect(decryptChatMessage({ ciphertext: malformed, roomId, senderId, secret }, webcrypto)).rejects.toThrow();
+    });
+});

extension/chat-format.js

@@ -0,0 +1,33 @@
+(function exposeChatFormat(root) {
+    function escapeChatHtml(value) {
+        return String(value ?? '')
+            .replace(/&/g, '&')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#039;');
+    }
+
+    function formatChatText(value) {
+        return escapeChatHtml(value)
+            .replace(/\*\*([^*\n]+)\*\*/g, '<strong>$1</strong>')
+            .replace(/\*([^*\n]+)\*/g, '<em>$1</em>');
+    }
+
+    function tokenizeChatText(value) {
+        const text = String(value ?? '');
+        const tokens = [];
+        const pattern = /\*\*([^*\n]+)\*\*|\*([^*\n]+)\*/g;
+        let cursor = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            if (match.index > cursor) tokens.push({ type: 'text', text: text.slice(cursor, match.index) });
+            tokens.push({ type: match[1] !== undefined ? 'strong' : 'em', text: match[1] ?? match[2] });
+            cursor = pattern.lastIndex;
+        }
+        if (cursor < text.length) tokens.push({ type: 'text', text: text.slice(cursor) });
+        return tokens;
+    }
+
+    root.KoalaSyncChatFormat = Object.freeze({ escapeChatHtml, formatChatText, tokenizeChatText });
+})(globalThis);

extension/chat-format.test.mjs

@@ -0,0 +1,22 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+beforeAll(async () => {
+    await import('./chat-format.js');
+});
+
+describe('chat formatting', () => {
+    it('escapes executable HTML before applying limited Markdown', () => {
+        const result = globalThis.KoalaSyncChatFormat.formatChatText('<img src=x onerror=alert(1)> **bold** *italic*');
+        expect(result).toBe('&lt;img src=x onerror=alert(1)&gt; <strong>bold</strong> <em>italic</em>');
+        expect(result).not.toContain('<img');
+    });
+
+    it('tokenizes only text, strong, and emphasis nodes', () => {
+        expect(globalThis.KoalaSyncChatFormat.tokenizeChatText('<script>x</script> **bold** *italic*')).toEqual([
+            { type: 'text', text: '<script>x</script> ' },
+            { type: 'strong', text: 'bold' },
+            { type: 'text', text: ' ' },
+            { type: 'em', text: 'italic' }
+        ]);
+    });
+});

extension/chat-overlay-contract.test.mjs

@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const extensionDir = path.dirname(fileURLToPath(import.meta.url));
+const overlaySource = fs.readFileSync(path.join(extensionDir, 'chat-overlay.js'), 'utf8');
+const backgroundSource = fs.readFileSync(path.join(extensionDir, 'background.js'), 'utf8');
+const popupSource = fs.readFileSync(path.join(extensionDir, 'popup.js'), 'utf8');
+const localeDir = path.join(extensionDir, 'locales');
+const chatKeys = [
+    'LABEL_CHAT_ENABLED',
+    'LABEL_CHAT_ENABLED_TOOLTIP',
+    'CHAT_TITLE',
+    'CHAT_LIVE_ONLY',
+    'CHAT_OPEN',
+    'CHAT_CLOSE',
+    'CHAT_DOCK_LEFT',
+    'CHAT_DOCK_RIGHT',
+    'CHAT_DETACHED',
+    'CHAT_PLACEHOLDER',
+    'CHAT_SEND',
+    'CHAT_MISSING_KEY',
+    'CHAT_TOO_LONG',
+    'CHAT_SEND_FAILED',
+    'CHAT_EMPTY'
+];
+
+describe('chat overlay contract', () => {
+    it('isolates the overlay and never renders markup as HTML', () => {
+        expect(overlaySource).toContain("attachShadow({ mode: 'open' })");
+        expect(overlaySource).not.toMatch(/\.innerHTML\s*=|insertAdjacentHTML|\.outerHTML\s*=/);
+        expect(overlaySource).toContain('document.createTextNode(token.text)');
+    });
+
+    it('injects formatting and overlay code only with the selected-tab content script', () => {
+        expect(backgroundSource).toContain("files: ['chat-format.js', 'chat-overlay.js', 'content.js']");
+        expect(overlaySource).toContain("const storageKey = `chatOverlayLayout:${location.origin}`");
+        expect(overlaySource).toContain('document.fullscreenElement || document.documentElement');
+    });
+
+    it('supports all layout and theme combinations with bounded message DOM', () => {
+        expect(overlaySource).toContain("['left', 'right', 'detached']");
+        expect(overlaySource).toContain('!layout.detachedInitialized');
+        expect(overlaySource).toContain('const rect = panel.getBoundingClientRect()');
+        expect(overlaySource).not.toContain('contentRect');
+        expect(overlaySource).toContain("#app[data-palette=\"cyber\"][data-theme=\"light\"]");
+        expect(overlaySource).toContain("#app[data-palette=\"graphite\"][data-theme=\"light\"]");
+        expect(overlaySource).toContain('const MAX_MESSAGES = 200');
+        expect(overlaySource).toContain('while (messages.querySelectorAll(\'.message\').length > MAX_MESSAGES)');
+        expect(overlaySource).toContain('Math.max(1, window.innerWidth)');
+        expect(overlaySource).toContain('min(${MIN_WIDTH}px, calc(100vw - 16px))');
+    });
+
+    it('blocks page playback shortcuts while the chat composer owns keyboard input', () => {
+        expect(overlaySource).toContain("for (const eventName of ['keydown', 'keyup', 'keypress'])");
+        expect(overlaySource).toContain('window.addEventListener(eventName, stopPageKeyboardShortcut, true)');
+        expect(overlaySource).toContain('path.includes(textarea)');
+        expect(overlaySource).toContain('event.stopImmediatePropagation()');
+        expect(overlaySource).toContain('window.removeEventListener(eventName, stopPageKeyboardShortcut, true)');
+    });
+
+    it('keeps the launcher draggable independently from dock mode', () => {
+        expect(overlaySource).toContain("launcher.addEventListener('pointerdown'");
+        expect(overlaySource).toContain("launcher.addEventListener('pointermove'");
+        expect(overlaySource).toContain('layout.launcherX = launcherDrag.x + deltaX');
+        expect(overlaySource).toContain('layout.launcherY = launcherDrag.y + deltaY');
+        expect(overlaySource).toContain('suppressLauncherClick = launcherDrag.moved');
+        expect(overlaySource).not.toMatch(/launcher\.style\.left = `\$\{layout\.x\}px`/);
+    });
+
+    it('reserves page space for real left and right dock modes', () => {
+        expect(overlaySource).toContain("const PAGE_DOCK_ATTRIBUTE = 'data-koalasync-chat-dock'");
+        expect(overlaySource).toContain('padding-left: var(${PAGE_DOCK_WIDTH}) !important');
+        expect(overlaySource).toContain('padding-right: var(${PAGE_DOCK_WIDTH}) !important');
+        expect(overlaySource).toContain('document.documentElement.setAttribute(PAGE_DOCK_ATTRIBUTE, side)');
+        expect(overlaySource).toContain('applyPageDock(layout.mode, dockWidth)');
+        expect(overlaySource).toContain('clearPageDock()');
+    });
+
+    it('counts unread remote messages on the bubble and clears the badge when opened', () => {
+        expect(overlaySource).toContain("const unreadBadge = element('span', 'unread')");
+        expect(overlaySource).toContain('if (!opened && !own) setUnreadCount(unreadCount + 1)');
+        expect(overlaySource).toMatch(/if \(opened\) \{\s*setUnreadCount\(0\)/);
+        expect(overlaySource).toContain("unreadBadge.classList.toggle('visible', unreadCount > 0)");
+        expect(backgroundSource).toMatch(/received\.senderId !== peerId[\s\S]*showChatNotification\([\s\S]*senderPeer\.username[\s\S]*received\.senderId/);
+        expect(backgroundSource).toContain("chrome.notifications.create(`chat_${Date.now()}`");
+        expect(backgroundSource).toContain("if (settings.chatNotifications === false) return");
+    });
+
+    it('renders timestamped room activity and keeps activity notifications opt-in', () => {
+        expect(overlaySource).toContain("if (message?.type === 'CHAT_EVENT') appendEvent(message.event)");
+        expect(overlaySource).toContain("const time = element('time', 'time')");
+        expect(overlaySource).toContain("date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })");
+        expect(overlaySource).toContain('if (!opened && context.eventNotifications) setUnreadCount(unreadCount + 1)');
+        expect(backgroundSource).toContain("eventNotifications: localeData.browserNotifications === true");
+        expect(backgroundSource).toContain("sendChatActivity(message.action, peerId, timestamp)");
+        expect(backgroundSource).toContain("sendChatActivity(event, data.senderId, data.actionTimestamp)");
+        expect(backgroundSource).toContain("sendChatActivity('joined', data.peerId, Date.now())");
+        expect(backgroundSource).toContain("sendChatActivity('left', data.peerId, Date.now())");
+    });
+
+    it('guards async refresh/send work and clears all composer state on room reset', () => {
+        expect(overlaySource).toContain('generation !== refreshGeneration');
+        expect(overlaySource).toContain('if (sending || !context?.enabled) return');
+        expect(overlaySource).toContain('textarea.value === submittedValue');
+        expect(overlaySource).toMatch(/CHAT_RESET[\s\S]*resetComposer\(\)/);
+        expect(overlaySource).toContain('setTimeout(() => finish(null), timeoutMs)');
+        expect(backgroundSource).toContain('chatReceiveQueue = chatReceiveQueue.catch(() => {}).then');
+        expect(backgroundSource).toContain("status: 'rate_limited'");
+    });
+
+    it('keeps chat hidden by default without discarding the room chat key', () => {
+        expect(popupSource).toContain('localData.chatEnabled === true');
+        expect(backgroundSource).toContain('chatEnabled: data.chatEnabled === true');
+        expect(backgroundSource).toContain('clientCapabilities: CLIENT_CAPABILITIES');
+        expect(overlaySource).toContain('all:initial;display:none;position:fixed');
+        expect(overlaySource).toContain("host.style.display = supported && optedIn ? '' : 'none'");
+        expect(overlaySource).toContain('supported && optedIn && hasKey && connected');
+        expect(popupSource).toContain("chrome.storage.local.set({ chatEnabled: elements.chatEnabled.checked })");
+        expect(popupSource).toMatch(/if \(isCreating\) \{[\s\S]*?type: 'CREATE_CHAT_KEY'[\s\S]*?chatKey = normalizeChatKey/);
+        expect(popupSource).not.toMatch(/chatEnabled[\s\S]{0,120}chatKey:\s*''/);
+    });
+
+    it('keeps unavailable chat controls discoverable to assistive technology', () => {
+        expect(overlaySource).toContain("launcher.setAttribute('aria-disabled'");
+        expect(overlaySource).not.toContain('launcher.disabled =');
+        expect(overlaySource).toContain("launcher.setAttribute('aria-describedby', launcherHint.id)");
+        expect(overlaySource).toContain("textarea.setAttribute('aria-describedby', 'chat-composer-count chat-composer-status')");
+        expect(overlaySource).toContain("status.setAttribute('role', 'status')");
+    });
+
+    it('creates a chat key for both generated-room entry points', () => {
+        expect(popupSource).toContain('let pendingRoomCreation = false');
+        expect(popupSource).toContain('const isCreating = pendingRoomCreation || !roomIdInput');
+        expect(popupSource).toMatch(/function handleCreateRoom\(\)[\s\S]*pendingRoomCreation = true[\s\S]*elements\.joinBtn\.click\(\)/);
+        expect(popupSource).toContain("type: 'CREATE_CHAT_KEY'");
+    });
+
+    it('contains every chat string in all 15 extension locales', () => {
+        const localeFiles = fs.readdirSync(localeDir).filter(file => file.endsWith('.json')).sort();
+        expect(localeFiles).toHaveLength(15);
+        for (const file of localeFiles) {
+            const messages = JSON.parse(fs.readFileSync(path.join(localeDir, file), 'utf8'));
+            for (const key of chatKeys) {
+                expect(messages[key], `${file}: ${key}`).toBeTypeOf('string');
+                expect(messages[key], `${file}: ${key}`).not.toBe('');
+                expect(messages[key], `${file}: ${key}`).not.toMatch(/[—–]/);
+            }
+        }
+    });
+});

extension/chat-overlay.js

@@ -0,0 +1,808 @@
+(function initKoalaSyncChatOverlay() {
+    if (window.koalaSyncChatOverlay?.refresh) {
+        window.koalaSyncChatOverlay.refresh();
+        return;
+    }
+
+    const MAX_MESSAGES = 200;
+    const MIN_WIDTH = 300;
+    const MIN_HEIGHT = 320;
+    const DEFAULT_WIDTH = 360;
+    const DEFAULT_HEIGHT = 520;
+    const LAUNCHER_SIZE = 48;
+    const EDGE_INSET = 8;
+    const DOCK_MIN_PAGE_WIDTH = 480;
+    const PAGE_DOCK_ATTRIBUTE = 'data-koalasync-chat-dock';
+    const PAGE_DOCK_WIDTH = '--koalasync-chat-dock-width';
+    const SIZE_PRESETS = Object.freeze({
+        compact: Object.freeze({ width: 320, height: 400 }),
+        standard: Object.freeze({ width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT }),
+        large: Object.freeze({ width: 440, height: 640 })
+    });
+    const storageKey = `chatOverlayLayout:${location.origin}`;
+    const systemTheme = window.matchMedia('(prefers-color-scheme: light)');
+    let context = null;
+    let opened = false;
+    let destroyed = false;
+    let saveTimer = null;
+    let applyingLayout = false;
+    let preferencesLoaded = false;
+    let startStateApplied = false;
+    let refreshGeneration = 0;
+    let sendGeneration = 0;
+    let sending = false;
+    let unreadCount = 0;
+    let layout = {
+        mode: 'right',
+        x: 24,
+        y: 72,
+        width: DEFAULT_WIDTH,
+        height: DEFAULT_HEIGHT,
+        customWidth: DEFAULT_WIDTH,
+        customHeight: DEFAULT_HEIGHT,
+        detachedInitialized: false,
+        launcherX: null,
+        launcherY: null,
+        launcherInitialized: false
+    };
+    let chatPosition = 'right';
+    let chatSize = 'standard';
+    let chatStartMode = 'bubble';
+    let themeMode = 'system';
+    let themePalette = 'eucalyptus';
+
+    const host = document.createElement('div');
+    host.id = 'koalasync-chat-overlay-host';
+    host.style.cssText = 'all:initial;display:none;position:fixed;inset:0;z-index:2147483647;pointer-events:none;contain:layout style paint;transform:translateZ(0);';
+    const shadow = host.attachShadow({ mode: 'open' });
+    const style = document.createElement('style');
+    style.textContent = `
+        :host { all: initial; }
+        * { box-sizing: border-box; }
+        #app {
+            --bg: oklch(0.205 0.025 155); --card: oklch(0.30 0.035 150);
+            --surface-alt: oklch(0.265 0.032 150); --surface-deep: oklch(0.205 0.025 155);
+            --accent: oklch(0.73 0.13 155); --accent-hover: oklch(0.79 0.12 155);
+            --text: oklch(0.96 0.01 90); --text-muted: oklch(0.78 0.02 90);
+            --border-soft: oklch(0.88 0.025 145 / 0.09); --border-strong: oklch(0.39 0.038 145);
+            --text-on-green: oklch(0.14 0.02 90); --danger: oklch(0.63 0.18 25);
+            position: fixed; inset: 0; pointer-events: none; color: var(--text);
+            font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        }
+        #app[data-theme="light"] {
+            --bg: oklch(0.935 0.018 110); --card: oklch(0.995 0.006 100);
+            --surface-alt: oklch(0.91 0.022 115); --surface-deep: oklch(0.935 0.018 110);
+            --accent: oklch(0.52 0.13 155); --accent-hover: oklch(0.45 0.12 155);
+            --text: oklch(0.21 0.03 140); --text-muted: oklch(0.43 0.03 135);
+            --border-soft: oklch(0.28 0.035 140 / 0.10); --border-strong: oklch(0.73 0.035 125);
+            --text-on-green: oklch(0.16 0.03 140);
+        }
+        #app[data-palette="cyber"] {
+            --bg: oklch(0.185 0.04 265); --card: oklch(0.285 0.05 265);
+            --surface-alt: oklch(0.25 0.048 265); --surface-deep: oklch(0.185 0.04 265);
+            --accent: oklch(0.59 0.20 275); --accent-hover: oklch(0.69 0.17 275);
+            --text: oklch(0.97 0.012 265); --text-muted: oklch(0.74 0.03 265);
+            --border-soft: oklch(0.9 0.03 265 / 0.10); --border-strong: oklch(0.42 0.05 265);
+            --text-on-green: oklch(0.99 0.006 275);
+        }
+        #app[data-palette="cyber"][data-theme="light"] {
+            --bg: oklch(0.945 0.014 265); --card: oklch(0.995 0.005 265);
+            --surface-alt: oklch(0.915 0.02 265); --surface-deep: oklch(0.945 0.014 265);
+            --accent: oklch(0.53 0.21 275); --accent-hover: oklch(0.46 0.20 275);
+            --text: oklch(0.26 0.05 265); --text-muted: oklch(0.48 0.045 265);
+            --border-soft: oklch(0.30 0.05 265 / 0.12); --border-strong: oklch(0.79 0.03 265);
+            --text-on-green: oklch(0.99 0.005 275);
+        }
+        #app[data-palette="graphite"] {
+            --bg: oklch(0.165 0.004 260); --card: oklch(0.255 0.005 260);
+            --surface-alt: oklch(0.225 0.005 260); --surface-deep: oklch(0.165 0.004 260);
+            --accent: oklch(0.93 0.006 260); --accent-hover: oklch(0.99 0.003 260);
+            --text: oklch(0.97 0.003 260); --text-muted: oklch(0.72 0.005 260);
+            --border-soft: oklch(0.92 0.008 260 / 0.11); --border-strong: oklch(0.42 0.006 260);
+            --text-on-green: oklch(0.20 0.004 260);
+        }
+        #app[data-palette="graphite"][data-theme="light"] {
+            --bg: oklch(0.928 0.003 260); --card: oklch(1 0 0);
+            --surface-alt: oklch(0.90 0.004 260); --surface-deep: oklch(0.928 0.003 260);
+            --accent: oklch(0.28 0.006 260); --accent-hover: oklch(0.18 0.005 260);
+            --text: oklch(0.22 0.005 260); --text-muted: oklch(0.46 0.006 260);
+            --border-soft: oklch(0.20 0.006 260 / 0.13); --border-strong: oklch(0.77 0.004 260);
+            --text-on-green: oklch(0.98 0.002 260);
+        }
+        button, textarea { font: inherit; }
+        button { color: inherit; }
+        .launcher {
+             position: fixed; width: 48px; height: 48px; border: 1px solid var(--border-strong);
+             border-radius: 16px; background: var(--card); color: var(--text); cursor: pointer;
+             pointer-events: auto; box-shadow: 0 10px 28px rgb(0 0 0 / .32); font-size: 22px;
+             touch-action: none; user-select: none;
+         }
+         .launcher:hover:not([aria-disabled="true"]) { border-color: var(--accent); transform: translateY(-1px); }
+         .launcher[aria-disabled="true"] { cursor: not-allowed; opacity: .58; }
+         .launcher-icon { pointer-events: none; }
+         .unread {
+             position: absolute; top: -7px; right: -7px; display: none; min-width: 22px; height: 22px;
+             align-items: center; justify-content: center; padding: 0 6px; border: 2px solid var(--card);
+             border-radius: 999px; background: var(--danger); color: white; font-size: 11px; font-weight: 800;
+             line-height: 1; pointer-events: none;
+         }
+         .unread.visible { display: flex; }
+         .panel {
+            position: fixed; display: none; flex-direction: column; overflow: hidden;
+            min-width: min(${MIN_WIDTH}px, calc(100vw - 16px)); min-height: min(${MIN_HEIGHT}px, calc(100vh - 16px)); max-width: calc(100vw - 16px);
+            max-height: calc(100vh - 16px); pointer-events: auto; color: var(--text);
+            background: var(--card); border: 1px solid var(--border-strong); border-radius: 18px;
+            box-shadow: 0 18px 55px rgb(0 0 0 / .38); transform: translateZ(0);
+         }
+         .panel.open { display: flex; }
+         .panel.docked { border-radius: 0; max-height: 100vh; }
+         .header { display: flex; align-items: center; gap: 10px; padding: 12px; border-bottom: 1px solid var(--border-soft); user-select: none; }
+        .header.detached { cursor: move; }
+        .heading { min-width: 0; flex: 1; }
+        .title { font-size: 14px; font-weight: 760; }
+        .subtitle { color: var(--text-muted); font-size: 11px; }
+        .modes { display: flex; gap: 4px; }
+        .icon-button { width: 30px; height: 30px; border: 1px solid var(--border-soft); border-radius: 9px; background: var(--surface-alt); cursor: pointer; }
+        .icon-button:hover, .icon-button.active { border-color: var(--accent); color: var(--accent); }
+        .messages { flex: 1; min-height: 0; overflow-y: auto; padding: 12px; background: var(--bg); overscroll-behavior: contain; }
+        .empty { color: var(--text-muted); text-align: center; padding: 32px 12px; font-size: 12px; }
+        .message { margin-bottom: 11px; overflow-wrap: anywhere; }
+        .meta { display: flex; align-items: baseline; gap: 7px; margin-bottom: 2px; }
+        .sender { color: var(--accent); font-weight: 700; font-size: 12px; }
+        .time { color: var(--text-muted); font-size: 10px; }
+         .body { white-space: pre-wrap; color: var(--text); }
+         .event-message {
+             display: flex; align-items: center; justify-content: center; gap: 7px; margin: 8px 0;
+             color: var(--text-muted); font-size: 11px; text-align: center;
+         }
+         .event-message::before, .event-message::after { content: ""; flex: 1; height: 1px; background: var(--border-soft); }
+         .event-text { max-width: 78%; }
+        .composer { padding: 10px; border-top: 1px solid var(--border-soft); background: var(--card); }
+        textarea { width: 100%; min-height: 62px; max-height: 132px; resize: vertical; border: 1px solid var(--border-strong); border-radius: 11px; padding: 9px; background: var(--surface-deep); color: var(--text); outline: none; }
+        textarea:focus { border-color: var(--accent); }
+        textarea::placeholder { color: var(--text-muted); }
+        .composer-row { display: flex; align-items: center; gap: 8px; margin-top: 7px; }
+        .count { flex: 1; color: var(--text-muted); font-size: 10px; }
+        .status { color: var(--danger); font-size: 10px; min-height: 14px; }
+        .send { border: 0; border-radius: 10px; padding: 8px 13px; background: var(--accent); color: var(--text-on-green); font-weight: 750; cursor: pointer; }
+        .send:hover:not(:disabled) { background: var(--accent-hover); }
+        .send:disabled { opacity: .55; cursor: wait; }
+        .visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+        @media (max-width: 520px) { .panel { max-width: calc(100vw - 12px); } }
+        @media (prefers-reduced-motion: reduce) { * { transition: none !important; } }
+    `;
+
+    function element(tag, className, text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text !== undefined) node.textContent = text;
+        return node;
+    }
+
+    const app = element('div');
+    app.id = 'app';
+    const launcher = element('button', 'launcher');
+    launcher.type = 'button';
+    const launcherIcon = element('span', 'launcher-icon', '💬');
+    const unreadBadge = element('span', 'unread');
+    unreadBadge.setAttribute('aria-hidden', 'true');
+    launcher.append(launcherIcon, unreadBadge);
+    const launcherHint = element('span', 'visually-hidden');
+    launcherHint.id = 'chat-launcher-hint';
+    const panel = element('section', 'panel');
+    panel.setAttribute('role', 'dialog');
+    const header = element('header', 'header');
+    const heading = element('div', 'heading');
+    const title = element('div', 'title');
+    const subtitle = element('div', 'subtitle');
+    heading.append(title, subtitle);
+    const modes = element('div', 'modes');
+    const leftButton = element('button', 'icon-button', '←');
+    const detachedButton = element('button', 'icon-button', '✥');
+    const rightButton = element('button', 'icon-button', '→');
+    const closeButton = element('button', 'icon-button', '×');
+    for (const button of [leftButton, detachedButton, rightButton, closeButton]) button.type = 'button';
+    modes.append(leftButton, detachedButton, rightButton, closeButton);
+    header.append(heading, modes);
+    const messages = element('div', 'messages');
+    messages.setAttribute('aria-live', 'polite');
+    const empty = element('div', 'empty');
+    messages.append(empty);
+    const composer = element('form', 'composer');
+    const textareaLabel = element('label', 'visually-hidden');
+    textareaLabel.htmlFor = 'chat-composer-input';
+    const textarea = element('textarea');
+    textarea.id = 'chat-composer-input';
+    textarea.setAttribute('aria-describedby', 'chat-composer-count chat-composer-status');
+    const composerRow = element('div', 'composer-row');
+    const count = element('span', 'count', '0/500');
+    count.id = 'chat-composer-count';
+    const sendButton = element('button', 'send');
+    sendButton.type = 'submit';
+    composerRow.append(count, sendButton);
+    const status = element('div', 'status');
+    status.id = 'chat-composer-status';
+    status.setAttribute('role', 'status');
+    composer.append(textareaLabel, textarea, composerRow, status);
+    panel.append(header, messages, composer);
+    app.append(launcherHint, launcher, panel);
+    shadow.append(style, app);
+    document.documentElement.append(host);
+    const pageDockStyle = document.createElement('style');
+    pageDockStyle.id = 'koalasync-chat-page-dock-style';
+    pageDockStyle.textContent = `
+        html[${PAGE_DOCK_ATTRIBUTE}="left"] {
+            box-sizing: border-box !important;
+            padding-left: var(${PAGE_DOCK_WIDTH}) !important;
+        }
+        html[${PAGE_DOCK_ATTRIBUTE}="right"] {
+            box-sizing: border-box !important;
+            padding-right: var(${PAGE_DOCK_WIDTH}) !important;
+        }
+    `;
+    document.documentElement.append(pageDockStyle);
+
+    function messageRuntime(payload, timeoutMs = 5000) {
+        return new Promise(resolve => {
+            let settled = false;
+            const finish = response => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeout);
+                resolve(response || null);
+            };
+            const timeout = setTimeout(() => finish(null), timeoutMs);
+            try {
+                chrome.runtime.sendMessage(payload, response => {
+                    if (chrome.runtime.lastError) finish(null);
+                    else finish(response);
+                });
+            } catch (_) {
+                finish(null);
+            }
+        });
+    }
+
+    function strings() {
+        return context?.strings || {};
+    }
+
+    function applyStrings() {
+        const text = strings();
+        title.textContent = text.title || '';
+        subtitle.textContent = text.liveOnly || '';
+        launcher.setAttribute('aria-label', text.open || '');
+        const unavailableHint = context?.supported && !context?.hasKey
+            ? (text.missingKey || '')
+            : context?.supported && !context?.connected ? (text.sendFailed || '') : '';
+        launcher.title = unavailableHint || text.open || '';
+        launcherHint.textContent = unavailableHint;
+        if (unavailableHint) launcher.setAttribute('aria-describedby', launcherHint.id);
+        else launcher.removeAttribute('aria-describedby');
+        panel.setAttribute('aria-label', text.title || '');
+        textarea.placeholder = text.placeholder || '';
+        textareaLabel.textContent = text.placeholder || text.title || '';
+        sendButton.textContent = text.send || '';
+        empty.textContent = text.empty || '';
+        leftButton.title = text.dockLeft || '';
+        detachedButton.title = text.detached || '';
+        rightButton.title = text.dockRight || '';
+        closeButton.title = text.close || '';
+        leftButton.setAttribute('aria-label', text.dockLeft || '');
+        detachedButton.setAttribute('aria-label', text.detached || '');
+        rightButton.setAttribute('aria-label', text.dockRight || '');
+        closeButton.setAttribute('aria-label', text.close || '');
+        applyUnreadCount();
+    }
+
+    function applyTheme() {
+        const light = themeMode === 'light' || (themeMode === 'system' && systemTheme.matches);
+        app.dataset.theme = light ? 'light' : 'dark';
+        app.dataset.palette = ['eucalyptus', 'cyber', 'graphite'].includes(themePalette) ? themePalette : 'eucalyptus';
+    }
+
+    function viewportBounds() {
+        return { width: Math.max(1, window.innerWidth), height: Math.max(1, window.innerHeight) };
+    }
+
+    function normalizePosition(value) {
+        return ['left', 'right', 'detached'].includes(value) ? value : 'right';
+    }
+
+    function normalizeSize(value) {
+        return ['compact', 'standard', 'large', 'custom'].includes(value) ? value : 'standard';
+    }
+
+    function preferredSize() {
+        return SIZE_PRESETS[chatSize] || {
+            width: Number(layout.customWidth) || DEFAULT_WIDTH,
+            height: Number(layout.customHeight) || DEFAULT_HEIGHT
+        };
+    }
+
+    function clampLauncher() {
+        const viewport = viewportBounds();
+        const maxX = Math.max(0, viewport.width - LAUNCHER_SIZE - EDGE_INSET);
+        const maxY = Math.max(0, viewport.height - LAUNCHER_SIZE - EDGE_INSET);
+        layout.launcherX = Math.min(Math.max(Number(layout.launcherX) || EDGE_INSET, EDGE_INSET), maxX);
+        layout.launcherY = Math.min(Math.max(Number(layout.launcherY) || EDGE_INSET, EDGE_INSET), maxY);
+    }
+
+    function initializeLauncher() {
+        if (layout.launcherInitialized) return;
+        const viewport = viewportBounds();
+        layout.launcherX = chatPosition === 'left'
+            ? Math.min(16, Math.max(EDGE_INSET, viewport.width - LAUNCHER_SIZE - EDGE_INSET))
+            : Math.max(EDGE_INSET, viewport.width - LAUNCHER_SIZE - 16);
+        layout.launcherY = Math.max(EDGE_INSET, Math.round(viewport.height / 2 - LAUNCHER_SIZE / 2));
+        layout.launcherInitialized = true;
+        clampLauncher();
+    }
+
+    function clearPageDock() {
+        document.documentElement.removeAttribute(PAGE_DOCK_ATTRIBUTE);
+        document.documentElement.style.removeProperty(PAGE_DOCK_WIDTH);
+    }
+
+    function applyPageDock(side, width) {
+        const viewport = viewportBounds();
+        if (!opened || document.fullscreenElement || viewport.width - width < DOCK_MIN_PAGE_WIDTH) {
+            clearPageDock();
+            return;
+        }
+        document.documentElement.setAttribute(PAGE_DOCK_ATTRIBUTE, side);
+        document.documentElement.style.setProperty(PAGE_DOCK_WIDTH, `${width}px`);
+    }
+
+    function applyUnreadCount() {
+        unreadBadge.textContent = unreadCount > 99 ? '99+' : String(unreadCount);
+        unreadBadge.classList.toggle('visible', unreadCount > 0);
+        const openLabel = strings().open || '';
+        launcher.setAttribute('aria-label', unreadCount > 0 ? `${openLabel} (${unreadCount})` : openLabel);
+    }
+
+    function setUnreadCount(next) {
+        unreadCount = Math.max(0, Number.isFinite(next) ? Math.trunc(next) : 0);
+        applyUnreadCount();
+    }
+
+    function clampDetached() {
+        const viewport = viewportBounds();
+        const maxWidth = Math.max(1, Math.min(600, viewport.width - 16));
+        const maxHeight = Math.max(1, viewport.height - 16);
+        const horizontalInset = Math.min(8, Math.max(0, Math.floor((viewport.width - 1) / 2)));
+        const verticalInset = Math.min(8, Math.max(0, Math.floor((viewport.height - 1) / 2)));
+        layout.width = Math.min(Math.max(Number(layout.width) || DEFAULT_WIDTH, Math.min(MIN_WIDTH, maxWidth)), maxWidth);
+        layout.height = Math.min(Math.max(Number(layout.height) || DEFAULT_HEIGHT, Math.min(MIN_HEIGHT, maxHeight)), maxHeight);
+        layout.x = Math.min(Math.max(Number(layout.x) || horizontalInset, horizontalInset), Math.max(horizontalInset, viewport.width - layout.width - horizontalInset));
+        layout.y = Math.min(Math.max(Number(layout.y) || verticalInset, verticalInset), Math.max(verticalInset, viewport.height - layout.height - verticalInset));
+    }
+
+    function saveLayout() {
+        if (saveTimer) clearTimeout(saveTimer);
+        saveTimer = setTimeout(() => {
+            saveTimer = null;
+            chrome.storage.local.set({ [storageKey]: layout }).catch(() => {});
+        }, 150);
+    }
+
+    function applyLayout() {
+        applyingLayout = true;
+        const size = preferredSize();
+        initializeLauncher();
+        clampLauncher();
+        launcher.style.left = `${layout.launcherX}px`;
+        launcher.style.right = 'auto';
+        launcher.style.top = `${layout.launcherY}px`;
+        panel.style.right = 'auto';
+        panel.style.left = 'auto';
+        panel.style.bottom = 'auto';
+        panel.style.resize = 'none';
+        panel.classList.toggle('docked', layout.mode !== 'detached');
+        header.classList.toggle('detached', layout.mode === 'detached');
+        leftButton.classList.toggle('active', layout.mode === 'left');
+        detachedButton.classList.toggle('active', layout.mode === 'detached');
+        rightButton.classList.toggle('active', layout.mode === 'right');
+        if (layout.mode === 'detached') {
+            clearPageDock();
+            clampDetached();
+            panel.style.left = `${layout.x}px`;
+            panel.style.top = `${layout.y}px`;
+            panel.style.width = `${layout.width}px`;
+            panel.style.height = `${layout.height}px`;
+            panel.style.resize = 'both';
+        } else {
+            const viewport = viewportBounds();
+            const dockWidth = Math.max(1, Math.min(size.width, viewport.width - 16));
+            panel.style.top = '0';
+            panel.style.bottom = '0';
+            panel.style.width = `${dockWidth}px`;
+            panel.style.height = `${viewport.height}px`;
+            panel.style[layout.mode] = '0';
+            applyPageDock(layout.mode, dockWidth);
+        }
+        globalThis.queueMicrotask(() => { applyingLayout = false; });
+    }
+
+    function setMode(mode, persistPreference = true) {
+        mode = normalizePosition(mode);
+        if (mode === 'detached' && !layout.detachedInitialized) {
+            const size = preferredSize();
+            layout.x = Math.max(8, Math.round((window.innerWidth - size.width) / 2));
+            layout.y = Math.max(8, Math.round((window.innerHeight - size.height) / 2));
+            layout.detachedInitialized = true;
+        }
+        chatPosition = mode;
+        layout.mode = mode;
+        applyLayout();
+        saveLayout();
+        if (persistPreference) chrome.storage.local.set({ chatPosition: mode }).catch(() => {});
+    }
+
+    function setSize(size, persistPreference = true) {
+        chatSize = normalizeSize(size);
+        const preset = SIZE_PRESETS[chatSize];
+        if (preset) {
+            layout.width = preset.width;
+            layout.height = preset.height;
+        } else {
+            layout.width = Number(layout.customWidth) || DEFAULT_WIDTH;
+            layout.height = Number(layout.customHeight) || DEFAULT_HEIGHT;
+        }
+        if (layout.mode === 'detached') clampDetached();
+        applyLayout();
+        saveLayout();
+        if (persistPreference) chrome.storage.local.set({ chatSize }).catch(() => {});
+    }
+
+    function setOpened(next) {
+        opened = !!next && !!context?.enabled;
+        panel.classList.toggle('open', opened);
+        launcher.style.display = opened ? 'none' : '';
+        if (opened) {
+            setUnreadCount(0);
+            textarea.focus();
+            messages.scrollTop = messages.scrollHeight;
+        }
+        applyLayout();
+    }
+
+    function applyContext(next) {
+        const previousRoomId = context?.roomId;
+        context = next || null;
+        const supported = !!context?.supported;
+        const optedIn = !!context?.enabled;
+        const hasKey = !!context?.hasKey;
+        const connected = !!context?.connected;
+        context = context ? { ...context, enabled: supported && optedIn && hasKey && connected } : null;
+        if (previousRoomId && previousRoomId !== context?.roomId) {
+            clearMessages();
+            startStateApplied = false;
+        }
+        host.style.display = supported && optedIn ? '' : 'none';
+        launcher.setAttribute('aria-disabled', String(!context?.enabled));
+        if (!optedIn) startStateApplied = false;
+        if (!context?.enabled) {
+            setOpened(false);
+        } else if (preferencesLoaded && !startStateApplied) {
+            startStateApplied = true;
+            setOpened(chatStartMode === 'open');
+        }
+        applyStrings();
+        applyLayout();
+    }
+
+    async function refresh() {
+        if (destroyed) return;
+        const generation = ++refreshGeneration;
+        const next = await messageRuntime({ type: 'GET_CHAT_CONTEXT' });
+        if (destroyed || generation !== refreshGeneration) return;
+        applyContext(next);
+    }
+
+    function appendMessage(message) {
+        if (!context?.enabled || !message || typeof message.text !== 'string') return;
+        if (empty.isConnected) empty.remove();
+        const wrapper = element('article', 'message');
+        const meta = element('div', 'meta');
+        const own = message.senderId === context.peerId;
+        if (!opened && !own) setUnreadCount(unreadCount + 1);
+        const sender = element('span', 'sender', own ? (strings().you || '') : (message.username || message.senderId || ''));
+        const time = element('time', 'time');
+        const date = new Date(message.timestamp);
+        time.textContent = Number.isFinite(date.getTime()) ? date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : '';
+        meta.append(sender, time);
+        const body = element('div', 'body');
+        const tokens = globalThis.KoalaSyncChatFormat?.tokenizeChatText(message.text) || [{ type: 'text', text: message.text }];
+        for (const token of tokens) {
+            const node = token.type === 'strong' ? document.createElement('strong') : token.type === 'em' ? document.createElement('em') : document.createTextNode(token.text);
+            if (node.nodeType === 1) node.textContent = token.text;
+            body.append(node);
+        }
+        wrapper.append(meta, body);
+        messages.append(wrapper);
+        while (messages.querySelectorAll('.message').length > MAX_MESSAGES) messages.querySelector('.message')?.remove();
+        messages.scrollTop = messages.scrollHeight;
+    }
+
+    function appendEvent(event) {
+        if (!context?.enabled || !event || typeof event.action !== 'string') return;
+        const own = event.senderId === context.peerId;
+        const displayName = own ? (strings().you || '') : (event.username || event.senderId || '');
+        const labels = {
+            play: strings().eventPlay,
+            pause: strings().eventPause,
+            seek: strings().eventSeek,
+            force_sync_prepare: strings().eventForcePrepare,
+            force_sync_execute: strings().eventForceExecute
+        };
+        let eventText = '';
+        if (event.action === 'joined' || event.action === 'left') {
+            const template = event.action === 'joined' ? strings().eventJoined : strings().eventLeft;
+            eventText = (template || '{name}').replace('{name}', displayName);
+        } else if (labels[event.action]) {
+            eventText = (strings().eventAction || '{name} {action}')
+                .replace('{name}', displayName)
+                .replace('{action}', labels[event.action]);
+        }
+        if (!eventText) return;
+
+        if (empty.isConnected) empty.remove();
+        if (!opened && context.eventNotifications) setUnreadCount(unreadCount + 1);
+        const wrapper = element('article', 'message event-message');
+        const body = element('span', 'event-text', eventText);
+        const time = element('time', 'time');
+        const date = new Date(event.timestamp);
+        time.textContent = Number.isFinite(date.getTime()) ? date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : '';
+        wrapper.append(body, time);
+        messages.append(wrapper);
+        while (messages.querySelectorAll('.message').length > MAX_MESSAGES) messages.querySelector('.message')?.remove();
+        messages.scrollTop = messages.scrollHeight;
+    }
+
+    function clearMessages() {
+        messages.replaceChildren(empty);
+        setUnreadCount(0);
+    }
+
+    function resetComposer() {
+        sendGeneration++;
+        sending = false;
+        textarea.value = '';
+        count.textContent = '0/500';
+        count.style.color = '';
+        status.textContent = '';
+        sendButton.disabled = false;
+    }
+
+    let launcherDrag = null;
+    let suppressLauncherClick = false;
+    launcher.addEventListener('click', event => {
+        if (suppressLauncherClick && event.detail !== 0) {
+            suppressLauncherClick = false;
+            return;
+        }
+        suppressLauncherClick = false;
+        setOpened(true);
+    });
+    launcher.addEventListener('pointerdown', event => {
+        launcherDrag = {
+            pointerId: event.pointerId,
+            startX: event.clientX,
+            startY: event.clientY,
+            x: layout.launcherX,
+            y: layout.launcherY,
+            moved: false
+        };
+        launcher.setPointerCapture(event.pointerId);
+    });
+    launcher.addEventListener('pointermove', event => {
+        if (!launcherDrag || event.pointerId !== launcherDrag.pointerId) return;
+        const deltaX = event.clientX - launcherDrag.startX;
+        const deltaY = event.clientY - launcherDrag.startY;
+        if (Math.hypot(deltaX, deltaY) >= 4) launcherDrag.moved = true;
+        layout.launcherX = launcherDrag.x + deltaX;
+        layout.launcherY = launcherDrag.y + deltaY;
+        clampLauncher();
+        launcher.style.left = `${layout.launcherX}px`;
+        launcher.style.top = `${layout.launcherY}px`;
+    });
+    launcher.addEventListener('pointerup', event => {
+        if (!launcherDrag || event.pointerId !== launcherDrag.pointerId) return;
+        suppressLauncherClick = launcherDrag.moved;
+        launcherDrag = null;
+        saveLayout();
+    });
+    launcher.addEventListener('pointercancel', () => {
+        launcherDrag = null;
+        suppressLauncherClick = false;
+    });
+    closeButton.addEventListener('click', () => setOpened(false));
+    leftButton.addEventListener('click', () => setMode('left'));
+    detachedButton.addEventListener('click', () => setMode('detached'));
+    rightButton.addEventListener('click', () => setMode('right'));
+
+    textarea.addEventListener('input', () => {
+        const length = [...textarea.value].length;
+        count.textContent = `${length}/500`;
+        count.style.color = length > 500 ? 'var(--danger)' : '';
+        status.textContent = length > 500 ? (strings().tooLong || '') : '';
+    });
+    const stopPageKeyboardShortcut = event => {
+        const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
+        if (!path.includes(textarea) && !path.includes(composer)) return;
+        if (event.type === 'keydown' && event.key === 'Enter' && !event.shiftKey) {
+            event.preventDefault();
+            if (!sending) composer.requestSubmit();
+        }
+        event.stopImmediatePropagation();
+    };
+    for (const eventName of ['keydown', 'keyup', 'keypress']) {
+        window.addEventListener(eventName, stopPageKeyboardShortcut, true);
+    }
+    composer.addEventListener('submit', async event => {
+        event.preventDefault();
+        if (sending || !context?.enabled) return;
+        const submittedValue = textarea.value;
+        const text = textarea.value.trim();
+        if (!text) return;
+        if ([...text].length > 500) {
+            status.textContent = strings().tooLong || '';
+            return;
+        }
+        const generation = ++sendGeneration;
+        sending = true;
+        sendButton.disabled = true;
+        status.textContent = '';
+        const response = await messageRuntime({ type: 'CHAT_SEND', text });
+        if (destroyed || generation !== sendGeneration) return;
+        sending = false;
+        sendButton.disabled = false;
+        if (response?.status === 'ok') {
+            if (textarea.value === submittedValue) {
+                textarea.value = '';
+                count.textContent = '0/500';
+            }
+        } else {
+            status.textContent = response?.status === 'too_long' ? (strings().tooLong || '') : (strings().sendFailed || '');
+        }
+    });
+
+    let drag = null;
+    header.addEventListener('pointerdown', event => {
+        if (layout.mode !== 'detached' || event.target.closest('button')) return;
+        drag = { pointerId: event.pointerId, startX: event.clientX, startY: event.clientY, x: layout.x, y: layout.y };
+        header.setPointerCapture(event.pointerId);
+    });
+    header.addEventListener('pointermove', event => {
+        if (!drag || event.pointerId !== drag.pointerId) return;
+        layout.x = drag.x + event.clientX - drag.startX;
+        layout.y = drag.y + event.clientY - drag.startY;
+        clampDetached();
+        applyLayout();
+    });
+    header.addEventListener('pointerup', event => {
+        if (!drag || event.pointerId !== drag.pointerId) return;
+        drag = null;
+        saveLayout();
+    });
+
+    const resizeObserver = new globalThis.ResizeObserver(() => {
+        if (applyingLayout || layout.mode !== 'detached') return;
+        const rect = panel.getBoundingClientRect();
+        if (!opened || !rect?.width || !rect.height) return;
+        if (Math.abs(rect.width - layout.width) < 1 && Math.abs(rect.height - layout.height) < 1) return;
+        layout.width = rect.width;
+        layout.height = rect.height;
+        layout.customWidth = rect.width;
+        layout.customHeight = rect.height;
+        if (chatSize !== 'custom') {
+            chatSize = 'custom';
+            chrome.storage.local.set({ chatSize }).catch(() => {});
+        }
+        clampDetached();
+        saveLayout();
+    });
+    resizeObserver.observe(panel);
+
+    function moveIntoFullscreen() {
+        const parent = document.fullscreenElement || document.documentElement;
+        if (parent && host.parentNode !== parent) parent.append(host);
+        globalThis.requestAnimationFrame(applyLayout);
+    }
+
+    function handleResize() {
+        clampLauncher();
+        applyLayout();
+        saveLayout();
+        if (layout.mode === 'detached') {
+            clampDetached();
+        }
+    }
+
+    function handleSystemTheme() {
+        if (themeMode === 'system') applyTheme();
+    }
+
+    function handleStorage(changes, area) {
+        if (area !== 'local') return;
+        if (changes.themeMode) themeMode = changes.themeMode.newValue || 'system';
+        if (changes.themePalette) themePalette = changes.themePalette.newValue || 'eucalyptus';
+        if (changes.themeMode || changes.themePalette) applyTheme();
+        if (changes.chatPosition) setMode(changes.chatPosition.newValue, false);
+        if (changes.chatSize) setSize(changes.chatSize.newValue, false);
+        if (changes.chatStartMode) {
+            chatStartMode = changes.chatStartMode.newValue === 'open' ? 'open' : 'bubble';
+            if (context?.enabled) {
+                startStateApplied = true;
+                setOpened(chatStartMode === 'open');
+            }
+        }
+        if (changes.locale) refresh();
+    }
+
+    function handleRuntime(message) {
+        if (message?.type === 'CHAT_MESSAGE') appendMessage(message.message);
+        if (message?.type === 'CHAT_EVENT') appendEvent(message.event);
+        if (message?.type === 'CHAT_CONTEXT_UPDATE' || message?.type === 'CONNECTION_STATUS') refresh();
+        if (message?.type === 'CHAT_RESET') {
+            clearMessages();
+            resetComposer();
+            refresh();
+        }
+        if (message?.type === 'CHAT_DESTROY') destroy();
+    }
+
+    function destroy() {
+        if (destroyed) return;
+        destroyed = true;
+        refreshGeneration++;
+        sendGeneration++;
+        if (saveTimer) clearTimeout(saveTimer);
+        resizeObserver.disconnect();
+        clearPageDock();
+        pageDockStyle.remove();
+        for (const eventName of ['keydown', 'keyup', 'keypress']) {
+            window.removeEventListener(eventName, stopPageKeyboardShortcut, true);
+        }
+        document.removeEventListener('fullscreenchange', moveIntoFullscreen);
+        window.removeEventListener('resize', handleResize);
+        systemTheme.removeEventListener('change', handleSystemTheme);
+        chrome.storage.onChanged.removeListener(handleStorage);
+        chrome.runtime.onMessage.removeListener(handleRuntime);
+        host.remove();
+        window.koalaSyncChatOverlay = null;
+    }
+
+    document.addEventListener('fullscreenchange', moveIntoFullscreen);
+    window.addEventListener('resize', handleResize, { passive: true });
+    systemTheme.addEventListener('change', handleSystemTheme);
+    chrome.storage.onChanged.addListener(handleStorage);
+    chrome.runtime.onMessage.addListener(handleRuntime);
+    chrome.storage.local.get([storageKey, 'themeMode', 'themePalette', 'chatPosition', 'chatSize', 'chatStartMode'], data => {
+        const storedLayout = data[storageKey];
+        if (storedLayout && typeof storedLayout === 'object') {
+            layout = { ...layout, ...storedLayout };
+            layout.customWidth = Number(storedLayout.customWidth) || Number(storedLayout.width) || DEFAULT_WIDTH;
+            layout.customHeight = Number(storedLayout.customHeight) || Number(storedLayout.height) || DEFAULT_HEIGHT;
+        }
+        chatPosition = normalizePosition(data.chatPosition);
+        chatSize = normalizeSize(data.chatSize);
+        chatStartMode = data.chatStartMode === 'open' ? 'open' : 'bubble';
+        layout.mode = chatPosition;
+        if (layout.mode === 'detached') layout.detachedInitialized = true;
+        const preset = SIZE_PRESETS[chatSize];
+        if (preset) {
+            layout.width = preset.width;
+            layout.height = preset.height;
+        }
+        themeMode = data.themeMode || 'system';
+        themePalette = data.themePalette || 'eucalyptus';
+        preferencesLoaded = true;
+        applyTheme();
+        applyLayout();
+        refresh();
+    });
+
+    window.koalaSyncChatOverlay = { refresh, destroy };
+})();

extension/chat-session.js

@@ -0,0 +1,58 @@
+export const MAX_ROOM_ID_LENGTH = 64;
+export const CHAT_SEND_LIMIT = 9;
+export const CHAT_SEND_WINDOW_MS = 10000;
+
+export function normalizeRoomId(value) {
+    if (typeof value !== 'string') return '';
+    return value.trim().replace(/[^a-zA-Z0-9\-]/g, '').slice(0, MAX_ROOM_ID_LENGTH);
+}
+
+export function createChatSendLimiter({
+    limit = CHAT_SEND_LIMIT,
+    windowMs = CHAT_SEND_WINDOW_MS,
+    now = () => Date.now()
+} = {}) {
+    let timestamps = [];
+
+    return {
+        take() {
+            const current = now();
+            timestamps = timestamps.filter(timestamp => current - timestamp < windowMs);
+            if (timestamps.length >= limit) {
+                return {
+                    allowed: false,
+                    retryAfterMs: Math.max(1, windowMs - (current - timestamps[0]))
+                };
+            }
+            timestamps.push(current);
+            return { allowed: true, retryAfterMs: 0 };
+        },
+        reset() {
+            timestamps = [];
+        }
+    };
+}
+
+export function createLatestTaskQueue() {
+    let generation = 0;
+    let tail = Promise.resolve();
+
+    return {
+        invalidate() {
+            generation++;
+        },
+        async run(task) {
+            const requestGeneration = ++generation;
+            const previous = tail;
+            let release;
+            tail = new Promise(resolve => { release = resolve; });
+            await previous.catch(() => {});
+            const isCurrent = () => requestGeneration === generation;
+            try {
+                return await task(isCurrent);
+            } finally {
+                release();
+            }
+        }
+    };
+}

extension/chat-session.test.mjs

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import {
+    CHAT_SEND_LIMIT,
+    createChatSendLimiter,
+    createLatestTaskQueue,
+    MAX_ROOM_ID_LENGTH,
+    normalizeRoomId
+} from './chat-session.js';
+
+describe('chat session boundaries', () => {
+    it('matches the relay room ID sanitizer and length limit', () => {
+        expect(normalizeRoomId('  ROOM_!42  ')).toBe('ROOM42');
+        expect(normalizeRoomId('A'.repeat(MAX_ROOM_ID_LENGTH + 10))).toBe('A'.repeat(MAX_ROOM_ID_LENGTH));
+        expect(normalizeRoomId(null)).toBe('');
+    });
+
+    it('keeps client chat bursts below the relay disconnect threshold', () => {
+        let current = 1000;
+        const limiter = createChatSendLimiter({ now: () => current });
+        for (let index = 0; index < CHAT_SEND_LIMIT; index++) {
+            expect(limiter.take()).toEqual({ allowed: true, retryAfterMs: 0 });
+        }
+        expect(limiter.take()).toEqual({ allowed: false, retryAfterMs: 10000 });
+        current += 10000;
+        expect(limiter.take()).toEqual({ allowed: true, retryAfterMs: 0 });
+        limiter.reset();
+        expect(limiter.take()).toEqual({ allowed: true, retryAfterMs: 0 });
+    });
+
+    it('serializes join work and prevents an older request from winning storage races', async () => {
+        const queue = createLatestTaskQueue();
+        let releaseFirst;
+        const writes = [];
+        const first = queue.run(async isCurrent => {
+            await new Promise(resolve => { releaseFirst = resolve; });
+            if (isCurrent()) writes.push('first');
+            return { status: isCurrent() ? 'ok' : 'superseded' };
+        });
+        await new Promise(resolve => setTimeout(resolve, 0));
+        const second = queue.run(async isCurrent => {
+            if (isCurrent()) writes.push('second');
+            return { status: 'ok' };
+        });
+        releaseFirst();
+        await expect(first).resolves.toEqual({ status: 'superseded' });
+        await expect(second).resolves.toEqual({ status: 'ok' });
+        expect(writes).toEqual(['second']);
+    });
+});

extension/chat-wire.js

@@ -0,0 +1,11 @@
+export function buildChatRelayPayload(ciphertext) {
+    return { ciphertext };
+}
+
+export function encodeSocketEvent(event, data, forbiddenSecret = '') {
+    const payload = JSON.stringify([event, data]);
+    if (forbiddenSecret && payload.includes(forbiddenSecret)) {
+        throw new Error('Refusing to send chat secret to relay');
+    }
+    return `42${payload}`;
+}

extension/chat-wire.test.mjs

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { buildChatRelayPayload, encodeSocketEvent } from './chat-wire.js';
+
+describe('chat wire boundary', () => {
+    const secret = 'R5Ti1nxp0crfAFHf3gVncw';
+
+    it('sends only ciphertext for chat messages', () => {
+        expect(buildChatRelayPayload('ciphertext')).toEqual({ ciphertext: 'ciphertext' });
+    });
+
+    it('rejects the secret anywhere in any outgoing relay event', () => {
+        for (const [event, payload] of [
+            ['join_room', { roomId: 'ROOM', password: 'PASS', chatKey: secret }],
+            ['peer_status', { status: 'heartbeat', nested: { secret } }],
+            ['chat_message', { ciphertext: `prefix-${secret}-suffix` }]
+        ]) {
+            expect(() => encodeSocketEvent(event, payload, secret)).toThrow('Refusing to send chat secret');
+        }
+        expect(encodeSocketEvent('join_room', { roomId: 'ROOM', password: 'PASS' }, secret)).not.toContain(secret);
+    });
+});

extension/episode-utils.js

@@ -0,0 +1,24 @@
+/**
+ * KoalaSync Episode Title Utilities
+ * Single source of truth — synced to content.js by build-extension.cjs.
+ * 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;
+}

extension/host-access.js

@@ -0,0 +1,194 @@
+export const HOST_ACCESS_REQUIRED_STATUS = 'host_permission_required';
+
+export function normalizeTabId(value) {
+    if (typeof value === 'number') {
+        return Number.isSafeInteger(value) && value > 0 ? value : null;
+    }
+    if (typeof value !== 'string') return null;
+
+    const normalized = value.trim();
+    if (!/^[1-9]\d*$/.test(normalized)) return null;
+    const tabId = Number(normalized);
+    return Number.isSafeInteger(tabId) ? tabId : null;
+}
+
+function browserSupportsPortMatchPatterns(chromeApi) {
+    // runtime.getBrowserInfo is a Firefox-only WebExtension API. Firefox does
+    // not accept ports in match patterns, while Chromium does.
+    return typeof chromeApi?.runtime?.getBrowserInfo !== 'function';
+}
+
+export function describeTabUrl(rawUrl, { includePort = true } = {}) {
+    if (typeof rawUrl !== 'string' || !rawUrl) return null;
+
+    try {
+        const url = new URL(rawUrl);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            const permissionHost = includePort ? url.host : url.hostname;
+            return {
+                url: rawUrl,
+                host: url.host,
+                originPattern: `${url.protocol}//${permissionHost}/*`
+            };
+        }
+        if (url.protocol === 'file:') {
+            return {
+                url: rawUrl,
+                host: 'local file',
+                originPattern: 'file:///*'
+            };
+        }
+    } catch (_e) {
+        // Invalid and browser-internal URLs cannot receive host access.
+    }
+
+    return null;
+}
+
+export async function inspectTabHostAccess(chromeApi, tabId) {
+    const tab = await chromeApi.tabs.get(tabId);
+    // executeScript targets the committed document. pendingUrl may already point
+    // at another origin while tab.url is still the document being injected into.
+    const descriptor = describeTabUrl(tab?.url || tab?.pendingUrl || '', {
+        includePort: browserSupportsPortMatchPatterns(chromeApi)
+    });
+    if (!descriptor) {
+        return {
+            tab,
+            url: tab?.url || '',
+            host: null,
+            originPattern: null,
+            granted: null
+        };
+    }
+
+    if (typeof chromeApi.permissions?.contains !== 'function') {
+        return { tab, ...descriptor, granted: null };
+    }
+
+    try {
+        const granted = await callBooleanPermissionMethod(
+            chromeApi,
+            'contains',
+            { origins: [descriptor.originPattern] },
+            { timeoutMs: 1000 }
+        );
+        return {
+            tab,
+            ...descriptor,
+            granted: granted === null ? null : granted === true
+        };
+    } catch (_e) {
+        // Permission inspection is advisory. The actual script injection below
+        // remains the source of truth, including temporary activeTab access.
+        return { tab, ...descriptor, granted: null };
+    }
+}
+
+function callBooleanPermissionMethod(chromeApi, methodName, request, { timeoutMs = null } = {}) {
+    const method = chromeApi.permissions?.[methodName];
+    if (typeof method !== 'function') return Promise.resolve(null);
+
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timeout = null;
+        const clearSettlementTimeout = () => {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+                timeout = null;
+            }
+        };
+        const finish = (value) => {
+            if (settled) return;
+            settled = true;
+            clearSettlementTimeout();
+            resolve(value === true ? true : value === false ? false : null);
+        };
+        const fail = (error) => {
+            if (settled) return;
+            settled = true;
+            clearSettlementTimeout();
+            reject(error instanceof Error ? error : new Error(String(error || 'Permission request failed')));
+        };
+        const callback = (value) => {
+            const lastError = chromeApi.runtime?.lastError;
+            if (lastError) {
+                fail(new Error(lastError.message || String(lastError)));
+                return;
+            }
+            finish(value);
+        };
+
+        if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+            timeout = setTimeout(() => finish(null), timeoutMs);
+        }
+
+        try {
+            const result = method.call(chromeApi.permissions, request, callback);
+            if (result && typeof result.then === 'function') {
+                result.then(finish, fail);
+            } else if (typeof result === 'boolean') {
+                finish(result);
+            }
+            // Callback-based Chromium/Firefox APIs return undefined and settle
+            // through callback. Promise-based implementations settle above.
+        } catch (error) {
+            fail(error);
+        }
+    });
+}
+
+export function requestOriginPermission(chromeApi, originPattern) {
+    if (typeof originPattern !== 'string' || !originPattern) {
+        return Promise.resolve(null);
+    }
+    return callBooleanPermissionMethod(
+        chromeApi,
+        'request',
+        { origins: [originPattern] },
+        { timeoutMs: 60000 }
+    ).catch(() => false);
+}
+
+export function isHostAccessError(error) {
+    const message = typeof error?.message === 'string' ? error.message : String(error || '');
+    return /host permission|permission to access (?:this|the|respective) host|cannot access contents of/i.test(message);
+}
+
+function hostAccessRequestDetails(tabId, originPattern) {
+    const request = { tabId };
+    if (typeof originPattern === 'string' && originPattern) {
+        request.pattern = originPattern;
+    }
+    return request;
+}
+
+export async function addTabHostAccessRequest(chromeApi, tabId, originPattern = null) {
+    if (typeof chromeApi.permissions?.addHostAccessRequest !== 'function') {
+        return false;
+    }
+
+    try {
+        await chromeApi.permissions.addHostAccessRequest(
+            hostAccessRequestDetails(tabId, originPattern)
+        );
+        return true;
+    } catch (_e) {
+        return false;
+    }
+}
+
+export async function removeTabHostAccessRequest(chromeApi, tabId, originPattern = null) {
+    if (typeof chromeApi.permissions?.removeHostAccessRequest !== 'function') {
+        return false;
+    }
+
+    try {
+        await chromeApi.permissions.removeHostAccessRequest(
+            hostAccessRequestDetails(tabId, originPattern)
+        );
+        return true;
+    } catch (_e) {
+        return false;
+    }
+}