Kaleido-Desktop/docs/development.md
Elijah 4985f1dde0
All checks were successful
Validate Kaleido Desktop / validate (push) Successful in 1m22s
Release Kaleido Desktop 0.1.0-beta.11
Fix a UI-thread deadlock between the player and window resizes: player_rect
held the video-surface lock while Tauri's hwnd() waited for the UI thread,
and on_resize, running on the UI thread, waited for that lock. Leaving full
screen for the miniplayer could freeze the window while mpv kept playing.
Resize handling now runs off the UI thread, and the Windows surface keeps its
HWND instead of asking the UI thread for it.

Add local diagnostics: a watchdog writes a dump of every thread when the UI
thread stops answering for 5 s, unhandled exceptions write a crash dump and
log the faulting module (Windows), and panics are logged. Windows release
builds keep function names in kaleido.pdb, archived per version in
.tools/symbols/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 17:04:07 -07:00

147 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```powershell
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.
## 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.