Module: Explorer
One place to browse a workspace, replacing three. explorer.home is a tool
whose sections
are contributed by other modules:
| Section | What it browses | Came from |
|---|---|---|
| Files | The workspace file tree | files.tree |
| Notebooks | .ipynb files under the notebook root | notebook.browser |
| Projects | Training projects | training.projects |
Why three became one
All three were the same pane wearing three hats: a narrow list you pick something out of and open elsewhere. They were separate for one structural reason — there was no way for a module to contribute to another module's pane. So each shipped its own, and the launcher grew a row of near-identical browsers distinguished only by remembering their names.
They are not deleted, they are embedded. Two of them (Notebooks, Projects) are
also region strips of their own document pane, and that keeps working untouched — a
notebook still carries its browser on the left. What they lose is a competing
top-level home.
What is deliberately not here
flow.library (Flows) and records.list (Tables) were sections here, and
that was the merge overreaching. Explorer answers "what is in this workspace",
and the three sections above are all trees over the same rooted content: you
navigate them to find a thing and open it. A saved flow and a table schema are not
that. Each is a switcher for one document type — it means nothing except beside
the canvas or the grid it re-points, and putting it next to the file tree asked the
user to go somewhere unrelated to change what the pane they were looking at shows.
Both are now a left region strip on their own document instead:
| View | Now hosted by |
|---|---|
flow.library | flow.editor (it already was — the Explorer section was a second home) |
records.list | records.grid, records.form, records.board |
Their names still resolve — see below. Leaving Explorer must not cost reachability any more than joining it did.
The extension point
export const myModule: ModuleManifest = {
explorerSources: [{ id: 'stuff', label: 'Stuff', icon: '📦', view: 'my.browser' }],
};
ExplorerSourceDecl is a SectionDecl — everything downstream (the tab strip,
the persisted active tab, show("notebooks"), the pick key, the agent's section
argument) is the section machinery, not a second mechanism. Explorer opts in with
explorerHost: true on its panel, so the registry resolves the host by declaration
rather than by hardcoding a view id.
The merge happens at read time, in registry.panels / registry.widgets — not
at registration — so module order cannot matter. Explorer may register before or
after its contributors and both must work. The merged declarations are memoized
against a registration counter: these getters run on every render path, and
returning a fresh decl object per call would defeat useSyncExternalStore
snapshots and every memo keyed on the decl. A view with no contributions is passed
through untouched.
This is the one place a module legitimately contributes a section to a pane it does
not own — and the reason a plugin can add a browser without a pane of its own
(PluginContributions.explorerSources).
Agent context per section
Section bodies render inside the host's PaneInstanceContext, so they register
under Explorer's real instance id — unlike a region strip, which gets a synthetic
id no enumeration descends into. Providers are keyed by instance and section,
so each source registers its own; FileTree's arrives under explorer.home with
the active section stamped on it by readPaneAgentContext. This used to be keyed
by instance alone, which made "exactly one provider per pane" a standing rule and
meant a second contributed source adding its own useAgentContext would silently
overwrite the first.
Every old name still works
show("files.tree"), show("Notebooks"), show("records.list") and the rest all
resolve, through VIEW_ALIASES, to whatever holds them now — a section for the
three above, a { kind: 'region' } target for the two that moved on to their own
document. Because all five views still exist and are merely embedded, show would
reach them through hostOfEmbedded regardless — the alias entries are what make the
titles resolve, and they keep resolution to one lookup instead of a scan. Pinned by
the table-driven test in layout/__tests__/sections.test.ts.
Contributions
- Panel:
explorer.home(tool,explorerHost). - Commands:
explorer.open,explorer.files. The contributing modules keep their own verbs (files.open,notebook.open,training.open) — they nowrevealSectioninstead of opening a pane.flow.openLibraryreveals its region strip instead, for the reason above. - Agent tools: unchanged.
files.*stays declared onfiles.tree; the backend groups tools by name prefix, so which view declares them is irrelevant, and moving them would have silently re-grouped them.
Not done yet
Only the Files section has an agent-context payload. The clobbering half of this
is fixed — the others can each register their own now — but none of them do yet,
and only the mounted body can provide at all. So show("notebooks") still returns
the section name, its siblings, and hasPayload: false (contributed centrally by
readPaneAgentContext), but not a listing.
That shape was found by asking the local model "show me my notebooks": it correctly
read the ambient context, correctly chose show('notebooks') — and then, with an
empty payload to answer from, answered from the editor tabs instead and reported
the two .py files open there. A pane that returns nothing does not produce "I don't
know"; it produces a confident answer sourced from whatever else was in the window.
Naming the sections is a floor, not a fix. The mechanism for the real one now
exists — a section body registers under its own key — so what is left is for each
source to write a provider. The remaining gap is a background section, which has
no mounted body and so can only be answered by a declarative, module-scope payload
on SectionDecl.
An embedded view saved as a pane of its own is restored as one. A layout from
before the merge that still holds a files.tree window keeps it; opening Files by
name lands in Explorer.