mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-18 15:23:13 +00:00
KoalaDev
36e1291d2c
The weighted score summed incomparable units, so size could outvote traits that disqualify an element outright. Measured on a real page: a display:none preload reports its full 1080p intrinsic size and scored 2073600, beating a visible unmuted player at 509920. Selection now compares an ordered list of signals, highest priority first: has a source, is rendered, is not a silent background loop, rendered size bucket, is playing, has controls, duration. Rendered size replaces intrinsic resolution, and mute state is gone from the ranking entirely: it is a viewer preference, not evidence about which element is the player. It stays a ranking rather than a filter, so a page of only bad candidates still yields one and findVideo never returns null where a video exists. The new tests/e2e suite runs the shipped finder against real fixture pages and drives the packed extension for injection, reinjection and remote play/pause/seek into a first-party frame. All five scoring scenarios fail against the previous implementation. 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.