Skip to main content

The desktop shell

You arrive at a desktop: a backdrop (by default the home screen), the docked workbench over it, and a status bar along the bottom with the Start menu, the open panes, the tray and the agent. An empty workbench shows the backdrop through its centre, so Home is what an empty workbench looks like.

This page covers that surface: backdrops, the status bar, boot and first run, Spotlight, the group chrome, presenting and fullscreen. The data panes live in — groups, docks, pop-outs — is FrameState, documented in windowing.mdx.

Status

All of it has landed: the backdrop providers, the status bar and Start menu, the boot splash and first-run flow, Spotlight, the themes, the wallpaper routes, the workbench chrome, and the agent verbs.

There is one shell view​

ShellView = 'boot' | 'oobe' | 'desktop'

home — the avatar and ask bar — was once a second landing screen competing with the desktop for the same job; it survives as the splash backdrop, which is strictly more useful, because the workbench sits over it. Nothing in the shell "navigates".

Installing the engine is the shell's job, not any one component's. The controller the agent tools drive, the debounced autosave, the frame module's commands and hydration all live in packages/ui/src/layout/install.ts and run from the shell. They used to sit in the tiling frame's mount effect, which was survivable 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 — no layout agent tools, no region or backdrop commands, no hydrated layout. Every one of those failures is silent.

One desktop, one paradigm​

Until 2026-10 a desktop could be floating or tiling — a Blender-style centre grid with tool docks, activity rails and a workspace tab strip — and there could be many of them: a dozen pre-arranged frames: presets (AI Research, Training, Lab…) plus any the user made. Tiling was removed rather than hidden. Two paradigms meant a lossy convert between them, a mode menu to choose, a setting for which kind a new desktop was, and every feature built twice.

For a month after that every pane was a free-floating window with snapping, minimize and a taskbar. In 2026-11 that was replaced in turn by the docked workbench, for reasons that came from free windows themselves — see the history at the top of windowing.mdx. The floating layer was deleted, not kept as a mode, for the same one-paradigm reason.

What that leaves:

  • One desktop, stored as the desktop workspace row. Other rows the backend may still hold are neither loaded nor deleted.
  • No mode. The desktop.defaultMode, desktop.workspaces and desktop.bootWorkspace settings are gone; a stale value in the settings store is simply never read. So is frame.windowPlacement.
  • Saved layouts carry over. Tiling-era and floating-era blobs migrate in order — see windowing.mdx.
  • SDK v3. defaultDock, defaultDockSize, dockable, DockSide and ModuleManifest.frames are gone; a plugin built against v2 is skipped by the loader until it is rebuilt. The workbench's dock and popout pane fields are optional additions.

What boots​

hydrate() loads the desktop row, creating it on a clean install with an empty frame on DEFAULT_BACKDROP — the home surface (see the default must be an interactive backdrop). It retries the read, because boot races the backend; on real failure the store stays un-hydrated so nothing can autosave a blank screen over the layout on disk.

The titlebar has to be grabbable

Under chrome.workspaceTabs the native window is undecorated and TitleBar.tsx is its titlebar: a slim frame-tabs--bare strip carrying data-app-drag-region (-webkit-app-region: drag) and the min/max/close cluster. (The capability is named for the workspace tab strip that used to be that titlebar.) In the browser it renders nothing.

The drag region must be given the strip's full height explicitly (.frame-tabs--bare .frame-tabs-scroll { align-self: stretch }). The strip centres its window controls, which overrides align-items: stretch, and the drag region's only content is nothing at all — so it measured full width and zero height, leaving a 28px titlebar with no grabbable pixel anywhere. Nothing looks wrong when this breaks: the attribute is present and correct on an element with no area to hit.

Backdrops​

A backdrop is a registered provider (BackdropDecl, contributed through ModuleManifest.backdrops and exported from the SDK), not a settings string — a wallpaper, a procedural animation, a live node-state view and a full dashboard are the same kind of thing to the desktop, and a plugin should be able to add one.

idWhat it is
noneFlat --bg.
auroraThree blurred CSS gradients drifting on a long keyframe, built from theme tokens.
gridCanvas: a drifting grid with a scanline sweep. Pairs with hud.
imageA wallpaper the user uploaded. params: { url, fit, dim }.
splashThe default. The home screen — avatar, ask bar, connector tiles — under the workbench, and a wallpaper of its own behind. Collapses to a docked ask bar over that wallpaper; see below.
pulseCanvas: one ripple per request through this node, read from the same telemetryStore the observability panel uses.
boardWidgets laid straight onto the desktop.

Nothing here bundles third-party imagery: the drawn ones are arithmetic, the live ones render the node's own state, and image shows what the user supplied. Same rule as the maps and the search engines.

A provider declares interactive when it wants pointer events (splash, board). A decorative one stays pointer-events: none and a transparent catcher over it collects the clicks, so the desktop's right-click menu works across the whole surface. That catcher is skipped entirely for an interactive backdrop, which would otherwise be sealed behind it.

The default must be an interactive backdrop​

DEFAULT_BACKDROP (packages/core/src/layout/types.ts) is splash, and that is a product decision rather than a cosmetic one. HomeView — the avatar, ask bar, connector tiles and first-run SetupCard — is rendered by exactly one thing in the app, the splash backdrop. While the default was aurora, a clean install opened on a wallpaper and a taskbar, and the whole tier-1 entry surface (the one PRODUCT.md says must work for someone who never opens a terminal) was unreachable unless the user happened to pick "Home" out of a list of seven wallpapers.

packages/core/src/__tests__/front-door.test.ts enforces this: the default must be a backdrop declared interactive, and that backdrop must still mount HomeView. It is the reachability invariant the panes already have, applied to a surface.

An unregistered backdrop id falls back rather than blanking the desktop. A plugin can be uninstalled while a saved workspace still names its backdrop; losing a wallpaper is not a reason to lose the panes on top of it.

The switch commands (desktop.backdrop:<id>) are synthesized by the registry, one per registered provider, exactly as the pane openers are — so a plugin's backdrop gets its command without a second list that can fall out of step.

The home screen minimizes​

splash was the one surface in the app with no way to get it out of the way. It is a backdrop, so it has no title bar to hang a control on and no status-bar button to restore it from, and it is interactive, so it takes pointer events across the whole desktop. The only escape was knowing that the desktop's right-click menu can swap the backdrop entirely — which is also the wrong verb: swapping throws the ask bar away in order to hide the greeting.

So it collapses instead, to a strip at the bottom holding the ask bar and nothing else. Everything the collapse drops is landing screen — a greeting and an avatar are worth seeing when you arrive and worth nothing when you are working over the top of them — and the ask bar is the reason to keep the surface at all.

The flag lives in the backdrop's own params ({ collapsed: true }), so it is per-desktop and persisted with the rest of the layout: a desktop you work in stays collapsed and one you land on stays open, with no global setting for the two to disagree about. setHomeCollapsed merges into the existing params rather than replacing them, because setBackdrop takes a whole BackdropRef.

Three ways in, because a control nobody finds is a control that does not exist: a Minimize button on the home column itself, desktop.toggleHome in the command palette, and an entry in the desktop's right-click menu — which appears only on a desktop actually showing the home screen, since an item that silently switched you to the home screen in order to collapse it would be a trap.

The palette also carries desktop.hideHome and desktop.showHome, the two directions named. A toggle is the wrong shape for the palette and for the agent: both act without seeing the screen, so "toggle" means "put it in whichever state it is not in", and running one twice leaves the home screen hidden. The toggle stays for the keyboard and the menu, where the current state is visible.

The home screen carries its own wallpaper​

Collapsing had nowhere to collapse to. A desktop has exactly one backdrop slot and splash is in it, so minimizing the home screen revealed a flat theme-coloured void — the wallpaper that would have been there is precisely what splash displaced. The desktop the collapse is supposed to land on did not exist.

So the home surface paints a second, decorative backdrop behind itself: resolveHomeUnderlay (packages/core/src/layout/home-surface.ts) reads params.under, defaulting to aurora — the id that was DEFAULT_BACKDROP before the home screen took the slot, so a desktop still looks like the one people know. Collapsing now lands on a genuine desktop: wallpaper, status bar, and the ask bar docked at the bottom.

The underlay is painted in both states, not swapped in on collapse. The landing screen has always been translucent over whatever is behind it, and a wallpaper that appeared only once you minimized would read as a rendering glitch rather than as the same desktop seen from closer up. A scrim between the two keeps the front door legible over an arbitrary wallpaper — including a photograph the user supplied — so "pick a wallpaper" and "read the home screen" are not a trade-off. It is scoped to the expanded form only; veiling the whole desktop for a single docked control would defeat having collapsed at all.

params.under sits beside params.collapsed in the same bag, which is why both writers go through one merging patchHome: either written as a replacement silently discards the other. The picker is the desktop menu's Wallpaper behind home, listed after Backdrop so the two read in order — what this desktop is, then what it looks like underneath.

The underlay may never be interactive

Two ids are refused, and both fail badly rather than visibly. splash under splash mounts HomeView inside HomeView forever — the symptom is a hung tab, not a wrong wallpaper. Any other interactive backdrop (board) puts two surfaces that both want the pointer in one square of screen with the lower one unreachable, which reads as the widgets having stopped working. resolveHomeUnderlay enforces it at render time and homeUnderlayMenuItems filters the menu, so the picker never offers what the renderer would refuse. An unregistered id falls back to the default the way the main slot does.

The transition​

Collapsing and expanding swap one form of HomeView for the other, so the motion is an entrance on whichever form arrived rather than a cross-fade: the outgoing DOM is gone by the time React commits, and keeping both mounted to animate an exit would mean two live agent request states — a question asked in the strip would be lost on expand. The landing screen lifts away to the wallpaper; the strip rises from the status bar. Under prefers-reduced-motion both keep the fade and drop the travel. Nothing animates the wallpaper itself: it is present in both states, and flashing it would make one desktop look like two.

The collapsed surface must stop eating clicks

splash is registered interactive, so its layer takes pointer events over the entire desktop. That is right when the home screen fills it and completely wrong when it is a strip: the desktop underneath would stop responding while looking like it should. .os-backdrop-splash[data-collapsed] is pointer-events: none and only the strip and its answer panel take clicks back.

Canvas backdrops​

backdrops/canvas.ts gathers the three things a canvas backdrop always has to get right, so a new one cannot forget one:

  • Theme tokens are read through readThemeTokens and the effect resubscribes on useThemeId. A canvas cannot use a CSS variable, so it resolves colours once — and this is a repeat bug in this codebase, so the hook makes it structural.
  • The loop stops on visibilitychange. requestAnimationFrame does not fire in a hidden window at all, so a loop driving its own clock off frame deltas resumes with a multi-minute jump. dt is clamped and the clock resets on resume.
  • The backing store follows devicePixelRatio, via setTransform rather than scale — this runs on every resize and scale compounds.

pulse adds one of its own: events are upserted by (source, id) (the backend re-emits one to fill in a streamed body), so "new" has to mean a key never seen, not "the array got longer". Ripples are placed by hashing the endpoint, so the same target always pulses in the same spot and the backdrop reads as a map of what this node talks to rather than as noise.

Wallpapers​

The one piece of the desktop that needs the server, because it is a file: backend/modules/desktop/ serves GET/POST /api/desktop/wallpapers and GET/DELETE /api/desktop/wallpapers/{id} out of $HORRIBLE_DATA_DIR/wallpapers/ (via backend.paths, never an inline os.environ.get).

Four rules there are load-bearing:

  • The stored extension comes from the content-type table, never the uploaded filename. Trusting the client's extension is how an upload route starts writing .html into a directory it also serves.
  • The id is 32 hex characters, pattern-enforced at the route boundary, and _resolve re-checks that the resolved path is inside the wallpaper directory. The pattern is the guard; the check is the assertion that the guard held. A .. here is how a read route becomes an arbitrary-file-read.
  • Uploads land via .part + rename, so a truncated image is never listed.
  • The stored url is api-relative (/desktop/wallpapers/<id>). The backend origin differs between the dev server, a packaged desktop build and a LAN-bound node, so an absolute URL baked into a saved workspace stops resolving the moment any of that changes. The frontend prepends /api — apiUrl prepends the origin only, and getting that wrong fails silently, because a background-image that 404s simply paints nothing and the desktop looks like the wallpaper was never set.

The status bar​

The strip along the bottom. It was the floating desktop's taskbar, which is why the code still says Taskbar, the setting desktop.taskbar and the theme tokens --taskbar-*; renaming any of those would drop users' saved configs and themes.

layout/taskbar.ts derives the pane buttons, pure over FrameState + the registry — the status bar has no opinion of its own about what is open. The strip itself is a zone container driven by the desktop.taskbar setting (start, windows, mx, tray, clock, agent, spacer); a stored config is merged over the defaults so a config written by an older build does not silently lose a zone the user never removed, and an unknown zone name is skipped rather than rendered as an error strip.

Right-click the strip to customize it (the taskbar context-menu kind): which zones show, top or bottom, labels, auto-hide, and a reset. The config was always a setting; what it had no way of being was edited, short of typing JSON into the settings page — which is not something anyone discovers about their own taskbar. The menu writes that same setting through the same merge, so it and a hand-written value cannot mean different things. Zones are toggles rather than a reorderable list (a menu is a poor reordering surface), and a zone switched back on is spliced in at its canonical position — zoneRank, i.e. ZONES' own key order — rather than appended past the clock. Reset the taskbar is the escape hatch that makes hiding everything safe: a bare strip still right-clicks, so there is no way to customize yourself out of reach of it.

A stored zones array is otherwise taken whole — it is an explicit choice, and quietly adding to it would defeat the point of being able to hide a zone. That leaves one problem, and ZONES_VERSION/ZONE_SINCE is the answer to it: a zone introduced after the stored config was written is inserted, and a zone the user actually removed is not. Without the version the two are indistinguishable, and someone who customized their taskbar once would never receive another zone again. Bump the version and add the entry in the same change that adds the zone.

The default zones are start, windows, spacer, mx, tray, clock, agent.

agent is last, past the clock. agent.chat is the pane you reach for constantly, and without a button of its own it was available only through the palette or the Start menu. The button toggles rather than reopening: an already-open chat goes through activateTaskbarEntry, the same verb a pane button runs, so a second click hides its dock. Calling openPanel unconditionally would look like nothing happened.

Pane buttons are a fixed width (--taskbar-btn-w, 168px), not shrink-wrapped around their label. Width used to track the text, so the strip was a ragged run of boxes whose click targets moved whenever a pane retitled itself — an editor button resizing as you switched buffers. Shrink is still allowed, so a crowded strip tightens before it starts scrolling, but nothing grows to fit its text; the label ellipsises inside the fixed box, and with labels off (is-iconic) the button collapses to a square rather than leaving most of a text-width box empty.

The strip must scroll, which is why the pane buttons run useHorizontalWheel, so a plain vertical wheel moves them sideways. They are overflow-x: auto with the scrollbar hidden, so before that the overflow was reachable only by trackpad or shift+wheel — on a mouse, the later buttons simply did not exist. The hook also stamps data-overflowing when it measures real overflow, which is what the edge fade keys off; fading unconditionally dims the first button of a strip that fits, and reads as a rendering fault.

The mx zone, and where the minibuffer went​

The minibuffer used to be the tiling frame's bottom row, so on the floating desktop it was not merely hidden but absent: alt+x flipped a store that nothing rendered, and — the part that was actually broken — every dialogs.prompt() waited forever on an answer the user was never shown, since the minibuffer is what serves prompts inline.

So the shell mounts it as <Minibuffer variant="overlay" />, floating just above the status bar and rendering nothing when idle. Idle is the whole difference: a permanent strip stacked over the status bar is a second status bar saying much the same thing. The status bar's mx zone carries the idle half instead — the M-x button and the echo area — which is also the answer to "where is M-x?": a keystroke with no visible presence is one nobody finds, the same argument the tray's fullscreen button already makes.

Two decisions in the derivation matter:

A button is per pane instance, not per group. A group of three tabs is three things the user can switch to, and one button for it would make two of them unreachable from here.

The order is stable — by the numeric suffix of the instance id, i.e. by the order panes were opened. Nothing about focus, moving a tab or hiding a dock may reorder it, because a strip that reshuffles on focus moves the button out from under a pointer already travelling toward it. (Comparing the ids as plain strings would put #10 before #2, so panes would visibly reshuffle the tenth time you opened one.)

Clicking runs one verb, activateTaskbarEntry: clicking the focused pane when it is in a dock hides that dock — the toggle every IDE panel button has — and clicking anything else brings it forward and focuses it, showing its dock or switching its group's tab as needed. Double-clicking a docked pane always hides its dock, whatever the first click did. A button's state is focused, open, minimized (in a hidden dock) or hidden (a background tab, or behind a maximized group).

Attention: a pane that finished while you were elsewhere​

Panes keep working out of sight — in a background tab or a hidden dock: a deep-research run, a training job, an ingest, a compile. requestPaneAttention(instanceId) sets PaneState.attention; the pane's status-bar button pulses and its tab shows a small accent marker until the user looks at it.

  • Cleared when the pane is focused, by any route (focusPane in dock/frame.ts): a click on its tab, its status-bar button, Spotlight, a key. Looking at the pane is what acknowledges it, and no timer clears it.
  • Refused for the focused pane. Flashing a button for the thing on screen is noise, so requestPaneAttention returns false and changes nothing.
  • A boolean, not a count. The button is a flash, not an inbox; "three things happened" is a story the pane tells once you are in it.
  • Absent rather than false on the pane, so a serialized layout never carries a stale "was flashing once" flag for every pane ever opened.
  • The accessible name becomes "<title> — finished", because a pulsing border conveys nothing to a screen reader; reduced-motion keeps the ring and drops the animation.

The start menu lists registry.panels + registry.widgets minus embedded, filtered exactly as the palette's openers are — an embedded view lives inside a host pane, and a launcher entry would present it as a second, competing home.

It is grouped into seven fixed categories (PaneCategory, labelled by PANE_CATEGORY_LABELS): AI Research, Agents, Build, Data & Knowledge, Play & Media, People, System — plus Plugins for a third-party view that declares none. A module declares category once on its manifest; a pane may override it (registry.viewCategory). start-menu-categories.test.ts fails the build on a built-in module without one, since it would otherwise land under Plugins silently.

Inside a category, a module with more than one launchable pane folds into one row (its title, a count, a chevron) that opens in place; single-pane modules list flat. This replaced grouping by owning module, which gave a heading per feature — most over a single row — and a catch-all "All panes" band that had become the longest list in the menu. Search still matches title, id, module and category, and flattens the groups.

Above the groups sits a Recent band: the last six panes opened, most recent first, from layout/recents.ts. It is recorded in registry.openPanel, so every route to a pane — launcher, command palette, spotlight, an agent tool — feeds one history. It lives in localStorage rather than settings deliberately: it is a per-device convenience, it changes on every open (a settings PUT per launch would be absurd), and GET /api/settings hands the whole bag to the browser. Ids are resolved against the live registry on read, so a renamed or uninstalled pane drops out instead of offering a dead entry. The band is absent until something has been opened — an empty "Recent" heading is a promise the launcher has not kept — and it is hidden while searching, where it would compete with the results.

The grouping used to be by PaneRole: Documents / Tools / Widgets. Sixty-odd entries in one alphabetical run did say nothing, but the role answers a question nobody browsing a launcher is asking — it describes what kind of pane something is, not what it is for. The feature a pane belongs to is what someone is actually hunting for, and it was already the axis the search box matched on: a view's title says what the pane is, the module's says what feature it is part of, and those are frequently different words — the Observability module's pane is called Data flow, so a search for the feature came back empty on a pane sitting right there under Tools. Promoting the module from a trailing suffix on each row to the heading above them makes browsing and searching agree, and drops the "Settings · Settings" repetition the suffix had to dodge. Searching still flattens the groups — three headings over four results is more structure than content.

Its footer is Settings / Setup / Theme. The bottom-left corner is where people go for settings, and the menu previously offered it only as one row of sixty, filed under S. Theme opens the tray's own taskbar.theme menu rather than a second list.

Boot and first run​

AppRoot shows the boot splash until bootReady(), then mounts the shell. That gate is not cosmetic: AppShell installs the frame engine on mount, and that hydrates the desktop — which prunes panes whose views are not registered. Mounting the shell before boot() has registered its modules and awaited loadPlugins() would not just look wrong, it would silently delete the user's layout and then save the result.

The splash narrates the real boot (bootStore), one step per thing that actually happened, with real timings. A fake progress bar that always takes 800 ms says nothing when the backend is not answering, which is exactly the moment the user most needs to be told something. Individual steps are non-fatal — a plugin that failed to load degrades the app rather than stopping it — and only a throw sets phase: 'failed'. The step list is time-gated (1.2 s), so a fast boot is a logo and a fade while a stalled one explains itself without being asked. The progress bar is deliberately indeterminate: the step count is known but their durations are not remotely comparable, so a real percentage would sit at 90% through the one step that actually takes time.

A step that can legitimately run long passes a hint to bootStep (shown under the label while it runs), and every running step shows its age in seconds once it is two seconds old — a still screen during a 45-second wait reads as a hang. The splash is mounted before anything is awaited, including the hosted hub probe; it used to mount after the hosted instance wait, which left the window black for that whole wait. apps/web/index.html carries a static copy of the splash (same os-boot classes, marked data-static-splash) for the seconds before the bundle has run; React replaces it on first render, and the boot-failure fallback treats a surviving static copy as "React never rendered".

First run (desktop.oobeComplete unset) goes through a three-step wizard — who you are, what it looks like, what it can reach — before the desktop. The third step is the existing SetupCard, not a copy of it: model / account / connectors already had one flow with a carefully argued shape (the account and the connectors are two steps on purpose — see that component), and a first-run duplicate would be a second thing to keep in step with reality. Every step is skippable, and "Skip setup" leaves the whole wizard rather than advancing one screen — a setup flow you cannot leave is one people close the app to escape.

The name the first step asks for is a setting (shell.userName), not localStorage. It used to be the latter, "a per-browser nicety" — but the greeting is a fact about the node, so a fresh browser profile, or a cleared origin, meant the wizard introduced itself to someone it had already met. As an ordinary declared setting it is also editable and resettable on the settings page afterwards, which is where a first-run answer belongs once first run is over. It is committed on leaving the step rather than per keystroke, and Finish/Skip setup await both it and desktop.oobeComplete before dismissing the wizard, warning by toast if the backend refused — firing the write and navigating away is how a failed save became a wizard that silently reappeared. (The bug underneath it was in the backend's settings bag — see the settings module.)

The wizard is a view, not a modal. It owns the screen until it is finished or skipped; a dismissible overlay over a half-configured desktop is exactly the "did I finish that?" state it exists to avoid.

Spotlight​

mod+k opens one surface that takes anything: commands, panes you already have open, and the agent. It replaced the command palette rather than sitting beside it — the agent is meant to be always available, and two overlays competing for one keystroke means the user has to decide which one they want before they can start typing.

spotlight.ts resolves the list, pure over the registry + a frame snapshot. Three things it settles:

  • Open panes rank above commands. Typing "terminal" almost always means the terminal you have, not the command that opens another one.
  • > / @ / ? restrict to commands / panes / the agent.
  • The agent is the fallback. It is offered last when other things matched, and first — alone — when nothing did. A palette that answers a typed sentence with "no matching commands" is the failure this surface exists to remove. It is not offered for an empty query, so opening the surface is not a prompt.

An ask keeps the spotlight open, unlike every other action: the answer is the point, and closing to deliver it somewhere else would mean going to find it.

The empty state is a hub, not a list. With nothing typed, Spotlight shows the AI briefing (the week's top papers and AI headlines), quick settings and notifications instead of every command in registry order, a list nobody read, since anyone who knew what they wanted typed it. The first keystroke swaps the hub for the results, so nothing reached by typing moved, and Enter and the arrows do nothing while the hub shows. The briefing.showInSpotlight setting restores the plain list. See briefing.mdx.

The workbench​

Panes live in tab groups: the centre split tree, three edge docks, and on desktop pop-out windows. The model, the verbs and the rules that keep a pane mounted are in windowing.mdx; this section covers what a group looks like and does.

A group's active tab is rendered through PaneWithRegions, so a pane keeps its region strips. That wrapper brings a constraint with it — the pane box (.wb-pane) must be display: flex, because PaneWithRegions's root carries flex: 1 and no height — and getting it wrong empties every pane (region-host-is-flex.test.ts).

The group header​

GroupHeader.tsx is the tab strip plus a cluster of stroke-icon buttons:

ButtonShown when
Fullscreen / Leave fullscreenthe active view declares fullscreen: true
Pop out into its own windowwindow.multi and the view declares popout: true
Dock back into the workbenchthe group is a pop-out
Hide the dockthe group is a dock
Maximize / Restorenot a pop-out (the OS maximizes those)
Closea pane is showing

The focused group carries a 2px accent top border. A double-click on the empty strip maximizes the group; on a tab it is just two clicks. Middle-click closes a tab, guarded.

The header's right-click menu​

The window.titlebar context menu (the kind keeps its floating-desktop name: the help items and any plugin that adds to the menu are keyed on it), contributed by the desktop module as two groups:

  • Help. Help: <pane> opens that pane's module page on the published docs, and All documentation opens the docs home. The page is found by module id (registry.viewOwnerId) in ui/desktop/help-links.ts; a module with no page gets no per-pane item rather than a guessed URL, and help-links.test.ts checks every listed page exists in docs/.
  • Group verbs. Hide the dock (in a dock), Maximize or Restore, Split into its own group (centre) or Move to the centre (dock), and Close.

A right-click on a tab is about that tab, not the active one: tabs carry data-wb-tab and the handler reads the target from the tab under the pointer.

Close​

Close runs closePaneGuarded, so a dirty pane still prompts. It is every close's path — the header button, middle-click, keybindings, the status bar and agent tools. A close has no exit animation: the floating desktop's window exit was the only one, and its hook went with it.

Motion​

A pane fades and lifts in when it opens or its tab is picked (.wb-pane-enter, 180ms). Moving, splitting, maximizing and dock toggles do not animate: they move a box, and animating a box that holds a canvas, a terminal or a browser engine every frame costs far more than it shows. All motion is off with the desktop.animations setting (mirrored onto <html data-motion> by workbench/motion.ts) and whenever the system asks for reduced motion.

Presenting and fullscreen​

Presenting a pane​

Maximizing a group fills the workbench, which is inset below the titlebar and above the status bar. Presenting goes past both: FrameState.presentedInstanceId names a pane, and its box (.wb-pane.is-presented) is drawn position: fixed; inset: 0 at z-index 48 — over the status bar and the titlebar, still under the spotlight, so mod+k reaches the user while a game fills the screen.

Four things here are load-bearing.

The pane is promoted in place, never re-rendered somewhere else. Rendering the pane into a separate full-screen layer reconciles as a different element and remounts it — killing a live PTY, socket or browser engine, the exact failure pane-lifetime exists to prevent. The pane keeps its host element and only its box's CSS changes.

The keybinding presents the focused group's showing pane (presentFocusedPane, behind the area.fullscreen command, which keeps its old id so saved keymap overrides still name it).

The reducer refuses an id that names no pane, and sanitizing the frame clears the id the moment it stops naming one. Both matter more than the focus equivalents: a stale id here is not a mis-aimed keybinding but a screen with the chrome hidden and no visible way out. Closing the pane or its group orphans it — one sweep covers both.

It is never serialized. serialize deletes the field and deserialize forces it null. It is a momentary way of looking at a pane, not a property of the workspace, and restoring a layout into a chrome-less full-screen pane is a state the user has to guess their way out of.

A view opts in with fullscreen: true (PanelDecl/WidgetDecl) — karaoke.stage, games.arcade, browser.view, visualizer.pane. (hassault.play was one until it became a launcher: the match is played in the native window, which owns its own fullscreen.) Only those get the Fullscreen button in the group header, and only those escalate to OS-window fullscreen on a native shell. Escalating every presented pane would turn an ordinary "show me this bigger" into something that swallows the display; and the escalation remembers whether the app was already fullscreen, so leaving a presented game does not drop an app the user had fullscreened themselves back into a window.

Escape unwinds it through the existing ladder — installKeymap's exitFullscreen calls presentPane(null).

App-window fullscreen​

Distinct again: this is the OS window (or, in the browser, the page), not a pane. toggleAppFullscreen in core/fullscreen.ts picks the mechanism — the windowControl seam under the desktop shell, the DOM Fullscreen API otherwise — so window.fullscreen is now granted in both layouts and the browser is no longer stuck windowed.

What the capability does not grant is the f11 binding. keymap/reserved.ts declares that key browser-owned with preventable: false, so a binding there would silently never fire; the key stays gated on the native seam, and the visible controls are what make the feature reachable in the browser: a ⛶ button in the tray (both layouts) and a fourth button at the head of the titlebar cluster under chrome.workspaceTabs. Both read live state through subscribeFullscreen, because a control that only re-reads on its own click shows the wrong icon the moment the user leaves fullscreen any other way — which is most of the ways people leave it.

On the native shell the command un-maximizes before it fullscreens, and re-applies the maximized state on the way out (enterFullscreen/leaveFullscreen in apps/desktop/src/window.ts). The app window is undecorated, and Windows clips an undecorated maximized window's client area to the monitor's work area so the taskbar stays usable. That clip survives the switch: the window frame grows to cover the whole monitor while the webview inside it stays work-area tall — which renders as a taskbar-shaped black band along the bottom of a fullscreen app, the OS taskbar hidden behind it. Dropping the maximized state first leaves Windows no work area to clip against. The previous state is remembered per window, so someone who fullscreens a maximized window does not get a small one back.

Un-maximizing on the way in is only half of it, because nothing stopped the window being maximized again once it was already fullscreen — and the band is back the moment it is. Three routes reached it, and all three are now closed:

RouteFix
The titlebar's maximize button (window_toggle_maximize)While fullscreen it leaves fullscreen instead — the same "restore" the gesture means on a maximized window, rather than a button that does nothing.
Double-clicking the titlebarA drag region is the window's caption to the OS, which maximizes on a double-click natively — it never reaches a command, so it cannot be guarded in the shell. TitleBar stops emitting data-app-drag-region while fullscreen.
Dragging an edgeResizing is native: Electron hit-tests a few pixels inside each edge of a frameless window as a resize border — and turns that border off while maximized or fullscreen. WindowResizeHandles renders nothing in fullscreen either, so the cursor never suggests the gesture. (window_start_resize_dragging is a no-op kept for the WindowControl contract: the OS takes the press before the page's grips see it.)

The frontend half is not belt-and-braces: the drag region is the one route with no shell side to guard, so the attribute has to go.

Page zoom​

Ctrl+= (or Ctrl++), Ctrl+- and Ctrl+0 zoom the whole dashboard the way a browser zooms a page, and so does Ctrl+wheel. The steps are Chromium's own (50% … 300%).

LayoutWho zooms
BrowserThe browser. Its page zoom already owns those keys, so the app binds nothing — a binding would preventDefault a working feature away.
Desktopcore/zoom.ts, through the shell's window_set_zoom (apps/desktop/src/window.ts). The shell removes the application menu — and with it Chromium's own zoom accelerators — so without this the keys did nothing. The commands are shell.zoomIn, shell.zoomOut, shell.zoomReset, registered only where the seam has setZoom.

Rules that are quiet if wrong:

  • Native zoom, not CSS zoom. Every pane — canvases, CodeMirror, pointer maths, the 3D views — sees an ordinary page at a different device-pixel ratio, exactly as under browser zoom, so none of them has to know.
  • Native browser panes are separate views placed in window pixels, while a pane measures itself in CSS pixels, which zoom makes bigger. desktopWindow.ts scales their bounds by the zoom factor on the way to the shell, and the panes' bounds tracking re-syncs them after a zoom change.
  • Pop-outs do not inherit the zoom. A child window starts at 1.0, so the shell copies the main window's factor to each pop-out when it opens and on every change.
  • Ctrl+wheel yields to anything that handled the event first: a canvas that zooms itself (the model graph) calls preventDefault and keeps its gesture. The listener is in the bubble phase on window for exactly that reason.
  • Remembered per machine (localStorage, guarded): a zoom belongs to the screen you are sitting at, not to your account. It is restored at boot.

Where it mounts​

The workbench is a sibling of the shell's views, inside .shell-content:

.shell
├── TitleBar ← native shell only: drag region + window controls
├── .shell-content (position: relative)
│ ├── Oobe first run
│ ├── .shell-view the desktop (backdrop)
│ └── Workbench ← groups, docks and panes, over the backdrop
├── Minibuffer (overlay)
└── Taskbar the status bar

Sibling rather than child because .shell-view[hidden] is display: none — panes nested inside the view would unmount (and lose their sessions) whenever the wizard showed. Inside .shell-content rather than .shell because that bounds it below the titlebar and above the status bar. Pop-out windows render through portals from the same tree, so they too stay mounted with it.

Z-index scale​

Declared once, in packages/ui/src/desktop/desktop.css:

Layerz-index
backdrop0
shell views1
workbench30 (groups, dividers and panes are offsets inside this band)
status bar40
start menu45
clock panel45
presented pane48
spotlight50
toasts9999
dialogs10000

A presented pane sits above the status bar and the titlebar — that is the point of it — but deliberately below the spotlight, so mod+k still reaches the user while a game fills the screen.

On desktop the browser pane's native child webview composites above all HTML, so any overlay that must appear over it calls suppressNativeOverlays() — the treatment the command palette already uses, and a tab drag claims it too.

A popover inside a pane must portal out​

.wb-pane has contain: strict, and layout/paint containment makes it the containing block of every position: fixed descendant, and clips them — so a fixed dropdown inside a pane is laid out relative to the pane, not the viewport, and cut off at the pane's edge, whatever z-index it carries. A panel that is meant to extend past its pane (the Agent pane's ModelPicker, the settings page's ModelCombobox, the shared ContextMenu) renders through a portal and measures its trigger with getBoundingClientRect(), which is already in viewport coordinates.

The portal target is the pane's own window's body, usePaneWindow().document.body, not the global document.body: a pane can be in a pop-out, and a popover portaled to the main window would open on the wrong screen. The same hook gives the viewport size to clamp against. See windowing.mdx.

Agent verbs​

Split across two groups, deliberately.

Arranging lives in the existing layout group: place_pane (the centre, a dock, a split beside a group, or into a group), pane_state (maximize/restore a group, hide/show a dock, present/unpresent) and arrange_panes (columns, rows, grid, tabs, even over the centre). Two panes side by side is one place_pane with a split. The floating desktop's open_window, window_state and arrange_windows are still answered, mapped onto these, and cost no schema. See agent-tools.mdx.

Appearance is its own lazily-loaded desktop group: desktop.set_backdrop, desktop.set_theme, desktop.configure_taskbar. It is not in the always-on core on purpose. Restyling the desktop is a rare request, the core was cut 34 → 11 tools for a measured reason (see agent-chat.mdx), and anything in the core is paid for on every turn by every agent — including the ones that never touch it. The group loads on demand, or when the prompt mentions a theme, wallpaper, backdrop or taskbar.

get_layout reports the center tree, the non-empty docks, any popouts, the focused and maximized group, and desktop.backdrop with the catalogs (desktop.backdrops, desktop.themes) — so the appearance verbs have ids the model cannot guess without two more always-on list_* schemas.

Every one of these refuses bad input with the valid options rather than guessing: an unknown backdrop returns the registered ids, and an unknown to, state or style returns the valid words.

Theming​

Group and status-bar chrome reads the --win-* / --taskbar-* token groups (the names are the floating desktop's, kept so existing themes still apply), so a theme restyles the shell by redefining tokens and touching no component. A group header's background is --win-titlebar-bg, and --win-titlebar-bg-active when it is the focused group, which also gets the 2px --accent top border. Control placement is not themeable: the header buttons sit at the right end of the strip in every theme.

See theming.mdx.