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>
This commit is contained in:
Elijah Kuntz 2026-11-02 15:14:40 -07:00
parent a3c05e9062
commit 7d0803481b
39 changed files with 1191 additions and 230 deletions

View file

@ -11,7 +11,7 @@ import { PageLoader } from '../ui/primitives';
import { Splash } from '../screens/Splash';
import { SignIn } from '../screens/SignIn';
import { ServerPicker } from '../screens/ServerPicker';
import { win } from '../platform/native';
import { isMac, win } from '../platform/native';
import { usePlayer } from '../player/store';
import { PlayerOverlay } from '../player/PlayerOverlay';
import { DialogHost } from '../screens/dialogs/DialogHost';
@ -100,13 +100,13 @@ function useGlobalShortcuts() {
if ((e.ctrlKey || e.metaKey) && (e.key === 'k' || e.key === 'f')) {
e.preventDefault();
navigate({ name: 'search' });
} else if (e.altKey && e.key === 'ArrowLeft') {
} else if ((e.altKey && e.key === 'ArrowLeft') || (isMac && e.metaKey && e.key === '[')) {
e.preventDefault();
useRouter.getState().back();
} else if (e.altKey && e.key === 'ArrowRight') {
} else if ((e.altKey && e.key === 'ArrowRight') || (isMac && e.metaKey && e.key === ']')) {
e.preventDefault();
useRouter.getState().forward();
} else if (e.key === 'F11') {
} else if (e.key === 'F11' || (isMac && e.metaKey && e.ctrlKey && e.key.toLowerCase() === 'f')) {
e.preventDefault();
win.isFullscreen().then((fs) => win.setFullscreen(!fs));
} else if ((e.key === 'Escape' || e.key === 'Backspace') && !isTyping(e.target) && !document.querySelector('.menu-layer, .dialog-layer')) {
@ -225,7 +225,16 @@ export function App() {
useEffect(() => {
useSession.getState().init();
// The window appears once the first frame is painted (no white flash).
requestAnimationFrame(() => win.show());
// WKWebView runs no animation frames until its window is shown, so a
// timeout stands in there.
let shown = false;
const show = () => {
if (!shown) win.show();
shown = true;
};
requestAnimationFrame(show);
const fallback = setTimeout(show, 150);
return () => clearTimeout(fallback);
}, []);
useEffect(() => {

View file

@ -5,7 +5,7 @@ import { useSettings } from './settings';
import { Icon } from '../ui/Icon';
import { KaleidoMark } from '../ui/primitives';
import { openMenu, type MenuItem } from '../ui/overlays';
import { isNative, win } from '../platform/native';
import { isMac, isNative, shortcut, win } from '../platform/native';
import { useDownloads } from '../downloads/store';
import { useHomeUsers } from './useHomeUsers';
@ -16,17 +16,18 @@ const NAV = [
{ id: 'downloads', label: 'Downloads', route: { name: 'downloads' } as const },
];
/** Caption buttons drawn by the page; macOS shows its own traffic lights instead. */
export function WindowControls() {
const [maximized, setMaximized] = useState(false);
useEffect(() => {
if (!isNative) return;
if (!isNative || isMac) return;
let off: (() => void) | undefined;
const sync = () => win.isMaximized().then(setMaximized);
sync();
win.onResized(sync).then((u) => (off = u));
return () => off?.();
}, []);
if (!isNative) return null;
if (!isNative || isMac) return null;
return (
<div className="window-controls">
<button aria-label="Minimize" onClick={() => win.minimize()}>
@ -109,7 +110,7 @@ export function TopBar({ solid }: { solid: boolean }) {
</nav>
</div>
<div className="topbar-right" data-tauri-drag-region>
<button className={`icon-btn${active === 'search' ? ' on' : ''}`} aria-label="Search" title="Search (Ctrl+K)" onClick={() => navigate({ name: 'search' })}>
<button className={`icon-btn${active === 'search' ? ' on' : ''}`} aria-label="Search" title={`Search (${shortcut('K')})`} onClick={() => navigate({ name: 'search' })}>
<Icon name="search" size={19} />
</button>
<button className={`icon-btn${active === 'settings' ? ' on' : ''}`} aria-label="Settings" title="Settings" onClick={() => navigate({ name: 'settings', mode: 'app', tab: 'general' })}>

View file

@ -54,7 +54,7 @@ export const useSession = create<SessionState>((set, get) => ({
async init() {
const info = await appInfo();
configureClient({ version: info.version, deviceName: info.deviceName });
configureClient({ version: info.version, deviceName: info.deviceName, platformVersion: info.osVersion });
let token = await secrets.get('account-token');
const stored = loadStoredServer();

View file

@ -13,6 +13,7 @@ import { useRouter } from './app/router';
import { usePlayer } from './player/store';
import { useSettings } from './app/settings';
import { useDownloads } from './downloads/store';
import { hostOS, isMac, isNative, win } from './platform/native';
if (import.meta.env.DEV) (window as any).__kaleido = { useSession, useRouter, usePlayer, useSettings, useDownloads };
@ -24,6 +25,15 @@ window.addEventListener('contextmenu', (e) => {
installKeyboardNav();
// Platform styling: macOS keeps its traffic lights at the top left, except in
// full screen, where the system hides them.
document.documentElement.classList.add(`os-${hostOS}`);
if (isNative && isMac) {
const syncFullscreen = () => win.isFullscreen().then((fs) => document.documentElement.classList.toggle('window-fullscreen', fs));
syncFullscreen();
win.onResized(syncFullscreen);
}
createRoot(document.getElementById('root')!).render(
<StrictMode>
<App />

View file

@ -7,6 +7,16 @@ import type { UnlistenFn } from '@tauri-apps/api/event';
export const isNative = typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window;
/** The host OS, known synchronously from the web view (WebView2, WKWebView, WebKitGTK). */
export const hostOS: 'windows' | 'macos' | 'linux' =
typeof navigator !== 'undefined' && /Macintosh|Mac OS X/.test(navigator.userAgent) ? 'macos' : typeof navigator !== 'undefined' && /Linux|X11/.test(navigator.userAgent) ? 'linux' : 'windows';
export const isMac = hostOS === 'macos';
/** A shortcut with the platform's command key: "⌘K" on macOS, "Ctrl + K" elsewhere. */
export const shortcut = (key: string) => (isMac ? `⌘${key}` : `Ctrl + ${key}`);
/** How the window enters full screen from the keyboard. */
export const fullscreenShortcut = isMac ? '⌃⌘F' : 'F11';
export async function invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T> {
if (!isNative) throw new Error(`${cmd} is only available in the desktop app.`);
const { invoke } = await import('@tauri-apps/api/core');
@ -47,6 +57,7 @@ export interface AppInfo {
dataDir: string;
defaultDownloadDir: string;
platform: string;
osVersion: string;
deviceName: string;
/** Graphics adapters by name (empty where not reported). */
gpus: string[];
@ -57,7 +68,7 @@ export async function appInfo(): Promise<AppInfo> {
if (info) return info;
info = isNative
? await invoke<AppInfo>('app_info')
: { version: '0.1.0-dev', dataDir: '', defaultDownloadDir: '', platform: 'browser', deviceName: 'Browser preview', gpus: [] };
: { version: '0.1.0-dev', dataDir: '', defaultDownloadDir: '', platform: 'browser', osVersion: '', deviceName: 'Browser preview', gpus: [] };
return info;
}
@ -107,6 +118,10 @@ export const win = {
await w.setFocus();
}
},
/** The OS's own window buttons (the macOS traffic lights); elsewhere the page draws them. */
async setButtonsVisible(visible: boolean) {
if (isNative && isMac) await invoke('window_buttons', { visible }).catch(() => {});
},
async onResized(cb: () => void): Promise<UnlistenFn> {
if (!isNative) {
window.addEventListener('resize', cb);

View file

@ -781,6 +781,14 @@ export function PlayerOverlay() {
return () => window.removeEventListener('keydown', onKey);
}, [st.open, st.mini, seekStep, poke]);
// The macOS traffic lights fade with the rest of the player's chrome.
const chromeHidden = st.open && !st.mini && !visible && st.firstFrame && !st.error;
useEffect(() => {
if (!chromeHidden) return;
win.setButtonsVisible(false);
return () => void win.setButtonsVisible(true);
}, [chromeHidden]);
if (!st.open || !st.item) return null;
if (st.mini) return <MiniPlayer />;
const item = st.item;

View file

@ -1,5 +1,5 @@
import { arr, bool, num, str } from './parse';
import { clientIdentifier, PlexError, plexRequest, PRODUCT } from './client';
import { clientIdentifier, DEVICE, PLATFORM, PlexError, plexRequest, PRODUCT } from './client';
import type { HomeUser, PlexUser, ServerConnection, ServerResource } from './types';
const TV = 'https://plex.tv/api/v2';
@ -26,8 +26,8 @@ export function authUrl(pin: Pin): string {
clientID: clientIdentifier(),
code: pin.code,
'context[device][product]': PRODUCT,
'context[device][platform]': 'Windows',
'context[device][device]': 'Windows',
'context[device][platform]': PLATFORM,
'context[device][device]': DEVICE,
});
return `https://app.plex.tv/auth#?${params.toString()}`;
}

View file

@ -1,7 +1,9 @@
import { httpFetch } from '../platform/native';
import { hostOS, httpFetch } from '../platform/native';
export const PRODUCT = 'Kaleido';
export const PLATFORM = 'Windows';
/** How Plex lists this player (Plex's own names for each OS and device). */
export const PLATFORM = hostOS === 'macos' ? 'macOS' : hostOS === 'linux' ? 'Linux' : 'Windows';
export const DEVICE = hostOS === 'macos' ? 'Mac' : hostOS === 'linux' ? 'Linux' : 'Windows';
export class PlexError extends Error {
constructor(
@ -14,7 +16,8 @@ export class PlexError extends Error {
let clientId = '';
let version = '0.1.0';
let deviceName = 'Windows PC';
let deviceName = hostOS === 'macos' ? 'Mac' : 'Windows PC';
let platformVersion = hostOS === 'windows' ? '11' : '';
/** A stable, random identifier for this installation (not secret). */
export function clientIdentifier(): string {
@ -27,9 +30,24 @@ export function clientIdentifier(): string {
return clientId;
}
export function configureClient(opts: { version?: string; deviceName?: string }) {
export function configureClient(opts: { version?: string; deviceName?: string; platformVersion?: string }) {
if (opts.version) version = opts.version;
if (opts.deviceName) deviceName = opts.deviceName;
if (opts.platformVersion) platformVersion = opts.platformVersion;
}
/**
* HTTP header values must be ASCII; Mac names usually aren't ("Elijah’s MacBook").
* Typographic punctuation becomes its plain form and accents are dropped.
*/
export function headerSafe(value: string): string {
return value
.replace(/[‘’]/g, "'")
.replace(/[“”]/g, '"')
.replace(/[–—]/g, '-')
.normalize('NFKD')
.replace(/[^\x20-\x7e]/g, '')
.trim();
}
export function plexHeaders(token?: string | null): Record<string, string> {
@ -39,9 +57,9 @@ export function plexHeaders(token?: string | null): Record<string, string> {
'X-Plex-Version': version,
'X-Plex-Client-Identifier': clientIdentifier(),
'X-Plex-Platform': PLATFORM,
'X-Plex-Platform-Version': '11',
'X-Plex-Device': 'Windows',
'X-Plex-Device-Name': `Kaleido (${deviceName})`,
'X-Plex-Platform-Version': platformVersion,
'X-Plex-Device': DEVICE,
'X-Plex-Device-Name': headerSafe(`Kaleido (${deviceName})`),
'X-Plex-Model': 'Desktop',
'X-Plex-Provides': 'player',
'X-Plex-Language': navigator.language || 'en',
@ -57,7 +75,7 @@ export function plexQuery(token?: string | null): Record<string, string> {
'X-Plex-Version': version,
'X-Plex-Client-Identifier': clientIdentifier(),
'X-Plex-Platform': PLATFORM,
'X-Plex-Device': 'Windows',
'X-Plex-Device': DEVICE,
'X-Plex-Device-Name': `Kaleido (${deviceName})`,
};
if (token) q['X-Plex-Token'] = token;

View file

@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
import { parseItem, parseScores } from './parse';
import { isLocalAddress } from './account';
import { partAt } from './playback';
import { headerSafe } from './client';
import { duration, formatBadges, isWatched, remaining, washGradient } from '../app/format';
import { buildFeatures } from '../screens/discover';
import type { Hub } from './types';
@ -112,3 +113,10 @@ describe('features', () => {
expect(washGradient(movie().ultraBlur)).toContain('rgba(48, 97, 143');
});
});
describe('headerSafe', () => {
it('turns Mac computer names into ASCII header values', () => {
expect(headerSafe('Elijah’s MacBook Pro')).toBe("Elijah's MacBook Pro");
expect(headerSafe('Zoë’s iMac — Studio')).toBe("Zoe's iMac - Studio");
});
});

View file

@ -174,7 +174,7 @@ export default function Downloads({ offline }: { offline?: boolean }) {
{!isNative && (
<div className="downloads-empty">
<EmptyState icon="download" title="Downloads need the desktop app">
Install Kaleido for Windows to save movies and episodes for offline viewing.
Install the Kaleido desktop app to save movies and episodes for offline viewing.
</EmptyState>
</div>
)}

View file

@ -1,22 +1,12 @@
import { isNative, win } from '../platform/native';
import { Icon } from '../ui/Icon';
import { isNative } from '../platform/native';
import { WindowControls } from '../app/TopBar';
/** A draggable strip with window controls for full-screen states without the top bar. */
export function WindowDrag() {
if (!isNative) return null;
return (
<div className="window-drag" data-tauri-drag-region>
<div className="window-controls">
<button aria-label="Minimize" onClick={() => win.minimize()}>
<Icon name="minimize" size={15} strokeWidth={1.4} />
</button>
<button aria-label="Maximize" onClick={() => win.toggleMaximize()}>
<Icon name="maximize" size={13} strokeWidth={1.4} />
</button>
<button aria-label="Close" className="close" onClick={() => win.close()}>
<Icon name="x" size={15} strokeWidth={1.4} />
</button>
</div>
<WindowControls />
</div>
);
}

View file

@ -5,7 +5,7 @@ import { useSections, useServerQuery } from '../../app/queries';
import * as api from '../../plex/api';
import { art } from '../../app/format';
import { useDownloads } from '../../downloads/store';
import { appInfo, isNative, openExternal, pickFolder, revealPath, type AppInfo } from '../../platform/native';
import { appInfo, fullscreenShortcut, isMac, isNative, openExternal, pickFolder, revealPath, shortcut, type AppInfo } from '../../platform/native';
import { checkForUpdate, installUpdate, useUpdater } from '../../app/updater';
import { Button, Segmented, Select, Switch } from '../../ui/primitives';
import { confirmDialog } from '../../ui/overlays';
@ -42,14 +42,16 @@ const skipOptions: { value: SkipMode; label: string }[] = [
{ value: 'off', label: 'Off' },
];
const OS_NAMES: Record<string, string> = { windows: 'Windows', macos: 'macOS', linux: 'Linux' };
const SHORTCUTS: [string, string][][] = [
[
['Ctrl + K', 'Search'],
['Alt + ← / Mouse back', 'Go back'],
['Alt + → / Mouse forward', 'Go forward'],
[shortcut('K'), 'Search'],
[isMac ? '⌘[ / Mouse back' : 'Alt + ← / Mouse back', 'Go back'],
[isMac ? '⌘] / Mouse forward' : 'Alt + → / Mouse forward', 'Go forward'],
['Esc', 'Go back or close a dialog'],
['F11', 'Full screen'],
['Ctrl + ,', 'Settings'],
[fullscreenShortcut, 'Full screen'],
[shortcut(','), 'Settings'],
['Right-click a title', 'Title actions'],
],
[
@ -182,7 +184,7 @@ export function AppSettings({ tab }: { tab: string }) {
<Pref label="Hardware decoding" description="Uses your graphics card to decode video. Turn off only if you see artifacts. Applies after restarting Kaleido.">
<Switch checked={s.hwdec} onChange={(v) => set('hwdec', v)} />
</Pref>
<Pref label="HDR passthrough" description="Sends HDR video to HDR-capable displays when Windows HDR is on. Applies after restarting Kaleido.">
<Pref label="HDR passthrough" description={`Sends HDR video to HDR-capable displays${isMac ? '' : ' when Windows HDR is on'}. Applies after restarting Kaleido.`}>
<Switch checked={s.hdrPassthrough} onChange={(v) => set('hdrPassthrough', v)} />
</Pref>
</SettingsSection>
@ -374,7 +376,7 @@ export function AppSettings({ tab }: { tab: string }) {
<div>
<h2>Kaleido</h2>
<p className="muted">
Version {info?.version ?? '—'} · {info?.platform === 'windows' ? 'Windows' : info?.platform}
Version {info?.version ?? '—'} · {OS_NAMES[info?.platform ?? ''] ?? info?.platform}
</p>
</div>
</div>

View file

@ -248,6 +248,14 @@
display: flex;
justify-content: flex-end;
}
/* macOS draws its traffic lights at the top left (tauri.macos.conf.json places
them in the bar's centre line); keep the bar's content clear of them. */
html.os-macos:not(.window-fullscreen) {
--traffic-lights: 92px;
}
html.os-macos:not(.window-fullscreen) .topbar {
padding-left: max(calc(var(--gutter) - 10px), var(--traffic-lights));
}
/* —— Splash ————————————————————————————————————————————————— */
.splash {

View file

@ -69,6 +69,9 @@
transition: opacity 400ms var(--ease);
}
/* The window's own buttons, top right, fading with the rest of the chrome. */
html.os-macos:not(.window-fullscreen) .player-top {
padding-left: var(--traffic-lights);
}
.player-top .window-controls {
position: absolute;
top: 0;