mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-07-28 12:59:45 +00:00
KoalaDev
17ac5c0a6f
Audit fixes (each verified against the actual code path): H-1 (server): track force-sync initiator on PREPARE; let the demoted initiator's EXECUTE through the host-only gate so mid-sync demotion no longer strands the whole room paused. Clear on EXECUTE/peer-leave. M-1 (background): episode-lobby gate now uses !amController() for parity with CONTENT_EVENT and server gates — co-hosts can drive the room and initiate lobbies, not just the owner. M-2/M-3 (popup/content/background): forceSyncReset respects hcmGuestLocked; desynced guest skips EPISODE_LOBBY so they don't get frozen in pause after lobby completion, and checkEpisodeLobbyCompletion excludes desynced peers from the required count so they don't block the lobby. M-4 (background): getHostSyncTarget clamps extrapolation to 2x heartbeat interval so a stale host heartbeat can't snap the guest tens of seconds past the host's real position. L-1..L-4 (server/content/background/popup): clarify dedup comment re: network-blip window, enforce desync invariant on SW-restore, add forceSyncBtn guest-locked backstop, refresh badge text in place. Backward compatibility (verified by BC-1..BC-4 regression tests): - Old client ↔ new server: server adds fields only, never requires; old heartbeats stripped of desynced; host-only enforced server-side even when the client has no awareness. - New client ↔ old server: empty capabilities → host-control UI hidden, all gates default to everyone, behavior byte-identical to pre-HCM. - Mixed rooms: every pre-HCM event type relays cleanly in both directions.
KoalaSync Browser Extension
A Manifest V3 Browser Extension (Chrome & Firefox) for synchronized video playback across any website.
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.
- On-Demand Connection: The service worker only maintains a WebSocket connection while you're in a room. No persistent background connections — privacy-first architecture. Based on
connectIntentflag that gates all reconnect attempts. - Live Diagnostics: Built-in "Dev" tab for real-time video state debugging (ReadyState, CurrentTime, etc.).
- Dynamic i18n (Multi-Language): Fully localized in 13 languages (
en,de,fr,es,it,pl,tr,nl,ja,ko,pt-BR,pt,ru) with auto-detected fallback and dynamic on-the-fly language selectors.
Tab Overview
- Room: Manage connections, view active peers, and share invitation links.
- Sync: Control video playback (Play/Pause/Force Sync) and view recent activity.
- Settings: Customize your Username, toggle domain-based Noise Filtering, and switch the App Language.
- Dev: Monitor connection status and view real-time video element metadata for debugging.
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.
- Zero Runtime Dependencies: The extension is built with pure Vanilla JS and contains no external libraries or tracking scripts, ensuring performance and privacy.
Installation
- Prepare Extension: From the repository root, run:
npm run build:extension - Open Chrome and go to
chrome://extensions/. - Enable Developer mode (top right).
- Click Load unpacked and select the
dist/chromefolder.
Development
If you modify shared/constants.js, you must synchronize the changes by running the build script from the root:
npm run build:extension
This ensures that the extension/shared folder is updated with the latest protocol constants.
Module Structure
| File | Purpose |
|---|---|
background.js |
Service worker: message routing, tab listeners, startup |
content.js |
Video detection, audio processing, episode transition (IIFE) |
popup.js |
Popup UI: join/create, tabs, status, settings |
bridge.js |
Landing page bridge (injected into sync.koalastuff.net) |
episode-utils.js |
Shared extractEpisodeId() / sameEpisode() — used by background.js, injected into content.js at build time |
i18n.js |
Translation loader |
shared/ |
Constants, blacklist, name generator |