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.
Development Scripts
This directory contains utility scripts for the KoalaSync development workflow.
build-extension.cjs
The primary build tool for KoalaSync. This Node.js script automates two critical tasks:
- Protocol Synchronization: Copies the "Single Source of Truth" constants (
shared/constants.js) and the domain blacklist (shared/blacklist.js) from the root/shareddirectory into theextension/shared/directory. - Content Script Injection: Injects protocol constants directly into
content.jsusing marker-based replacement. This is necessary becausecontent.jsexecutes synchronously and cannot use ES module imports. - Artifact Generation: Compiles the extension into browser-specific bundles for Chrome and Firefox, located in the
dist/directory.
Usage
From the repository root, run:
node scripts/build-extension.cjs
Why this script exists
KoalaSync uses Vanilla JS in the extension to maintain zero runtime dependencies and maximum privacy. Since we don't use a bundler (like Webpack or Vite) inside the extension, this script serves as our lightweight "pre-build" step to ensure that the protocol constants remain synchronized between the extension and the relay server.
Content Injection Markers
The build script uses marker comments in content.js to locate and replace constant blocks:
| Marker Pair | Injected Value | Source |
|---|---|---|
SHARED_EVENTS_INJECT_START / END |
The full EVENTS object |
shared/constants.js |
SHARED_HEARTBEAT_INJECT_START / END |
HEARTBEAT_INTERVAL value |
shared/constants.js |
⚠️ Do NOT remove or modify these marker comments in
content.js. They are required for the build script to function. If the markers are missing, the build will fail with a clear error message.