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.
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.
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.

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.

Package entry points

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 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 type declarations and exported entry points are the signature reference; do not copy a partial host interface into an extension.