All checks were successful
Validate Kaleido Desktop / validate (push) Successful in 1m29s
Rebuild the Up Next screen on Kaleido's own components: - Backdrop, colour wash, buttons and cards from the title pages; the credits play in a top-left frame with a matching hole in the page. - Season and related rows use Shelf, so they scroll with side arrows instead of scrollbars; the season row starts at the playing episode. - Returning to the video at the end no longer restarts the episode. - Compact layout for short windows; Mac window buttons stay visible. - Restore the flat Episodes and markers settings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
153 lines
8.7 KiB
Markdown
153 lines
8.7 KiB
Markdown
# 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.
|
||
|
||
Up Next (`player/PostPlay.tsx`) opens at an episode's first credits marker, or at the end
|
||
without markers. The video is drawn into its top-left frame (`player_rect`) behind a
|
||
matching hole in the page; check that the two line up after resizing, changing display
|
||
scale and returning to the video. In the browser, open it from the console by setting
|
||
`postPlay: true` (with `item`, `nextUp`, `episodeContextReady`) on `__kaleido.usePlayer`.
|
||
|
||
## 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.
|