Skip to main content

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:

  • home was a second landing screen competing with the desktop for the same job. It survives as the splash backdrop — same avatar, greeting and ask bar, now under the workbench. shell.home still 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.verb ids, 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​

KeyAction
t / n / btoggle 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+arrowsfocus the nearest group in that direction (docks included)
alt+grave / alt+shift+gravenext / previous group
mod+shift+arrowsmove the focused tab into a new group on that side
mod+alt+upmaximize / restore the focused group
mod+alt+[ / mod+alt+] / mod+alt+jshow / hide the left, right, bottom dock
mod+kspotlight — ask, run a command, or jump to a pane (a focused pane may shadow it — the terminal binds it to terminal.clear)
alt+xminibuffer / M-x — slash commands (override, never shadowable)
mod+k mod+sKeyboard 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:

CapabilityBrowserDesktop (Electron)
fs.nativeDialogsno (backend workspace roots only)yes (native open/save dialogs)
shell.revealInOSnoyes
notifications.systemWeb Notifications (tab-scoped)OS notifications
window.multino (no pop-out control)yes (a tab group pops out to its own OS window)
window.fullscreenyes (DOM Fullscreen API; tray control, no F11)yes (native OS-window fullscreen; F11 or the titlebar control)
chrome.workspaceTabsno (the page is already in a window)yes (undecorated window; the app draws the titlebar)
shortcuts.globalnoyes (global: true bindings registered with the OS)
traynoyes
media.displayCaptureyesyes (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 declare popout: true can 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.toggleFullscreen takes 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 the WindowControl seam where there is one, and the DOM Fullscreen API where there is not. The key is native-only — keymap/reserved.ts declares f11 browser-owned with preventable: 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) and TitleBar.tsx is its titlebar: a data-app-drag-region strip (-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 to localhost:8000 over a keep-alive agent. Without one, http-proxy sends Connection: close and relays it back, so every API call opened a new TCP connection to the dev server — and on Windows a new connection to localhost costs ~250ms, because the IPv6 attempt is refused before IPv4 is tried (Vite listens on 127.0.0.1). Start the backend yourself (scripts/dev-backend.ps1 or uv 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 :8000 if there is one (dev-backend.ps1 coexistence; it must answer GET /api/health as horrible-dashboard, so a stranger holding the port is skipped rather than adopted), otherwise picks a port (8000 preferred, ephemeral fallback) and spawns uvicorn bound to 127.0.0.1 — via the repo's .venv python when present, else uv run — with MinGW dirs stripped from the child PATH (the no OPENSSL_Applink crash). It restarts the process with backoff if it dies (3 fast failures → failed with 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, and backend/parent_watch.py shuts it down on that pipe's EOF (opted into with HORRIBLE_EXIT_WITH_PARENT=1, which it consumes so its own children do not inherit it). The frontend polls the backend_status command 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 logs renderer 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 in packages/core/src/toasts.ts (exported as toastsStore and type Toast from @horrible/core). Operates as a simple pub/sub store with React useSyncExternalStore support:
    • toastsStore.add(type, title, message, duration?) — triggers a new notification. Default duration is 4 seconds (4000ms); set to 0 or negative to keep it persistent until closed.
    • toastsStore.remove(id) — clears a notification by its unique ID.
  • Component (Toasts) — lives in packages/ui/src/Toasts.tsx (rendered in the global AppShell layout overlay). Uses glassmorphism styling (backdrop-filter: blur(12px)) and cubic-bezier transition slide animations defined in packages/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);

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: true renders the confirm button red for destructive actions (delete).
  • Component (Dialogs) — packages/ui/src/Dialogs.tsx, mounted in AppShell beside <Toasts />. Renders the active dialog centered over a dimmed backdrop; Enter submits, Escape and backdrop-click cancel, the field auto-focuses. Styles (.dialog-*) live in packages/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's backend_status command; 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 or packages/.