mirror of https://github.com/Shik3i/KoalaSync.git synced 2026-07-26 20:18:14 +00:00

Files

T

MacBook 5157428e74 docs: comprehensive repository polish + step-by-step user guide

Documentation Rewrites:
- AI_INIT.md: fix duplicate section numbers, add file responsibility map,
  fix stale manual mirror instruction, add room ID constraint
- PRIVACY.md: add TL;DR statement, data retention table, explicit
  <all_urls> justification, self-hosted instance disclaimer
- CONTRIBUTING.md: add local testing guide, version warning, room ID
  constraint, bug report requirements
- shared/README.md: complete event table (all 15 events), fix stale
  manifest.json reference
- docs/SYNC_GUIDE.md: Chrome→Browser, add README.md to sync list,
  drop stale RC5 reference
- server/README.md: sync env defaults with .env.example (1000/50)

New Documentation:
- docs/HOW_IT_WORKS.md: 10-step walkthrough covering room creation,
  invitation bridge flow, synchronized playback, force sync protocol,
  heartbeat system, and episode auto-sync. Includes exact data payloads.

Infrastructure Cleanup:
- docker-compose.yml: remove deprecated version key
- .dockerignore: remove dead .bat/.sh patterns
- README.md: add self-hosting extension config tip, link HOW_IT_WORKS

2026-05-04 05:41:43 +02:00

2.1 KiB

Raw Blame History

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:

After a fresh git clone or git pull (as the synced files are ignored by git).
After modifying shared/constants.js.
After modifying shared/blacklist.js.
Before committing changes to the repository if any protocol-related files were touched.
Before deploying the server or releasing the extension.

How to sync

Run the Node.js build script from the repository root:

node scripts/build-extension.js

What does it do?

The build script performs the following actions:

Synchronizes protocol constants by copying shared/constants.js, shared/blacklist.js, and shared/README.md into extension/shared/.
Injects EVENTS and HEARTBEAT_INTERVAL into content.js via marker-based replacement.
Compiles browser-specific manifest files.
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.
Always run the build 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 build script is run. Always edit the files in the root shared/ directory and then run the build script.

2.1 KiB Raw Blame History