Skip to main content

Module: Explorer

One place to browse a workspace, replacing three. explorer.home is a tool whose sections are contributed by other modules:

SectionWhat it browsesCame from
FilesThe workspace file treefiles.tree
Notebooks.ipynb files under the notebook rootnotebook.browser
ProjectsTraining projectstraining.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:

ViewNow hosted by
flow.libraryflow.editor (it already was — the Explorer section was a second home)
records.listrecords.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 now revealSection instead of opening a pane. flow.openLibrary reveals its region strip instead, for the reason above.
  • Agent tools: unchanged. files.* stays declared on files.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.