prometeu-studio/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md

Studio Shell and Workspace Layout Specification

Status: Draft Scope: Studio shell, project entry, and workspace frame Purpose: Define the normative shell structure of the Studio UI.

Authority and Precedence

This specification consolidates the accepted Studio shell decision into normative form.

Normative Inputs

• the Studio application shell
• project entry or launcher flow
• shell-level workspace navigation
• shell-level utility and run surfaces

Core Rules

1. The Studio must open through a project launcher or home surface before entering the main workspace shell.
2. The main shell must expose a top global menu region.
3. The main shell must expose a left fixed workspace selector.
4. The main shell must expose a center workspace host.
5. The main shell must expose a right global utility panel.
6. The main shell must expose an always-visible run surface in the top-right area.
7. Workspaces mounted in the shell must follow the Studio event-driven workspace framework.
8. The shell must preserve a clear path for reusable workspace framework primitives shared across workspaces.

Project Entry

The Studio must not land directly into a workspace as its primary entry behavior.

Baseline project entry behavior is:

• show a lightweight launcher or home surface first;
• show existing or recent projects;
• expose Open Project and Create Project as first-class actions;
• the project-creation flow may include an optional extra-details step for project-local setup such as editor indentation policy;
• enter the main workspace shell only after a concrete project is selected or created.

Workspace Model

The left workspace selector remains fixed in the baseline Studio shell.

The baseline workspace set includes:

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

Workspace-local behavior for the first Code Editor wave is defined in:

• 5. Code Editor Workspace Specification.md

BuilderWorkspace is transitional and must not be treated as a long-term architectural reference for the final shipping surface.

Workspace Architecture Model

The shell-level workspace host exists to mount independently authored workspaces under one Studio contract.

Baseline workspace architecture rules are:

• each workspace should have a composition root that mounts the workspace into the shell;
• a workspace composition root should coordinate workspace services, state orchestration, and structural sync, but it should not own every local render path directly;
• project-session services that must survive workspace focus changes should be owned above individual workspace focus lifecycles and then consumed by workspace composition roots;
• event-observing workspace controls must be lifecycle-managed;
• workspace-local updates should flow through the Studio event system rather than ad hoc imperative redraw chains;
• future workspaces should consume shared Studio workspace framework primitives where those primitives already cover the needed behavior.

The shell must not encourage a workspace model where every interaction falls back to whole-workspace refresh.

Detailed local workspace composition remains workspace-owned. For example, Code Editor-local layout, navigator behavior, tab rules, passive placeholder surfaces, document access-mode behavior, and editor-local save surfaces are not shell-global rules and must be defined by the workspace-local editor specification.

Project-session boundaries may still exist above a workspace when the state must remain alive while the project window stays open.

Rules:

• the shell may construct and own project-session services that survive workspace focus changes;
• workspaces may consume those project-session services without inheriting their ownership;
• introducing a project-session service must not collapse shell and workspace responsibilities into one monolithic root.
• project-local Studio state under .studio/ must be loaded through the project-session boundary rather than through shell-local ad hoc persistence;
• session-restoration state under .studio/state.json must be loaded through the project-session lifecycle;
• project-local setup under .studio/setup.json is configuration rather than session snapshot state and may be read on demand by the consumer that needs it;
• shell-restorable state accepted by Studio must be restored when the project shell mounts and persisted when the project shell closes.

Right Utility Panel

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

Baseline rules:

• the initial tab set contains only Activity;
• the panel must be extendable with additional tabs later;
• Run is not a tab.

The right utility panel exists for shell-level visibility and utility, not for general per-workspace log dumping.

Logs and Operational Detail

Detailed execution output belongs to the active workspace that owns the operation.

Rules:

• the shell must not define a single mandatory global console as the baseline logging model;
• each workspace may expose its own logs, console, or detailed operational output;
• shell-level utility surfaces may summarize shared activity, but they do not replace workspace-owned detail.

UI Remodeling Scope

The Studio UI may be remodeled substantially during this wave.

That flexibility is constrained by:

• theme support must remain preserved;
• i18n support must remain preserved;
• the resulting shell must keep a clear path for reusable Studio controls.

Deferred Docking

A fully docked IDE shell is not baseline behavior.

Rules:

• docking is explicitly deferred;
• shell topology and workspace responsibilities must be proven first;
• future dockability may be revisited only after the baseline shell is stable in actual use.

Non-Goals

• defining the full internal layout of every workspace
• defining the final future tab set of the right utility panel
• defining the detailed activity rendering model
• defining every reusable workspace primitive in this document

Exit Criteria

This specification is complete enough when:

• project entry and shell regions are unambiguous;
• workspace and shell responsibilities are clearly separated;
• the shell-level expectations for workspace architecture are explicit;
• the baseline Studio frame is stable enough for implementation planning.