Workspace & Layout Management
Relevant source files
The following files were used as context for generating this wiki page:
Workspace & Layout Management coordinates the organization and display of multiple research entities within the PRKS application. It manages a system of in-app tabs and a flexible tiling engine that allows users to view content in stacked or split-view configurations. The system handles tab lifecycle, persistent layout state, and spatial repositioning of panes without requiring multiple browser tabs.
The architecture uses a central workspace model to maintain a "Main" tab and a recursive tree of "Secondary" panes. This model enables complex layouts while enforcing a visible-pane cap to maintain performance and usability. Layout state is persisted across browser reloads, allowing users to resume their research session exactly where they left off.
Sources: frontend/js/workspace-tabs.js, frontend/js/workspace-model.js, README.md:16-19
Workspace Architecture
The workspace operates on a dual-mode system: Stacked and Tiled. In Stacked mode, only the Main tab is visible. In Tiled mode, the Main tab occupies the primary region, while a Secondary region displays a tree of split panes. The system supports up to 4 total visible panes (1 Main + 3 Secondary leaves).
Core Components
| Component | Responsibility |
|---|---|
WorkspaceShell | Vue-based presentation layer that renders the tab strip and pane frames. |
workspace-tabs.js | The live effect coordinator that manages navigation, mounting, and tab lifecycle. |
workspace-model.js | The typed canonical model containing pure state transforms and invariants. |
workspace-tree.js | Manages the recursive structure of Secondary panes (leaves and split nodes). |
tab-context.js | Tracks the runtime state, entities, and resources for an individual tab. |
Sources: frontend/js/workspace-tabs.js:8-12, frontend/js/workspace-model.js, frontend-app/src/workspace-shell/WorkspaceShell.vue
Data Flow for Layout Updates
When a layout change occurs (e.g., splitting a pane), the intent is processed by the coordinator, which generates a "plan" using the pure model. If the plan is valid, the canonical state is updated, and a detached projection is published to subscribers like WorkspaceShell.
The coordinator ensures that DOM updates do not cause unnecessary TabContext remounts by reusing existing host elements.
Sources: frontend/js/workspace-tabs.js:146-155, frontend/js/workspace-tabs.js:521-536
Tab Lifecycle & Navigation
The system distinguishes between Active, Visible, and Parked tabs.
- Main Tab: The primary active tab, always reflected in the browser's URL hash.
- Visible Secondaries: Tabs currently displayed in a split-view tile.
- Parked Tabs: Open tabs that are not currently visible in any pane. They exist as state only, with no DOM or active fetch processes.
Navigation Logic
The prksWorkspaceNavigate function handles multi-target navigation. It can update the current tab, open a new tab, or target the "tile" region.
Tab Leave Decision
Before a tab is closed, parked, or navigated away from, the prksTabLeave engine assesses whether the operation is allowed. This check prevents the loss of unsaved research notes or metadata. Probes (like person-profile) register with the engine to provide specific assessment logic.
Sources: frontend/js/workspace-tabs.js:705-720, frontend/js/components/people.js:476-484
Tiling & Split Management
Tiling is managed through a recursive tree of leaves (tabs) and split nodes (containers). Split nodes define an axis (left-right or top-bottom) and a ratio.
Split Constraints
- Visible Pane Cap: PRKS limits the workspace to 4 visible panes to ensure usability.
- Narrow Fallback: If the physical viewport width is less than 720px (
PRKS_WORKSPACE_NARROW_PX), the system falls back to a stacked layout, hiding the Secondary tree. - Ineligible Routes: Certain views (e.g., those that are not "tileable") will force promotion to the Main tab if a user attempts to open them in a split.
Sources: frontend/js/workspace-tabs.js:20-22, frontend/js/workspace-tabs.js:370-384, frontend/js/workspace-tiling.js:14-19
Tiling State Model
Command Palette Integration
The Command Palette (Ctrl+K) serves as a primary entry point for workspace management. It allows users to search for entities and choose a navigation target.
| Command Palette Action | Resulting Workspace Intent |
|---|---|
| Click / Enter | target: 'current' — Navigates the focused tab. |
| Ctrl/Cmd + Click | target: 'new-tab' — Opens the entity in a parked background tab. |
| Alt + Click | target: 'tile' — Opens the entity in a split pane beside Main. |
Sources: frontend/js/command-palette.js:314-340, frontend/js/workspace-tabs.js:56-62
Summary of Key Functions
| Function | Purpose |
|---|---|
prksWorkspaceInit() | Bootstraps the workspace, restores persisted state, and binds event layers. |
prksWorkspaceNavigate(hash, opts) | High-level navigation entry point for shell and feature code. |
prksWorkspaceSetMode(mode) | Toggles between stacked and tiled visual modes. |
prksWorkspaceSplitLeaf(target, axis, opts) | Atomically splits a specific pane to insert a new tab. |
prksWorkspaceMovePane(src, target, axis, placement) | Spatial repositioning of leaves within the split tree. |
prksWorkspaceSubscribe(listener) | Allows UI components to receive frozen, detached workspace projections. |
Sources: frontend/js/workspace-tabs.js:1159-1175, frontend/js/workspace-tabs.js:1320-1323, frontend/js/workspace-tabs.js:1340-1350
Workspace & Layout Management ensures a cohesive research experience by treating the entire application surface as a single, multi-pane environment. By separating pure model transforms from DOM-heavy coordinator effects, the system maintains a responsive and stable UI during complex layout transitions.