Windowing: the docked workbench
There is one workbench, IDE-style. Panes live in tab groups: a centre split
tree of groups, three edge docks (left, right, bottom), and on the
desktop shell, groups popped out into OS windows of their own. Inside a pane,
region strips (the successor of panel groups — see
panel-groups.mdx) run down its own sides. That is the whole
model. The surface around it — the backdrop, the status bar, boot — belongs to
desktop-shell.mdx; this page covers the data panes live in and
the verbs that change it.
- Until 2026-10 a desktop could be floating or tiling (a Blender-style
centre grid with tool docks, rails and a dozen
frames:presets). Tiling was removed: two paradigms meant a lossy convert between them, a mode menu, and every feature built twice. - 2026-10 to 2026-11 the app was floating-only: every pane in a free window with snapping, minimize and a taskbar.
- Since 2026-11 (frame schema v4) it is this workbench. The floating desktop was replaced, not kept as a mode, for the same one-paradigm reason, because of four problems that came from free windows themselves: window geometry bugs (pixel rects, viewport rescaling, snap and restore state), overlap the user had to manage by hand, drag/resize/maximize jank, and the native browser view drawing over windows stacked above it. A workbench has no rects to get wrong and nothing in the main window overlaps a pane. The escape hatches are maximizing a group, presenting a pane, and popping a group out.
Saved layouts from every earlier era load — see Persistence.
Decisions
-
Custom engine, no dockview. A pure data layer plus a handful of React components. Modules never import the engine — the module registry stays the public API. dockview was tried once (
8fe54e01, dropped in68cec8e9): panes had to re-implement their companions inside it, which is why regions and sections exist, and it would take the layout tree away from the pure reducer that autosave, migrations, share and the DOM-free tests depend on. -
Two layers.
packages/core/src/layout/is the React-free source of truth:dock/(the v4 model, tree ops, reducer, geometry, drop targets, migration and schema — see The engine),model.ts(pure tab and pane ops),store.ts(one reducer store),controller.ts(opening, placement, group verbs, regions, pop-out, theLayoutControllerseam),persistence.ts(autosave and hydration), andserialize.ts/legacy-frame.ts, which now only read older blobs — all unit-tested (pnpm --filter @horrible/core test).packages/ui/src/workbench/renders the groups, docks and pop-outs;packages/ui/src/desktop/the backdrops and the status bar;packages/ui/src/layout/what a pane draws inside itself (PaneHost,Region,SectionTabs), the nativeTitleBar, andinstall.ts, which installs the engine from the shell. -
One workbench. The layout is stored as the
desktopworkspace row. The backend still models a list of workspaces — it predates this — and rows other thandesktop(and itsdesktop-v3-backup) are left alone: nothing loads them and nothing deletes them. -
A pane never places itself. Modules open panes through
registry.openPanel,revealSectionandrevealRegionView; where the pane lands is the controller's decision (Where a pane opens), and no module reads layout geometry. -
Roles describe a pane, and give it a default home. Every view declares
role: 'document' | 'tool' | 'widget'. A document opens in the centre, a tool or widget in a dock, until the user moves it somewhere else. The role is also how a view describes itself to the agent (list_available_panes) and to anything that groups panes:- a document is a surface you work in — one per subject, several open at once, and it benefits from tabs;
- a tool is a companion to whatever you are working on — narrow, singleton, always the same thing;
- a widget is a readout — glanceable, sized to a tile, and the thing you
would put on the
boardbackdrop.
Single-instance-ness is the
singletonflag on a panel (widgets always are), not the role. -
A narrow companion is a region strip. Most of the obvious candidates (
editor.recentNotes,observability.logs,training.metrics) already are regions of their host pane. A view that has become purely a companion says so withembedded: true. See Embedded views and sections.
Model
The types are DockFrame and friends in packages/core/src/layout/dock/types.ts;
FrameState is an alias for DockFrame.
- AreaNode — a tab group, the one node type for every place a pane can be. The
centre's leaves, each dock and each pop-out hold one, so
SET_ACTIVE_TAB,REORDER_TAB,INSERT_PANEand a drop work the same everywhere.findAreaAnywhere/findPaneAnywhereresolve an id to its group and host (AreaHost: centre, a dock side, or a pop-out). - center — a split tree. A
SplitNodelayschildrenside by side (row) or stacked (column) with fractionalsizes;normalizekeeps every split at two or more children and the tree never empty — with nothing open it is one empty area, which shows the backdrop (Home). - docks —
left,right,bottom, each{ visible, size, area }.sizeis pixels and is clamped to the surface when drawn. There is no top dock: the title bar is there. A hidden dock keeps its panes open. - popouts — groups in their own OS window (desktop only), with the bounds the shell last reported. See Pop-out windows.
- No stored rects. Pixel geometry is derived from the frame and the measured
surface every time (
dock/geometry.ts), so a layout cannot hold a rect that lands off-screen, and resizing the app changes no stored state. - maximizedAreaId and presentedInstanceId — a group drawn over the whole workbench, and a pane drawn over the whole shell. Neither is serialized: they are ways of looking, not layout, and restoring into a chrome-less presented pane is a state the user would have to guess their way out of.
- focusedInstanceId and focusedAreaId — both, because an empty centre group can hold focus (it is where the next document opens) and has no instance.
- PaneState — one live pane instance (
${viewId}#${n}); carries its params, its persisted per-instance region strips, and itsactiveSection(see Embedded views and sections). - paneSeq — one monotonic counter for pane instances, groups, splits and pop-outs, never reset, so a dispatcher holding a snapshot can precompute the ids an action will mint.
Embedded views and sections
Two declarations exist to make one pane hold what used to be several, without either half of the merge going wrong: the retired surface must stop being a destination, and it must not stop being reachable.
embedded: true (on PanelDecl / WidgetDecl) says a view exists only inside
another pane. It stays fully registered — regions and sections keep working — but it
drops out of every affordance that would present it as a competing home:
| Surface | Effect |
|---|---|
pane.open:<id> command | not synthesized (registry.ts) |
| the Start menu | filtered |
list_available_panes | no top-level row — listed under its host instead |
The last row is the one that matters for the agent, and it is why show learned to
resolve an embedded view to where it lives: show("Outline") reveals it in its
host's region strip or section rather than failing to open it standalone. An
embedded view that nothing hosts is a declaration error, and fails loudly
(ok: false, and openPane returns null with a warning) rather than quietly opening
a pane the flag said shouldn't exist.
openPane / registry.openPanel make the same resolution: opening an embedded id
reveals it in its host's strip or section (hostOfEmbedded) instead of opening it
bare as a pane of its own. A button labelled "Radar" and the agent's show("Radar")
must land in the same place — and the pane consolidation turned many former panes
(hAssault's companions, karaoke's queue, arXiv, the Python reference) into embedded
views, so every existing openPanel('<old id>') keeps working unchanged.
sections?: SectionDecl[] are in-pane tabs — the sibling of a region strip. A
region is a companion beside the main content; a section replaces it. Each
section declares an id, a label (what show("friends") matches), an optional
pick key, and its body as either an inline component or the view id of a
registered (usually embedded) view.
The host owns everything a module used to hand-roll:
PaneState.activeSection, persisted per instance — the module singletons this replaces (games'hub-section, the client drawer) forgot the user's choice on every reload, and two panes of one view shared one value.SectionTabs(packages/ui), rendered byPaneHostabove the body.- A synthesized
section.show:<host>:<section>command per section, plus a host-scoped keybinding for any declaredkey. Regions and sections share one per-host letter space — they share a keyboard scope, so a duplicate letter is dropped with a warning rather than left to resolve arbitrarily. activeSectionOfresolves rather than reads: a stored section id can outlive the declaration that named it (a saved layout loads against today's code), so it falls back to the default instead of rendering a strip with nothing selected.
A module picks its style: a section with its own component/view is rendered by
the host, and one with neither falls through to the host's own component, which
switches internally via usePaneSection(). Both exist because a pane being merged
usually already switches internally, and a new one usually doesn't want to.
Three options extend this, all introduced by the interpretability suite:
sectionsLayout: 'rail'draws the sections as a vertical rail down the left edge (SectionRail), grouped underSectionDecl.groupheadings with vector icons named bySectionDecl.glyph— for a pane with more sections than a top strip holds.sectionsKeepAlive: truekeeps a section mounted after its first visit, hiding it rather than unmounting it. Because a hidden section's verbs stay bound, the keymap has apaneSectioncontext key; a single-key binding into such a pane names its section as well as the pane.SectionScopeContextlets a host answerusePaneSection()for a body one level down, so a pane that switched its own sections can become a section of another pane unchanged, its own tabs now a sub-strip. A rename inRENAMED_VIEWSmay name a section ({ to, section }), so a merged pane's saved layout reopens on the right tab.
The agent-context rule. Unlike a region strip — which gets a synthetic instance
id (${host}:${position}:${viewId}) that neither listPanes nor visiblePanes
descends into — a section body renders inside its host's PaneInstanceContext, so
its provider registers under the real, enumerable pane instance id. Providers
are therefore keyed by instance and section: PaneHost supplies the section
id through SectionInstanceContext around a body it renders itself, and
useAgentContext takes it from there (a pane that switches sections internally
passes it explicitly instead — its own registration is pane-level, and stamping the
host with the active section would put it and its inner bodies back on one key).
Keying on the instance alone was a silent-overwrite bug: whichever provider mounted last won, its unmount restored nothing, and the workaround was a standing rule that a pane may have only one. Now a pane-level snapshot and the mounted section's merge, section last, and reads are pinned to the active section so a provider that outlives its switch cannot answer for the tab that replaced it.
The active section and the list of siblings are stamped onto every snapshot
centrally by readPaneAgentContext, not left to each module — a merged pane's
snapshot is ambiguous without the first, and a module that forgot would produce a
plausible-looking snapshot the agent then reasons about wrongly. The sibling list is
there because many sections still have no provider at all (only the mounted body
can provide): a bare {section} gave the model nothing to answer from, and a pane
that returns nothing does not produce "I don't know" — it produces a confident
answer sourced from whatever else was in the context window. hasPayload: false
now names that case explicitly.
Contributed sections. Sections are declared by the pane that owns them, which is
right when the tabs are the pane's own — and wrong for Explorer,
whose entire purpose is to be the one place you go to find something, wherever it
lives. A view opts in with explorerHost: true, and any module (or plugin) adds a
tab through ModuleManifest.explorerSources. ExplorerSourceDecl is a
SectionDecl, so nothing downstream is a second mechanism.
Shell indicators. Some state must stay on screen when no pane shows it — the
canonical case is share's "your screen
is being broadcast". A module declares ModuleManifest.shellIndicators
({id, component}), and packages/ui/src/layout/ShellIndicators.tsx renders every one
in the status bar's Tray and, on the native shell, in the TitleBar too. The module
decides visibility: each component renders null when it has nothing to say, and the
slot is display: contents, so an empty one adds no gap. Keep them rare; the tray's
own rule applies — a strip that grows one icon per module is a strip nobody reads.
The merge happens in the registry.panels / registry.widgets getters — at read
time, not registration — so module order cannot matter; the host may register
before or after its contributors. Merged decls are memoized against a registration
counter, because those getters run on every render path and a fresh object per call
would defeat useSyncExternalStore snapshots and every memo keyed on the decl.
The minibuffer
Emacs's minibuffer and echo area. State and command matching live in
core/src/minibuffer.ts (pure, unit-tested); the strip is
packages/ui/src/layout/Minibuffer.tsx. Three states, in priority order:
| State | When | What it shows |
|---|---|---|
| prompt | a dialogs.prompt() is pending | the prompt inline — label, prefilled input, OK/Cancel |
| input | alt+x (M-x) | slash-command entry with live completions |
| status | idle | workspace › focused pane, plus the echo area |
Slash commands resolve against the same registry.commands the palette uses,
so nothing is registered twice. A command opts into a short name with
slash: 'save' (runs as /save); the leading slash is optional, so /save and
save are the same query. Anything without a slash stays reachable by fuzzy
title/id search. Ranking is exact-slash → slash-prefix → exact verb → verb-prefix
→ id substring → title substring, ties broken by registration order — which is
what makes first-registered-wins the rule for two commands claiming one slash
name. Current names: /save, /save-as, /save-all, /new, /find.
Prompts render here, not in a modal. dialogs.prompt() already existed and is
what editor Save As calls, so serving it in the minibuffer gave "save as, right
here" with no new API and every existing caller for free. <Dialogs />
deliberately skips kind === 'prompt' — rendering it in both places would show
two competing inputs for one pending promise. confirm/choice stay modal: a
destructive Save / Don't Save / Cancel should interrupt, not be a line you can
ignore.
The alt+x binding is declared override: true so a focused editor pane can't
shadow it — the minibuffer is the escape hatch and has to be reachable anywhere.
The shell mounts it as <Minibuffer variant="overlay" />, which floats above the
status bar and renders nothing in the status state, because the status bar's
mx zone is the status line. (It once wasn't mounted on the floating desktop at all:
alt+x flipped a store nothing rendered, and every prompt waited forever on an
answer the user was never shown.) See
desktop-shell.mdx.
Where a pane opens
placeFor(viewId, explicit?) in the controller decides, in order:
- An explicit target, when the caller gave one (
PlaceTarget: a group, the centre, a dock, a split beside a group, or a pop-out). - Where that view was last left — a dock side or the centre
(
layout/pane-placement.ts). - Its role. A document opens in the focused centre group; a tool or widget in
the dock its declaration names (
PanelDecl.dock), else the right dock.
The memory cannot live in the layout blob: a closed pane is not in the frame to
remember anything with, and "reopen the terminal where I put it" is precisely a
question asked after it was closed. So it rides the settings store under
frame.panePlacement, globally and keyed by view id. Keying by pane instance
would be useless: instance ids are minted per open, so the key could never be
looked up again. It records a side, not a rect. (The floating desktop kept a rect
and snap zone under frame.windowPlacement; that setting is no longer read.)
Recording is a store subscriber, not a hook in the reducer or the drag handler. A pane changes place by a tab drag, a split command, an agent verb or a dock-back, and remembering from each means the next one silently does not; reading the result catches them all by construction.
Only a move is recorded. A pane appearing for the first time (an open, a load,
a v3 migration) was placed by these same rules, so recording it would only re-file
the default. The one exception is a move into a pop-out: there the place the
pane is leaving is recorded, because Dock back asks placeFor where to put it
and the answer has to be where it came from. Without that, a terminal that arrived
in the bottom dock from a saved layout, and was never dragged, came back on the
right.
View types vs pane instances work as before: widgets are singleton-by-view-id,
panels honor their singleton flag, and multi-instance panes get #n suffixes.
A caller-supplied instanceId (e.g. editor.buffer:<source>) focuses the
existing instance instead of duplicating.
Tabs and groups
Every group has a tab strip (GroupHeader.tsx). Dragging a tab onto another
group's strip joins that group; dropping it on a group's body splits beside it on
the side under the pointer (resolveDrop in dock/drop.ts). Both commit one
MOVE_PANE on pointer-up. mod+shift+<arrow> moves the focused tab into a new
group on that side; tearOffPane (the window.tearOff command, Split into its
own group) does the same to the right, and from a dock it moves the tab to the
centre. Middle-click closes a tab, guarded, so a dirty buffer can still prompt.
Nothing is left framing nothing: an emptied centre group is removed (unless it is
the last), an emptied dock hides, and an emptied pop-out closes.
REORDER_TAB carries activeTab by identity, not by index. Every naive reorder
bug is the same one: the user drags a background tab past the active one and the
group silently switches to a different pane. Rearranging the strip must not change
what is on screen.
Maximize (mod+alt+up, the header button, a double-click on the strip) draws
one group over the whole workbench; the others stay mounted underneath.
Presenting a pane (area.fullscreen) goes further, over the status bar and
title bar — see desktop-shell.mdx.
Opening a pane that is already open
openPane(viewId, {params}) on a pane that is already open applies the params,
then focuses it. It used to focus and return, dropping them.
The failure was invisible and inverted: a deep link — "compare these six runs", "score this checkpoint", "show me the turn behind this eval case" — worked only while its target pane happened to be closed, and did nothing when it was open. Open is the normal state for a pane you are working in. Nothing threw and nothing warned; the pane came to the front showing what it showed before, which reads as the button being broken.
RETARGET_PANE cannot serve here — it refuses instanceId === newInstanceId by
design, and a singleton's instance id is its view id, so there is no new identity
to move to. Hence SET_PANE_PARAMS, applied where openPane focuses an existing
pane.
Params are applied only when supplied. A plain "open the LocalTrack pane" from
the palette passes none and must not wipe a selection a deep link (or the user)
established — absent means "no opinion", not "clear it". Pinned by
controller.test.ts.
The controller: one set of verbs, three callers
All mutations are dispatches into the layout store, exposed two ways from
core/layout/controller.ts:
- the
LayoutControllerseam (registry.setLayoutController) for the engine-agnostic basics (close, focus, list, tear off,changePaneType), and - plain controller exports for everything else —
openPane,openDocument,retargetPane,placeFor, the group verbs (movePaneTo,splitFocused,tearOffPane,toggleDock,arrangePanes,toggleMaximizedGroup,focusGroup,cycleGroups,focusDirection,activateTaskbarEntry), the pop-out verbs (canPopOut,popOutPane,dockPopoutBack),presentPane, the region verbs (toggleRegion,setRegionView,revealRegionView),setPaneSection,revealSection, andshowTarget.
openPane(viewId, opts) opens a view, or focuses it. Identity: a
caller-supplied instanceId is focus-or-create; a singleton (every widget, and any
panel that says so) is found by view id, so a second open focuses the first rather
than adding a twin; anything else opens a fresh pane each time — a second terminal
is a second shell. A new pane opens where placeFor says
(Where a pane opens).
showTarget(target) is the intent verb sitting above all of them: it takes loose
text (a pane title, a view id, a section label, a region label), resolves it with
layout/show.ts (pure, unit-tested), then open-or-focuses, switches to the named
section or reveals the region — returning the resulting pane's agent-context
snapshot. It exists so the agent can reach a surface in one call instead of
list_available_panes → open_pane → get_pane_context; see
agent-tools. VIEW_ALIASES beside it keeps
retired pane names resolving forever, which is deliberately a different lifetime from
serialize.ts's RENAMED_VIEWS (that one repairs saved layouts; this one preserves
the agent's vocabulary).
retargetPane(instanceId, newInstanceId, params) is the reuse counterpart to
openPane: it re-points an already-open pane at a new identity in place, keeping its
group, tab position, viewId, and region strips, and refuses when the new id is
already taken (the caller then falls back to a normal focus-or-create open). It
exists so a caller that knows a pane holds nothing worth preserving can land in it
rather than accumulate placeholders — the editor uses it so opening a note from a
blank, unmodified buffer reuses that editor instead of opening a second one. See
editor.
openDocument(viewId, instanceId, params, canReuse?) packages that rule as the
one way a module opens "a thing" (a notebook, a project, a URL) in a
non-singleton document pane. It resolves in three steps:
- Already open — a pane with that
instanceIdexists → focus it. This is why theinstanceIdmust be derived from the thing's identity (notebook.editor:<path>), not left to the#ncounter: without it, opening the same notebook twice yields two panes. - Reusable pane open — a pane of the same view that isn't dirty
(
setPaneDirty/isPaneDirty) and that the caller'scanReuseaccepts →retargetPaneinto it, so the group, tab position and region strips survive. Only the module can judge reuse, so the predicate is its call; a module whose panes autosave (notebook, training notebook, browser) passes() => true, meaning "any clean pane of mine". - Otherwise — a normal
openPane.
Omitting canReuse opts out of step 2 and gives identity-only behavior. A pane
that genuinely wants one instance per invocation (a terminal) uses neither and
calls openPanel directly.
Such an opener should also pass a title param naming the thing it opened.
A view's declared title names a kind of pane, so without it every open notebook
is a tab reading "Notebook Editor". paneDisplayTitle(pane)
(layout/controller.ts) is the one rule — title → name → path → the view's
declared title — and the group's tabs, a pop-out's OS title and the status bar's
open-panes zone all resolve
through it, so a pane is never labelled two different ways at once.
The user's gestures, the keybinding commands, and the agent's layout
tools (show, place_pane, pane_state, arrange_panes, toggle_region,
get_layout, … relayed through tool-exec.ts) all converge on these same functions —
one code path, and every mutation rides the store's autosave. Layout verbs stay
ungated. See agent-tools.mdx.
Pane lifetime: unmount is not close
Only a group's active tab renders, so a pane unmounts constantly, for reasons
that have nothing to do with the user closing anything. A React cleanup cannot tell
those apart, and the panes that owned something expensive assumed the destructive
reading: TerminalPane killed its PTY on unmount, and the browser released the last
reference to the shared Chromium engine. Looking at another tab for four seconds
destroyed your shell — and handed back a fresh one that looked identical, which is
why it read as "state was lost" rather than as a bug.
layout/pane-lifetime.ts is where that distinction lives. A resource created
through paneSession survives every unmount and is disposed only on a real close:
closePaneGuarded and changePaneType (the outgoing view's resource). Nothing is
timer-based. The pattern is
not new — notebook and training kernels are already process-global for exactly this
reason ("closing a pane leaves the kernel running; reopening reattaches") — this
generalizes it to the frontend.
Two details are load-bearing:
- Keys are scoped by workspace row —
(workspaceId, instanceId)— becausepaneSeqlives onFrameState, so instance ids are unique only within a frame. There is one desktop now, but the key still says which layout a resource belongs to. - The terminal keeps its DOM element, not just its session. Moving the xterm host between mounts preserves the rendered scrollback exactly; rebuilding the terminal around a surviving PTY would not.
Moving or covering a pane must not unmount it either. Moving a tab to another
group, splitting, maximizing, hiding a dock and popping out all leave the pane
mounted (see The workbench UI). A covered pane is hidden with
visibility, never display: none and never by rendering different JSX: an early
return with a different tree makes React reconcile the body to a different position
and rebuild the subtree, which is exactly this failure with a new trigger.
display:none is also wrong here for a second reason — it collapses a canvas or an
xterm to zero size, and many of them never recover their measurement when shown
again.
If a close path is ever missed the resource leaks until the page closes, where the
backend reaps it anyway (PTYs die with their /ws connection). That is deliberately
the failure we chose: strictly better than killing a live shell on every tab switch.
View state: the cheap half
Beside the resources sits paneUiBag — the same keys, a separate map, and the same
close/move/reset paths, holding what a pane was looking at: scroll offset, caret
position, which markdown cell was open for editing. Nobody loses work when one of
these is dropped, which is why they are not sessions. But a notebook that jumps back
to the top and an editor whose caret resets to zero every time you glance at another
tab are indistinguishable, to the person using them, from having lost their place —
and the fix is small enough that it should not be reinvented per pane.
use-pane-ui-state.ts is the React side: usePaneUiState(key, initial) is shaped
like useState so there is no way to update a value and forget to remember it, and
usePaneScroll() returns a ref for a scroll container. Two details are easy to get
backwards:
- Restore in an effect, not on state init. The element has no scrollable content until its children have laid out; an earlier write is clamped to 0 and the pane still jumps to the top.
- Save on scroll, not in a cleanup. A tab switch tears the subtree down, and a
cleanup that reads
scrollTopcan find the element already detached — where it reads 0, which is exactly the value that looks like success.
A second, separate cache lives in BufferView for the same reason, keyed by source
URI rather than by pane: reopening a file anywhere should land where you left it,
not only in the pane you left it in. It records caret and scroll on view.destroy(),
before the teardown detaches scrollDOM, and restores only when no
code locus claimed the buffer first — a locus is someone asking for a line, and
restoring over it would silently undo a go-to-definition.
None of this is written to the layout blob. serialize.ts carries what the user
arranged; a scroll offset is where they happened to be looking, and persisting it
would dirty the layout — and drive the 600ms autosave — on every wheel tick.
Persistence
The store holds { workspaceId, frame } as one atom; the debounced (~600ms)
autosave reads both from the same snapshot at fire time, so it can never write a
layout under the wrong id — this retired the old engine's race-guard refs.
Losing an edit: the four ways, and why none of them are open
A layout edit is invisible until it is written, and a pane that is still on screen looks saved whether or not it is. Every one of these presented as "refreshing reset my desktop", so each is closed deliberately rather than by luck:
- A save that fails is retried.
lastSavedRevisionadvances only after the PUT resolves. It used to advance before, so a failed write — the backend restarting under--reload, a dropped connection — left the store believing it was clean and no retry was ever attempted. The frame is a full snapshot, so the retry needs no record of what was lost: one later success carries every edit since. - Saves never overlap. Each serializes the frame before awaiting, so a slow save of revision 5 landing after a fast save of revision 6 would write the older layout last. They are strictly sequential, and a request arriving mid-flight waits rather than skipping (skipping would report an unsent edit as saved).
- The last edit before a refresh is flushed.
pagehide/ tab-hidden writes the pending frame with akeepalivePUT — a normalfetchstarted during unload is cancelled with the document, which made the 600ms debounce a window in which every edit was lost.sendBeaconis the obvious tool and the wrong one: it can only POST. - A boot that cannot read the layout never overwrites it.
hydrateretries the read (boot races the backend: the desktop shell spawns it alongside the UI,pnpm devrestarts it on every save), and on real failure the store stays un-hydrated — which is what keeps autosave switched off, so the blank frame on screen can never be written over the layout still safely on disk. The shell then says so and offers a reload, because an empty desktop with no message is indistinguishable from one that was erased.
Layouts serialize as a versioned envelope
{ schema: 'horrible.frame', version: 4, frame } to PUT /api/workspaces/desktop;
the backend (backend/modules/workspace/) stores each layout opaquely.
deserializeDock (dock/serialize.ts) validates defensively, prunes panes whose
views no longer exist (e.g. an uninstalled plugin), renames views that were merged
away (RENAMED_VIEWS), and returns null for anything that isn't a frame blob — a
pre-frame legacy layout is discarded by design and the workbench starts empty.
An older blob loads by running the migrations in order: v1 and v2 to floating
windows (legacy-frame.ts and serialize.ts, below), then windows to the
workbench.
v3 → v4 replaced the floating desktop (dock/migrate.ts). No pane is closed:
- documents become tabs in the centre; a window snapped to the left or right (half, third or quarter) was a deliberate side-by-side, so it seeds a column;
- tools and widgets go to the dock the view asks for, else the one the window's shape and position suggest (wide and short was a bottom panel);
- minimized windows become background tabs, and a dock that held only minimized windows starts hidden.
Geometry cannot survive — a workbench has no free rects — so what is kept is the intent the geometry expressed.
Before the first v4 write the untouched v3 blob is copied to a
desktop-v3-backup workspace row (persistence.ts). It is the only rollback: an
older build rejects a newer schema version, so a v3 build reading the v4 row would
start empty.
A loaded layout can name pop-outs the build cannot open — the browser build, or a
desktop build without window.multi. Their groups are docked back on load rather
than dropped.
v2 → v3 removed the tiling frame. A v2 blob still carries center (the split
tree) and docks, and on a floating desktop those held panes too — the grid was
retained, just not drawn. legacy-frame.ts turns them into windows rather than
dropping them:
- a tiling desktop's grid becomes one window per non-empty area, at the pixel rect that area occupied, so the first load after the upgrade looks like the last one before it; a visible dock's active tool becomes a window at the dock's geometry, and every other docked tool a minimized window — mounted, one click away, not on screen, which is what a tool behind a rail glyph was;
- a floating desktop's grid and docks were never on screen, and the taskbar already called those panes minimized, so they stay minimized.
The migrated windows stack beneath the ones the blob already had, ids are minted past
everything in it, and nothing is clamped there: on a v1 blob the basis is the unit
square, where the pixel helpers in snap.ts would produce nonsense.
SET_WINDOW_VIEWPORT clamps every rect once it knows the real size.
v1 → v2 was the desktop shell's own migration. floating[] became windows[],
and the old fractional rects are carried over by setting windowViewport to
{w:1,h:1} so they scale into pixels through the ordinary rescale path rather
than through migration-only arithmetic that only ever runs once and is therefore
never exercised again. A v1 blob takes both steps in one load.
The backdrop is the one thing that deliberately does not come back as it was: a
v1 desktop had no backdrop, because there was no surface one could show on. Choosing
none would look conservative and would in fact hand every upgrading user a blank
landing screen for a feature they never turned off, so a migrated desktop gets
DEFAULT_BACKDROP.
The version guard rejects a blob whose version is higher than this build's, so an older build reading a newer blob starts empty — downgrading discards the layout rather than corrupting it. That is the intended trade, and the reason the v3 backup row exists.
Browser vs desktop
The engine is web-only and shared verbatim by the browser and the desktop shell
(no per-platform fork). The workbench and pane presentation are in-window; the
native shell claims the OS-level versions through capabilities, all via the
WindowControl seam: window.multi — pop-out OS windows
(Pop-out windows); window.fullscreen — on desktop F11
(shell.toggleFullscreen) toggles native OS-window fullscreen, orthogonal to
presenting a pane in-window (area.fullscreen); and chrome.workspaceTabs — the
desktop window is undecorated and the app draws its titlebar (TitleBar.tsx: drag,
double-click maximize, min/maximize/close controls, and edge-resize grips for the
borderless frame). The capability keeps the name of the workspace tab strip that
used to be that titlebar. (window.perWorkspace — a workspace in its own OS window —
went with the workspaces.) See the capability table in
layout-shell.mdx.
External links. The app page never opens windows of its own, pop-outs aside
(about:blank with a horrible-popout: frame name, and nothing else) — the shell
refuses every other window.open and target="_blank" and
sends http(s) ones to the system browser — and it exposes an open_external
command (apps/desktop/src/window.ts, http/https only) that hands a URL to the
user's default browser via shell.openExternal. The shared helper
openExternal(url) (packages/core/src/external.ts) branches on the runtime:
browser layout → window.open, desktop → the command. The desktop boot also
installs a document-level external-link bridge (installExternalLinkBridge,
capture-phase click handler) so every plain <a href="https://…"> in the app
routes to the system browser without per-component work. OAuth flows (games
sign-in, connectors) call openExternal directly — the system browser carries the
user's existing sessions, and Google refuses OAuth inside embedded webviews
(RFC 8252). Distinct from browser_open_url, which deliberately opens an
app-owned browser window as the embedded browser's un-iframable-site escape hatch.
The shell answers only the names in its COMMANDS table (apps/desktop/src/main.ts);
anything else rejects — no build error, no type error, and nothing in the UI unless
the caller checks. Under the Tauri shell the same failure had a second cause (an ACL
permission missing beside the registration), and open_external shipped that way:
openExternal caught the rejection and returned false, the link bridge discarded
that false, and OAuth sign-in and every external link in the desktop app silently
did nothing. scripts/desktop-smoke.mjs now drives the commands in the packaged app.
See Onboarding.
Both mechanisms fail quietly, so openExternal returns whether it actually
opened and callers that need the user to arrive somewhere must check it. The
bridge reports failure through onExternalOpenFailed, which AppShell turns into
a persistent toast carrying the URL — necessary because the bridge cancels the
browser's own navigation before substituting its own, so a failed substitute means
the click is simply gone.
Dev affordance
In dev builds the shell exposes window.__horribleFrame = { store, registry, exec } — exec(name, args) runs any relayed layout tool exactly as the agent
would (await __horribleFrame.exec('get_layout', {})). Not set in production.
Status
Implemented: the docked workbench (centre split tree, three edge docks, tab drag
and drop, maximize, presentation), pop-out windows on desktop, engine-native
persisted regions and sections, remembered pane placement, the minibuffer, the
versioned serialization schema with its migrations from v1, from the tiling frame
and from the floating desktop, the agent layout tools, and the native shell's
capabilities (window.multi, window.fullscreen, chrome.workspaceTabs). Not yet:
region view cycling on repeat-press, and dragging a tab into or out of a pop-out.
The engine
packages/core/src/layout/dock/:
tree.ts: the centre split tree, revived from the tiling frame removed in9738e4f5.frame.ts: verbs that address a pane or group wherever it lives (centre, dock or pop-out). Closing a pop-out docks its panes back; it never closes them.geometry.tsanddrop.ts: pixel layout and drop targets, derived from the frame and the surface size every time, so no rect is stored and none can land off-screen.arrange.ts: the centre presets behindarrange_panes.reducer.ts: the action set.layout/store.tsdelegates to it; maximizing and presenting re-render without bumpingrevision.migrate.tsandserialize.ts: frame schema v4 and the step from v3 — see Persistence.
The workbench UI
packages/ui/src/workbench/. Workbench.tsx measures the surface, lays it out
with computeWorkbench, and draws three layers: the groups' tab strips
(GroupHeader.tsx), the dividers, and the panes. Four rules there are
load-bearing:
- Panes render into host elements, not into their boxes. Each mounted pane is
portaled into its own host
div(pane-hosts.tsx), and aPaneSlotpositioned over the pane's group appends that host. Moving a tab to another group, splitting, maximizing, presenting, hiding a dock or popping out moves one DOM node; it never remounts the pane, so an iframe keeps its page and a terminal its shell. The portals render in first-seen order, never layout order, because React moves a keyed node to match a new order and a moved iframe reloads. - Nothing is hidden with
display: none. A group behind a maximized one, or a hidden dock, keeps its pane mounted at its last size and hides it withvisibility. - Drags are local until pointer-up. A divider drag lays live sizes over the
frame and commits one
SET_SPLIT_SIZESorSET_DOCK_SIZE; a tab drag commits oneMOVE_PANEorREORDER_TAB. A drop on a group's tab strip always joins its tabs; elsewhereresolveDroppicks a split side or the group's tabs.
The desktop backdrop shows through an empty centre, so Home is what an empty workbench looks like.
Keys: alt+grave / alt+shift+grave cycle groups, alt+arrow moves focus by
geometry (docks included), mod+alt+up maximizes the focused group,
mod+shift+arrow moves the focused tab into a new group on that side, and
mod+alt+[, mod+alt+] and mod+alt+j show or hide the left, right and bottom
docks. The pane region keys t, n and b are unchanged.
The agent's verbs are place_pane (centre, a dock, a split beside a group, or
into a group), pane_state (maximize/restore, hide/show a dock, present) and
arrange_panes (columns, rows, grid, tabs, even, rebuilding the centre
tree through ARRANGE_CENTER and leaving docks alone). The floating desktop's
open_window, window_state and arrange_windows are still answered in
tool-exec.ts, mapped onto these, and cost no schema.
The native browser view yields its OS surface by asking the layout
(isPaneShowing) rather than hit-testing its region on a poll: in the workbench
nothing overlaps a pane except overlays that already claim
suppressNativeOverlays(), and a tab drag now claims it too. Its bounds follow a
ResizeObserver plus a layout-store subscription instead of a per-frame sampler.
Pop-out windows
On the desktop shell (window.multi), a tab group can leave the main window for an
OS window of its own: the Pop out button in its header, popOutPane(instanceId)
from code. Closing that window, or its Dock back button, returns each pane to
the slot placeFor picks, which is where it was popped out from (see
Where a pane opens). It never closes the panes. A build without window.multi
that loads a layout with pop-outs docks them back on load.
A view opts in with popout: true on its PanelDecl or WidgetDecl; a view
without it shows no button. Today that is the terminal, the editor buffer and the
browser view. Opting in means the view was checked for the things below.
One realm, not a second app. The page opens
window.open('', 'horrible-popout:<id>') and React portals the group into that
blank document. Every store, the backend socket and the AudioContext stay in the
main page; the backend never learns a pop-out exists. apps/desktop/src/popouts.ts
allows exactly that URL and frame-name prefix, clamps the window to a display's
work area, copies the main window's zoom, and reports moves and closes on the
popout event channel. The zoom is copied again once the child's about:blank
has loaded: that commit replaces any earlier zoom with Chromium's saved per-host
zoom for about:blank, which lives in the profile, so a copy made only at
did-create-window left the pop-out at 1.0 beside a main window at 1.1. The pop-out document has no horribleDesktop bridge.
Panes move; they do not remount. Every pane renders into its own host element
(pane-hosts.tsx), and a PaneSlot appends that element wherever the pane is
shown now. Popping out moves one DOM node into the child document, so a shell,
an editor's undo history and an iframe's state carry over.
What a popped-out view must not assume, and what the shell does about it:
ResizeObserverdoes not cross windows. One built in the main page never fires for an element in a pop-out.installCrossWindowObservers()replaces the global at boot with a router that observes each element through its own window's observer;rehomeObservers()re-routes after a move.windowanddocumentmean the main window. UseusePaneWindow()for listeners, viewport sizes and portal targets (win.document.body), andfocusedDocument()for the active element.instanceoffails across windows.el instanceof HTMLElementis false for a pop-out's element; checknodeTypeinstead.- Drag listeners on
windowgetpointermove/pointerupfrom the pop-out throughforwardPointerEvents, so a splitter mid-drag still sees its release.
Keymaps listen in every pop-out. Context menus open in the window they were requested from. Toasts, dialogs and Spotlight stay in the main window. A tab cannot yet be dragged into or out of a pop-out.
The native browser view moves its WebContentsView to the pop-out's
BrowserWindow with attach_browser_webview.