Workbench composition
Extension UI is built from views, pages, and modes. This page explains what each one owns and how they share the workbench’s panel regions.
Views, pages, and modes
A view supplies content. A page owns its route, routed resource, Main presentation, and extra panels. A mode owns shared panels, chrome, and region policy. A resource identifies data. Its owner resolves its normal presentation and can select related resources to open.
Define each view body once with defineView. Native tree, file, controls, table, and Kanban views follow the same placement rules as webviews.
Pages declare resource: { kinds } separately from main. A Main view renders routed content; a Main collection renders peer panels and an empty view. Page slots and mode placements use the same item contract: a static view, or a resource binding. A binding declares kinds, view, cardinality, and an optional add action. Presence, mounting, and tab presentation mean the same thing for both.
Regions and targets
Main, Side, and Secondary are the three panel regions. Page and mode owners can contribute to the same region.
Use page targets to change location and panel targets for auxiliary content. A panel target opens one instance without changing the page location. Generated refs such as page.panels.inspector keep the page as the panel’s owner. A compound page-and-panel target enters an owner before opening its dependent panel, and commits only when all steps resolve.
Sessions consumers use sessionBrowser.commands.create from @pstdio/sdk/extensions.
Use side: true to create a draft beside the current page. Its optional panel
is a declared PlacementRef; omitting it selects the Sessions Project placement.
Compatibility callers can supply an existing placement in another mode without
owning draft identity or persistence. Normal placement availability and resource
binding checks still apply. replace: true instead switches the invoking viewer;
the captured Main or Side placement remains the navigation owner.
Current-view keyboard commands receive the selected target’s resource, region and placement. That placement is captured before awaiting an extension response, so a returned viewer action cannot accidentally act on another focused panel.
Mode chrome and navigation
Navigation items and trees contribute to the default host sidebar, including in custom modes. When a mode omits a chrome key, the host keeps its own navigation there, including custom-mode navigation items. A declared view replaces that chrome; false hides it. Mode placements keep their identity across pages in the same mode and are removed when their owner is removed.
Status details
On main (planned for 0.46.0), a status bar item can declare popover: details.ref
alongside its view and slot. The dashboard advertises
status-bar-item.popover.v1. Hosts without that capability reject the contribution.
Both references must name registered views.
The host opens the detail view above the item, aligned with its leading or trailing
slot. Its content can extend beyond the status bar iframe. Webviews use their
intrinsic height, and long details scroll inside the shared popover. Details
preload before the first click. Closing hides them and keeps their state and
webview, so reopening reuses the loaded view. Removing the status item
or unmounting the workbench releases the detail view. The status view remains
mounted while the details are closed. Existing items without popover keep their
current behavior.
Native view effects pause while hidden. Webviews keep their bridge connected and receive
document.hidden, document.visibilityState, and visibilitychange updates for their
host presentation as well as the browser document. Webviews should suspend subscriptions
and timers while hidden; React views can place their content inside an Activity driven
by document visibility. The visibility listener must sit outside that Activity so it can
resume the content. Performance Monitoring follows this contract and prepares one snapshot
without retaining a live subscription while closed.
Examples
The workbench cookbook links working examples for editable pages, inspectors, shared panels, editor collections, provider refs, and webview lifecycle. See also Contributions, Modes and layout, and Navigation and layout state.
Updated at: 2026-11-07