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