Skip to main content

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.

History, and why it is a workbench
  • 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 in 68cec8e9): 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, the LayoutController seam), persistence.ts (autosave and hydration), and serialize.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 native TitleBar, and install.ts, which installs the engine from the shell.

  • One workbench. The layout is stored as the desktop workspace row. The backend still models a list of workspaces — it predates this — and rows other than desktop (and its desktop-v3-backup) are left alone: nothing loads them and nothing deletes them.

  • A pane never places itself. Modules open panes through registry.openPanel, revealSection and revealRegionView; 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 board backdrop.

    Single-instance-ness is the singleton flag 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 with embedded: 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_PANE and a drop work the same everywhere. findAreaAnywhere / findPaneAnywhere resolve an id to its group and host (AreaHost: centre, a dock side, or a pop-out).
  • center — a split tree. A SplitNode lays children side by side (row) or stacked (column) with fractional sizes; normalize keeps 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 }. size is 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 its activeSection (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:

SurfaceEffect
pane.open:<id> commandnot synthesized (registry.ts)
the Start menufiltered
list_available_panesno 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 by PaneHost above the body.
  • A synthesized section.show:<host>:<section> command per section, plus a host-scoped keybinding for any declared key. 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.
  • activeSectionOf resolves 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 under SectionDecl.group headings with vector icons named by SectionDecl.glyph — for a pane with more sections than a top strip holds.
  • sectionsKeepAlive: true keeps a section mounted after its first visit, hiding it rather than unmounting it. Because a hidden section's verbs stay bound, the keymap has a paneSection context key; a single-key binding into such a pane names its section as well as the pane.
  • SectionScopeContext lets a host answer usePaneSection() 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 in RENAMED_VIEWS may 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:

StateWhenWhat it shows
prompta dialogs.prompt() is pendingthe prompt inline — label, prefilled input, OK/Cancel
inputalt+x (M-x)slash-command entry with live completions
statusidleworkspace › 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:

  1. An explicit target, when the caller gave one (PlaceTarget: a group, the centre, a dock, a split beside a group, or a pop-out).
  2. Where that view was last left — a dock side or the centre (layout/pane-placement.ts).
  3. 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 LayoutController seam (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, and showTarget.

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:

  1. Already open — a pane with that instanceId exists → focus it. This is why the instanceId must be derived from the thing's identity (notebook.editor:<path>), not left to the #n counter: without it, opening the same notebook twice yields two panes.
  2. Reusable pane open — a pane of the same view that isn't dirty (setPaneDirty / isPaneDirty) and that the caller's canReuse accepts → retargetPane into 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".
  3. 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) — because paneSeq lives on FrameState, 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 scrollTop can 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. lastSavedRevision advances 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 a keepalive PUT — a normal fetch started during unload is cancelled with the document, which made the 600ms debounce a window in which every edit was lost. sendBeacon is the obvious tool and the wrong one: it can only POST.
  • A boot that cannot read the layout never overwrites it. hydrate retries the read (boot races the backend: the desktop shell spawns it alongside the UI, pnpm dev restarts 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.

A command the shell does not know is refused at runtime

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 in 9738e4f5.
  • 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.ts and drop.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 behind arrange_panes.
  • reducer.ts: the action set. layout/store.ts delegates to it; maximizing and presenting re-render without bumping revision.
  • migrate.ts and serialize.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 a PaneSlot positioned 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 with visibility.
  • Drags are local until pointer-up. A divider drag lays live sizes over the frame and commits one SET_SPLIT_SIZES or SET_DOCK_SIZE; a tab drag commits one MOVE_PANE or REORDER_TAB. A drop on a group's tab strip always joins its tabs; elsewhere resolveDrop picks 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:

  • ResizeObserver does 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.
  • window and document mean the main window. Use usePaneWindow() for listeners, viewport sizes and portal targets (win.document.body), and focusedDocument() for the active element.
  • instanceof fails across windows. el instanceof HTMLElement is false for a pop-out's element; check nodeType instead.
  • Drag listeners on window get pointermove/pointerup from the pop-out through forwardPointerEvents, 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.