Overview
@pstdio/workbench is for people who build a host app on the workbench, not for extension authors. Extensions use @pstdio/sdk/extensions instead.
The package supplies the headless application model and the React shell that Prompt Studio itself runs on. Its registries and layout controllers are host APIs. Extension authors should read the Extension API reference, starting with Workbench composition and Modes and layout.
Install
bun add @pstdio/workbench
The React integration needs the peer dependencies react and react-dom (19), @chakra-ui/react (3), and @emotion/react (11). The root, storage, and webview-runtime entries load without React. The package guide covers setup.
Pages
- API covers package entry points, core services, panel registration, composition queries, resources, modes, persistence, and extension placement.
- Contribution ownership explains module and extension attribution, lifecycle, and instance ownership.
- Navigation explains explicit targets, canonical locations, breadcrumbs, and history.
Runnable examples live in the workbench’s Canvas stories under packages/pstdio-workbench/src/examples. Start with the panels and pages stories.
Tabs
Adding a tab creates it directly in the panel whose + was selected and keeps other empty panels open. Closing or moving the last existing tab out of Side or Bottom closes that panel.
Host Add commands receive the destination in WorkbenchCommandExecutionContext.region.
Pass it to the placement open call or panel navigation target. Placement open calls
use it for that open, including reuse of an existing tab. Omit it on ordinary opens
to retain the live layout’s placement. Extension command navigation
results inherit the destination from the Add action.
Main tabs and their selection persist separately for each tabbed page. Resource routes under a tabbed collection share that collection’s Main tray. Side and Bottom stay shared within the mode. A static page browser declared in Main is offered only in that collection’s Main. Resource viewers with an Add command remain available in other eligible pages. Independent panel views declared in Side or Bottom remain available across pages. These Add rules do not restrict where an existing tab can move.
A resource binding with an Add command uses the command’s label and icon in the + menu and default placeholder cards. The opened resource keeps the view’s own tab presentation.
A host tab provider can expose WorkbenchWidgetTab.isDisposed() when its owner
retires. Layout restoration replaces retired providers with the current registered
contribution, preserving live per-placement overrides. Retired providers must stop
their subscriptions and must not start new reads when an older snapshot calls them.
Reading a snapshot prepares its identity; subscribing admits optional query work.
Hosts pass a stable presentationLocale (requested locale and fallback hierarchy)
to registerWorkbenchExtensionContributions. Localized tab queries retain separate
locale results and depend on catalog and accepted translation changes. Returning
to an unchanged project or locale reuses its accepted presentation.
Hover over a tab or focus it with the keyboard to see its full title in a tooltip. The tooltip appears below the tab after 300 ms.
Views in tab panels have closable tabs. Main has one header row with history and either tabs or page breadcrumbs with a resource-action dropdown, followed by view menus. A page with main.presentation: "page" owns Main directly and has no tab or close action. Its main.tab presentation supplies the breadcrumb label, icon and resource actions. Tabbed pages keep their single scrolling tab row even when one tab remains.
Drag empty page-header space to transfer that individual live view to an auxiliary panel or its tab strip. It becomes a tab there. The same Move actions are available in its resource dropdown and header context menu. Moving out of a dedicated Main page returns Main to its configured default. Whole tabbed panels retain their existing layout-position gestures and never become tabs or merge groups.
Opening a resource explicitly uses its requested destination. An existing view in that panel is selected; a compatible view elsewhere moves there. A requested different renderer is opened as that semantic view while the conflicting independent representation is retired. Main page navigation brings a resource out of Side when necessary. Panel opens with no explicit host region retain that declared placement’s existing location. Passive restoration and background completion preserve placement.
Tabs can be dragged onto other tab panels, including webview content. A dedicated page has no tab-insertion strip; a resolvable resource drop can open its page. During dragging, host pointer handling keeps iframe content from interrupting a drop. Outside dragging, webviews receive normal pointer and native file events.
Panel menus
The header controls open and close panel menus. Page and tab presentations keep these controls in the same Main header. The opener attaches the menu directly when its panel is wider than 580 px and has room for the menu, other attached menus, resize handles, and at least 120 px of content. Menu minimum widths come from their contributions. Panels 580 px wide or narrower keep their full width for content, so their menus float even when a menu would fit. Menus that cannot be closed stay attached.
When attachment is not allowed, the opener shows a floating menu below the button. The floating menu is as tall as its content. Taller content stops at the bottom of the viewport, and the menu body scrolls under its title. It is a temporary view. Opening or dismissing it does not change whether the menu is open.
An open menu attaches again as soon as its panel is wide enough. When space is short, menus that cannot be closed attach first, then open menus from left to right. Main, Secondary, and Side panel menus use the same rule.
Menu selection and the floating launcher
Selection in shared menus uses a checkmark at the far right. Icons and labels stay
together on the left. Selection has no background fill; pointer hover and keyboard
focus keep their own feedback. Tree and navigation rows keep their selected backgrounds.
Use SearchableMenu or resource actions with isSelected for shared selection rows.
Native Chakra menu choices use Menu.ItemText and Menu.ItemIndicator with the shared recipe.
The floating Side Panel hides its launcher while open and restores it when closed. The hidden launcher is inert and outside the accessibility tree. Panel content stays mounted while closed, so minimizing and reopening preserves drafts. See the menu selection story and Side Panel stories.
Updated at: 2026-11-09