mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-19 15:46:15 +00:00
Timo
bf0dfb82c6
A monitor took the current DOM as its baseline on install, so a video that was already present counted as "not a change" and was never announced. The discovery poll added in the previous commit reinstalled monitors every 2s, which meant a video appearing between two reinstalls was silently swallowed — the reported debug log had no [Content] lines at all, which is the signature of exactly this. Monitors now announce a video that is already there when they install, which also makes the rebuilt-frame case work by construction rather than by timing. The reinstall interval is raised to 5s now that each install is informative. Also adds docs/frame-targeting-handoff.md: why v3.1.2 worked immediately with webNavigation, why reconstructing that single call from sweeps, a learned registry, per-frame monitors and a poll keeps producing timing windows, and the proposed structural replacement (chrome.scripting.registerContentScripts with allFrames, no new permission) together with the project invariant it conflicts with — which is the owner's decision, not a code change to make unasked. 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.