Navigation
The workbench navigates only to explicit targets. This page lists the target kinds, how navigation validates them, and how history and mounted views behave.
Targets
workbench.navigation.openTarget() accepts explicit targets:
| Target | Effect |
|---|---|
page |
Opens Main by default, or the requested auxiliary panel. A resource with one representable Main renderer becomes a tab in the current tabbed container; otherwise activates its page and mode and updates location, URL, history, breadcrumbs and restore state. |
panel |
Opens one active page slot or mode placement without changing the location. |
command |
Executes one command target. |
href |
Opens an external URL. |
compound |
Prepares page and panel steps against proposed state, then publishes the final state with at most one history entry. |
A page target may carry resource, section or position, open, and contextual parent. A panel target may carry resource and open. Both may specify region: "main" | "side" | "secondary"; an auxiliary page target requires a resource. Targets do not carry activation callbacks.
Resource tabs keep their semantic page context without changing the receiving container’s route. Pages with multiple Main views or static landings open their complete page. Explicit page-location navigation, URL loads, Back/Forward and Main-body drops keep their full-page meaning; tab-strip drops follow the receiving container.
Native chat views use those same page and panel targets. Their action bindings capture the current placement, so conversion does not give a delayed navigation result the previous viewer’s context.
Related resources
Appearance’s Open related resources setting is on by default. Opening a resource or selecting its tab evaluates its owner’s optional relatedOpenings command. Only entries with autoOpen: true open automatically. Targets use their normal owner resolvers; automatic openings do not recursively open their own related resources.
Ticket supplies its latest session in Side. Workspace supplies its latest session in Side. Terminals open manually. Owners choose their defaults; the host applies shared presentation rules. Page entry always places automatic tabs, including inside panels remembered as closed. Resource pages remember related resource choices and manual closures only for destinations in their current automatic openings; remembered choices do not steal selection. Panels revealed automatically close on leave unless the user keeps them through normal tab or panel controls. Other Side/Bottom state is shared within one project and mode, including closures made on another page. Page or resource navigation within that mode closes all unpinned tabs in every tray. A mode switch preserves the outgoing tabs, selection, panel visibility, sizes and running terminals and restores them on return. Modes show only their supported panels. See related resource openings for selection, focus, persistence and cleanup rules.
Each tray keeps at most one unpinned preview, always at the left. Opening or unpinning another preview replaces the previous preview across page, mode and shell owners. Dragging and dropping an unpinned tab pins it instead, preserving the destination preview. The insertion marker and rounded tray outline show its destination; cancelling leaves retention unchanged. The same rule applies to moves through the tab menu or movePanel. Pinned resources stay pinned. Automatic related opening protects its initiating preview. Late results are discarded after source/project changes, owner removal, or disabling the setting. Ordinary tab edits and layout reconciliation preserve a valid page-entry lookup; remembered closures control reveal without suppressing placement.
Validation and history
Navigation validates the complete target before changing state. An unresolved page or inactive panel owner produces one error and leaves location, history, breadcrumbs, page instances, mode placements, selection, and visibility unchanged. Commands and external links remain standalone actions. It does not search by resource kind or fall back to main.
Browser Back and Forward replay canonical PageLocation values. Replay replaces the active owner set and does not push another history entry. Refreshing metadata for the same logical location preserves the selected panel; replaying a different document or location activates its destination.
History entries record the resource-removal clock that existed when they were captured. Replay removes deleted resources from the full contextual parent chain. A clock from an earlier workbench instance cannot hide a deletion in the current instance. Resource viewers keep their page parameters and contextual parents when switching resources on the same page. An explicit viewer page change follows the destination page’s normal navigation rules.
A parent breadcrumb is navigable when its contribution renders its own Main view, names a resource, or declares a collection landing view. Tab presentation does not affect this rule. Page groups and panel collections without a landing view remain labels. A group declares main: { kind: "group", default: childPage.ref }; opening its route resolves to that child in one navigation. The child must be in the same mode and open without a resource. The group stays in the breadcrumb parent chain and can own navigation trees, but has no content, resource, slots, or panel view of its own. Breadcrumbs use each contribution’s declared icon; a resource type does not replace it with a status indicator.
The routed page owns its breadcrumb and page actions. A collection page uses Main’s selected document for its document context. Focusing Side or Secondary does not replace that context. A resource-bound page keeps its routed resource as the breadcrumb subject, even when Main renders another resource. An independent resource viewer can supply its resource label and icon. Static context views keep their tab controls without renaming the routed resource.
Mounted views
Project selection
Before a project is selected, the required Projects dialog appears on an empty background. Project selection hides navigation, activity, status widgets, floating panels, project tabs, and panel controls. Native window controls remain available. The dialog footer opens global Settings; closing Settings returns to the picker. System errors still use the status bar when they need attention.
Creating the first project opens its configured Home page and tools without reloading. Project selection commits the project scope and dialog changes together, so automatic selection cannot interrupt that transition.
Main fullscreen
The fullscreen control expands Main over the workbench. It appears when Main has content. In the browser it sits at the end of the navigation header. Desktop places it beside the panel controls in the top bar and keeps the exit button clear of the native window controls. It stays reachable when panel headers or mode navigation chrome are hidden. Fullscreen hides project tabs, panel controls, the activity bar, Sidenav, Bottom, Main’s tab header, and the status bar as presentation. It does not replace or save the global layout, change the page URL, or create page panels.
An open attached or floating Side becomes a temporary floating overlay when the mode allows floating. A closed Side stays closed. While Side is minimized, its bubble remains available in fullscreen and reopens the temporary overlay. The bubble hides beneath the open overlay. A mode without Side, or with a nonfloating Side, hides it. The fullscreen header keeps only the exit control. The bubble and overlay close action change only the temporary presentation. They follow the mode’s open and close permissions. Dismissing Side returns focus to the bubble; exiting returns focus to the fullscreen entry control. Escape first lets nested menus and dialogs handle the key, then dismisses Side, then exits fullscreen.
Page navigation keeps fullscreen active. A mode or project change, disposal, or a full reload clears it. Existing views and manual terminal processes remain mounted through these transitions. Automatic previews still follow the related-opening cleanup and remembered-closure rules above. On exit, the underlying tabs, selection, sizes, dock position, and visibility remain available, including ordinary user edits made during fullscreen.
Main tabs belong to the current page, including pinned shell, mode and host tabs moved there. They hide on page leave and restore with that page. Side and Bottom keep shared tabs within the current mode. Moving a tab out of Main makes it shared again. Pinning controls retention, not scope.
Visited registered views remain mounted while their tabs are open, including inactive pages and modes. Closing or replacing a tab keeps its view for 30 minutes so returning preserves reading position, iframe state, and local input. After that grace period the closed view unmounts. Registered mode chrome and status views keep their contribution as their owner. Docked views have stable portal hosts owned by the workbench. Moving a tab changes the host’s DOM parent without remounting its React content. Hidden views do not take layout space or accept user input. A pinned Main terminal keeps its running process while its page is hidden.
An auxiliary resource binding with cardinality: "one" keeps one placement when its resource changes. The host updates that live view’s resource and attached menus. Main keeps a separate view for each routed resource or declared document, including with cardinality: "one", and reuses it on return while open or within the same grace period. A binding with cardinality: "many" gives each open resource its own placement.
The host exposes getPanelDestinations(instanceId), movePanel(instanceId, region, position?), and resetLayout(). A position is "start", "end", { beforeWidgetId }, or { afterWidgetId }. Moves preserve the current page route and the primary resource anchor. The workbench.movePanel and workbench.resetLayout commands expose the same operations to commands and agents. onDidResetLayout lets host UI clear its active layout preferences after the reset.
Retention is local to the current project and workbench. Removing a view contribution, switching projects, or closing the workbench releases its retained views. A project switch releases only those views: the panels, navigation header, Sidenav and status bar stay mounted. A full application reload starts new views. Views are not mounted merely because they are registered; mountStrategy: "keep-mounted" can mount inactive placements before their first selection.
Resource removal uses the shared registry cleanup for page, mode and shell placements. It matches the full resource identity, including project and extension, and invalidates pending related openings. Session deletion and archive use this same cleanup; closing a Session view alone does not delete or stop the Session. Resource cleanup does not save a manual panel closure. A retained dirty editor may stay visible while its pending related lookup is cancelled.
Tree selection follows Main’s selected document or the routed page resource when Main has no document. A node’s declared selected value distinguishes documents that share a resource identity, but applies only while that resource or page is active. Rows without a resource or navigation target keep their declared selection. Contextual parent trees remain visible without overriding the current workspace selection. Returning to the parent restores its active document selection.
Clicking a tree row with a navigation target opens that target, including rows with children. Its chevron expands or collapses the children separately. Rows without a navigation target continue to expand or collapse when clicked.
Tree reads belong to the mounted placement. Changing its resource or navigation level refreshes its data while keeping the current rows until the complete replacement arrives. Rows with the same identity keep their DOM, focus, and scroll position. A changed read scope cancels older reads and ignores their late results. Opening a different tree or project starts a new snapshot. A changed search filter also starts a new snapshot, so results from the previous query cannot be clicked while its replacement loads.
Navigation trees in the sidenav keep their available rows when a read fails. They do not show an inline load-error notice or Retry button, including on the initial load. Later data refreshes and connection recovery load the tree again. Trees in other panels keep their load-error notices and Retry controls.
Navigation item groups
A navigation item’s group names a collapsible Sidenav section. The section belongs to the extension that declared the item: its ID is <extensionId>:<group>. Each extension’s items for one owner and slot also register as their own contribution. Two extensions that both use group: "Tools" therefore show two separate Tools sections. The workbench does not merge equal labels from different extensions, because a merged section would have no single owner for its order, hiding, and moves. An empty group places items at the slot root. See navigation-item-contributions.ts.
Choose a group label that names your tool, such as its display name, rather than a generic word. Use New group in the Sidenav menu to create a group for the current navigation level. Each level shows its own groups, including when pinned rows from a parent level are visible. See API.
Resource actions on navigation rows
Set TreeNode.resource to the subject of row actions. target remains the normal-click destination. Session rows in the Sessions level, workspace group, and Planner ticket section use the same session reference for both. The shared tree resolves resource menu contributions and keeps the clicked resource in command context, including parameter dialogs. Opening or dismissing a menu does not navigate.
Resource-owned menu contributions also appear on resource tabs and resource breadcrumbs. The workbench resolves one ordered resource group for the explicit subject of each menu. Navigation-specific actions supplement that group; a row’s menu path does not replace it. Parent breadcrumbs resolve their own resource actions. Tab controls, placement sections, and current-page actions remain separate groups.
A view’s custom tab controls belong only to the current breadcrumb with the same declared document reference. A parent resource breadcrumb never inherits those document controls, even when both references share a resource ID.
A host resource kind can supply resolve and subscribe to read current state and notify menu consumers. This keeps an inactive tab’s actions consistent with navigation after a status or capability change. Resource data stays with its owner; the workbench does not store another copy.
Owner refreshes distinguish a resource’s declared document selection. Two documents on the same resource resolve their own labels and metadata. Refreshing or activating one placement preserves the other placement’s selected document.
The primary resource watcher owns refreshes for the current page resource. When an inactive placement becomes primary, its pending placement refresh is canceled and its late result is ignored. An older response cannot restore stale titles, permissions, or menu metadata over the primary watcher’s newer result.
Keep these identities separate when they differ. A file row may open its parent ticket while declaring file-specific contextMenuActions. Do not infer its action subject from the destination. Rows with no applicable actions and the navigation background keep the customization menu.
Document routes and source positions
A routed resource page can declare document: { metadataKey: "workspaceFilePath" }. The selected document stays in that ResourceRef metadata field. The shared page URL codec projects only that declared string into the document query parameter. Labels, roots, permissions, and other metadata stay out of URLs. Owners hydrate those values and validate document membership before loading content.
serializePageUrl and parsePageUrl from @pstdio/sdk/extensions round-trip the declared selector. Browser history distinguishes documents within one resource. Display or capability refreshes preserve selection without adding a history entry. Each declared document has its own Main snapshot and optional-view choices. Changing documents closes previews and restores that document’s Main tabs. Section and source-position changes within the same document keep its layout and mounted view. Side and Bottom remain shared within the mode.
position: { line, column?, endLine?, endColumn? } is a one-based source location. It requires a selected document and cannot be combined with a Markdown heading section. URLs use the same named coordinate parameters. Monaco reveals and selects the requested range after loading, and on another explicit navigation within the same file. It retains the editor draft. Images and rich Markdown show a notice when source positions are unavailable. Markdown heading navigation still uses section.
Chat UI accepts an optional linkHandler with resolveHref, open, and optional describe methods. It passes the original destination and its origin (Markdown, inline code, reference, or tool) to the host. The session host resolves relative paths from the originating workspace root, checks rooted paths against that root, and uses registered page URLs for saved resources. A file path under .pstdio/extension-storage/pstdio.planner/tickets opens those workspace bytes. It does not imply a saved Planner document. Absolute dashboard URLs must have the dashboard’s origin; another project is selected before its page is restored. Raw custom schemes cannot execute commands. Uploaded attachments retain their own open behavior.
The legacy public onOpenFile callback remains available and is deprecated in favor of linkHandler. Existing callers without a handler retain their behavior.
Shared panel commands
Global panel controls render in the web navigation header: closed Sidenav recovery before history, and Bottom/Side controls after breadcrumbs. Desktop hosts use the exported WorkbenchPanelToggles and WorkbenchFullscreenToggle beside project tabs and set Workbench.panelControlsPlacement="host". With keepTitleBarInFullscreen, the host title bar stays visible and provides the exit control. The navigation header provides the exit control by default. Custom mode navigation chrome keeps these host controls. Session panels are available in each mode that allows Side or Bottom and retain that project/mode’s own tabs. Project navigation stays inside Main’s outline and follows Main’s placement relative to Bottom. The Sidenav control icon mirrors when Navigation is on the right, including while Navigation is closed.
shell.getPanelPolicy(region) resolves availability, visibility, opening, closing, tab acceptance, resizing, floating and header visibility. UI controls, tab destinations, public commands and restoration use this policy. workbench.movePanel moves an individual tab or live page-content instance; workbench.repositionPanel changes whole-container placement.
| Command | Parameters |
|---|---|
workbench.setPanelOpen |
region: sidenav, secondary, side, open: boolean |
workbench.setPanelHeaderVisible |
region: main, secondary, side, visible: boolean |
workbench.resizePanel |
region: sidenav, secondary, side, size: number in pixels |
workbench.setSidePanelPresentation |
presentation: attached, floating, closed |
The matching shell methods enforce the same permissions. Main has a single header with history and either a tab strip or breadcrumbs/resource actions, followed by its view-menu controls. Dedicated pages have no tab or close action. Their current breadcrumb and empty header space move the individual live page; their menu offers the same operation. The current breadcrumb uses grab/grabbing cursors, while ancestor links and controls keep their own gestures. Whole tabbed containers cannot drop onto tab strips. Legacy header setters cannot override the page’s presentation. Optional panels collapse when their last tab leaves or closes.
Normal page opening targets Main, so a resource already in Side moves into Main. Resource creation follows that same receiving presentation, including a tabbed Main left without an active page after moving its content away. Page and panel targets can specify region: "main" | "side" | "secondary". An auxiliary page target requires a resource and presents its semantic view with its page parameters, document and section context. A page in another mode enters its owning mode; a denied same-mode auxiliary opening preserves the source. Canonical resource identity prevents duplicates, while the requested page/view determines the renderer. Source-following Properties views do not reserve a resource. Dedicated pages without a compatible panelView receive a private portable placement; extensions do not need an additional declaration to support movement. A multi-view resource page can preview its declared landing view in an auxiliary panel.
Resource references, including ticket links and related-resource links, default to a Side preview. They keep the source page visible and retain existing pins. Single-instance panel bindings use their normal replacement behavior without a retention intent; many-resource bindings default to preview. Explicit multi-result openers retain their requested pins so later results do not replace earlier ones. Navigation entries, resource creation and explicit Main drops retain their own destination behavior. Navigation selection follows Main: moving Home out clears its selected entry until Home returns.
Moves prepare ownership, location and destination policy before browser acceptance and commit. Compatible live hosts and captured viewer leases survive transfer. Background replacement may update the same moved view without relocating it or stealing focus; closed/replaced or scope-changed sources remain stale. Explicit Back/Forward brings its resource into Main using the existing history index. Boot, project/mode restoration and intent: "restore" preserve stored placement.
Panel placement and closed-edge drops
Dragging Main content or a Main tab into Side or Bottom requires that specific panel to be open. Closing it during the gesture cancels that destination. Explicit Move menu actions can still open an eligible closed panel.
The shared shell owns whole-panel positions in the existing project and mode layout. Side can sit left or right of Main. Navigation sits at the far left or far right. Main and Bottom can flip their vertical order. The action bar can sit on any outer edge. Moving a panel keeps its tabs, resources, selection and live content. Reset layout restores the default positions.
Drag empty Main, attached Side or Bottom header space to an allowed edge. A floating Side header, including the temporary fullscreen overlay, does not start a whole-panel drag. Reattaching Side restores its panel drag handle. Main contains history controls and either breadcrumbs or tabs in one header inside its outline. This navigation row follows Main when it moves below Bottom, and its empty space is Main’s drag handle and placement context menu. Navigation and the action bar also accept drags from empty space. Buttons, tabs and resource controls keep their own gestures. The header context menu offers the same placement actions through right-click, Shift+F10, the Context Menu key and touch hold. Unavailable moves and the current position are omitted. Actions refresh after each placement change.
Insertion targets reserve space at the boundary that owns the panel: Side sits between Navigation and Main, and Bottom stays within Main’s column. The current placement has no target. A whole tabbed Main container can change vertical placement only while Bottom is open. Individual page transfer uses the destination opening rules above. During a whole-panel drag, the original grab point competes with allowed destinations. Releasing closer to that point keeps the current placement, so returning toward the start cancels a move. Approaching a destination selects its full rounded outline and accent fill, without a center bar. Empty movable chrome uses a grab cursor and dragging uses a grabbing cursor. Leaving the workbench or cancelling also preserves the placement.
Agents use the same shell operations through these commands:
workbench.repositionPaneltakesregion(main,secondary,sideorsidenav) andposition(left,right,toporbottom). The controller rejects unsupported combinations and mode restrictions before changing the layout.workbench.setActionBarPositiontakespositionon any outer edge.workbench.movePanelcontinues to move a single tab. It respects the destination policy and the placement’s allowed trays.
During an auxiliary tab drag, a closed eligible Side offers both allowed left/right edges and Bottom offers both allowed top/bottom edges, including before their first opening. Fixed placement rules keep only the saved edge available. A valid drop saves the chosen edge, opens the panel and inserts the pinned tab in one step. Closed Side opens attached. Cancelling or dropping elsewhere leaves visibility and tab retention unchanged. Open panels accept incoming tabs only within their current visible bounds. When dragging the sole tab of Side or Bottom, that panel also offers its opposite permitted edge. Dropping there moves the panel with the same tab and live content, pins an unpinned tab, and saves the new edge. A floating Side attaches at the chosen edge. Cancelling preserves placement, presentation and retention. Panels with multiple tabs and fixed panels offer no alternate edge for their own tabs. Tab edge targets stay invisible until the pointer approaches an eligible edge. Only the nearest target appears, including where edges meet. Its complete rounded outline and filled background reserve space at the owning layout boundary, like a whole-panel dropzone, without guidance text. Leaving the edge removes the slot and restores the content bounds. Choosing the nearest edge stays stable while the preview shifts content. Existing tab targets keep priority and remain reachable while a slot shifts their header. An existing destination preview stays open and leftmost; the dropped tab never replaces it. Removed page panels have no targets.
Project default page
An application supplies an eligible resource-free page through createWorkbench({ defaultPage }), using a page reference or a callback that reads its current configuration. Prompt Studio reads the fully qualified reference from public project composition. The distribution chooses the ordinary Home page initially; people and agents can replace that choice through the same SDK, HTTP, or CLI interface.
An explicit destination and a valid saved location take precedence over the default. A project-root bookmark restores that saved location when available. The Open default page command follows the current configured choice. Updating composition refreshes the open workbench’s choices without moving away from its current page. The project breadcrumb retains its last root-level location before using the default.
If the configured page is missing, disabled, or requires a resource, the selected mode and shared panels remain active and the existing empty workbench and extension-management controls remain usable. Core does not guess another page or supply a Start/Home alias. Old presentation links and saved references are discarded by the coordinated alpha API break; workspace and session data remain in their existing stores.
Workspace provider destinations
Workspaces declares its own ordinary page references for its grouped list, Files, workspace, overview, and synced history. Its opener chooses among those pages using workspace capabilities. Files use its declared document metadata key on the routed host-owned workspace resource; its default-folder presentation omits Changes. Other tools may declare different names, document keys, page structures, and normal page/panel/compound targets. Local file and execution actions retain the host’s current provider permissions.
Bare workspace references use the project’s configured public resource opener. Workspaces owns its normal page references and capability-to-page choices. An ordinary extension can present the same core resource kind through its own declared pages. Core keeps ownership of workspace data and file services.
Updated at: 2026-11-15