API
This page lists the @pstdio/workbench entry points and the core services a host app uses.
The workbench separates reusable bodies, routed pages, mode-wide placement, and navigation.
Core services
| API | Responsibility |
|---|---|
views |
Register reusable view bodies and create independent instances for placements. |
pages |
Register routed screens and resolve page-owned slots. |
modePlacements |
Register content owned by a mode. |
navigation |
Open explicit page, panel, command, href, or compound targets. |
viewers |
Switch a calling resource viewer or focus its existing resource without duplicating it. |
pageLocations |
Own the canonical active page, browser history, restore, and breadcrumb projection. |
layout |
Render and persist owner-scoped placement state. |
sidePanel |
Read and change the Side Panel presentation stored in the layout’s side region, under the active mode’s floating policy. |
fullscreen |
Present Main with a temporary Side overlay, without saving a replacement layout. |
modes |
Register mode context used by pages and placements. |
resources |
Register resource kinds and hierarchy data. Resource identity does not choose presentation. |
Host modules and extensions register pages through the same page registry. Page activation resolves the declared mode and reconciles shell, mode, and page placements as one desired set.
Use navigation.openTarget() for user navigation. View and mode registries expose lower-level lifecycle operations for the page runtime; callers must not combine them into a second navigation path.
Host callbacks that finish later use viewers.capture(identity) to capture their calling viewer. The returned switcher becomes stale when that opening closes, changes resource, or leaves its project. Pinning and moving keep it valid. Reopening the same resource creates a separate lifetime. For navigation requests, capture viewers.captureContext(identity) when creating the action and pass that context to navigation.openTarget(). Shared menus and extension bridges preserve this guard through commands and parameter dialogs. Extensions use their normal public navigation APIs; the host captures their caller.
Panel open state is layout state, including the Side Panel’s. The side region’s visible flag says whether the panel is open, and its presentation says whether it is attached or floating. The presentation therefore follows the layout persistence scope like every other region. A scope without a saved layout uses initialSidePanelMode. Page, resource, section, and contextual parent are location state. Breadcrumbs, the URL, history, and last-location persistence all derive from that one location.
See Navigation, Modes and layout, and Workbench composition.
Main fullscreen uses fullscreen.enter() and fullscreen.exit(). Both are idempotent. fullscreen.canEnter() reads the active mode’s canFullscreen policy; enter() rejects modes that disable it. fullscreen.showSide() and fullscreen.hideSide() control the temporary overlay and enforce the mode’s Side permissions. The matching commands are workbench.enterMainFullscreen, workbench.exitMainFullscreen, workbench.showFullscreenSide, and workbench.hideFullscreenSide. UI controls execute those commands. fullscreen.store exposes active and sideOpen for host presentation.
The Sidenav tree’s right-click menu includes New group. Enter a name inline and press Enter to create a collapsible group, then drag navigation rows onto its header. Group headers show their name without an icon. Escape or leaving the input cancels creation. Right-click the group header, or open Group actions, to rename or remove it. Removing a group returns its rows to their contributed sections. Reset to default also clears user-created groups. Group names, row membership, order, and pinned placement use the same host storage as other tree customizations, separately for each tree and project. Groups follow the navigation owner’s move scope, so they accept the same moves as contributed sections.
Package entry points
Hosts with a backend connection wrap the workbench in WorkbenchConnectionProvider from @pstdio/workbench/react and pass connected from live sync. Native views retain loaded data after transport failures. Local reads remain available during an outage, and reconnecting refreshes those views. Ordinary query errors keep their view notice. An initial transport failure offers Retry while the host remains connected; during a confirmed outage it waits for recovery. The host owns the connection warning in its status bar. Without the provider, views assume they are connected.
| Import | Surface |
|---|---|
@pstdio/workbench |
Core registries, module contracts, layout, and resource types |
@pstdio/workbench/react |
React shell, providers, panels, and host renderers |
@pstdio/workbench/storage |
Workbench persistence adapters |
@pstdio/workbench/extensions |
Host integration for extension contributions |
@pstdio/workbench/webview-runtime |
Guest runtime HTML and script helpers |
See webview host adapters for shared extension capability wiring.
registerWorkbenchExtensionContributions accepts an optional renderTreeNodeEndContent(resource) host callback alongside resolveTreeNodeResource. It receives the resolved resource for root, lazy and continuation rows and returns mounted row content. Authored badges take precedence. Acquire live observations inside that component’s committed lifecycle; returning a React element during mapping starts no work. This does not change extension tree wire data. Copied resource metadata does not provide ongoing observation.
For optional reads inside native tree content, useTreeListRowVisibility() from @pstdio/ui reports whether its section and ancestors are expanded. CSS collapse keeps rows mounted for motion; observing this value stops their optional work while retaining the same DOM. Virtualized rows release their own observations when unmounted.
See the package guide for setup. Host modules register through a module context and dispose their registrations on teardown. Extension authors use the public SDK authoring API rather than importing host registries.
Complete core contract
The WorkbenchCore types define every available service and callback. In addition to the navigation and layout groups above, module contexts expose command, context-key, menu, tree, settings, status, theme, terminal, preference, and panel controllers. Resource change listeners return disposables. registerModule, unregisterModule, and dispose control module lifetime.
The status bar registers views in leading, center or trailing slots. statusBar.reorderItem(id, { beforeItemId }) or { afterItemId } moves an item within its current slot. statusBar.moveItem(id, slot, position?) also changes alignment, including empty slots. The bar aligns with the outer panel frame. Widgets use the list item corner radius and panel header padding, with 2px above and below each widget and a 2xs gap between widgets. Hover and selection use tab colors across the widget surface. Drag from the widget surface or from the padding around an inline iframe. A rounded placeholder shows the exact drop position and makes room between the other widgets. Moving or reordering keeps mounted widget content intact.
User order and alignment take priority over registration defaults and survive temporary unregistration. Pass statusBarPersistence to createWorkbench to store them. Its optional getSlots and setSlots methods store alignment overrides; existing order-only adapters remain supported. createLocalStorageWorkbenchPersistence supplies both with device-local keys in the host namespace. Drag to reorder or align widgets, use the widget’s context menu to choose left, center or right, or press Alt+Left/Right to reorder and Alt+Shift+Left/Right to change alignment.
A mode’s chrome.status view uses the same widget host, with leading alignment as its default. It supports the same dragging, alignment menu and saved position. The mode owns its visibility and still replaces ordinary status contributions. Leaving and returning to the mode retains its mounted view. The host removes the temporary registry item when the mode or its status view is removed.
The type declarations and exported entry points are the signature reference; do not copy a partial host interface into an extension.
Native Markdown sessions
Custom hosts can use createNativeDocumentSession({ projectId, target, client })
from @pstdio/workbench with the SDK’s client.nativeDocuments. start() opens
the local room. getSnapshot() returns the shared document, pending save state,
connection state, and participants; subscribe() reports changes. setSelection()
publishes transient selection positions. flush() waits for local acknowledgement,
retry() reconnects, and close() drains pending edits before releasing the room.
An unreachable local host leaves unacknowledged edits pending. Native file views
use this session automatically; extensions only declare their text source.
Error feedback
The pinned System activity widget stays available in the status bar even when the notice list is empty. System information and errors reported with notifications.show(...) appear there with their details, recovery actions, and dismissal controls. In a mode that hides the status bar, a pending system notice brings the widget to the bottom without resizing the view. Durable requests live in the Notifications inbox.
For user actions, use a local error display or runUserAction(workbench, label, run). The helper captures the originating view before running the action and shows a failure there, even if focus changes while it runs. Retrying clears that view’s previous action error. Dialogs keep failed submissions open and show the reason beside their controls. Action errors do not appear in the system-error widget.
Tree views can provide synchronous getStructure, getHeaderStructure, and getFooterStructure callbacks for the content, header, and footer. The renderer uses these rows while the corresponding data reads are pending, including when navigation changes the page owner.
Navigation contributions keep their latest resolved rows for one project and resource scope. Returning to an owner uses those rows immediately while a fresh read runs. A different project or resource starts from its declared structure, and removing a contribution discards its snapshot.
Updated at: 2026-11-17