update specs studio
This commit is contained in:
parent
9ed16301ab
commit
2ee37d7d13
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -45,6 +45,8 @@ Use it to:
|
||||
- decide how Studio consumes services and events,
|
||||
- define what must be visible, staged, or confirmed in the UI.
|
||||
|
||||
When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set.
|
||||
|
||||
### `decisions/`
|
||||
|
||||
`decisions/` records closed Studio product and UX decisions before they are fully propagated.
|
||||
@ -55,6 +57,8 @@ Use it to:
|
||||
- define invariants for UI behavior,
|
||||
- capture what must be implemented in Studio code and service contracts.
|
||||
|
||||
Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue.
|
||||
|
||||
### `pull-requests/`
|
||||
|
||||
`pull-requests/` contains execution plans for Studio changes.
|
||||
@ -99,9 +103,11 @@ The preferred Studio documentation flow is:
|
||||
## Practical Rule
|
||||
|
||||
- `agendas/` stores currently open Studio questions.
|
||||
- `decisions/` stores decisions that still need propagation.
|
||||
- `decisions/` stores only decisions that still need propagation.
|
||||
- `pull-requests/` stores execution plans.
|
||||
- `specs/` stores the normative Studio contract.
|
||||
- `learn/` stores teaching-oriented Studio knowledge.
|
||||
|
||||
The current Studio core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
|
||||
|
||||
If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`.
|
||||
|
||||
@ -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.
|
||||
@ -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
|
||||
|
||||
|
||||
@ -1,145 +0,0 @@
|
||||
# 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.
|
||||
@ -2,9 +2,12 @@
|
||||
|
||||
This directory contains Studio decision records.
|
||||
|
||||
Current retained Studio decisions:
|
||||
There are currently no retained Studio decision records.
|
||||
|
||||
1. [`001-studio-shell-workspace-navigation-and-layout-decision.md`](./001-studio-shell-workspace-navigation-and-layout-decision.md)
|
||||
The first Studio decision wave was already consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
@ -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`.
|
||||
60
docs/studio/learn/mental-model-studio-shell.md
Normal file
60
docs/studio/learn/mental-model-studio-shell.md
Normal file
@ -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.
|
||||
@ -0,0 +1,105 @@
|
||||
# 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.
|
||||
|
||||
## 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;
|
||||
- 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`.
|
||||
|
||||
`BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
|
||||
|
||||
## 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
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- project entry and shell regions are unambiguous;
|
||||
- workspace and shell responsibilities are clearly separated;
|
||||
- the baseline Studio frame is stable enough for implementation planning.
|
||||
123
docs/studio/specs/2. Studio UI Foundations Specification.md
Normal file
123
docs/studio/specs/2. Studio UI Foundations Specification.md
Normal file
@ -0,0 +1,123 @@
|
||||
# Studio UI Foundations Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Naming, event publication model, and Studio UI foundations
|
||||
Purpose: Define the shared infrastructure rules that all Studio UI work must follow.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio UI foundations decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- Studio shell structures
|
||||
- workspace UI structures
|
||||
- Studio-owned services
|
||||
- shell and workspace event publication needs
|
||||
- reusable Studio control infrastructure
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. Studio UI naming must be explicit by role.
|
||||
2. The Studio must define its own typed event system.
|
||||
3. The Studio event system must include one global bus and one bus per workspace.
|
||||
4. Every event published on a workspace bus must also be published on the global bus automatically.
|
||||
5. Studio UI must preserve theme and i18n compatibility by construction.
|
||||
|
||||
## Naming by Role
|
||||
|
||||
Studio naming must follow role-oriented conventions.
|
||||
|
||||
Baseline naming guidance:
|
||||
|
||||
- `StudioShell*` for shell-level structures;
|
||||
- `*Workspace` for workspaces;
|
||||
- `*Panel` for composed regions or panels;
|
||||
- `*View` for focused visual views;
|
||||
- `*Item` or `*Row` for list and cell-like elements;
|
||||
- `StudioEvent*` for event types;
|
||||
- `*Service` for operational services;
|
||||
- `*Control` for reusable low-level visual controls.
|
||||
|
||||
Names must communicate responsibility directly.
|
||||
Vague naming that hides shell, panel, workspace, or control roles is non-conforming.
|
||||
|
||||
## Studio Event System
|
||||
|
||||
The Studio must not rely on stringly-typed event routing as its primary contract.
|
||||
|
||||
Baseline event rules:
|
||||
|
||||
- event publication is local to the process;
|
||||
- event publication is strongly typed;
|
||||
- event payloads are DTOs and should be immutable where practical;
|
||||
- the baseline model should remain intentionally small;
|
||||
- a large reactive framework is not baseline behavior.
|
||||
|
||||
## Global and Workspace Buses
|
||||
|
||||
The baseline event topology includes:
|
||||
|
||||
- one global `StudioEventBus`;
|
||||
- one workspace-local event bus per workspace.
|
||||
|
||||
Propagation rules:
|
||||
|
||||
- every event published on a workspace bus is automatically republished on the global bus;
|
||||
- propagation is workspace to global;
|
||||
- global-to-workspace rebroadcast is not baseline behavior.
|
||||
|
||||
This topology exists so callers do not need to duplicate publication decisions manually.
|
||||
|
||||
## Event Categories
|
||||
|
||||
The exact event catalog may evolve incrementally.
|
||||
|
||||
Illustrative baseline categories include:
|
||||
|
||||
- project lifecycle events;
|
||||
- workspace selection events;
|
||||
- run and build intent events;
|
||||
- activity publication events;
|
||||
- progress update events;
|
||||
- diagnostics update events;
|
||||
- asset selection events.
|
||||
|
||||
## Theme and i18n Compatibility
|
||||
|
||||
Shared Studio UI foundations must preserve:
|
||||
|
||||
- CSS-based theming;
|
||||
- locale-safe user-facing text behavior;
|
||||
- safe runtime locale updates where text changes dynamically;
|
||||
- no hardcoded user-facing text in reusable Studio controls.
|
||||
|
||||
Theme and i18n compatibility are admission requirements for shared UI infrastructure.
|
||||
|
||||
## Foundation Boundary
|
||||
|
||||
Shared Studio foundations include:
|
||||
|
||||
- shell-level UI conventions;
|
||||
- event publication and observation infrastructure;
|
||||
- reusable Studio control conventions.
|
||||
|
||||
Shared Studio foundations do not include:
|
||||
|
||||
- domain-specific workspace business logic;
|
||||
- speculative control catalogs;
|
||||
- unrelated non-visual infrastructure that does not directly serve Studio UI.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the full event catalog in advance
|
||||
- defining every future workspace interaction
|
||||
- defining the first concrete control implementation wave in detail
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- naming rules are stable enough to guide new Studio code;
|
||||
- the event topology is explicit;
|
||||
- theme and i18n constraints are unambiguous for shared Studio UI work.
|
||||
130
docs/studio/specs/3. Studio Components Module Specification.md
Normal file
130
docs/studio/specs/3. Studio Components Module Specification.md
Normal file
@ -0,0 +1,130 @@
|
||||
# Studio Components Module Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
|
||||
Purpose: Define the authoritative visual control layer for the Studio.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio components module decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- `prometeu-studio-components`
|
||||
- Studio shell and workspace UI needs
|
||||
- JavaFX controls actively used by the Studio
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. `prometeu-studio-components` is the official visual control module for Studio UI.
|
||||
2. Studio UI should normally consume visual controls from `prometeu-studio-components`, not directly from raw JavaFX.
|
||||
3. A control enters the module when it is needed by the current Studio UI wave.
|
||||
4. Controls in the module wrap and shape the JavaFX controls the Studio actively uses, but do not clone the full JavaFX API.
|
||||
5. Every admitted control must preserve theme and i18n compatibility.
|
||||
|
||||
## Module Role
|
||||
|
||||
`prometeu-studio-components` is:
|
||||
|
||||
- the authoritative Studio control layer;
|
||||
- the home of the Studio visual dialect;
|
||||
- the place where Studio-facing controls are shaped for Studio use.
|
||||
|
||||
`prometeu-studio-components` is not:
|
||||
|
||||
- a speculative generic framework;
|
||||
- a full reimplementation of JavaFX;
|
||||
- a dumping ground for unrelated non-visual infrastructure.
|
||||
|
||||
## Admission Policy
|
||||
|
||||
A control is admissible when it is needed by the current Studio UI work.
|
||||
|
||||
Rules:
|
||||
|
||||
- immediate current Studio use is sufficient justification;
|
||||
- a second use is not required when the control is clearly part of the shell or the current workspace surface;
|
||||
- no control should be added without an immediate Studio consumer.
|
||||
|
||||
## Studio Usage Rule
|
||||
|
||||
The baseline Studio UI should not rely on raw JavaFX controls as its normal visual surface.
|
||||
|
||||
Rules:
|
||||
|
||||
- a visual control used by Studio should normally come from `prometeu-studio-components`;
|
||||
- extremely trivial local composition may stay in `prometeu-studio`;
|
||||
- local exceptions must remain exceptional rather than becoming the default path.
|
||||
|
||||
## Wrapping Boundary
|
||||
|
||||
Controls in `prometeu-studio-components` must wrap the JavaFX controls the Studio actively uses.
|
||||
|
||||
Rules:
|
||||
|
||||
- the Studio-layer control should expose the Studio-facing API actually needed;
|
||||
- exhaustive mirroring of upstream JavaFX APIs is not required;
|
||||
- the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type.
|
||||
|
||||
## Typical Control Scope
|
||||
|
||||
Typical controls that belong in the module include:
|
||||
|
||||
- shell controls;
|
||||
- action controls and buttons;
|
||||
- tab systems;
|
||||
- tree and list controls;
|
||||
- inspector and panel surfaces;
|
||||
- activity and feedback surfaces;
|
||||
- badges, headers, and related Studio primitives.
|
||||
|
||||
What stays outside the module:
|
||||
|
||||
- workspace-specific composition logic;
|
||||
- non-visual domain behavior;
|
||||
- speculative controls with no immediate Studio consumer.
|
||||
|
||||
## Theme and i18n
|
||||
|
||||
Every admitted control must support:
|
||||
|
||||
- CSS-based theming;
|
||||
- safe locale-aware text behavior when text is exposed;
|
||||
- no hardcoded user-facing text;
|
||||
- explicit visual states where state matters.
|
||||
|
||||
## Organization Guidance
|
||||
|
||||
The module should be organized by Studio role rather than vague technical buckets.
|
||||
|
||||
Illustrative areas include:
|
||||
|
||||
- shell;
|
||||
- actions;
|
||||
- navigation;
|
||||
- feedback;
|
||||
- inspection;
|
||||
- trees.
|
||||
|
||||
## Anti-Bloat Rule
|
||||
|
||||
The module must remain:
|
||||
|
||||
- intentional;
|
||||
- Studio-driven;
|
||||
- small enough to reason about;
|
||||
- broad enough to prevent UI entropy in the application.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the first concrete component set in full detail
|
||||
- defining final package layout exhaustively
|
||||
- mirroring the entire JavaFX control hierarchy
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- the module role is unambiguous;
|
||||
- admission rules are stable enough to guide implementation;
|
||||
- the JavaFX wrapping boundary is clear enough to prevent drift.
|
||||
@ -45,3 +45,19 @@ Specs should normally be fed by:
|
||||
4. then spec integration.
|
||||
|
||||
If a spec edit would require guessing unresolved UI behavior, stop and surface the missing decision first.
|
||||
|
||||
## Current Corpus
|
||||
|
||||
The current Studio core corpus is:
|
||||
|
||||
1. [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
2. [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
3. [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. shell and workspace layout;
|
||||
2. shared UI foundations;
|
||||
3. components module policy.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user