Layout shell: one frontend, two layouts
The browser app and the desktop app render the same React frontend. There is no per-platform fork of the UI. The differences between the two are confined to (a) the app entry that boots the shell and (b) the platform capabilities exposed to modules.
Implementation status
Implemented: module registry, spotlight (Ctrl+K), keybinding service
(mod+ prefix), capability service, and both entries (apps/web on port 5173
proxying /api and /ws to the backend on port 8000; apps/desktop Electron shell
loading the same dev server, or the built UI from app://horrible when packaged). The shared /ws socket is consumed via a single
multiplexed client (packages/core/src/ws.ts, channel subscriptions + sendChannel)
— its users are the observability telemetry channel (see
../modules/observability.md) and the agent
channel that drives the agent orchestrator (see
../modules/agent-chat.md). The backend /ws handler
is a bidirectional router: telemetry pushes outbound while one receive loop
dispatches inbound channel messages.
The shell has exactly one main view. ShellView is 'boot' | 'oobe' | 'desktop', and the first two are the states before you arrive at it.
That is a change from the original two-view design. The workspace view (a tiling
frame) is gone along with tiling itself — see
desktop-shell.mdx — and:
homewas a second landing screen competing with the desktop for the same job. It survives as thesplashbackdrop — same avatar, greeting and ask bar, now under the workbench.shell.homestill exists and still means "take me to the landing surface"; the destination is now the desktop.
Installing the layout engine is correspondingly a shell job rather than the
frame's: packages/ui/src/layout/install.ts installs the LayoutController, binds the
autosave, registers the frame module's commands and hydrates the desktop. That
used to live in the tiling frame's mount effect, which worked only while the frame
was the only place you could be — once the desktop became the landing surface a
fresh boot installed none of it, and every one of those failures was silent.
See desktop-shell.mdx for the desktop, its backdrops, the status bar and the boot flow.
What survived from the old home view is the avatar
(packages/core/src/Avatar3D.tsx — moved to core so feature modules like the agent
chat pane can use it too). It is a
rigged glTF character (/my-avatar.glb) loaded with three's GLTFLoader,
with pointer-tracking. It expresses the agent's emotional mood as a looping
animation: the moods prop maps mood names to animation clips
(DEFAULT_AVATAR_MOODS — happy → /dancing.glb, flair → /flair.glb,
error → /falling-over.glb, all in apps/web/public/) and the mood prop
selects the active one, cross-fading on change. Adding a mood is one .glb
plus one line in the map. Orbiting the avatar is Dashy, the dashboard
mascot — a cute glowing orb with eyes that face the viewer, whose glow doubles
as the agent status light. three is dynamically imported so a desktop not
showing the splash backdrop never loads it. The scene itself lives in
packages/core/src/avatar-scene.ts, apart from the component, because building
it is expensive (a 4.7 MB model, fifteen textures, seven shader programs — over a
second of main-thread work, which froze every pane): assets are parsed once
per session, textures are shrunk to 512px off the main thread before upload,
shaders compile through compileAsync, and an unmounted avatar's scene is
parked for five minutes and adopted by the next mount instead of rebuilt.
Every pane lives in a tab group of the docked workbench: the centre split tree,
an edge dock, or on desktop a pop-out window. Region strips run down a pane's own
sides. See windowing.mdx for the model, roles, pane types vs
instances, and persistence. Panes are opened from the spotlight, the Start menu, a
command, or the agent. The minibuffer floats above the status bar — alt+x for
slash commands, and where dialogs.prompt() renders (see
windowing.mdx).
The workbench sits over the view as a sibling of it, not inside it, so panes do
not unmount when the view is hidden (.shell-view[hidden] is display: none). It
is bounded by .shell-content, which keeps it below the native titlebar and its
drag region — and the status bar sits outside .shell-content, so a maximized
group cannot cover it. See desktop-shell.mdx.
The shell may never scroll, and says so with overflow: clip rather than hidden.
A hidden box hides its scrollbar but is still a scroll container: the browser
scrolls it to reveal a focused element. On the floating desktop a window hanging off
the bottom of the layer scrolled every window up at once, out of reach; and a status
bar label that wrapped overflowed the shell by 2px, the page grew a scrollbar, and
the desktop lost 10px of width. A clip box cannot be scrolled by anything.
Branding: source art lives in assets/ (logo.svg, banner.svg) —
pnpm build:icons regenerates the web favicon (apps/web/public/favicon.ico,
16/32/48), the SVG favicon copy, and the desktop app icons (apps/desktop/build/) from
assets/logo.svg. assets/banner.svg is the README banner.
The workspace
The shell owns the desktop: panes in tab groups, persisted as one layout. Modules
never render themselves into the DOM directly — they register panels with the
module registry (packages/core), and the shell decides where panes live (where
that view was last left, else by its role; the user can rearrange freely).
A pane body is loaded when it first renders, not at boot. Every manifest is
registered before the shell paints, so a component a manifest imports statically is
parsed on every launch whether or not its pane is ever opened — which is how three.js,
Rapier, Agora, pdf.js, xterm, xyflow, MUI and CodeMirror all used to load up front.
Manifests declare component: lazyPane(() => import('./Panel'), 'Panel') instead, and
PaneHost (and a board tile, and a settings section) renders it under <Suspense>.
The rule that makes it work: the file behind the import() must not also be
imported statically from anything on the boot path — a barrel re-export counts —
or the bundler has nothing to split and the pane quietly stays eager. The production
entry is ~0.8 MB (from 3.0 MB, plus eight vendor chunks that are no longer preloaded),
and pnpm dev loads ~430 modules at boot instead of ~1,500.
The one bundler trap: Vite's __vitePreload helper is shared by every dynamic
import, and Rollup hoists it into whichever manualChunks chunk used it first. It
landed in vendor-codemirror (via language-data), so the entry preloaded all of
CodeMirror to call a 1 KB helper. apps/web/vite.config.ts pins it to its own
runtime chunk.
Everything user-facing routes through two shell services:
- Spotlight (
mod+k) — every module capability is a registered command (module.verbids, e.g.terminal.new,chat.focusInput). Panels' buttons invoke commands; the spotlight and keybindings invoke the same commands. This is what keeps both layouts behaviorally identical. The spotlight also searches open panes and falls through to the agent when nothing matches, so one keystroke covers ask, run and open — see desktop-shell.mdx. - Keybinding service — maps keys to command ids, conditioned on the focused pane and on whether a pane has captured the keyboard. Modules declare defaults, the user can rebind anything, and on desktop it registers OS global shortcuts. Fully documented in keybindings.mdx; the summary below is just the frame's own defaults.
Keybindings
A KeybindingDecl is { key, command } plus optional when (a condition over a
closed context-key vocabulary), override, hosts/platforms, and global.
Precedence is capture gate → user override → override: true → most specific
when → registration order. Key specs are +-separated modifier tokens plus
the key (mod+k, alt+shift+left, mod+k mod+s for a sequence, code:KeyW for
a physical key).
Focus lives in frame.focusedInstanceId; a pane that needs the whole keyboard
takes capture, and Escape unwinds through one ordered ladder. All of that,
plus host-reserved chords and the keymap.* agent tools, is in
keybindings.mdx. (CodeMirror/xterm keep their own internal
keymaps; this service is for registry command bindings.)
Default desktop keybindings
| Key | Action |
|---|---|
t / n / b | toggle the focused pane's left / right / bottom region strip |
declared letters (o, s, g, …) | reveal that region view on the focused pane |
ctrl+space (Linux) · mod+alt+f (mac/Windows) | present the focused group's pane over the whole screen |
f11 (desktop only) | toggle native OS-window fullscreen. Desktop-only because f11 is browser-owned and unpreventable — the browser layout reaches app fullscreen through the tray control instead |
alt+arrows | focus the nearest group in that direction (docks included) |
alt+grave / alt+shift+grave | next / previous group |
mod+shift+arrows | move the focused tab into a new group on that side |
mod+alt+up | maximize / restore the focused group |
mod+alt+[ / mod+alt+] / mod+alt+j | show / hide the left, right, bottom dock |
mod+k | spotlight — ask, run a command, or jump to a pane (a focused pane may shadow it — the terminal binds it to terminal.clear) |
alt+x | minibuffer / M-x — slash commands (override, never shadowable) |
mod+k mod+s | Keyboard Shortcuts pane |
Two of those rows split by host or platform for a reason: f11 is browser-owned,
and ctrl+space is the IME toggle on Windows and the input-source switch on macOS.
Both are in the reserved table, and the Shortcuts pane flags any binding that lands
on one.
Platform capability service
Modules must never check window.horribleDesktop or user-agent sniff. packages/core
exposes a capability service; feature code branches on capabilities and degrades
gracefully:
| Capability | Browser | Desktop (Electron) |
|---|---|---|
fs.nativeDialogs | no (backend workspace roots only) | yes (native open/save dialogs) |
shell.revealInOS | no | yes |
notifications.system | Web Notifications (tab-scoped) | OS notifications |
window.multi | no (no pop-out control) | yes (a tab group pops out to its own OS window) |
window.fullscreen | yes (DOM Fullscreen API; tray control, no F11) | yes (native OS-window fullscreen; F11 or the titlebar control) |
chrome.workspaceTabs | no (the page is already in a window) | yes (undecorated window; the app draws the titlebar) |
shortcuts.global | no | yes (global: true bindings registered with the OS) |
tray | no | yes |
media.displayCapture | yes | yes (the shell answers getDisplayMedia with the screen; macOS 15+ shows the system picker) |
Every row is now uniform across the desktop, because every platform runs the same
Chromium. It was not under the Tauri shell: media.displayCapture was withheld on
macOS, where WKWebView exposed navigator.mediaDevices.getDisplayMedia and then
rejected the call with NotAllowedError — byte-identical to the host dismissing the
picker — so a probe would have reported "available" and the share failed silently.
That is why it is a capability at all, and why desktopCapabilities() is still a
function: a shell that cannot do something must subtract it there. Everything else
about capture is feature-detected; see the share module.
The window.*/chrome.* rows are the contract for the native shell (pop-out
windows, an app-drawn titlebar, OS fullscreen). They exist in the Capability union so the
shell can branch on them. The desktop shell grants these through DESKTOP_CAPABILITIES, and the
desktop entry wires a WindowControl seam (packages/core/src/window.ts) to
the shell's window_* commands (apps/desktop/src/window.ts).
Shipped so far:
window.multi— a tab group of views that declarepopout: truecan pop out into an OS window and dock back. The page opens the window itself (window.open('', 'horrible-popout:<id>')) and portals the group into it, so one realm keeps every store and the backend socket; the shell only allows that window, clamps it to a display, syncs zoom and reports moves and closes. See windowing.mdx.window.fullscreen—shell.toggleFullscreentakes the whole app fullscreen, distinct from presenting a pane in-window. It is granted in both layouts:toggleAppFullscreen(core/fullscreen.ts) drives the native OS window through theWindowControlseam where there is one, and the DOM Fullscreen API where there is not. The key is native-only —keymap/reserved.tsdeclaresf11browser-owned withpreventable: false, so binding it in a tab yields a binding that silently never fires. The tray's⛶button is what makes the feature reachable in the browser.chrome.workspaceTabs— the desktop window is frameless (frame: false) andTitleBar.tsxis its titlebar: adata-app-drag-regionstrip (-webkit-app-region: drag— the OS's caption: it moves the window and maximizes on double-click), the min/maximize/close controls (WindowControls), and invisible edge grips (WindowResizeHandles). Electron keeps native resize borders on a frameless window, so the OS takes an edge press before the grips see it. The name is the workspace tab strip's, which used to be that titlebar. All three ship. (window.perWorkspace— a workspace in its own OS window — was removed with the workspaces.)
Every shell command goes through one door: the preload exposes
window.horribleDesktop.invoke(command, args) (and listen(event, fn)), and the
main process answers only names in its COMMANDS table (apps/desktop/src/main.ts),
only from the app's own page. Wiring a new native capability: grant it in
DESKTOP_CAPABILITIES, add the command to COMMANDS, extend the relevant host seam,
and gate the feature on hasCapability(...) so the browser degrades cleanly.
The desktop build claims DESKTOP_CAPABILITIES (vs the browser's
BROWSER_CAPABILITIES) via the isDesktopShell() branch in apps/web/src/main.tsx.
Backend connection
Both layouts talk to the same FastAPI backend over HTTP + WebSocket, through one
origin switch (packages/core/src/origin.ts, set once at boot via
initBackendOrigin):
- Browser: origin stays
null— paths are relative (/api,/ws) and the Vite dev server proxies them tolocalhost:8000over a keep-alive agent. Without one, http-proxy sendsConnection: closeand relays it back, so every API call opened a new TCP connection to the dev server — and on Windows a new connection tolocalhostcosts ~250ms, because the IPv6 attempt is refused before IPv4 is tried (Vite listens on127.0.0.1). Start the backend yourself (scripts/dev-backend.ps1oruv run uvicorn backend.app:app --port 8000). Anything that executes on the backend (terminals, file access, agents) runs where the backend runs, not where the browser runs. Module docs call this out where it matters. - Desktop: the shell spawns and supervises the backend itself
(
apps/desktop/src/backend.ts). On launch it locates the repo checkout (or, in a packaged install, the bundled runtime), reuses an already-running backend on:8000if there is one (dev-backend.ps1 coexistence; it must answerGET /api/healthashorrible-dashboard, so a stranger holding the port is skipped rather than adopted), otherwise picks a port (8000 preferred, ephemeral fallback) and spawns uvicorn bound to127.0.0.1— via the repo's.venvpython when present, elseuv run— with MinGW dirs stripped from the child PATH (theno OPENSSL_Applinkcrash). It restarts the process with backoff if it dies (3 fast failures →failedwith the stderr tail) and stops it before the app exits. If the shell dies without getting there (a crash, a SIGKILL), the backend still goes: its stdin is a pipe the shell holds and never writes to, andbackend/parent_watch.pyshuts it down on that pipe's EOF (opted into withHORRIBLE_EXIT_WITH_PARENT=1, which it consumes so its own children do not inherit it). The frontend polls thebackend_statuscommand at boot and uses absolute http/ws URLs from then on — no Vite proxy in the loop, so dev and packaged builds exercise the same path. If the backend never comes up, boot proceeds pluginless; the boot splash records the failed step and the status bar's tray shows the backend as offline. - Desktop renderer crashes (
apps/desktop/src/crashPolicy.ts). When the UI's process dies, the shell logsrenderer process gone: reason=… exitCode=…and reloads the page — at once, then after 2 s, then 5 s. Four crashes inside a minute and it stops reloading and shows a crash page with the reason and a reload link, rather than leaving a blank frameless window (the old handler reloaded once and then left the window dead, with nothing logged). A hang is logged too, when the window becomes unresponsive and when it recovers. A reload rebuilds every pane, so an unexplained "the desktop reset itself" is worth checking against these lines.
A packaged desktop build has no repo checkout; it runs the bundled runtime instead (see releases). A per-session auth token between shell and backend is a planned follow-up — today anything on localhost can reach the API.
The shell owns a single multiplexed WebSocket connection with reconnect/backoff; modules subscribe to channels on it rather than opening their own sockets.
Toast notifications
The layout shell contributes a global Toast Notification System for displaying non-blocking, transient visual alerts (success, info, warning, error) that slide in from the top-right corner. It is designed to be usable by any module or plugin to announce background events (such as peer connections, file exports, or network status changes).
- Store (
toastsStore) — lives inpackages/core/src/toasts.ts(exported astoastsStoreand typeToastfrom@horrible/core). Operates as a simple pub/sub store with ReactuseSyncExternalStoresupport:toastsStore.add(type, title, message, duration?)— triggers a new notification. Default duration is 4 seconds (4000ms); set to0or negative to keep it persistent until closed.toastsStore.remove(id)— clears a notification by its unique ID.
- Component (
Toasts) — lives inpackages/ui/src/Toasts.tsx(rendered in the globalAppShelllayout overlay). Uses glassmorphism styling (backdrop-filter: blur(12px)) and cubic-bezier transition slide animations defined inpackages/ui/src/styles.css.
Usage Example
import { toastsStore } from '@horrible/core';
// Success notification
toastsStore.add('success', 'File Exported', 'Workspace layout successfully saved to disk.');
// Error notification with persistent display
toastsStore.add('error', 'Sync Failed', 'Failed to connect to the peer fabric.', 0);
Modal dialogs (prompt / confirm)
Toasts inform; dialogs ask. The shell contributes a promise-based modal
system that replaces the browser's window.prompt / window.confirm (which are
unstyled, untestable, and block the whole tab). No module calls the native dialogs
anymore — they all route through here, so input and confirmation look and behave
the same in both layouts.
- Store (
dialogsStore/dialogs) —packages/core/src/dialogs.ts, exported from@horrible/core. Requests queue (one shown at a time) and each returns a promise:dialogs.prompt({ title, message?, defaultValue?, placeholder?, confirmLabel?, cancelLabel? })→Promise<string | null>(null on cancel).dialogs.confirm({ title, message?, confirmLabel?, cancelLabel?, danger? })→Promise<boolean>.danger: truerenders the confirm button red for destructive actions (delete).
- Component (
Dialogs) —packages/ui/src/Dialogs.tsx, mounted inAppShellbeside<Toasts />. Renders the active dialog centered over a dimmed backdrop; Enter submits, Escape and backdrop-click cancel, the field auto-focuses. Styles (.dialog-*) live inpackages/ui/src/styles.css.
Outside React (commands, CodeMirror keymaps) call await dialogs.prompt(...)
directly; where a handler must return synchronously (e.g. an editor keymap), fire
the promise and act in .then(...). Pair the result with a toast for feedback —
e.g. confirm a delete, then toastsStore.add('info', 'Deleted', …).
Usage Example
import { dialogs, toastsStore } from '@horrible/core';
const name = await dialogs.prompt({ title: 'New workspace', confirmLabel: 'Create' });
if (name?.trim()) {
await createWorkspace(name.trim());
toastsStore.add('success', 'Workspace created', `“${name.trim()}” is ready.`);
}
const ok = await dialogs.confirm({
title: 'Delete file',
message: "This can't be undone.",
confirmLabel: 'Delete',
danger: true,
});
if (ok) await remove();
What belongs in each entry
apps/web: boot the shell, resolve the backend origin (desktop: ask the shell'sbackend_statuscommand; browser: relative + proxy), register the browser capability set. Nothing feature-specific.- Boot is async: after registering built-in modules, the entry awaits
loadPlugins()(installed marketplace plugins, see plugin-sdk.md) before the first render, so restored layouts find plugin panels/widgets already registered. If the backend is down, boot proceeds without plugins. apps/desktop: the Electron main process — window chrome, global shortcuts, browser views, pop-out windows, updates, the backend supervisor. It stays a thin shell; app logic belongs in the backend orpackages/.