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.
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
desktopworkspace row. Other rows the backend may still hold are neither loaded nor deleted. - No mode. The
desktop.defaultMode,desktop.workspacesanddesktop.bootWorkspacesettings are gone; a stale value in the settings store is simply never read. So isframe.windowPlacement. - Saved layouts carry over. Tiling-era and floating-era blobs migrate in order — see windowing.mdx.
- SDK v3.
defaultDock,defaultDockSize,dockable,DockSideandModuleManifest.framesare gone; a plugin built against v2 is skipped by the loader until it is rebuilt. The workbench'sdockandpopoutpane 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.
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.
| id | What it is |
|---|---|
none | Flat --bg. |
aurora | Three blurred CSS gradients drifting on a long keyframe, built from theme tokens. |
grid | Canvas: a drifting grid with a scanline sweep. Pairs with hud. |
image | A wallpaper the user uploaded. params: { url, fit, dim }. |
splash | The 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. |
pulse | Canvas: one ripple per request through this node, read from the same telemetryStore the observability panel uses. |
board | Widgets 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.
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.
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
readThemeTokensand the effect resubscribes onuseThemeId. 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.requestAnimationFramedoes not fire in a hidden window at all, so a loop driving its own clock off frame deltas resumes with a multi-minute jump.dtis clamped and the clock resets on resume. - The backing store follows
devicePixelRatio, viasetTransformrather thanscale— this runs on every resize andscalecompounds.
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
.htmlinto a directory it also serves. - The id is 32 hex characters, pattern-enforced at the route boundary, and
_resolvere-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
urlis 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—apiUrlprepends the origin only, and getting that wrong fails silently, because abackground-imagethat 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 (
focusPaneindock/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
requestPaneAttentionreturnsfalseand 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
falseon 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:
| Button | Shown when |
|---|---|
| Fullscreen / Leave fullscreen | the active view declares fullscreen: true |
| Pop out into its own window | window.multi and the view declares popout: true |
| Dock back into the workbench | the group is a pop-out |
| Hide the dock | the group is a dock |
| Maximize / Restore | not a pop-out (the OS maximizes those) |
| Close | a 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, andAll documentationopens the docs home. The page is found by module id (registry.viewOwnerId) inui/desktop/help-links.ts; a module with no page gets no per-pane item rather than a guessed URL, andhelp-links.test.tschecks every listed page exists indocs/. - 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:
| Route | Fix |
|---|---|
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 titlebar | A 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 edge | Resizing 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%).
| Layout | Who zooms |
|---|---|
| Browser | The browser. Its page zoom already owns those keys, so the app binds nothing — a binding would preventDefault a working feature away. |
| Desktop | core/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.tsscales 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
preventDefaultand keeps its gesture. The listener is in the bubble phase onwindowfor 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:
| Layer | z-index |
|---|---|
| backdrop | 0 |
| shell views | 1 |
| workbench | 30 (groups, dividers and panes are offsets inside this band) |
| status bar | 40 |
| start menu | 45 |
| clock panel | 45 |
| presented pane | 48 |
| spotlight | 50 |
| toasts | 9999 |
| dialogs | 10000 |
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.