KoalaDev
dfa0a3d03e
Findings recovered from the multi-agent audit (verification phase was cut off by a
usage limit; verified inline against the code):
HIGH:
- Host was demoted on peerId dedup (fast reconnect / second tab): the dedup path
removes the old socket and the kicked socket's 'disconnect' both ran the
host-leave fallback before the same peerId re-joined → room silently unlocked on
every host network blip. Now skip the fallback while a join for that peerId is in
flight (peerJoinLocks). Regression test added. (A long real disconnect still
falls back — that's the deferred host-grace EC-10.)
- Episode auto-advance froze a gated guest: in host-only the guest's EPISODE_LOBBY
is dropped server-side, but the guest still self-paused (PAUSE_FOR_LOBBY) waiting
for readies that never came → 60s freeze. A host-only guest now skips creating a
lobby (the host drives episode sync).
LOW / cleanup:
- GET_HCM_STRINGS could return a raw key name ("HCM_DIALOG_TITLE") if the locale
dictionary failed to load (getMessage returns the key on miss) → omit it so
content keeps its English fallback.
- hcmReset now also clears the snap-back cooldown + buffering grace, so a stale
cooldown can't swallow the first snap-back after a room/host change.
- Popup play/pause labels reset on lock too (not just unlock), so a button can't
freeze on "Playing…" when host-only activates mid-click.
- Fix a stale comment (heartbeat now carries 'desynced').
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.