update specs studio
This commit is contained in:
@@ -41,3 +41,10 @@ If content grows, prefer:
|
||||
- overview documents,
|
||||
- explicit learning paths,
|
||||
- consolidation of duplicated explanations.
|
||||
|
||||
## Current Learning Path
|
||||
|
||||
Start here:
|
||||
|
||||
1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md)
|
||||
2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
# Studio Events and Components Mental Model
|
||||
|
||||
Two things are meant to stop the Studio from becoming messy as it grows:
|
||||
|
||||
- a typed event model;
|
||||
- a single authoritative control layer.
|
||||
|
||||
These two rules solve different problems, but they reinforce each other.
|
||||
|
||||
## Why a Studio-owned event system?
|
||||
|
||||
Without it, the shell, workspaces, and services begin to call each other directly.
|
||||
|
||||
That usually feels fine at first, because the UI is small. Then the application gains:
|
||||
|
||||
- global activity surfaces;
|
||||
- background operations;
|
||||
- multiple workspaces;
|
||||
- status and progress reporting;
|
||||
- cross-cutting actions such as run or diagnostics.
|
||||
|
||||
At that point, direct references become the path of least resistance and the UI starts coupling itself in ways that are hard to unwind.
|
||||
|
||||
The Studio event system exists to keep event publication explicit and typed.
|
||||
|
||||
## Why both a global bus and workspace buses?
|
||||
|
||||
Because the Studio needs both segregation and shared visibility.
|
||||
|
||||
Workspaces should be able to keep their local activity scoped.
|
||||
The shell should still be able to observe what is happening globally.
|
||||
|
||||
The chosen rule is therefore:
|
||||
|
||||
- each workspace has its own bus;
|
||||
- the Studio has a global bus;
|
||||
- every workspace event is automatically republished to the global bus.
|
||||
|
||||
This means callers do not need to decide when to duplicate publication manually.
|
||||
|
||||
## Why not rely on raw JavaFX controls directly?
|
||||
|
||||
Because raw JavaFX use spreads quickly and creates UI drift.
|
||||
|
||||
When each part of the app consumes JavaFX controls directly, the Studio gradually accumulates:
|
||||
|
||||
- inconsistent naming;
|
||||
- inconsistent styling hooks;
|
||||
- repeated local wrappers;
|
||||
- uneven behavior between screens;
|
||||
- more work each time theme or locale behavior needs to change.
|
||||
|
||||
That is why the Studio uses `prometeu-studio-components` as its visual control layer.
|
||||
|
||||
## Does that mean reimplementing JavaFX?
|
||||
|
||||
No.
|
||||
|
||||
The goal is not to reproduce every JavaFX API.
|
||||
The goal is to expose the Studio-facing API the application actually needs.
|
||||
|
||||
That keeps the control layer:
|
||||
|
||||
- opinionated;
|
||||
- smaller than JavaFX;
|
||||
- aligned with the Studio's own UI dialect.
|
||||
|
||||
## Practical reading rule
|
||||
|
||||
When adding UI code, ask two questions:
|
||||
|
||||
1. Is this communication really an event?
|
||||
2. Is this control part of the Studio's visible dialect?
|
||||
|
||||
If the answer to the first question is yes, it should probably publish a typed Studio event.
|
||||
If the answer to the second question is yes, it should probably come through `prometeu-studio-components`.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Studio Shell Mental Model
|
||||
|
||||
The Studio shell exists to frame workspaces, not to absorb every piece of UI.
|
||||
|
||||
That distinction matters because a lot of early JavaFX applications slowly become a single giant layout where every new concern gets added to the same frame. The shell model chosen here avoids that.
|
||||
|
||||
## What belongs to the shell?
|
||||
|
||||
The shell owns:
|
||||
|
||||
- project entry through a launcher or home surface;
|
||||
- global menus;
|
||||
- fixed workspace navigation;
|
||||
- the workspace host;
|
||||
- the right-side utility surface;
|
||||
- the always-visible run surface.
|
||||
|
||||
The shell does not own the full operating detail of every domain workflow.
|
||||
|
||||
## What belongs to a workspace?
|
||||
|
||||
A workspace owns its main body and its domain-specific detail.
|
||||
|
||||
That includes things like:
|
||||
|
||||
- editor-specific structure;
|
||||
- asset-management views;
|
||||
- debugger and profiler views;
|
||||
- workspace-local logs and detailed operational output.
|
||||
|
||||
This is why the Studio does not define a mandatory single global console as the primary logging model.
|
||||
|
||||
## Why avoid a fully docked shell right now?
|
||||
|
||||
Because the Studio is still proving its topology.
|
||||
|
||||
If docking is introduced too early, the codebase starts solving these problems before the product actually needs them:
|
||||
|
||||
- panel restore rules;
|
||||
- drag-and-drop docking behavior;
|
||||
- focus and lifecycle complexity;
|
||||
- layout persistence;
|
||||
- too many shell-level extension points.
|
||||
|
||||
The structured shell keeps the frame stable without pretending the full IDE model is already known.
|
||||
|
||||
## Why is `Run` always visible?
|
||||
|
||||
Because run is a primary action, not a secondary panel.
|
||||
|
||||
If running the project requires opening a tab first, the shell is hiding one of the most important actions behind navigation friction. The Studio therefore treats `Run` as a persistent shell control.
|
||||
|
||||
## Practical reading rule
|
||||
|
||||
When deciding whether something belongs in the shell or in a workspace, ask:
|
||||
|
||||
> “Is this a Studio-wide framing concern, or is it operational detail of one workspace?”
|
||||
|
||||
If it is framing, it belongs in the shell.
|
||||
If it is operational detail, it probably belongs in the workspace.
|
||||
Reference in New Issue
Block a user