For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/desktop/internals.md (or send Accept: text/markdown).
Inside the desktop shell
Boot page, navigation gate, plugin stack, and configuration reference.
The boot page
The window loads the bundled page in apps/desktop/ui first: it reads the injected __SUPASTACK_APP_URL__, probes the backend with a ten-second timeout, and forwards to it when reachable. An unreachable backend renders a Can't reach host state with a Retry that also fires on network recovery, so a cold start never shows a blank window. A ?target= query parameter exercises the page in a plain browser.
Native features are plugins, not IPC
The shell registers no custom commands — every native capability arrives through Tauri plugins: single-instance with the deep-link feature (which routes second-launch arguments on Windows and Linux), deep-link, window-state (geometry only — zoom and channel keep their own sidecars), opener, dialog, process (restart after update), updater, autostart, and global-shortcut, plus the tray-icon feature. Extending the shell means adding a plugin and a permission, not forking webview UI.
The navigation gate
Navigation stays for the bundled shell pages, the dev-server origin, and the exact configured app origin. Credential-free HTTP(S), mailto:, and tel: links leave through the system browser via the opener plugin; every other scheme is cancelled. A deep link arriving before the window exists is buffered in managed state and applied once it does.
Config and capability reference
tauri.conf.json sets productName, version (bump before a release — the workflow can override it), the identifier (check:release-config requires changing it from com.supastack.desktop), the supastack deep-link scheme, the updater sentinel block, bundle targets, and the placeholder icons. capabilities/default.json grants core:default plus opener:allow-open-url — widen it only when a new plugin needs more.
How the shell is tested
corepack pnpm --filter @supastack/desktop test syntax-checks the boot page and runs the Rust unit suite covering URL resolution, deep links, zoom, and channel logic; typecheck runs cargo check. The JavaScript release scripts are covered by the repository's vitest suites, and the CI pipeline builds real installers on all three operating systems for every change.
corepack pnpm --filter @supastack/desktop typecheck
corepack pnpm --filter @supastack/desktop test
corepack pnpm --filter @supastack/desktop check:release-configVerification and troubleshooting
Run the package suite after touching src-tauri, then verify the native behavior by hand on each target OS — unit checks prove the rules, not the window. Keep new shell behavior inside plugins and menu items so the webview stays a plain web app.