prometeu-studio/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md

Studio Shell, Workspace Navigation, and Layout Decision

Status

Accepted

Cycle

Studio UI Wave 01

Context

prometeu-studio already has a shell scaffold, but it was assembled manually and does not yet define a stable Studio UI contract.

At the same time, the Studio is about to grow in at least these directions:

• code editing;
• asset management;
• debugger and profiler work;
• future shipping flows;
• shared activity and run controls.

The shell therefore needs to be stabilized before the Assets workspace and broader UI work expand further.

This decision applies only to the Studio UI layer at this stage. It does not reopen unrelated service or domain contracts.

Decision

The Studio adopts a structured shell, not a fully docked IDE shell, for the current UI wave.

The baseline shell is:

• top global menu region;
• left fixed workspace selector;
• center workspace host;
• right global utility panel with tabs;
• top-right always-visible run surface.

The shell must open through a lightweight project launcher or home surface before entering the main workspace frame.

Invariants and Constraints

Global Shell Regions

The baseline mandatory shell regions are:

• top global menus;
• left workspace navigation;
• center workspace host;
• right global utility panel;
• top-right run surface.

Logs and detailed operational output do not belong to the global shell as a single shared console. They belong to the active workspace that owns the operation.

Workspace Model

The left-side workspace selector remains fixed for now.

The baseline workspace set is:

• Code Editor;
• Asset Management;
• Debugger/Profiler;
• Shipper, temporarily represented by the current BuilderWorkspace.

BuilderWorkspace may remain in the shell for now because it is still useful for testing, but it is a transitional surface and should receive minimal new investment until the future Shipper is properly defined.

Right-Side Utility Panel

The right-side global utility surface is tab-based.

Baseline rules:

• the initial tab set contains only Activity;
• the panel must remain easy to extend with additional tabs later;
• Run is not a tab.

The right-side panel is for general Studio awareness and shell-level utility, not for per-workspace log dumping.

Project Entry

The Studio must not land directly into a workspace as the primary entry flow.

Baseline behavior:

• first show a lightweight project launcher or home surface;
• show existing or recent projects;
• expose Open Project and Create Project as first-class actions;
• enter the main workspace shell only after a concrete project is selected or created.

UI Remodeling Scope

The Studio UI may be substantially remodeled in code during this wave.

That flexibility is limited by these requirements:

• theme support must be preserved;
• i18n support must be preserved;
• the resulting UI should create a clear path for reusable Studio components rather than ad hoc JavaFX fragments.

No Fully Docked Shell Yet

A fully docked IDE shell is explicitly deferred.

Reasons:

• shell topology is still being proven;
• workspace responsibilities are still being defined;
• early docking would force layout and lifecycle decisions too soon;
• the extra complexity is not justified by the current product maturity.

Dockability may be revisited only after shell regions and workspace panel responsibilities are stable in actual use.

Explicit Non-Decisions

This decision does not yet define:

• the full set of future right-side tabs beyond Activity;
• the detailed content model of the Activity surface;
• the Studio event system architecture in detail;
• custom component admission policy;
• the internal panel composition of each workspace.

Those topics remain delegated to follow-up Studio agendas and decisions.

Propagation Targets

This decision must propagate to:

• Studio shell specifications under docs/studio/specs/;
• Studio foundation work on naming, events, and custom components;
• future PR/plan work for MainView, workspace switching, project launcher, and shell composition;
• code implementation in prometeu-studio and future shared UI work in prometeu-studio-components.

Validation Notes

A conforming first UI wave should make these behaviors visible:

• the user enters through a project launcher or home surface;
• the shell shows a fixed workspace rail on the left;
• the selected workspace owns its main body and its own logs;
• the right side exposes Activity as a global utility surface;
• run controls remain immediately visible without opening a tab.