dtourolle
95129d04a3
DR-172 reverted native video to opt-in after it shipped as audio with no picture, naming the compositing as the suspect. The compositing was fine. Five separate defects sat between ExoPlayer and the screen, each able to produce that exact symptom on its own, and each invisible to the others. DR-185 — the app shell painted over the surface. app.css clears the page's opaque layers through three selectors, one of which targets `[data-app-shell]`, an attribute NO component has ever set, in any commit. The shell paints --color-background across the whole viewport and VideoPlayer stacks above it, so the WebView composited opaque no matter what else was cleared. Invisible three ways over: the CSS is valid, the selector is plausible, and a rule matching nothing looks exactly like a rule matching something already transparent. DR-182 — nothing could lift the poster card. Every markMediaReady() call site is an HTML5 <video> event, and the native branch renders no element, so the black title card covered the surface for the entire session. The first fix hooked `player://position-update` / `player://state-changed`; those channels are never emitted by the backend, so it passed a test that fired them by hand and did nothing on a device. Driven from the player store now, as the seek bar already was. DR-183 — the JS bridges raced the page load. Installed 500ms after onCreate by walking the view tree, while WebView binds injected objects at page-load time, and the identity guard then declined to re-inject forever. setTransparent(true) could never arrive. Installed from WryActivity.onWebViewCreate instead, which wry calls immediately before the first loadUrl. DR-184 — the SurfaceView was never detached. detachVideoSurface had no callers anywhere, mirroring the DR-151 defect: every native video left its surface parented to the content view and the next one stacked another beneath it. DR-191 — the overlay stopped repainting. Incremental damage (the clock's text, the control bar's opacity) never reached the screen while structural changes did, so the progress bar froze, the controls would not fade, and the play overlay appeared to work because it is added and removed from the DOM. Driven from the Activity via postInvalidateOnAnimation while compositing is on. Two UI defects only this path could reveal came with them: isPlaying froze at its initial value, leaving the play overlay dimming and covering the video (DR-186), and the control bar's auto-hide was armed solely by mousemove, which a touchscreen never fires (DR-189). Immersive mode now applies on entering the player rather than only via the fullscreen button (DR-187). Verified on a device (Honor ROD2-W09, Android 16): logcat carries `WebView transparent = true` and `Marking media ready` with video on screen — the pair DR-172 went looking for and could not find — and skip, seek, rotation and subtitle rendering were exercised by hand. The default stays OFF (DR-188). Turning it on surfaced a further unverified sub-path: returning from background audio is HTML5-only, so playback stays dead (DR-190, proposed). Shipping it would have repeated DR-161 exactly — a verified sub-path made default over an unverified one.
Development Scripts
Collection of utility scripts for building, testing, and deploying JellyTau.
Testing Scripts
test-all.sh
Run all tests (frontend + Rust backend).
./scripts/test-all.sh
test-frontend.sh
Run frontend tests only.
./scripts/test-frontend.sh # Run all tests
./scripts/test-frontend.sh --watch # Watch mode
./scripts/test-frontend.sh --ui # Open UI
test-rust.sh
Run Rust tests only.
./scripts/test-rust.sh # Run all tests
./scripts/test-rust.sh -- --nocapture # Show println! output
Android Scripts
build-android.sh
Build the Android APK.
./scripts/build-android.sh # Debug build
./scripts/build-android.sh release # Release build
deploy-android.sh
Install APK on connected Android device.
./scripts/deploy-android.sh # Deploy debug APK
./scripts/deploy-android.sh release # Deploy release APK
build-and-deploy.sh
Build and deploy in one command.
./scripts/build-and-deploy.sh # Build + deploy debug
./scripts/build-and-deploy.sh release # Build + deploy release
check-android.sh
Check Android development environment setup.
./scripts/check-android.sh
logcat.sh
View Android logcat filtered for the app.
./scripts/logcat.sh
Traceability & Documentation
extract-traces.ts
Extract requirement IDs (TRACES) from source code and generate a traceability matrix mapping requirements to implementation locations.
bun run traces # Generate markdown report
bun run traces:json # Generate JSON report
bun run traces:markdown # Save to docs/traceability.md
bun run traces:coverage # Coverage gate — exits non-zero below 50%
The script scans all TypeScript, Svelte, and Rust files (plus scripts/)
looking for TRACES: comments and generates a comprehensive mapping of:
- Which code files implement which requirements
- Line numbers and code context
- Coverage summary by requirement type (UR, IR, DR, JA)
bun run traces:coverage is the supported way to check requirement coverage
locally — it runs the same computation CI does. Coverage denominators are
derived from docs/requirements.md at run time; they are never hardcoded. An ID
that appears in a TRACES: comment but is not defined in requirements.md is
reported as orphaned and does not count toward coverage (see DR-093).
Removed:
check-req-coverage.sh,check-test-coverage.sh, andfind-req-implementations.shwere deleted in July 2026. They read an undocumented@req:tag convention parallel toTRACES:, greppedsrc-tauri/unscoped (hanging on ~40 GB oftarget/artifacts), and in one case reported "all requirements implemented" from an empty result set.extract-traces.tsis the single source of truth for requirement coverage. See docs/specs/req-coverage-script-removal.md.
Example TRACES comment in code:
// TRACES: UR-005, UR-026 | DR-029
function handlePlayback() { ... }
See docs/traceability.md for the latest generated mapping.
CI/CD Validation
The traceability system is integrated with Gitea Actions CI/CD:
- Automatically validates TRACES on every push and pull request
- Enforces minimum 50% coverage threshold
- Warns if new code lacks TRACES comments
- Generates traceability reports automatically
For details, see:
- Traceability CI Guide - Full CI/CD documentation
- TRACES Quick Reference - Quick guide for adding TRACES
Utility Scripts
clean.sh
Clean all build artifacts.
./scripts/clean.sh
NPM Script Aliases
You can also run these via npm/bun:
bun run test:all # All tests
bun run test:rust # Rust tests
bun run android:build # Build Android APK
bun run android:deploy # Deploy to device
bun run android:dev # Build + deploy debug
bun run android:check # Check environment
bun run clean # Clean artifacts