From 59b675ce175588deb651e7f1b8fea600d4a9dd87 Mon Sep 17 00:00:00 2001 From: KoalaDev <6156589+Shik3i@users.noreply.github.com> Date: Fri, 19 Jun 2026 11:35:49 +0200 Subject: [PATCH] docs: audit and update script references, supported languages, and completed milestones --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/release.yml | 2 +- CONTRIBUTING.md | 12 ++++++------ docs/AI_INIT.md | 16 ++++++++-------- docs/ROADMAP.md | 5 ++++- docs/TRANSLATION.md | 6 +++--- extension/README.md | 2 +- scripts/README.md | 4 ++-- scripts/build-extension.cjs | 6 +++--- shared/README.md | 2 +- shared/blacklist.js | 2 +- shared/constants.js | 4 ++-- shared/names.js | 2 +- website/README.md | 10 +++++----- 14 files changed, 39 insertions(+), 36 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e3662a9..775db90 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -37,7 +37,7 @@ Closes # - [ ] I have performed a self-review of my code - [ ] I have added/updated tests if needed - [ ] I have updated documentation if needed (`docs/`, README, etc.) -- [ ] Protocol changes: I ran `node scripts/build-extension.js` and updated relevant docs +- [ ] Protocol changes: I ran `node scripts/build-extension.cjs` and updated relevant docs - [ ] No new warnings, secrets, or hardcoded credentials introduced ### Additional Context diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 839444a..67cbd08 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -94,7 +94,7 @@ jobs: echo " ✓ manifest.base.json -> $VERSION" # 2. shared/constants.js — APP_VERSION - sed -i "s/export const APP_VERSION = '.*'/export const APP_VERSION = '$VERSION'/" shared/constants.js + sed -i "s/export const APP_VERSION = [\"'].*[\"']/export const APP_VERSION = \"$VERSION\"/" shared/constants.js echo " ✓ shared/constants.js -> $VERSION" # 3. package.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 141859e..b9ddb8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ Please note that by participating in this project, you agree to abide by our [Co git clone https://github.com/Shik3i/KoalaSync.git cd KoalaSync npm install -node scripts/build-extension.js +node scripts/build-extension.cjs ``` --- @@ -62,7 +62,7 @@ node scripts/build-extension.js ### Website ```bash -node website/build.js # Compile static site → www/ +node website/build.cjs # Compile static site → www/ python3 -m http.server 8080 -d website/www # Serve locally ``` @@ -77,7 +77,7 @@ KoalaSync uses a **single source of truth** for all protocol constants in `share > [!IMPORTANT] > After modifying `shared/constants.js`, you **must** run the build script to sync changes to the extension: > ```bash -> node scripts/build-extension.js +> node scripts/build-extension.cjs > ``` > This automatically injects constants into `content.js` and regenerates browser bundles in `dist/`. @@ -109,7 +109,7 @@ If you are new to open-source contributions, follow these steps to propose your 3. **Create a Branch**: `git checkout -b my-new-feature` (e.g. `feature/dark-mode` or `fix/translation-de`) 4. **Make your Changes**: Edit the files, then verify them locally. - *Extension/Server changes*: Test on Chrome/Firefox and check `npm run lint`. - - *Website/Translation changes*: Run `node website/build.js` and check the output in `www/`. + - *Website/Translation changes*: Run `node website/build.cjs` and check the output in `www/`. 5. **Commit and Push**: `git commit -m "Add my feature"` and `git push origin my-new-feature` 6. **Open a Pull Request (PR)**: Go to the original KoalaSync repository on GitHub and click "New Pull Request". @@ -156,9 +156,9 @@ KoalaSync supports multiple languages. To add or improve translations: 1. Read the **[Translation Guide](docs/TRANSLATION.md)** first. It explains how our localization system works. 2. Edit the `.json` files in `website/locales/` (for the website) and `extension/locales/` (for the extension). 3. Test your translations locally by running: - - `node scripts/test-locales.js` (for extension) + - `node scripts/test-locales.cjs` (for extension) - `node scripts/test-website-locales.mjs` (for website) - - `node website/build.js` (to build the site) + - `node website/build.cjs` (to build the site) 4. Follow the **Open Source Workflow** above (Fork -> Branch -> Edit -> PR) to submit your translations. --- diff --git a/docs/AI_INIT.md b/docs/AI_INIT.md index a0955d2..b99280c 100644 --- a/docs/AI_INIT.md +++ b/docs/AI_INIT.md @@ -21,14 +21,14 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi - `extension/`: Browser Extension (Chrome & Firefox, Manifest V3). Contains background service worker, content scripts, and popup UI. - `server/`: Node.js Relay Server using Socket.IO (WebSocket-only). - `website/`: **Landing Page** & Invitation Bridge (Marketing, Tutorials, and Downloads). - - **`build.js`**: Zero-dependency static site compiler. Translates `template.html` + `locales/*.json` → `www/`. Also minifies CSS/JS automatically. - - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.js` to regenerate. CSS/JS are output as `.min.*` files — a built-in cleanup step removes stale artifacts on each build. + - **`build.cjs`**: Zero-dependency static site compiler. Translates `template.html` + `locales/*.json` → `www/`. Also minifies CSS/JS automatically. + - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.cjs` to regenerate. CSS/JS are output as `.min.*` files — a built-in cleanup step removes stale artifacts on each build. - `shared/`: **Single Source of Truth** for protocol constants and event names. -- `scripts/`: Development utilities (e.g., `build-extension.js`). +- `scripts/`: Development utilities (e.g., `build-extension.cjs`). - `docker-compose.yml`: Root-level orchestration for the relay server. > [!IMPORTANT] -> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.js`. +> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.cjs`. > - **Extension Modules** (`background.js`, `popup.js`) import directly from `./shared/constants.js`. > - **Content Scripts** (`content.js`) use a **marker-injected synchronous copy** of the constants. The build script automatically replaces the marked blocks — no manual mirroring needed. @@ -41,7 +41,7 @@ Before touching any code, you MUST read the following documents in order: ## 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: - **Synchronous Execution**: `content.js` MUST execute synchronously to catch early media events. -- **Automated Injection**: The build script (`node scripts/build-extension.js`) automatically injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details). +- **Automated Injection**: The build script (`node scripts/build-extension.cjs`) automatically injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details). - **Maintenance**: After modifying `shared/constants.js`, simply run the build script. No manual mirroring is required. ## 5. File Responsibility Map @@ -137,18 +137,18 @@ Before starting any task, committing, or pushing, you **MUST** run `git pull --r ### Adding a Protocol Event 1. Add the event name to `shared/constants.js`. -2. Run the build script (`node scripts/build-extension.js`). +2. Run the build script (`node scripts/build-extension.cjs`). 3. Implement the handler in `server/index.js` and `background.js`. ### Making Website Changes 1. Edit source files in `website/` (`template.html`, `style.css`, `app.js`, `lang-init.js`, or `locales/*.json`). -2. Run the compiler: `node website/build.js`. This generates the multilingual pages in `www/` and minifies CSS/JS. +2. Run the compiler: `node website/build.cjs`. This generates the multilingual pages in `www/` and minifies CSS/JS. 3. Verify the output: `node --check website/www/app.js && node --check website/www/lang-init.js`. 4. Test locally: `npx serve website/www` or `python3 -m http.server 8080 -d website/www`. 5. Commit both source changes and the updated `www/` output. ### Testing Locally -1. Run the build script: `node scripts/build-extension.js`. +1. Run the build script: `node scripts/build-extension.cjs`. 2. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (or `dist/firefox/` in Firefox). 3. Start the server from the root: `docker-compose up --build`. 4. Use **different browser profiles** or vendors to test multi-peer logic. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 4361dd2..effee3d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -87,4 +87,7 @@ | Feature | Shipped | |---|---| -| *(none yet)* | | +| **Lazy WebSocket Connection** (only connects when active/popup open) | v2.4.0 | +| **Interactive Onboarding Tour** (guided first-run user experience) | v2.3.0 | +| **Artifact Attestations** (SLSA supply chain security via GitHub Actions) | v2.2.3 | +| **Multi-Language Support** (expanded to 13 locales with dynamic switching) | v2.2.0 | diff --git a/docs/TRANSLATION.md b/docs/TRANSLATION.md index caf2d43..2c9748e 100644 --- a/docs/TRANSLATION.md +++ b/docs/TRANSLATION.md @@ -69,19 +69,19 @@ The website hosts the landing page and invitation bridge. "LANG_TOGGLE_TEXT": "EN" } ``` -5. If creating a **brand new language**, register it in `website/build.js` by adding it to the `languages` array. +5. If creating a **brand new language**, register it in `website/build.cjs` by adding it to the `languages` array. ### Step 4: Verify Locally Ensure your JSON files are valid and all keys match the English baseline. Open your terminal in the KoalaSync root folder and run: ```bash # Tests the extension locales for missing keys or syntax errors -node scripts/test-locales.js +node scripts/test-locales.cjs # Tests the website locales for missing keys or syntax errors node scripts/test-website-locales.mjs # Builds the website with your new translations -node website/build.js +node website/build.cjs ``` *Note: If you receive any errors about missing keys or `TODO` placeholders, please fix them before submitting.* diff --git a/extension/README.md b/extension/README.md index be4f5d9..8e9c68b 100644 --- a/extension/README.md +++ b/extension/README.md @@ -8,7 +8,7 @@ A Manifest V3 Browser Extension (Chrome & Firefox) for synchronized video playba - **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 `connectIntent` flag 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 6 languages (`en`, `de`, `fr`, `es`, `pt-BR`, `ru`) with auto-detected fallback and dynamic on-the-fly language selectors. +- **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 1. **Room**: Manage connections, view active peers, and share invitation links. diff --git a/scripts/README.md b/scripts/README.md index 4fdbf11..53ada3f 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -2,7 +2,7 @@ This directory contains utility scripts for the KoalaSync development workflow. -## build-extension.js +## build-extension.cjs The primary build tool for KoalaSync. This Node.js script automates two critical tasks: @@ -15,7 +15,7 @@ The primary build tool for KoalaSync. This Node.js script automates two critical From the **repository root**, run: ```bash -node scripts/build-extension.js +node scripts/build-extension.cjs ``` ### Why this script exists diff --git a/scripts/build-extension.cjs b/scripts/build-extension.cjs index 4f69299..d7b8c2c 100644 --- a/scripts/build-extension.cjs +++ b/scripts/build-extension.cjs @@ -77,7 +77,7 @@ function copyExtensionFiles(targetDir, browserName) { const eStart = '// --- SHARED_EVENTS_INJECT_START ---'; const eEnd = '// --- SHARED_EVENTS_INJECT_END ---'; const ePattern = new RegExp(`${eStart}[\\s\\S]+?${eEnd}`); - const eRep = `${eStart}\n // This block is automatically updated by /scripts/build-extension.js\n const EVENTS = ${eventsObject};\n ${eEnd}`; + const eRep = `${eStart}\n // This block is automatically updated by /scripts/build-extension.cjs\n const EVENTS = ${eventsObject};\n ${eEnd}`; if (ePattern.test(content)) { content = content.replace(ePattern, eRep); @@ -108,7 +108,7 @@ function copyExtensionFiles(targetDir, browserName) { .replace(/^\/\*\*[\s\S]*?\*\/\s*/m, '') .replace(/export function /g, 'function ') .trim(); - const euRep = `${euStart}\n // This block is automatically updated by /scripts/build-extension.js\n${stripped.split('\n').map(l => ' ' + l).join('\n')}\n ${euEnd}`; + const euRep = `${euStart}\n // This block is automatically updated by /scripts/build-extension.cjs\n${stripped.split('\n').map(l => ' ' + l).join('\n')}\n ${euEnd}`; if (euPattern.test(content)) { content = content.replace(euPattern, euRep); } else { @@ -127,7 +127,7 @@ function copyExtensionFiles(targetDir, browserName) { const uPattern = new RegExp(`${uStart}[\\s\\S]+?${uEnd}`); const placeholderUrl = "https://bye.koalastuff.net/c/camp_99ztjRVbK1BNN2RU"; - let uRep = `${uStart}\n // This block is automatically updated by /scripts/build-extension.js\n`; + let uRep = `${uStart}\n // This block is automatically updated by /scripts/build-extension.cjs\n`; uRep += ` const UNINSTALL_URL = "${placeholderUrl}";\n`; uRep += ` const BROWSER_TYPE = "${browserName}";\n`; uRep += ` ${uEnd}`; diff --git a/shared/README.md b/shared/README.md index fb515a9..0d82083 100644 --- a/shared/README.md +++ b/shared/README.md @@ -4,7 +4,7 @@ This directory contains constants and protocol definitions used by both the exte ## Syncing with the Extension > [!IMPORTANT] -> Every time this directory is modified, you must run `node scripts/build-extension.js` to keep the extension's copy up to date. +> Every time this directory is modified, you must run `node scripts/build-extension.cjs` to keep the extension's copy up to date. Because Browser Extensions (Manifest V3) cannot load files outside their root directory, all files in this directory must be copied to `extension/shared/` whenever they are modified. The build script handles this automatically. diff --git a/shared/blacklist.js b/shared/blacklist.js index fd207bc..a61f383 100644 --- a/shared/blacklist.js +++ b/shared/blacklist.js @@ -2,7 +2,7 @@ * blacklist.js * * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH. - * If you edit this file, you MUST run: node scripts/build-extension.js + * If you edit this file, you MUST run: node scripts/build-extension.cjs * to propagate changes to the extension and relay server. * * Domains to be filtered out from the tab selection dropdown to reduce "noise". diff --git a/shared/constants.js b/shared/constants.js index 5a0e85b..cbbd582 100644 --- a/shared/constants.js +++ b/shared/constants.js @@ -2,12 +2,12 @@ * KoalaSync Shared Constants & Protocol Definitions * * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH. - * If you edit this file, you MUST run: node scripts/build-extension.js + * If you edit this file, you MUST run: node scripts/build-extension.cjs * to propagate changes to the extension and relay server. */ export const PROTOCOL_VERSION = "1.0.0"; -export const APP_VERSION = "1.9.0"; +export const APP_VERSION = "2.4.1"; export const OFFICIAL_SERVER_URL = 'wss://syncserver.koalastuff.net'; export const OFFICIAL_LANDING_PAGE_URL = 'https://sync.koalastuff.net'; diff --git a/shared/names.js b/shared/names.js index d6eccb0..179255b 100644 --- a/shared/names.js +++ b/shared/names.js @@ -2,7 +2,7 @@ * KoalaSync Shared Name Generation & Emoji Mapping * * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH. - * If you edit this file, you MUST run: node scripts/build-extension.js + * If you edit this file, you MUST run: node scripts/build-extension.cjs * to propagate changes to the extension. * * The emoji map covers every animal/creature that has a Unicode emoji. diff --git a/website/README.md b/website/README.md index 7f0cb0f..aa1b4a0 100644 --- a/website/README.md +++ b/website/README.md @@ -5,7 +5,7 @@ This directory contains the KoalaSync website. It serves a dual purpose: it is b ## Core Roles ### 1. Marketing & Onboarding -Provides a premium, multi-language (EN/DE/FR/ES/PT-BR/RU) overview of features, setup instructions, and direct links to the extension stores. +Provides a premium, multi-language (EN/DE/FR/ES/PT-BR/RU/IT/PL/TR/NL/JA/KO/PT) overview of features, setup instructions, and direct links to the extension stores. ### 2. The Invitation Bridge (`join.html`) The website handles incoming invitation links. When a user clicks a link like `sync.koalastuff.net/join.html#join:roomID:pass`, the website: @@ -16,8 +16,8 @@ The website handles incoming invitation links. When a user clicks a link like `s ## Architecture The website is 100% **Static HTML, CSS, and JS**. -- **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.js`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`. -- **Build-time Minification**: `build.js` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified (`style.css`, `app.js`, `lang-init.js`) — always edit source files, never the generated `.min.*` files in `www/`. +- **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.cjs`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`. +- **Build-time Minification**: `build.cjs` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified (`style.css`, `app.js`, `lang-init.js`) — always edit source files, never the generated `.min.*` files in `www/`. - **Zero Backend**: No Node.js, PHP, or databases are required to host the compiled website. - **Zero Tracking**: All assets (fonts, icons) are self-hosted to prevent third-party tracking. - **Responsive**: Fully optimized for mobile with a native-feel hamburger menu. @@ -62,7 +62,7 @@ sync.koalastuff.net { 1. Run the compilation script from the repository root to generate the `/website/www` folder: ```bash - node website/build.js + node website/build.cjs ``` 2. Serve the compiled `/www` directory using any local development server: ```bash @@ -71,4 +71,4 @@ sync.koalastuff.net { 3. To test the invitation flow locally, navigate to `http://localhost:5000/join.html#join:test-room:test-pass`. > [!IMPORTANT] -> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.js`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.js` to apply changes. CSS and JS are output as `style.min.css`, `app.min.js`, and `lang-init.min.js` — the `.min.*` naming makes it visually obvious these are build artifacts. Editing minified files in `www/` will result in lost changes on the next build. +> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.cjs`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.cjs` to apply changes. CSS and JS are output as `style.min.css`, `app.min.js`, and `lang-init.min.js` — the `.min.*` naming makes it visually obvious these are build artifacts. Editing minified files in `www/` will result in lost changes on the next build.