mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-19 15:46:15 +00:00
Timo
226453fd45
Reported as "Receiving end does not exist" with targetReady true and no activation errors: the election named a frame the player had already torn down. Three defects were stacked, each hidden by the one in front of it. The election was never released. getReadyTabVideoState() recovered through the guarded refresh, which reports "unchanged" when no video is reachable, so the stale frameId/documentId survived; adoption compounded it by setting hasVideo, after which the target only moves on a frame change. An unreachable content script — as opposed to a page that simply has no video yet — now releases the frame election back to the top frame. The tab selection is never touched. Switching frames destroyed the top frame's scripts. Promoting the target out of frame 0 called deactivateTargetTab() on the previous target, which sent TARGET_DEACTIVATE to frame 0 and tore down its content script and the chat overlay with it. That is why chat delivery failed after promotion, and why releasing the election pointed at an empty frame. An in-tab frame switch now leaves the top frame alone. Discovery could deadlock. Monitors announce new players, but a rebuilt frame is a new document with no monitor, so the video created in it was never reported — and nothing then triggered the upkeep that would have installed one. Monitors are reinstalled on every lifecycle notification with a trailing-edge debounce, and a bounded discovery poll breaks the cycle when no notification arrives at all: 2s, capped, only while a tab is selected with no video found, stopping the moment one is. The new browser test adopts a nested player, destroys its document the way the real player does, and asserts both the release and that the rebuilt player is picked up again without touching the popup. It was flaky until the deadlock was closed, and now passes repeatedly at a stable 8.3s. 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.