mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-17 23:07:48 +00:00
KoalaDev
477dad03a3
Audit follow-ups on the same-origin frame walk: - prune detached frames from the load-hook set so ad/SPA frame churn no longer grows it for the page's lifetime - hook load on nested frames, not just top-level ones - re-observe from scratch after a frame reload instead of leaving the replaced document's tree registered - reset the frame registry when the heartbeat error path disconnects Also: a broad parent domain in the blacklist no longer hides a host with its own supported player path (drive.google.com behind google.com), while an exact user entry for that host still filters it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Technical Documentation
This directory contains deep-dives into the KoalaSync protocol, architecture, roadmap, and operational guidelines.
Start Here by Role
- Users and reviewers: Start with HOW_IT_WORKS.md, then PRIVACY.md and TESTED_SERVICES.md.
- Self-hosters: Start with the root README.md, then devops.md, PROTOCOL.md, and the examples in
../examples/. - Contributors: Start with ../CONTRIBUTING.md, then ARCHITECTURE.md, SYNC_GUIDE.md, and the README for the subdirectory you are editing.
- AI agents: Start with AI_INIT.md, then read the relevant subdirectory README before changing files.
- Security reviewers: Start with SECURITY.md, KNOWN_LIMITATIONS.md, PRIVACY.md, and PROTOCOL.md.
🏗️ Core Architecture & Design
- ARCHITECTURE.md: Overview of the communication flows, Dual Heartbeat architecture, and synchronization logic.
- HOW_IT_WORKS.md: Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
- host-control-mode.md: Design, requirements, and edge cases of the Host Control feature.
- AI_INIT.md: Maintainer and AI-agent onboarding: non-negotiables, workflow order, and safety checks.
📡 Protocol & Synchronization
- PROTOCOL.md: Low-level message format and payload descriptions for the KoalaSync sync protocol.
- SYNC_GUIDE.md: Guide on keeping protocol constants synchronized across the workspace.
📋 Compatibility, Roadmap & Contribution
- TESTED_SERVICES.md: Status of compatibility with major streaming services and contribution guidelines for testing new platforms.
- KNOWN_LIMITATIONS.md: Threat model and accepted design limitations (NOFIX entries) for security audits.
- PRIVACY.md: Privacy model and data-handling policy for users, reviewers, and contributors.
- ROADMAP.md: Planned features, backlog items, and rejected proposals.
- TRANSLATION.md: Guide for native speakers to contribute and audit dynamic extension/website translations.
🚀 DevOps & Releases
- devops.md: Guide on the automated tag-based release pipeline.
- CHANGELOG.md: Detailed history of releases and changes.
For high-level project information and developer setup instructions, refer to the root README.md.