Kaleido-Desktop/docs/development.md
Elijah 0361a98fa4
All checks were successful
Validate Kaleido Desktop / validate (push) Successful in 2m7s
Release Kaleido Desktop 0.1.0-beta.15
2026-11-11 23:29:47 -07:00

8.8 KiB
Raw Blame History

Development

Setup (Windows)

  1. Node 22+, Rust stable (MSVC), Visual Studio C++ build tools, 7-Zip.
  2. npm ci
  3. .\scripts\fetch-libmpv.ps1 downloads the shinchiro mpv-dev-x86_64 build (the Windows libmpv builds linked from mpv.io) into vendor/mpv/windows.
  4. Put a .env in the repository root for the development sign-in: PLEX_SERVER_URL=... and PLEX_TOKEN=.... It is ignored by git and only read by debug builds and the Vite dev server. Never commit or print it.
  5. npm run tauri dev

Setup (macOS)

  1. Node 22+, Rust stable (brew install rustup && rustup default stable), the Xcode command line tools and Homebrew.
  2. npm ci
  3. sh scripts/fetch-libmpv.sh installs Homebrew's mpv and copies libmpv with every library it links into vendor/mpv/macos, rewritten to find each other there (@loader_path) and signed, so the bundle doesn't depend on Homebrew. Homebrew builds for the macOS it runs on, so the app's minimum macOS is that of the build machine (scripts/build.sh sets it from the libraries).
  4. .env as on Windows, then npm run tauri dev.

Debug builds on macOS keep the Plex token in dev-secrets.json in the app data folder rather than the Keychain: every rebuild is a new unsigned binary, which the Keychain would ask about again. Release builds always use the Keychain.

The interface alone runs in a browser with npm run dev (port 1420), which is handy for layout work; playback, downloads and native dialogs need the desktop app. In development builds the stores are available as window.__kaleido for debugging.

To drive the desktop app from scripts, start it with WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333 and attach over the Chrome DevTools Protocol.

Checks

npm run typecheck
npm test
cargo check --manifest-path src-tauri/Cargo.toml

Playback tests change real Plex progress; resume an in-progress title near its saved position, or restore it afterwards. Selecting audio or subtitle tracks is saved to Plex for that file.

Up Next: automatic episode credits open the screen immediately; button-only credits open it on click, and EOF opens it regardless of the credits preference. There is one autoplay timer. Clicks, keypresses (including Tab), and scrolling cancel it; pointer movement leaves it running. Esc returns to the video; F/F11 toggles full screen. The video rectangle must follow window resizes and DPI changes and return to the full window on dismissal, episode changes, errors, and closing. Verify those native video transitions on a GPU-equipped machine; browser layout checks cannot prove rendering.

Diagnostics

src-tauri/src/diagnostics.rs writes to the app's log folder (%LOCALAPPDATA%\tv.kaleido.desktop\logs on Windows); nothing is uploaded.

  • Hangs: a watchdog asks the UI thread to answer every second. After 5 seconds of silence it writes kaleido-hang-<time>-v<version>.dmp with every thread's stack (once per stall) and notes the stall and the recovery in diagnostics.log.
  • Crashes (Windows): an unhandled exception writes kaleido-crash-…dmp and logs the exception and faulting module, e.g. access violation at libmpv-2.dll+0x1234.
  • Panics are logged with a backtrace.

The newest five dumps of each kind are kept. To read one, open it in WinDbg with the symbols of the exact build that wrote it: scripts/build.ps1 keeps each release's kaleido.exe and kaleido.pdb in .tools/symbols/<version>/ (release builds keep function names and line tables in the .pdb; the installer doesn't change). In WinDbg: .sympath+ <that folder>, .reload, then ~*k for every thread's stack.

Development builds have two test commands: debug_freeze_ui ({ seconds }, holds the UI thread) and debug_crash (an access violation); both refuse to run in release builds.

Threading rule learned the hard way: Tauri's window getters (hwnd(), sizes…) called off the UI thread wait for it to answer, so never call one while holding a lock the UI thread might wait on, and keep window-event handlers from waiting on the player's locks (they run on the UI thread; lib.rs hands resize handling to a background thread).

App icon

src-tauri/icons/app-icon.svg is the source. Render it to a 1024×1024 app-icon.png with a transparent background, run npx tauri icon src-tauri/icons/app-icon.png -o <temp dir>, and copy back only the files already in src-tauri/icons (the Android and iOS sets aren't used).

Releases

Releases are built and published locally: Windows on the Windows machine, macOS on the Mac. CI only validates; it never builds installers on push (there are no Windows/macOS runners). Versions follow SemVer; betas use a prerelease suffix (0.1.0-beta.1) and are published as pre-releases. Each release carries both platforms, and the update feed is written only once both are uploaded.

Checklist for version X.Y.Z (run from the repository root):

  1. Version (either machine): set X.Y.Z in package.json, src-tauri/Cargo.toml and src-tauri/tauri.conf.json, then npm install --package-lock-only to update package-lock.json.
  2. Changelog: add a ## X.Y.Z section at the top of CHANGELOG.md. It becomes the release notes and the in-app update notes.
  3. Check: npm run typecheck, npm test, cargo check --manifest-path src-tauri/Cargo.toml.
  4. Commit and tag: commit as Release Kaleido Desktop X.Y.Z, then git tag -a vX.Y.Z -m "Kaleido Desktop X.Y.Z" and git push origin main vX.Y.Z (SSH remote origin, already configured). Pull it on the other machine.
  5. Build and publish on Windows: .\scripts\build.ps1 → src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe and its .sig; then node scripts/publish-release.mjs X.Y.Z (add --prerelease for betas) creates the Forgejo release with the notes from CHANGELOG.md and uploads them.
  6. Build and publish on macOS: sh scripts/build.sh → bundle/dmg/Kaleido_X.Y.Z_aarch64.dmg (first installs) and bundle/macos/Kaleido_X.Y.Z_aarch64.app.tar.gz with its .sig (updates); then node scripts/publish-release.mjs X.Y.Z [--prerelease] adds them to the same release. The order of 5 and 6 doesn't matter.
  7. Update feed (either machine): node scripts/update-manifest.mjs X.Y.Z reads the release's assets (downloading each .sig) and rewrites updates/latest.json; commit it (Publish the X.Y.Z update feed) and push. Installed copies offer the update on their next start. The script refuses while a platform's build is missing from the release, so neither OS is ever pointed at an older build; --allow-missing publishes the feed without it (that OS then sees no update until the feed is regenerated).
  8. Verify: download each artifact from the release and compare its SHA-256 with the local file; https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json should list both platforms at the new version; CI on Actions should finish green.

Both publishing scripts read FORGEJO_TOKEN (repository read/write) from the environment or the ignored .env, and never print it. Re-running publish-release.mjs replaces that machine's assets.

Update signing: both build scripts sign update artifacts with the updater key from .tools/updater.key (ignored; keep it safe — replacing it breaks in-app updates for existing installs) or TAURI_SIGNING_PRIVATE_KEY. Both build machines need the same key in .tools/; without it a build has no update archive.

Windows installs per user (%LOCALAPPDATA%\Kaleido, no admin) and is not code-signed, so SmartScreen warns on first run. In-app updates run the installer in passive mode and relaunch.

macOS builds are signed with a self-signed certificate, "Kaleido Self-Signed", in the build Mac's login keychain (backed up, with its password, as .tools/macos-signing.p12 and .tools/macos-signing.password). A lasting signature keeps the app's identity across updates, so the Keychain keeps trusting it with the Plex token; ad hoc signatures change with every build and would make macOS ask again after each update. To build on another Mac, import the backup: security import .tools/macos-signing.p12 -k ~/Library/Keychains/login.keychain-db -P "$(cat .tools/macos-signing.password)" -T /usr/bin/codesign. The app isn't notarized, so the first launch of a downloaded .dmg needs System Settings → Privacy & Security → Open Anyway (or right-click → Open); in-app updates aren't quarantined and install without that. Building runs Finder through AppleScript to lay out the disk image window; set CI=true to skip that step.

Linux can be built with sh scripts/fetch-libmpv.sh and npx tauri build but isn't published. .forgejo/workflows/release.yml validates every push and tag; .forgejo/workflows/build-installers.yml can build installers in CI once runners exist for each platform, and only runs when started by hand.