KoalaSync/website

KoalaSync Website & Invitation Bridge

This directory contains the KoalaSync website. It serves a dual purpose: it is both the marketing landing page and the technical bridge for joining synchronized rooms.

Core Roles

1. Marketing & Onboarding

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:

• Detects the Extension: Verifies if KoalaSync is installed via the bridge.js content script.
• Privacy-First Handshake: The room credentials (ID/Password) are stored in the URL Hash (#). This ensures the sensitive credentials never reach the web server and are processed entirely within the user's browser.
• Auto-Join: If the extension is detected, it automatically triggers the join flow without requiring user input.

Architecture

The website is 100% Static HTML, CSS, and JS.

• 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.

Hosting with Caddy

Caddy is the recommended web server. It provides automatic HTTPS and high-performance static file serving.

Recommended Caddyfile

For a more comprehensive configuration that includes the Relay Server reverse proxy, see the root Caddyfile.example.

sync.koalastuff.net {
    root * /var/www/koalasync/website/www
    file_server
    encode zstd gzip

    # Static Caching for high-performance PageSpeed (1 year with validation)
    @static {
        file
        path *.ico *.css *.js *.png *.svg *.webp
    }
    header @static Cache-Control "public, max-age=31536000, must-revalidate"

    # Security Headers & Content Security Policy (CSP)
    header {
        # Strict Content Security Policy (restricts scripts and connections to self, forbids frames)
        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none';"
        # Prevent FLoC tracking
        Permissions-Policy interest-cohort=()
        # Security best practices
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
}

Local Development & Compilation

1. Run the compilation script from the repository root to generate the /website/www folder:

   node website/build.cjs
   

2. Serve the compiled /www directory using any local development server:

   npx serve website/www
   

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.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.