From 652f1cef4fe898b19ec17b5a61e32c59044a7199 Mon Sep 17 00:00:00 2001 From: MacBook Date: Mon, 4 May 2026 04:43:30 +0200 Subject: [PATCH] refactor: automate protocol sync and reorganize repo for store readiness --- AI_INIT.md | 4 +-- CONTRIBUTING.md | 35 +++++++++++++++++++++++ PRIVACY.md | 27 ++++++++++++++++++ README.md | 12 ++++++-- assets/SOCIAL_PREVIEW.png | Bin 0 -> 473573 bytes ARCHITECTURE.md => docs/ARCHITECTURE.md | 0 docs/README.md | 6 ++++ SYNC_GUIDE.md => docs/SYNC_GUIDE.md | 0 extension/content.js | 4 ++- scripts/build-extension.js | 36 +++++++++++++++++++++++- 10 files changed, 117 insertions(+), 7 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 PRIVACY.md create mode 100644 assets/SOCIAL_PREVIEW.png rename ARCHITECTURE.md => docs/ARCHITECTURE.md (100%) create mode 100644 docs/README.md rename SYNC_GUIDE.md => docs/SYNC_GUIDE.md (100%) diff --git a/AI_INIT.md b/AI_INIT.md index f27f85b..8b2d2e4 100644 --- a/AI_INIT.md +++ b/AI_INIT.md @@ -29,9 +29,9 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi ## 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. +1. [docs/ARCHITECTURE.md](docs/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. +3. [docs/SYNC_GUIDE.md](docs/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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8d8c381 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing to KoalaSync + +Thank you for your interest in contributing to KoalaSync! We welcome all contributions, from bug reports to new features. + +## Development Workflow + +### 1. Prerequisites +- Node.js (v18+) +- Docker (for local server testing) + +### 2. Setup +1. Clone the repository. +2. Run `npm install` in the root directory to install build dependencies. + +### 3. Protocol Synchronization +KoalaSync uses a "Single Source of Truth" for protocol constants in `shared/constants.js`. +- **CRITICAL**: If you modify the constants, you MUST run the build script: + ```bash + node scripts/build-extension.js + ``` + This will automatically synchronize the changes to the extension and generate the browser-specific bundles in the `dist/` folder. + +### 4. Code Standards +- **Vanilla JS**: The extension must remain dependency-free. Do not add npm packages to the `extension/` directory. +- **Privacy**: Do not add external requests (CDNs, fonts, etc.). +- **Comments**: Maintain the existing documentation style, especially for complex sync logic. + +## Pull Request Process +1. Create a new branch for your feature or bugfix. +2. Ensure your code is tested locally (Chrome and Firefox). +3. Update relevant documentation (e.g., `docs/ARCHITECTURE.md` if you change the protocol). +4. Submit your PR with a clear description of the changes. + +## Security +If you find a security vulnerability, please do not open a public issue. Instead, refer to our `SECURITY.md` for disclosure instructions. diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..6230876 --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,27 @@ +# Privacy Policy + +KoalaSync is built with a **Privacy-First** architecture. We believe that your browsing habits and watch history are your business, not ours. + +## 1. Zero External Requests +The KoalaSync extension and its official marketing website are designed to be completely self-contained. +- **No CDNs**: We do not load scripts or styles from external Content Delivery Networks. +- **No Google Fonts**: We use a modern system font stack to avoid tracking by third-party font services. +- **No Analytics**: There are no tracking pixels, telemetry, or analytics scripts (like Google Analytics or Mixpanel) in the codebase. + +## 2. Data Sovereignty +- **Self-Hostable**: You can host your own relay server using our Docker image, giving you 100% control over your data. +- **Memory-Only State**: The relay server stores all room data in RAM. Nothing is written to a database or disk. When a room is empty, it is purged immediately. +- **No Logs**: The official relay server (`sync.shik3i.net`) does not log user IP addresses or room activity. + +## 3. Extension Permissions +KoalaSync requires the following permissions to function: +- `storage`: To remember your username and server preferences locally. +- `tabs` & `scripting`: To detect video elements on pages you visit so they can be synchronized. +- ``: Necessary because KoalaSync works on any website with a `