paseo/docs/side-panel.md

Side panel

The companion surface beside the user's work: Changes, Files, the pull request, and anything an agent asks to show alongside its output.

Everything that opens, reveals, hides, or asks about it goes through packages/app/src/workspace-tabs/side-panel.ts. Nothing else branches on which surface the current layout uses.

Three renderings, two facts

Layout	Rendering
compact	slide-over overlay, owned by the panel store
non-compact + splits	dedicated right pane, owned by the layout store
non-compact, no splits	ordinary tabs in the focused pane

The third case is the one that bites. A native tablet renders one pane at a time and the tab row only lists the focused pane's tabs, so anything routed into a separate side panel pane there disappears with no way back.

Placement

Where a tab lands is an intent the caller declares, not something the store infers from a paneId that happens to be in scope. WorkspaceTabPlacement (packages/app/src/stores/workspace-layout-actions.ts) has four modes, and the difference between them only shows up when the tab is already open somewhere:

Mode	New tab	Tab already open
pane	opens in the pane	moves to the pane
prefer	opens in the pane	stays where the user left it
focused	focused pane	focuses it in place
ambient	focused pane	focuses it in place

pane is a pane-local affordance — that pane's + menu, its empty-state launcher. The user is placing the tab and expects it to arrive.

prefer is an implicit supporting open — an agent's file link or a failed workspace setup. It has an opinion about new tabs only. Yanking a tab out of the pane the user deliberately moved it to is the failure this mode exists to prevent.

ambient differs from focused in one rule: reconciliation opens tabs with nobody behind the click, and the side panel can hold focus from an earlier reveal, so an ambient open of something the user works in (an agent, a terminal, a browser) is pushed out of the side panel. A focused open honours the focused pane whatever it is, because the user is standing in it.

Deduplication lives in openTabInLayoutFocused, so it obeys the placement intent for every caller. Do not re-place a tab after opening it.

Lifecycle

The side panel lives in the ordinary split tree, so it is a pane like any other until it empties or the user dismisses it:

• Close pane on the side panel hides it; its tabs are waiting on the next reveal.
• Close pane on any other pane removes it.
• Closing the Side panel's final tab hides the pane. Revealing it returns the empty launcher. This is close-only: claiming or dragging that tab to another pane leaves the empty Side panel visible.
• Nothing takes the last visible pane away. closePane will not remove it, and neither closePane nor hideSidePanel will hide it — including the header toggle reaching hideSidePanel after every other pane is gone. The gate is one check in setPaneHiddenInLayout; do not add a second one upstream.

closePane in the layout store owns that distinction. React renders the button and does not decide what it means.

Dragging a pane's last tab into another pane collapses the source pane — except the side panel, which the user summons and expects to find again, split size and all.

What the side panel never does

It does not seed itself. Revealing it opens an empty pane with the launcher; the user picks what goes in. Detecting a pull request makes the launcher's card available and opens nothing. A failed workspace setup adds a background tab to the main pane. Running and successful setup never seed tabs.

Routing preference

Settings → General → Open supporting tabs in the Side panel, on by default, persisted in client app settings as openSupportingTabsInSidePanel. Off means new supporting tabs land in the focused pane instead. Mobile ignores it. Explicit actions — the header toggle, a pane's + menu, the empty-state launcher — are never subject to it. The Changes keyboard shortcut and the diff-stat pill above an agent composer are supporting opens: they follow the preference and focus an existing Changes tab wherever the user left it. When Changes is already visible in the Side panel, the diff-stat pill hides the panel without closing the tab. A different visible Side panel tab switches to Changes instead.

The name

The product surface is the Side panel. File Explorer is still the name of the Files view inside it. Persisted identifiers keep their pre-rename spelling: the pane id is the literal string "explorer" (SIDE_PANEL_PANE_ID) and the persisted layout key is explorerPaneIdByWorkspace. The persisted state schema is strict, so renaming either would fail every saved blob and wipe the layout it describes.