Kaleido-Desktop/docs/development.md
Elijah Kuntz 7d0803481b Port Kaleido Desktop to macOS
macOS (Apple silicon) now plays, browses and updates like Windows:

- Video: libmpv's render API draws into a CAOpenGLLayer beneath the
  WKWebView, with the miniplayer rectangle, HDR passthrough through
  extended dynamic range (PQ/BT.2020) and display-sleep prevention.
- Window: native traffic lights on the top bar's centre line, hidden
  with the player's controls; the page's caption buttons are Windows-only.
- Interface: macOS shortcut labels (⌘K, ⌘[, ⌃⌘F), Plex identifies the
  player as a Mac, and header values are kept ASCII (Mac computer names
  usually contain a curly apostrophe).
- The window appears without waiting for an animation frame, which
  WKWebView doesn't run in a hidden window.
- Credentials: release builds use the Keychain and are signed with a
  lasting self-signed certificate so access survives updates; debug
  builds keep tokens in a private file to avoid prompts on every rebuild.
- Bundling: scripts/fetch-libmpv.sh makes Homebrew's libmpv and its
  libraries self-contained; scripts/build.sh builds the .app, .dmg and
  signed update archive.

Releases now carry both platforms: publish-release.mjs uploads each
machine's build into one release, and update-manifest.mjs writes the
feed from that release's assets, refusing while a platform is missing.

The updater uses a new signing key (public key in tauri.conf.json), so
existing installs must be reinstalled once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 15:14:40 -07:00

6.7 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.

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.