Context menus
One menu, assembled per right-click from whoever has something to say about the thing under the cursor.
The problem it replaces
There were four hand-rolled menus — the file tree, the activity rail, the workspace tabs, the game panel — and each one owned all three of the hard parts itself:
- Its own dismissal. Three separate
windowkeydown listeners, each closing on Escape (and one on any key), racing the shell's Escape ladder. - Its own positioning. The activity rail rendered at the raw
clientX/clientYwith no clamp at all, so a right-click near the bottom-right corner put the menu off-screen entirely. The file tree clamped against hardcoded guesses at its own size (window.innerWidth - 200,window.innerHeight - 260) — correct only while that menu had exactly the items it had the day the numbers were written. - Its own item list, baked into the component that owned the pixels. That
makes "the menu depends on what was clicked" something every component
reimplements, and it makes a cross-module action impossible: the file tree
cannot know that the notebook module would like an Open as Notebook entry on
a
.ipynb.
The model
A right-click reports a target — a kind plus that kind's payload — and the
menu is built from every provider registered for that kind.
onContextMenu={(e) => {
if (openContextMenu(e, { kind: 'files.node', path: row.path, nodeKind: row.kind })) {
e.preventDefault();
}
}}
openContextMenu returns false when no provider offered an item, and the caller
should then let the event through to the browser's own menu rather than
swallowing the gesture to show an empty box.
Providers are declared on the module manifest, next to commands and panels:
contextMenu: [{ kind: 'files.node', order: 0, items: filesNodeItems }],
or registered imperatively with addContextMenuProvider for shell chrome, which
has no manifest.
Groups, not a flat list
itemsForTarget returns one group per provider, ordered by order then
registration. Each group is drawn with a separator above it. Grouping is preserved
rather than flattened because the separator is the only cue that two items came
from different places — flattened, another module's Delete sits flush against
the owner's Open as though they belonged together.
A provider that returns [] is dropped entirely, so declining a target costs
nothing and never leaves a stray divider. A provider that throws is logged and
skipped: one module's bad provider must not take down the whole menu.
hint beside, detail below
An item can carry two kinds of secondary text and they are not interchangeable.
A hint shares the row with the label, right-aligned: a keybinding, a parent
directory, a one-word state. A detail is a sentence and is drawn on its own
line underneath.
The row can only lay out one of those well. The label column is
minmax(0, 1fr), so it is what gives way when the row is crowded — passing prose
as a hint took the whole 340px and ellipsized the label to nothing. That is
literally what happened to the theme picker: every entry showed a full sentence
about a theme and none of them showed its name, in a menu whose only job is to
let you pick one by name. Both the theme and backdrop pickers now pass their
description as detail; a hint is additionally capped at half the row.
Absent, not disabled
A virtual root in the file tree (a mounted Drive) is read-only and has no local directory behind it, so every write action is omitted rather than greyed out. There is no state in which they become available, and a permanently disabled row only invites the user to keep trying it.
Placement
placeLayer (packages/core/src/overlay/placement.ts) is pure and unit-tested.
The component measures itself first and then positions, so the arithmetic runs
against the menu's real size rather than a guess:
- Choose a side: the preferred one if it fits, else the opposite if that fits, else whichever has more room. Keeping the preference when neither fits pushes items off the edge where they cannot be clicked at all.
- Clamp on both axes to the padded viewport.
- With
shrink, cap the height so the tail scrolls instead of being drawn past the edge.
A menu taller than the window is capped to the space on the side it was placed on, not expanded to the full viewport — growing it past its own anchor would move it away from the thing it acts on, and the anchor is the only cue about what the menu applies to.
Escape and the keyboard
The menu registers on the shared transient stack (registerTransient), so
Escape closes it through the shell's one ordered ladder instead of a fifth
window keydown listener racing the other four. See
Keybindings.
Arrows, Home/End, and Enter are handled on the focused menu element — not on
window — with ArrowRight/ArrowLeft opening and closing submenus. Hover and
keyboard focus set the same activeIndex, so a menu driven by both never shows
two highlighted rows.
Scrolling the surface under an open menu closes it: a menu left anchored to a row that has moved is pointing at the wrong thing.
Built-in target kinds
| kind | payload | contributors |
|---|---|---|
files.node | path, nodeKind, name | files, notebook |
files.background | (none) | files |
desktop | (none) | desktop |
taskbar | (none) | desktop |
taskbar.window | instanceId (a status-bar pane button) | desktop |
taskbar.theme | (none) | desktop |
editor.selection | uri, text, empty | llamacpp |
library.chunk | text, title, sourceId, chunkIndex | llamacpp |
training.project | projectId, name, owner | training |
files.background is the empty space below the last row of the tree, which the
tree used to swallow. It is a separate kind rather than files.node with a
null path, because the two genuinely differ: there is no row, so every row-scoped
verb (open, rename, delete, copy path) is absent, and the create verbs fall back to
the first writable root instead of the clicked directory. Reusing the node kind
would have produced a menu whose every second item was permanently grey — exactly
what absent, not disabled exists to prevent. The tree's row handler runs first
and this one checks defaultPrevented, so a row click never opens both.
training.project is a row in the training projects list, and is the clearest case
of the menu paying for itself. That row used to carry five inline buttons — open,
recipe, two pushes and delete — on one flex line in a narrow list; the row is the
open action now and the rest live here, with Kaggle/Colab folded into a
Push a copy to ▸ submenu. A project another module owns keeps every item but
disabled with a detail saying why, rather than absent: the explanation is the
point, and hiding them would make an inert project look identical to a healthy one.
Delete stays enabled, because reclaiming the disk is exactly what still applies.
The row also exposes a ⋯ button that opens this same menu — a menu nobody knows
is there is the actions being gone.
editor.selection and library.chunk are the two text kinds, and both exist
because a surface owned by one module holds text another can do something with:
the llama.cpp module puts Trace this on both, and neither the editor nor the
library has any idea it did. The editor reads the selection from the live
CodeMirror view rather than the buffer's persisted bytes — what is on screen is
what was right-clicked, and acting on anything else is worse than declining. An
empty selection is a real target rather than an absent one, following the same
convention "run selection" tools use: no selection means the whole file.
files.node is the one to copy: the notebook module contributes Open as
Notebook for a .ipynb without the files module knowing anything about it, and
deliberately in addition to Open rather than instead of it — a notebook is
still a JSON file, and opening the raw text is how you fix one the editor cannot
load.
Adding a surface
-
Call
openContextMenu(event, target)fromonContextMenu, andpreventDefault()andstopPropagation()only when it returnstrue.A nested surface must stop propagationpreventDefault()suppresses the browser's menu; it does nothing about the event continuing up the tree. Where a surface sits inside another one that also has a menu — a taskbar window button inside the taskbar, a file row inside the tree — the ancestor's handler runs next and callsopenContextMenuagain, and because the store keeps a singleopenmenu the ancestor's simply replaces the one just opened.The failure is quiet and looks like a missing feature rather than a bug: for a while a right-click on a taskbar window button showed the taskbar's own menu (Position / Auto-hide / Reset), so Close appeared not to exist even though
windowButtonMenuhad always offered it. -
Retarget any selection first if the click landed outside it — acting on a row the user cannot see highlighted is how Delete hits the wrong thing.
-
Declare a provider in the owning module's manifest with
order: 0. -
Put the actions somewhere a provider can reach. They must not live in a component closure; the file tree's
deleteSelectionmoved tomodules/files/actions.tsfor exactly this reason, which also collapsed a second, drifting copy that the command palette had been using.