update specs studio

This commit is contained in:
2026-03-24 13:42:39 +00:00
parent 9ed16301ab
commit 2ee37d7d13
14 changed files with 532 additions and 471 deletions
@@ -1,154 +0,0 @@
# Studio Shell, Workspace Navigation, and Layout Agenda
## Status
Closed
## Purpose
Define the baseline Studio shell:
- main window layout,
- workspace navigation model,
- shell regions and panel hierarchy,
- default landing behavior,
- how future workspaces should fit into the frame.
## Domain Owner
`docs/studio`
## Current Code Context
Current `prometeu-studio` already provides:
- `MainView` as the root shell;
- `WorkspaceBar` as left-side workspace navigation;
- `EditorWorkspace` as the most concrete workspace;
- placeholder workspaces for `Assets` and `Device`;
- a `BuilderWorkspace` implementation artifact with logs and toolbar.
The shell exists, but it is still closer to a scaffold than a documented Studio UX contract.
This shell may be substantially remodeled in code as long as the resulting Studio preserves:
- theme support;
- i18n support;
- a clear path for custom Studio components instead of ad hoc UI fragments.
## Core Questions
1. What is the long-lived shell structure of the Studio?
2. Is left-side workspace switching the correct baseline navigation model?
3. Which shell regions are global and which belong to each workspace?
4. How should the Assets workspace coexist with Editor, Device, and future shipping flows?
5. What should the default landing workspace be?
## Options
### Option A
Keep the current shell mostly intact and grow workspaces within it.
### Option B
Evolve toward a multi-panel shell with global activity and contextual side panels.
### Option C
Adopt a dock-heavy IDE-style shell from the start.
## Tradeoffs
- Option A is fast and consistent with current code, but may constrain richer workflows later.
- Option B preserves the current shell while creating room for Studio-grade interaction design.
- Option C is powerful, but likely too heavy for the current code and service maturity.
Specific concern with adopting a fully docked shell too early:
- it forces panel lifecycle and layout-persistence decisions before the core workspace model is stable;
- it adds implementation weight around focus, restore, drag/drop, and window state without proving that the Studio already needs that flexibility;
- it increases UX complexity while the Assets workspace and background activity model are still being defined;
- it risks stabilizing the wrong shell topology too early.
## Recommendation
Prefer Option B.
Recommended direction:
- keep workspace switching in the shell,
- formalize a stable frame with top global menus, left workspace selectors, center workspace body, and right global utility panel,
- let each workspace own its internal panels, including logs and detailed operational output,
- avoid a fully dockable IDE model for the first Studio UI wave,
- revisit dockability only after the shell regions and workspace panel responsibilities are proven in use.
## Open Questions
1. Which shell regions are baseline and always present:
top global menus, left workspace navigation, right global utility panel, status/progress bar?
2. Which right-side tabs are baseline in v1, and which are future additions?
3. Should the Studio land directly in a workspace, restore the last workspace, or open through a project launcher/home surface first?
4. Does `BuilderWorkspace` remain a first-class shell workspace, or should future shipping/build flows move toward a different Studio surface?
5. Which parts of the shell must be fixed in v1, and which can remain future extension points without immediate docking support?
## Current Direction
The preferred direction for question 3 is to introduce a lightweight project launcher or home surface before the main workspace shell.
Target experience:
- closer to Unity or the IntelliJ family than to direct last-tab restore;
- show existing projects immediately;
- make `open project` and `create project` first-class actions;
- only enter the workspace shell after a concrete project is selected or created.
This keeps project entry intentional and gives the Studio a stable place for project lifecycle actions without overloading the main workspace shell.
The current preferred shell model is:
- top region with global Studio menus such as `File`, `Edit`, `View`, and similar shell-level actions;
- left-side fixed workspace selector, closer to IntelliJ-style workspace switching than to a free docking system;
- center region fully owned by the selected workspace;
- right-side global utility surface implemented as tabs;
- logs and detailed execution output owned by each workspace instead of a single global bottom console.
The right-side global utility surface is intended for concerns such as:
- general activity visibility;
- contextual inspector or summary views;
- global shortcuts and shell-level utility surfaces.
`Run` should not be modeled as a tab.
It should remain always visible at the top-right portion of the shell so that running the current project or relevant flow is always easy to reach.
This keeps run/build controls immediately accessible while allowing the right-side tab system to serve broader global concerns.
Current baseline answers:
- the initial right-side tab set contains only `Activity`;
- the right-side panel must remain easy to extend with additional tabs later;
- `BuilderWorkspace` may remain in the shell temporarily because it is still useful for tests, but it should be treated as a low-investment transitional surface on the path toward a future `Shipper`;
- the baseline fixed workspace set is:
- Code Editor
- Asset Management
- Debugger/Profiler
- Shipper, temporarily represented by the current `BuilderWorkspace`
The shell and workspaces should also evolve with explicit foundations for:
- clear naming conventions,
- a Studio event system,
- reusable custom components such as directory trees and related structured UI controls.
## Expected Follow-up
- a shell decision,
- a Studio shell spec,
- a PR/plan for `MainView`, `WorkspaceBar`, and workspace composition.
- a separate Studio foundations agenda for naming, events, and custom component architecture.
## Outcome
Closed in [`001-studio-shell-workspace-navigation-and-layout-decision.md`](../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md).
@@ -1,104 +0,0 @@
# Studio UI Foundations - Naming, Events, and Custom Components Agenda
## Status
Open
## Purpose
Define the shared UI foundations required before the Studio grows into a larger product surface.
This agenda exists to keep the Studio from becoming a pile of unrelated JavaFX screens with inconsistent naming, ad hoc event wiring, and one-off controls.
## Domain Owner
`docs/studio`
## Context
The current `prometeu-studio` shell is still small enough to be remodeled.
Today there is no real Studio-wide event system.
Current behavior is still largely based on direct wiring between UI elements, workspace hosts, and service calls.
That is the right moment to establish explicit foundations for:
- clear naming conventions;
- a Studio event system;
- reusable custom components;
- long-lived support for i18n and themes.
The immediate driver is the upcoming Assets workspace, but the same foundations will affect Editor, Debugger/Profiler, and the future Shipper surface.
## Core Questions
1. Which naming conventions should apply to Studio shell classes, workspaces, panels, services, and events?
2. What kind of Studio-wide event system should exist between shell, workspaces, and background services?
3. Which custom components should become first-class reusable Studio controls instead of one-off implementations?
4. How should i18n and theme support constrain custom component design from day 1?
5. Where is the boundary between generic infrastructure and domain-specific workspace UI?
## Initial Areas To Close
### Naming
Need clear and stable names for:
- shell surfaces;
- workspace types;
- right-side utility tabs;
- events and event payloads;
- reusable controls and component packages.
### Events
Need a Studio event model that can support:
- shell-level state changes;
- workspace-local interactions;
- background service notifications;
- progress and activity publication;
- future debugger/profiler integration.
Current direction:
- introduce a Studio-owned event system instead of continuing with ad hoc direct coupling;
- keep it small, local, and strongly typed;
- model it as a `StudioEventBus` or equivalent typed publish/subscribe surface;
- avoid stringly-typed event names and avoid overbuilding a large reactive framework too early.
Illustrative event categories include:
- project lifecycle events;
- workspace selection events;
- run/build intent events;
- activity publication events;
- diagnostics and asset-selection events.
### Custom Components
Likely candidates include:
- directory tree or project tree controls;
- activity feed views;
- diagnostics list views;
- inspector panels;
- staged action and preview surfaces.
## Recommendation
Close this agenda early, right after the shell decision.
Recommended direction:
- establish naming before adding many more UI classes;
- define a Studio-owned typed event system before workspaces start integrating services ad hoc;
- invest in reusable components only where the shell or multiple workspaces will truly benefit;
- require i18n and theme compliance for every Studio-specific control.
## Expected Follow-up
- one or more Studio foundation decisions,
- a foundational Studio spec,
- a PR/plan for shared UI infrastructure in `prometeu-studio`.
@@ -1,60 +0,0 @@
# Studio Components Module and Admission Policy Agenda
## Status
Open
## Purpose
Define the role of `prometeu-studio-components` and the rules for what should enter that module.
The module now exists as a base project, but it should not become a dumping ground for wrappers around JavaFX controls or speculative framework work.
## Domain Owner
`docs/studio`
## Context
The Studio UI is about to be remodeled.
We want:
- a consistent Studio UI dialect;
- reusable JavaFX-based Studio components;
- easier customization and stronger engineering around shared controls;
- continued compatibility with i18n and themes.
At the same time, we explicitly do not want to populate the module prematurely.
## Current Direction
`prometeu-studio-components` should remain empty until concrete Studio UI work requires shared controls.
The baseline policy is:
- the module exists now so Studio UI work has a clear home for shared components;
- components are admitted only when they are needed by the current Studio UI wave;
- the module should stay focused on real Studio shell and workspace needs, not general JavaFX abstraction for its own sake.
## Core Questions
1. Which kinds of components belong in `prometeu-studio-components` from day 1?
2. Which controls should remain local to `prometeu-studio` until a second use appears?
3. What theme and i18n requirements must every admitted component satisfy?
4. How much infrastructure should live in this module versus in Studio application code?
5. How do we prevent the module from turning into a speculative component catalog?
## Recommendation
Keep the module intentionally sparse.
Recommended admission rule:
- add a component when it is part of the shell or has immediate reuse in the current Studio UI work;
- otherwise keep it local until the need is proven.
## Expected Follow-up
- a decision on the admission policy for `prometeu-studio-components`;
- a future spec or learn artifact once the first component wave actually exists.
+3 -5
View File
@@ -11,16 +11,14 @@ The initial Studio UI planning wave is:
3. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md)
4. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md)
5. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md)
6. [`01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md`](./01.6.%20Studio%20UI%20Foundations%20-%20Naming,%20Events,%20and%20Custom%20Components%20Agenda.md)
7. [`01.7. Studio Components Module and Admission Policy Agenda.md`](./01.7.%20Studio%20Components%20Module%20and%20Admission%20Policy%20Agenda.md)
Recommended discussion order:
`01.6 -> 01.7 -> 01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5`
`01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5`
The Studio shell baseline was closed in [`../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md`](../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md).
The shell, UI foundations, and components admission baselines were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
The remaining order closes the shared UI foundations, then the components admission policy, then the asset workspace structure, and only after that the detailed interaction flows.
The remaining order closes the asset workspace structure first, and only after that the detailed interaction flows.
## Purpose