Kaleido-Desktop/docs/development.md
Elijah 242a1cec1b Replace the startup iris with a kaleidoscope and enlarge the app icon
The splash now gathers a mirrored field of shards into the mark, idles with
circling shards while startup finishes, and flies through the mark's centre
as before. The app icon's mark fills ~77% of the tile (was ~45%); the icon
set is generated from the new app-icon.svg.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 19:32:35 -07:00

81 lines
4.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`
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 <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 from this Windows machine. 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.
Checklist for version `X.Y.Z` (run from the repository root):
1. **Version**: 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. **Build**: `.\scripts\build.ps1` → `src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe`
and its `.sig`. The updater key is read from `.tools/updater.key` (ignored; keep it
safe — replacing it breaks in-app updates for existing installs) or from
`TAURI_SIGNING_PRIVATE_KEY`.
5. **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).
6. **Publish**: `node scripts/publish-release.mjs X.Y.Z` (add `--prerelease` for betas)
creates the Forgejo release with the notes from `CHANGELOG.md` and uploads the
installer and `.sig`. It reads `FORGEJO_TOKEN` (repository read/write) from the
environment or the ignored `.env`, and never prints it. Re-running it replaces the
assets.
7. **Update feed**: `node scripts/update-manifest.mjs X.Y.Z https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/releases/download/vX.Y.Z`
rewrites `updates/latest.json`; commit it (`Publish the X.Y.Z update feed`) and push.
Installed copies offer the update on their next start. Publish the feed only after
the release assets exist, or clients would be sent to a missing file.
8. **Verify**: download the installer from the release URL and compare its SHA-256 with
the local file; `https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json`
should show the new version; CI on Actions should finish green.
The installer is per user (`%LOCALAPPDATA%\Kaleido`, no admin) and is not code-signed,
so SmartScreen warns on first run. In-app updates run it in passive mode and relaunch.
For macOS and Linux, build on those systems (`scripts/fetch-libmpv.sh`, then
`npx tauri build`) and merge their bundles into the same feed with `KALEIDO_BUNDLES`.
`.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.