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>
Development Scripts
This directory contains build, synchronization, and verification scripts for the KoalaSync workspace. Run all commands from the repository root unless a script says otherwise.
Main Commands
npm run build:extension
npm run verify
npm run lint
npm run test:unit
npm run build:extensionrunsscripts/build-extension.cjs.npm run verifyruns the full release-safety suite inscripts/verify-release.mjs.npm run lintruns ESLint across the repository.npm run test:unitruns Vitest tests.
build-extension.cjs
The primary extension build tool performs these steps:
- Recreates
dist/. - Copies
shared/constants.js,shared/blacklist.js,shared/names.js, andshared/README.mdintoextension/shared/. - Injects synchronous shared values into
content.js. - Injects browser-specific uninstall URL constants into
background.js. - Injects the build timestamp into
popup.html. - Generates browser-specific manifests for Chrome and Firefox.
- Creates
dist/koalasync-chrome.zipanddist/koalasync-firefox.zip.
Usage:
node scripts/build-extension.cjs
# or
npm run build:extension
Injection Markers
The build script uses marker comments/placeholders. Missing markers are a hard build failure so release artifacts cannot silently contain stale protocol data.
| Target | Marker / Placeholder | Injected Value | Source |
|---|---|---|---|
content.js |
SHARED_EVENTS_INJECT_START / END |
Full EVENTS object |
shared/constants.js |
content.js |
SHARED_HEARTBEAT_INJECT_START / END |
HEARTBEAT_INTERVAL |
shared/constants.js |
content.js |
SHARED_EPISODE_UTILS_INJECT_START / END |
extractEpisodeId() and sameEpisode() |
extension/episode-utils.js |
background.js |
UNINSTALL_URL_INJECT_START / END |
Uninstall URL and browser type | scripts/build-extension.cjs |
popup.html |
__BUILD_TIMESTAMP__ |
UTC build timestamp | Build time |
Do not remove or rename these markers without updating the build script and tests.
Verification Suite
scripts/verify-release.mjs is the best single command before release, PR review, or handoff:
npm run verify
It currently runs:
- Vitest unit tests.
- Server ops, route, WebSocket, and rate-limiter checks.
- Episode parser, title privacy, audio settings, popup cooldown, names, and content-video-finder checks.
- JavaScript syntax checks for server and extension entry points.
- Extension and website locale coverage checks.
- ESLint.
- Production
npm auditchecks for root and server dependencies. - Extension build and website build.
Focused Scripts
| Script | Purpose |
|---|---|
test-server-ops.mjs |
Health payload and admin metrics helpers |
test-server-routes.mjs |
HTTP health routes, caching, and admin metrics access |
test-server-ws.mjs |
Socket.IO relay integration, including host-control behavior |
test-rate-limiter.mjs |
Rate-limiter map and cooldown behavior |
test-episode-utils.mjs |
Episode-title extraction and comparison |
test-title-privacy.mjs |
Tab/media title privacy sanitization |
test-audio-settings.mjs |
Audio settings defaults and normalization |
test-popup-refresh-cooldown.mjs |
Popup refresh throttling behavior |
test-names.mjs |
Generated username format and coverage |
test-content-video-finder.cjs |
Content-script video selection helpers |
test-locales.cjs |
Extension runtime and browser-store locale coverage |
test-website-locales.mjs |
Website locale coverage |
Do Not Break
- Keep scripts runnable from the repository root.
- Keep build output under
dist/and generated website output underwebsite/www/. - Keep shared protocol sync automated; do not add manual copy steps.
- Treat warnings in verification scripts as release blockers unless the script explicitly documents them as informational.