---
id: LSN-0006
ticket: studio-docs-import
title: Studio shell mental model legacy lesson
created: 2026-03-26
tags:
  - studio
  - legacy-import
  - shell
  - workspace-boundary
---

## Context

Legacy import from `docs/studio/learn/mental-model-studio-shell.md`.

This lesson preserves the Studio-wide boundary between shell framing concerns and workspace operational detail.

Relevant spec:

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

## Key Decisions

### The shell should frame workspaces without absorbing their operational detail

**What:** The Studio shell owns project entry, global menus, fixed workspace navigation, the workspace host, right-side utility surface, and always-visible run control, while each workspace owns its own main body and domain-specific operational detail.
**Why:** Early JavaFX apps often collapse into one giant frame where every new concern lands at shell scope. The chosen shell model avoids that drift and keeps topology stable without prematurely committing to a fully docked IDE model.
**Trade-offs:** A structured shell limits early flexibility compared with full docking, but it prevents the codebase from solving layout-persistence and docking complexity before the product actually needs it.

## Patterns and Algorithms

- Keep shell concerns focused on framing, not workspace internals.
- Keep operational detail such as asset-management views, debugger/profiler content, and workspace-local logs inside the relevant workspace.
- Treat `Run` as a persistent shell control because it is a primary action rather than a secondary panel.
- Use the practical rule: framing concerns go to the shell; workspace operational detail stays in the workspace.

## Pitfalls

- Adding every new concern to one giant shell layout.
- Treating shell-wide console surfaces as mandatory for all detailed logs.
- Introducing docking complexity before the product topology is proven.
- Hiding primary actions like `Run` behind avoidable navigation friction.

## Takeaways

- The shell frames workspaces; it does not absorb them.
- The shell/workspace boundary is a product rule, not just a layout preference.
- Legacy source attribution: `docs/studio/learn/mental-model-studio-shell.md`.
