Skip to main content

Regions

Regions are toggleable, resizable strips inside a pane — Blender's N/T-panel idea applied to every view. They replaced panel groups: instead of a hand-rolled mini-dock rendered inside one pane (the old PaneGroupShell), regions are engine-native and persisted — part of the pane's state in the layout store, saved with the layout, restored exactly as left.

Concept​

A view declares the region views it hosts in its manifest (regions on a PanelDecl/WidgetDecl):

{
id: 'editor.buffer',
role: 'document',
regions: [
{ id: 'code.outline', label: 'Outline', icon: '≡', key: 'o', position: 'right' },
{ id: 'code.search', label: 'Symbol Search', icon: '⌕', key: 's', position: 'right' },
{ id: 'git.provenance', label: 'Provenance', icon: '⎇', key: 'g', position: 'right' },
{ id: 'editor.recentNotes', label: 'Recent notes', icon: '🗒', key: 'r', position: 'left' },
],
}
  • Each position (left/right/bottom) is one strip; multiple views at the same position stack as tabs within it — one visible at a time, at the strip's full extent. The right-hand strip used to be a special case that showed every view at once; see One view at a time below.
  • A region view is any registered panel/widget id — cross-module is fine (the editor hosts views from the code and git modules).
  • Region state is per pane instance: every editor buffer keeps its own strip sizes, open flags, and active views, persisted with the layout.
  • A strip can also collapse to a thin rail (Blender's tucked toolbar) without forgetting its contents.
┌─────────────────────────────────────────────────────────────┐
│ ✎ ▾ main.py │ notes.md ◧ ◨ ⬓ ☰ │ ← area header
├──────────┬──────────────────────────┬───────────────────────┤
│ Recent │ │ ≡ Outline ⌕ Search ⎇ │ ← right strip tabs
│ notes │ editor.buffer ├───────────────────────┤
│ (left │ (the pane) │ active region view │
│ strip) │ │ │
└──────────┴──────────────────────────┴───────────────────────┘

A put-away region leaves a rail​

A region is drawn in one of three ways, from regionDisplay(pane, position):

statedrawn as
the view declares nothing at that positionnothing
closed (open: false) or collapseda thin rail of icons
open and not collapsedthe full strip

Closed and collapsed look the same on purpose. A closed region used to render null, and regionsFor opens a strip only where some view declares defaultOpen — which most do not. The training notebook declares six (Metrics, Architecture, Rollout, Manim, Peers, Projects) and none of them sets it, so all six started closed and the pane showed no sign that any of them existed. They were reachable from the command palette and from a keychord, and from nowhere on screen, which from the user's side is indistinguishable from a feature that was never built.

So: putting a strip away never removes the way back. Each icon in the rail is its own button that opens that view — not "whichever was active last", which is a coin flip once a pane stacks five of them, and the icons are the only thing telling you the pane has a metrics chart at all.

That also collapsed two header controls into one. The chevron and the ✕ now produce the same visible result, so only the chevron remains. toggleRegion(id, position, false) still exists for the agent and for games' drawer — it now lands on a rail instead of on nothing.

One view at a time​

The right-hand strip used to render every view at once, stacked vertically, while left and bottom were tabbed. On training.notebook, which declares five, that meant Metrics, Architecture, Rollout, Manim and Peers each received a fifth of a 300px column — about 60px — and none of them could draw anything legible.

Stacking also silently cost the two properties the tabbed branch has: RegionState.activeView meant nothing (so a rail button could not open a particular view, only the whole stack), and there was no draggable header — which is the real answer to wanting two companions at once. Drag a strip's header into the centre and it opens as a full pane of its own, while the strip stays where it is.

So there is now one renderer for all three positions:

  • Tabs when the position holds more than one view, with the label on the active tab only — five icon+label tabs are about 375px, which overflows the header into a horizontal scroller you have to discover before you can reach the last one. An inactive tab is its icon, with the label in title/aria-label.
  • A plain title when it holds exactly one.
  • defaultSize on any decl at that position sets the strip's width; the engine's fallback is 300px, and training.notebook declares 420 because a loss curve and a dagre graph are both wider than that.

A strip's PaneHost also inherits its host's params. A companion is about the document it rides on, and without this every strip beside the training notebook was blind to which project it sat next to — two notebooks open side by side overwrote each other's charts.

One consequence worth knowing: regionAt resolves the instance's state or the view's declaration. regions is written onto a pane when it is opened, so a region added to a view later is absent from every pane already in a saved layout; reading the instance alone made those panes permanently railless.

Keyboard model​

Two layers, both synthesized by the registry (no per-module boilerplate) and scoped to the host view's focus:

  1. Universal position keys — t toggles the left strip, n the right, b the bottom (Blender muscle memory), identical across every view. Reserved: a declared key of t/n/b is dropped with a warning.
  2. Declared pick letters — each region view's key reveals that view in its strip (pressing it again while it's the visible one closes the strip). E.g. in an editor buffer: o Outline, s Symbol Search, g Provenance.

Programmatic reveals​

revealRegionView(viewId) / toggleRegionView(viewId) (core/layout/controller.ts) replace the old reveal/toggle companion buses: they find the host view, open a host pane if none exists (focusing an existing instance for non-singleton hosts like editor.buffer), and flip the strip — plain store actions, no mounted-shell handshake or buffering. The Game Board still pops automatically when a match goes live (game-ws.ts revealBoard).

The agent drives the same thing with toggle_region / set_region_view; the REPL with dash.layout.toggle_region() / set_region_view().

Built-in region hosts​

Host viewRegions (key)
editor.buffer (document)right: Outline o, Symbol Search s, Provenance g; left: Recent notes r
ide.workbench (document)left: Explorer e, Search f, Source Control v, Outline o, Provenance g; right: Agent a; bottom: Terminal j, Problems m
games.lobby (document)right: Agent Harness h, Ladder l, Challenges c; bottom: Game Board v
training.notebook (document)right: Metrics m, Architecture a, Rollout u, Manim, Peers; left: Projects p
notebook.editor (document)left: Notebooks k
flow.editor (document)left: Flows f
network.peers (tool)bottom: Peer Chat, Peer Monitor, Lobby, Agent Relay
commons.directory (widget)right: Requests, Profile
observability.io (tool)bottom: Inspector

A view being someone's region view doesn't stop it opening standalone (e.g. the Agent Harness also opens as a pane of its own; the Game Board is also a document).

The two notebook hosts above are different documents on different kernels, and they are titled apart to say so: notebook.editor is Notebook Editor (the domain-neutral .ipynb editor) and training.notebook is Training Notebook (a project's own notebook, on that project's venv). Both were called "Notebook" once, which made two identical Open: Notebook palette rows and an ambiguous show target — registry.register now warns on a duplicate pane title.

Where a region host may live​

A window — every pane is in one, and keeps the strips it declares. That is worth stating because it was not always true: a window used to render a bare PaneHost, so a region host in a window silently dropped every strip it had, with nothing to say a companion view had gone missing.

That fix carries a constraint for anything that hosts PaneWithRegions:

A region host has to establish a flex context. PaneWithRegions's root (.frame-pane-regions) sizes itself with flex: 1 and declares no height of its own, so a parent that is not display: flex leaves it collapsed to its content's natural height.

The bare PaneHost it replaced got away with any parent, because .frame-pane-host sets height: 100%. The tiling frame's areas and docks were already flex containers; .os-window-body was not, and the result was a floating window drawn as a titlebar with nothing under it — measured at 44px of pane header where there should have been 648px, with the pane's canvas at zero.

It is worth knowing how that hid, because the shape recurs: floating windows were the desktop layout's ordinary way of showing a pane, while the browser layout of the time put panes in areas and docks. So the browser build looked completely healthy while every pane in the desktop build was empty. region-host-is-flex.test.ts pins the rule — today for the workbench's .wb-pane box — and also asserts its own premises, that the pane box still renders regions and that .frame-pane-regions still has no height, so it fails loudly rather than passing vacuously if either changes.

Compared to panel groups​

The old system kept companion state in unmounted React state (lost on reload), used three separate open/close mechanisms (reveal bus, toggle bus, bracket-key handler), and re-implemented tabs/resize/collapse inside a dockview pane. Regions delete all of that: one store, one controller, persisted, and the strips render through the same PaneHost as everything else (each region view gets a synthetic instance id ${hostInstance}:${position}:${viewId}, so e.g. per-buffer outlines keep distinct agent-context keys).